Docs
EntrarCriar conta
Ambiente
Base URLhttps://api.sancopay.com/api/v1
Arquivo para IA
Começar

Idempotência

Rede cai, timeout acontece. Com idempotência você repete a mesma chamada com segurança: a API reconhece a repetição e devolve o resultado da primeira, sem cobrar nem pagar duas vezes.

Cobranças: header Idempotency-Key

  • POST /charges exige o header Idempotency-Key, único por cobrança. Sem ele: 422 idempotency_key_required.
  • Repetir a mesma chave devolve 200 com a cobrança já criada e o header Idempotent-Replayed: true.
  • Gere a chave a partir do seu pedido (ex.: pedido-123) e reaproveite-a em todas as tentativas daquele pedido.
Repetição200 OK

Mesma Idempotency-Key: a cobrança original, sem criar outra.

Idempotent-Replayed: true {  "id": 4821,  "tracking_id": "c62abd1d-9092-4892-b163-cef2951912ad",  "reference": "PED-123",  "status": "pending",  "amount": 150,  "fee": null,  "message": "Pedido #123",  "customer": {    "name": "Maria Souza",    "email": "[email protected]",    "tax_id": "12345678909"  },  "pix": {    "copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d65204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2"  },  "end_to_end_id": null,  "metadata": {    "order_id": "123",    "coupon": "OFF10"  },  "failure_reason": null,  "created_at": "2026-11-09T15:04:05.000000Z",  "updated_at": "2026-11-09T15:04:05.000000Z"}

Saques e pré-aprovações: reference

  • POST /payouts, cada item de POST /payouts/batch e POST /pre-approvals exigem reference no corpo ou o header Idempotency-Key. Sem os dois: 422 reference_required.
  • Reenviar uma reference já usada responde 409 duplicate_reference com o registro existente em payout (ou pre_approval). Trate como “já feito” e leia o status dele.
  • 409 request_in_progress: outro saque da conta ainda está em processamento. Espere alguns segundos e repita.

Recorrência: reference

Planos e assinaturas aceitam reference. Se ela já existir, a API responde 200 (em vez de 201) com o registro existente e o header Idempotent-Replayed: true, sem criar outro nem emitir outra cobrança.