Guia de Pagamento com Chave Pix

Este guia mostra a implementação de envio Pix por chave para casos como pagamento de fornecedores, parceiros e repasses.

Quando usar este fluxo

Use pagamento com chave quando o recebedor informou uma chave Pix (CPF, CNPJ, EMAIL, PHONE ou EVP).

Pré-requisitos

1. Token JWT válido (veja Guia de Autenticação);
2. Header Authorization: Bearer <token>;
3. amount em centavos;
4. external_id único por operação para idempotência de negócio.

Fluxo do pagamento

Passo 1 - Iniciar transferência por chave

Endpoint de referência: Pagar com Chave Pix

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

{
  "amount": 7550,
  "key": "[email protected]",
  "key_type": "EMAIL",
  "external_id": "pag-fornecedor-2026-03-001"
}

Campos obrigatórios:

• amount
• key
• key_type

Tipos de chave aceitos:

• CPF
• CNPJ
• EMAIL
• PHONE
• EVP

Passo 2 - Persistir dados de conciliação

Na resposta, salve principalmente:

• id: identificador interno da transferência;
• external_id: seu identificador de negócio;
• end_to_end_id: rastreio no ecossistema Pix;
• status: estado atual da transferência.

Passo 3 - Acompanhar status

Endpoints de consulta:

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

Status possíveis:

• PROCESSING
• CONFIRMED
• ERROR

Recomendação: trate PROCESSING como pendente e só libere a etapa de negócio após CONFIRMED.

Alertas importantes

• Evite tentativas repetidas para chaves inválidas;
• Nunca reutilize external_id para pagamentos diferentes;
• Registre meta.request_id em logs de integração.