Guia de Pagamento com Dados Bancários

Este fluxo é usado quando você não recebeu uma chave Pix, mas possui os dados bancários completos do recebedor.

Quando usar este fluxo

Use pagamento manual quando tiver:

• Nome e documento do favorecido;
• ISPB da instituição;
• Agência, conta e tipo da conta.

Pré-requisitos

1. Token JWT válido (veja Guia de Autenticação);
2. amount em centavos;
3. Dados bancários completos e válidos;
4. external_id único para conciliação.

Fluxo do pagamento

Passo 1 - Iniciar pagamento manual

Endpoint de referência: Pagar com dados bancários

POST /v1/connect/transfer/manual HTTP/1.1
Host: api.qesh.ai
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 50000,
  "external_id": "pag-manual-2026-03-002",
  "credit_party": {
    "name": "Fornecedor XPTO Ltda",
    "tax_id": "12345678000199",
    "ispb": "12345678",
    "branch": "0001",
    "account_number": "12345678",
    "account_type": "CHECKING"
  }
}

Campos obrigatórios de credit_party:

• name
• tax_id
• ispb
• branch
• account_number
• account_type

Valores de account_type:

• CHECKING
• SAVINGS
• SALARY
• TRANSACTIONAL

Passo 2 - Monitorar liquidação

Use os mesmos endpoints de consulta de transferência:

• Consultar transferência por ID
• Consultar transferência por ID externo
• Consultar transferência por End To End ID

Persista:

• id
• external_id
• end_to_end_id
• status
• credit_party retornado

Diferença para pagamento por chave

• No manual, o recebedor é identificado por conta bancária;
• Não envie key e key_type nesse fluxo;
• A qualidade do cadastro bancário impacta diretamente a taxa de sucesso.

Boas práticas

• Validar formato de documento antes da chamada;
• Padronizar branch/account_number no seu sistema;
• Tratar ERROR com fila de reprocessamento e análise manual;
• Registrar meta.request_id e payload enviado para auditoria.