externalId e idempotência

O externalId é um identificador seu — normalmente o número do pedido, da fatura ou da venda no seu sistema — enviado na criação de pagamentos e links. Ele cumpre dois papéis:

1. Correlação — o externalId volta em todas as respostas da API e no campo data dos webhooks, permitindo ligar cada evento ao registro correspondente no seu sistema sem precisar armazenar o mapeamento antes.
2. Proteção contra duplicidade — a OrcaPay garante que existe no máximo um pagamento ativo por externalId em cada estabelecimento.

O campo é opcional, mas recomendamos fortemente enviá-lo sempre: sem ele, não há nenhuma proteção contra cobranças duplicadas em retentativas.

A regra de unicidade

Um externalId está ocupado enquanto existir um pagamento ativo com ele. Pagamentos nos status CANCELLED e FAILED liberam o identificador para reuso; todos os outros o mantêm reservado:

Status do pagamento existente	externalId
PENDING, PROCESSING	Ocupado
CONFIRMED (inclusive com estorno parcial)	Ocupado
REVERSED, CHARGEBACK	Ocupado
CANCELLED, FAILED	Liberado

Repare que estorno (REVERSED) e chargeback não liberam o externalId — a venda existiu e foi desfeita; para uma nova tentativa de venda, use um novo identificador.

A unicidade é garantida por restrição no banco de dados, então vale inclusive para requisições simultâneas: se duas chegarem ao mesmo tempo com o mesmo externalId, uma cria o pagamento e a outra recebe 409 CONFLICT.

Comportamento no Pix

POST /payments/pix é idempotente por externalId. Repetir a requisição com o mesmo externalId tem o seguinte comportamento:

Situação do pagamento existente	Resultado
Pix pendente, dentro da validade, mesmo valor	Retorna o mesmo pagamento (mesmo id, mesmo QR Code) — nenhuma cobrança nova é criada
Pix pendente, dentro da validade, valor diferente	409 CONFLICT — cancele o pagamento existente antes de gerar outro com o novo valor
Pix pendente já expirado	O pagamento expirado é cancelado automaticamente e um novo Pix é criado
Pago, em processamento, estornado ou em chargeback	409 CONFLICT

Na prática isso significa que sua aplicação pode repetir o POST /payments/pix com segurança — em caso de timeout, falha de rede ou clique duplo do usuário, a retentativa devolve o mesmo QR Code em vez de gerar uma segunda cobrança:

curl -X POST https://api.orcapay.com.br/payments/pix \
  -H "X-Api-Key: op_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 159.90,
    "externalId": "pedido-1042",
    "customerName": "Maria Silva",
    "customerDocument": "12345678900",
    "customerEmail": "maria@exemplo.com.br"
  }'

Duas execuções seguidas dessa requisição retornam o mesmo id e o mesmo pixQrCode.

Comportamento no cartão

POST /payments/card não reaproveita pagamentos: qualquer pagamento ativo com o mesmo externalId faz a requisição retornar 409 CONFLICT, sem processar o cartão de novo.

{
  "status": 409,
  "code": "CONFLICT",
  "message": "externalId já utilizado por pagamento confirmado: pedido-1042"
}

Use isso a seu favor no tratamento de falhas de rede: se você enviou um POST /payments/card, não recebeu resposta e não sabe se o pagamento foi processado, repita a requisição com o mesmo externalId:

• Se a primeira tentativa não chegou a criar o pagamento, a retentativa o cria normalmente.
• Se a primeira tentativa foi processada, a retentativa retorna 409 — a cobrança existe e não será duplicada. Confirme o status pelo webhook PAYMENT_CONFIRMED ou consultando o pagamento.

Nunca repita a tentativa com um externalId diferente (ou sem externalId) antes de confirmar o desfecho da primeira — isso pode cobrar o cliente duas vezes.

Links de pagamento

No POST /payments/links o externalId é apenas correlação: não há verificação de unicidade e é possível criar vários links com o mesmo identificador. O controle de duplicidade acontece no pagamento gerado quando o link é pago.

Boas práticas

• Envie sempre o externalId na criação de pagamentos.
• Use um identificador estável e único por venda no seu sistema (ex.: pedido-1042), não valores gerados a cada tentativa como timestamps ou UUIDs aleatórios — um identificador novo a cada retentativa anula a proteção.
• Guarde o id retornado pela OrcaPay junto ao seu registro assim que receber a resposta.
• Trate 409 CONFLICT como “esta venda já tem um pagamento ativo”, não como erro inesperado: consulte o pagamento existente e siga o fluxo a partir do status dele.
• Para vender novamente após estorno ou chargeback, gere um novo externalId (ex.: pedido-1042-r2).