Pagamentos
Cancelar pagamento
Como cancelar uma cobrança de cartão ainda não paga.
Use POST /v1/payments/:id/cancel para cancelar uma cobrança de cartão que ainda está aguardando pagamento.
Cancelamento não é estorno. Pagamentos já confirmados não podem ser cancelados por esta rota.
Regras
| Regra | Comportamento |
|---|---|
| Método | Apenas card. |
| Status aceitos | pending ou processing. |
| Pix | Retorna 400 cannot_cancel_pix; o QR Code deve expirar naturalmente. |
| Pagamento pago | Retorna 409 cannot_cancel_paid. |
| Status final | Retorna 409 already_canceled para canceled, expired ou failed, incluindo status com o valor atual. |
Cartão no Pagar.me: o pagamento precisa ter sido criado com customer.phone válido. Pagamentos legados criados sem phone podem responder 502 gateway_error no cancelamento: o adapter não revalida o campo, mas o gateway pode rejeitar. Se isso acontecer, deixe a cobrança expirar naturalmente (cartão não pago expira no gateway depois do prazo configurado).
Exemplo
curl --request POST \
--url https://payments-api.allyasolutions.com/v1/payments/pay_7f3e0c9a12b44d63a9f612c42a8d2b90/cancel \
--header "Authorization: Bearer sk_test_..."Resposta:
{
"id": "pay_7f3e0c9a12b44d63a9f612c42a8d2b90",
"status": "canceled",
"method": "card",
"gateway": "pagarme",
"amount": 12990,
"currency": "BRL",
"externalId": "pedido_124",
"gatewayRef": "pl_abc",
"customer": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"documentLast4": "0000"
},
"checkoutUrl": "https://...",
"pix": null,
"card": null
}Quando o status muda, a Allya registra um evento interno e envia o webhook outbound payment.canceled para os endpoints configurados.
Códigos de resposta
| Status | Error | Significado |
|---|---|---|
200 | - | Pagamento cancelado e retornado no formato normalizado. |
400 | invalid_id | ID na rota é inválido. |
400 | cannot_cancel_pix | Pagamentos Pix não são cancelados pela API. |
401 | unauthorized | API key ausente ou inválida. |
404 | not_found | Pagamento não existe no ambiente da API key. |
409 | cannot_cancel_paid | Pagamento já foi confirmado. |
409 | already_canceled | Pagamento já está em status final. A resposta inclui status com o valor atual. |
409 | cannot_cancel_status | Status atual não permite cancelamento. A resposta inclui status com o valor atual. |
409 | missing_gateway_ref | Pagamento não tem referência do gateway para cancelar. |
409 | provider_not_configured | Gateway do pagamento não está configurado no ambiente. |
429 | rate_limit_exceeded | Limite por API key excedido (default 10/min). Veja Retry-After. |
501 | not_implemented | O gateway atual ainda não expõe cancelamento seguro pela Allya. |
502 | gateway_error | O gateway recusou ou falhou durante o cancelamento. |
Veja também
- Status de pagamento: diferença entre
cancelede refund. - Cancelar assinatura: cancelamento recorrente, com regra própria.
- Sincronizar pagamento: útil quando o status local diverge do gateway antes de cancelar.