API de Transações PIX

Documentação completa das rotas de depósito, saque e webhook

POST

/wallet/deposit/payment

Rota para gerar um QRCode PIX para depósito na carteira do usuário.

Parâmetros Requeridos

Parâmetro Tipo Descrição
token string Token de autenticação do usuário (max: 255 chars)
secret string Segredo de autenticação do usuário (max: 255 chars)
amount numeric Valor do depósito (0.01 a 100000)
debtor_name string Nome do pagador (max: 100 chars)
email email E-mail do pagador (max: 100 chars)
debtor_document_number string CPF/CNPJ do pagador (max: 20 chars)
phone string Telefone do pagador (max: 20 chars)
method_pay string Método de pagamento (apenas 'pix' aceito)
postback url URL de callback para notificação (max: 512 chars)

Exemplo de Requisição

{
    "token": "user123token",
    "secret": "user123secret",
    "amount": 100.50,
    "debtor_name": "Fulano de Tal",
    "email": "fulano@example.com",
    "debtor_document_number": "12345678901",
    "phone": "5511999999999",
    "method_pay": "pix",
    "postback": "https://seusite.com/webhook/pix"
}

Resposta de Sucesso

{
    "status": "success",
    "criacao": "2023-01-01T00:00:00Z",
    "expiracao": 3600,
    "transaction": {
        "id": "tx123456789",
        "qrcode": "000201010212...",
        "qr_code_image_url": "https://example.com/qrcode.png",
        "expires_at": "2023-01-01 00:10:00",
        "amount": "100.50"
    }
}

Erros Comuns

422 - Validação falhou

Quando algum parâmetro não atende às validações

404 - Usuário não encontrado

Quando a combinação token/secret é inválida

POST

/send/transfer/pix

Rota para enviar transferências PIX para outras contas (saque).

Parâmetros Requeridos

Parâmetro Tipo Descrição
token string Token de autenticação do usuário (max: 255 chars)
secret string Segredo de autenticação do usuário (max: 255 chars)
valor numeric Valor da transferência (0.01 a 9999999.99)
favorecido.chave string Chave PIX do favorecido (max: 140 chars)
callback string URL de callback para notificação (max: 255 chars)

Exemplo de Requisição

{
    "token": "user123token",
    "secret": "user123secret",
    "valor": 500.75,
    "favorecido": {
        "chave": "12345678901"
    },
    "callback": "https://seusite.com/webhook/pix"
}

Resposta de Sucesso

{
    "status": "success",
    "idTransaction": "env123456789",
    "valor": "500.75",
    "statusTransacao": "EM_PROCESSAMENTO"
}

Erros Comuns

400 - Saldo insuficiente

Quando o usuário não tem saldo suficiente para a transferência

400 - Erro no gateway

Quando o gateway de pagamento retorna um erro

POST

Webhook de Notificação

Este webhook será chamado automaticamente para notificar sobre o status de depósitos e saques PIX.

Estrutura do Payload

Para Depósitos (Pagamentos Recebidos)

{
    "status": "paid",
    "id_transaction": "tx123456789",
    "amount": "100.50"
}

Para Saques (Transferências Enviadas)

{
    "status": "paid" | "refused",
    "id_transaction": "env123456789",
    "amount": "500.75"
}

Status Possíveis

  • paid - Pagamento confirmado (depósito) ou transferência realizada com sucesso (saque)
  • refused - Transferência recusada (apenas para saques)

Fluxo de Processamento

  1. O sistema valida a estrutura básica do payload
  2. Cada transação PIX no payload é processada individualmente
  3. O status da transação é atualizado no banco de dados
  4. O sistema envia notificação para a URL de postback/callback informada
  5. Retorna resumo do processamento com quantidades de sucessos e falhas

Tratamento de Erros

Se o callback para o cliente falhar, a transação ainda será marcada como concluída no sistema, mas um log de erro será registrado.

Resposta do Webhook

{
    "success": true,
    "processed": 1,
    "errors": 0,
    "results": [
        {
            "type": "deposit",
            "status": "success",
            "txid": "tx123456789"
        }
    ],
    "errors_detail": [],
    "timestamp": "2023-01-01 00:00:00"
}