Começando

Idempotência

Falhas de rede acontecem. Para retentar com segurança, envie um external_id — o identificador do pedido no seu sistema — em toda criação de cobrança ou saque.

Como funciona

O external_id é único por conta, considerando todos os tipos de transação (cobranças PIX e saques).
Se você repetir um external_id, nada é criado e a API responde 409 duplicate_external_id com details.transaction_id apontando para a transação original.
Formato: 1 a 100 caracteres, apenas letras, números e _ - . : (regex ^[A-Za-z0-9_\-.:]+$).
Você pode consultar a transação pelo próprio external_id: GET /transactions/pedido-1042.

Estratégia de retentativa recomendada

Em caso de timeout ou 5xx, repita a mesma requisição com o mesmo external_id. Se receber 409, a primeira tentativa foi processada: busque a transação com details.transaction_id (ou pelo external_id) e siga o fluxo normalmente.

Requisições simultâneas

Em requisições simultâneas com o mesmo external_id, apenas uma é criada; as demais recebem 409 com details.transaction_id apontando para a transação criada.

Requisição

curl -X POST "https://reloadbank.app/api/v1/pix/cash-in" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 100,
  "external_id": "pedido-1042"
}'

Resposta

{
  "error": {
    "code": "duplicate_external_id",
    "message": "Já existe uma transação com este external_id",
    "details": {
      "transaction_id": "cm2r8x1qz0004lk08abcd1234"
    }
  }
}