Xipatchi Gateway

📑 Índice

• Como começar
• Requisitos
• Endpoints principais
• Autenticação
• Métodos de pagamento
• Webhooks
• Tratamento de erros
• Exemplo PHP
• Exemplos em outras linguagens
• Respostas JSON
• Limites e quotas
• Documentação Swagger
• FAQ

🚀 Como começar

1. Registe-se na página oficial do Xipatchi Gateway para obter o seu token de desenvolvedor em https://xipatchi.com/auth/registar.
2. Inclua o cliente PHP XipatchiClient.php no seu projeto. Pode obter este arquivo em https://github.com/jMabunda2025/Xipatchi-Gateway
3. Configure o ambiente - Utilize o token de desenvolvedor para autenticar todas as requisições.
4. Envie pagamentos usando o endpoint /payment/create.

📋 Requisitos

• PHP 7.4 ou superior (para o cliente PHP)
• cURL habilitado
• Token de desenvolvedor válido
• Número M-Pesa válido (para transações com M-Pesa)
• SSL para ambiente de produção

🔌 Endpoints principais

🔐 Autenticação

Todas as requisições devem incluir o cabeçalho:

Authorization: Bearer SEU_TOKEN

Este TOKEN habilita o Desenvolvedor a enviar pagamentos e solicitar retiradas dentro do Xipatchi Gateway.

💳 Métodos de Pagamento

🔔 Webhooks

O Xipatchi Gateway pode notificar seu sistema sobre eventos importantes via webhooks. Configure a URL no painel do desenvolvedor.

Eventos disponíveis:

• payment.success - Pagamento confirmado
• payment.failed - Pagamento falhou
• withdrawal.success - Saque processado
• withdrawal.failed - Saque falhou

Exemplo de payload (payment.success):

{
  "event": "payment.success",
  "timestamp": "2026-03-08T14:30:00Z",
  "data": {
    "transaction_id": "cc2a41rjx1hl",
    "amount": 500,
    "cliente_id": 2,
    "metodo": "mpesa"
  }
}

⚠️ Tratamento de Erros

📝 Exemplo de integração (PHP)

require_once __DIR__ . '/XipatchiClient.php';

use Xipatchi\XipatchiClient;

// Inicializa o cliente com a URL da API e o token do developer
$client = new XipatchiClient(
    "https://xipatchi.com", // ou http://localhost/xipatchi em ambiente local
    "SEU_TOKEN_AQUI"
);

// ============================
// Criar pagamento
// ============================
$dadosPagamento = [
    "cliente_id"   => 2,
    "developer_id" => 1,
    "item_id"      => 1,
    "metodo"       => "mpesa",
    "mpesa"        => "84xxxxxxx", // número valido da Vodacom M-Pesa (84 ou 85 + 7 dígitos)
    "amount"       => 500
];

$resPagamento = $client->createPayment($dadosPagamento);
echo "Pagamento:\n";
echo json_encode($resPagamento, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

// ============================
// Solicitar saque
// ============================
$dadosSaque = [
    "valor"  => 300,
    "metodo" => "mpesa"
];

$resSaque = $client->requestWithdrawal($dadosSaque);
echo "\n\nSaque:\n";
echo json_encode($resSaque, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

// ============================
// Histórico de retiradas
// ============================
$resHistorico = $client->getHistory();
echo "\n\nHistórico:\n";
echo json_encode($resHistorico, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

// ============================
// Saldo atual
// ============================
$resSaldo = $client->getBalance();
echo "\n\nSaldo atual:\n";
echo json_encode($resSaldo, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

🌐 Exemplos em diferentes linguagens

cURL

# Criar pagamento
curl -X POST https://xipatchi.com/payment/create \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": 2,
    "developer_id": 1,
    "item_id": 1,
    "metodo": "mpesa",
    "mpesa": "84xxxxxxx",
    "amount": 500
  }'

# Solicitar saque
curl -X POST https://xipatchi.com/withdrawals/request \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 300,
    "metodo": "mpesa"
  }'

# Consultar histórico de retiradas
curl -X GET https://xipatchi.com/withdrawals/history \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

# Consultar saldo atual
curl -X GET https://xipatchi.com/withdrawals/balance \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

JavaScript (Node.js com fetch)

const fetch = require("node-fetch");

async function criarPagamento() {
  const resposta = await fetch("https://xipatchi.com/payment/create", {
    method: "POST",
    headers: {
      "Authorization": "Bearer SEU_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      cliente_id: 2,
      developer_id: 1,
      item_id: 1,
      metodo: "mpesa",
      mpesa: "84xxxxxxx",
      amount: 500
    })
  });

  const resultado = await resposta.json();
  console.log(resultado);
}

criarPagamento();

// Solicitar saque
async function solicitarSaque() {
  const resposta = await fetch("https://xipatchi.com/withdrawals/request", {
    method: "POST",
    headers: {
      "Authorization": "Bearer SEU_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ valor: 300, metodo: "mpesa" })
  });
  console.log(await resposta.json());
}

// Histórico de retiradas
async function historicoSaque() {
  const resposta = await fetch("https://xipatchi.com/withdrawals/history", {
    method: "GET",
    headers: {
      "Authorization": "Bearer SEU_TOKEN",
      "Content-Type": "application/json"
    }
  });
  console.log(await resposta.json());
}

// Saldo atual
async function saldoAtual() {
  const resposta = await fetch("https://xipatchi.com/withdrawals/balance", {
    method: "GET",
    headers: {
      "Authorization": "Bearer SEU_TOKEN",
      "Content-Type": "application/json"
    }
  });
  console.log(await resposta.json());
}

solicitarSaque();
historicoSaque();
saldoAtual();

Python (requests)

import requests

url = "https://xipatchi.com/payment/create"
headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
}
dados = {
    "cliente_id": 2,
    "developer_id": 1,
    "item_id": 1,
    "metodo": "mpesa",
    "mpesa": "84xxxxxxx",
    "amount": 500
}

resposta = requests.post(url, json=dados, headers=headers)
print(resposta.json())

headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json"
}

# Solicitar saque
dados_saque = { "valor": 300, "metodo": "mpesa" }
resposta = requests.post("https://xipatchi.com/withdrawals/request", json=dados_saque, headers=headers)
print("Solicitar saque:", resposta.json())

# Histórico de retiradas
resposta = requests.get("https://xipatchi.com/withdrawals/history", headers=headers)
print("Histórico:", resposta.json())

# Saldo atual
resposta = requests.get("https://xipatchi.com/withdrawals/balance", headers=headers)
print("Saldo atual:", resposta.json())

Java (HttpClient)

import java.net.http.*;
import java.net.URI;
import java.net.http.HttpResponse.BodyHandlers;

public class XipatchiClient {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        // ============================
        // Criar pagamento
        // ============================
        String pagamentoJson = """
        {
          "cliente_id": 2,
          "developer_id": 1,
          "item_id": 1,
          "metodo": "mpesa",
          "mpesa": "841234567",
          "amount": 500
        }
        """;

        HttpRequest pagamentoRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://xipatchi.com/payment/create"))
            .header("Authorization", "Bearer SEU_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(pagamentoJson))
            .build();

        HttpResponse pagamentoResponse = client.send(pagamentoRequest, BodyHandlers.ofString());
        System.out.println("Pagamento: " + pagamentoResponse.body());

        // ============================
        // Solicitar saque
        // ============================
        String saqueJson = """
        {
          "valor": 300,
          "metodo": "mpesa"
        }
        """;

        HttpRequest saqueRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://xipatchi.com/withdrawals/request"))
            .header("Authorization", "Bearer SEU_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(saqueJson))
            .build();

        HttpResponse saqueResponse = client.send(saqueRequest, BodyHandlers.ofString());
        System.out.println("Saque: " + saqueResponse.body());

        // ============================
        // Histórico de retiradas
        // ============================
        HttpRequest historicoRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://xipatchi.com/withdrawals/history"))
            .header("Authorization", "Bearer SEU_TOKEN")
            .header("Content-Type", "application/json")
            .GET()
            .build();

        HttpResponse historicoResponse = client.send(historicoRequest, BodyHandlers.ofString());
        System.out.println("Histórico: " + historicoResponse.body());

        // ============================
        // Saldo atual
        // ============================
        HttpRequest saldoRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://xipatchi.com/withdrawals/balance"))
            .header("Authorization", "Bearer SEU_TOKEN")
            .header("Content-Type", "application/json")
            .GET()
            .build();

        HttpResponse saldoResponse = client.send(saldoRequest, BodyHandlers.ofString());
        System.out.println("Saldo atual: " + saldoResponse.body());
    }
}

📦 Resposta JSON

Exemplo de resposta de sucesso (pagamento):

{
  "success": true,
  "message": "Payment processed successfully.",
  "data": {
    "cliente_id": "2",
    "item_id": "1",
    "transaction": "cc2a41rjx1hl",
    "reference": null,
    "status": "completed",
    "timestamp": "2026-03-08T14:30:00Z"
  }
}

Exemplo de resposta de sucesso (saque):

{
  "status": "success",
  "mensagem": "Saque solicitado com sucesso",
  "referencia": "WD641A2F",
  "data": "2026-03-08",
  "valor": 300,
  "metodo": "mpesa"
}

Exemplo de resposta de erros:

{
  "success": false,
  "message": "❌ Falha no pagamento.",
  "error": {
    "code": "INVALID_MPESA",
    "details": "Número M-Pesa inválido"
  },
  "data": {}
}

{
  "status": "error",
  "mensagem": "Não autenticado",
  "error": "invalid_token"
}

📊 Limites e quotas

📖 Documentação Swagger

A especificação completa está disponível em swagger.yaml.

Pode ser carregada no Swagger Editor ou acedida diretamente em https://sandbox.xipatchi.com//swagger.

❓ FAQ