Skip to main content

​
Quando usar

Sempre envie uma chave única por operação quando houver risco de retry por timeout/rede.

​
CASHIN: referenceId

Endpoint: POST /v1/integrations/create-transaction
  • Campo: referenceId (UUID)
  • Escopo: único por userId + type = CASHIN
  • Se repetir: retorna a mesma transação criada anteriormente
Se a chave já existir em outro contexto, a API responde 409 Conflict.

​
CASHOUT: idempotencyKey

Endpoint: POST /v1/integrations/create-cashout
  • Campo: idempotencyKey (UUID)
  • Escopo: único por userId + type = CASHOUT
  • Se repetir: retorna o mesmo saque
Se a chave já existir em outro contexto, a API responde 409 Conflict.

​
Padrão recomendado

  1. Gere UUID no seu backend no momento da intenção de pagamento/saque.
  2. Salve essa chave no seu banco junto com o pedido.
  3. Em retry, reutilize exatamente a mesma chave.
  4. Nunca gere nova chave para o mesmo evento de negócio.

​
Exemplo

{
  "amount": 20.00,
  "description": "Pedido #1234",
  "referenceId": "77823bb5-3d84-4cbf-a2a4-43230cc3b1d1"
}

​
Observação importante

Idempotência evita duplicidade de criação na AXNPAY, mas você ainda deve ter idempotência no seu próprio sistema para fechamento de pedido e conciliação.