Reverta um pagamento

POST

payment

{id}

cancel_or_refund

curl -X POST https://api.therius.io/v1/payment/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e/cancel_or_refund \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001"
  }'

{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "cancelled",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-002",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 9900, "exponent": 2 }
}

Se você não quer rastrear no seu próprio sistema se um pagamento está no estado authorized ou captured, POST /payment/{id}/cancel_or_refund faz isso por você. O Therius verifica o estado atual do pagamento e automaticamente cancela a autorização (se não capturada) ou emite um reembolso total (se já capturada). Isso é especialmente útil em fluxos de reversão de pedidos onde o estado do pagamento pode variar conforme o momento — por exemplo, um cliente cancelando um pedido enquanto o cumprimento está em andamento.

Identificar o pagamento

{id} é o id de pagamento do Therius devolvido por POST /payment/authorization e POST /payment/purchase. orderCode e paymentCode são os seus próprios campos de referência e não são aceitos aqui. Um id desconhecido ou não pertencente devolve 404.

Este endpoint sempre reverte o pagamento completo — anula toda a retenção de autorização, ou reembolsa todo o valor capturado. Para emitir um reembolso parcial em um pagamento capturado, chame Refund com um amount em vez disso.

Exemplo

Reverter um pagamento sem conhecer o estado dele

curl -X POST https://api.therius.io/v1/payment/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e/cancel_or_refund \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001"
  }'

{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "cancelled",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-002",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 9900, "exponent": 2 }
}

Resposta quando o pagamento estava capturado (caminho de reembolso) — 200 OK

{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "refunded",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-001",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 4999, "exponent": 2 }
}

Este endpoint é ideal para fluxos de reversão de pedidos disparados pela sua UI de cancelamento voltada ao cliente, onde o mesmo caminho de código trata tanto os estados anteriores à captura quanto os posteriores. Use o status na resposta para determinar qual ação foi tomada e atualize os seus registros internos de acordo.

Autorizações

Authorization

string

header

obrigatório

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Cabeçalhos

Idempotency-Key

string<uuid>

A UUID you generate per operation. Required in production. Retrying with the same key returns the original response.

Parâmetros de caminho

string<uuid>

obrigatório

The Therius payment id returned by POST /payment/authorization or POST /payment/purchase.

Corpo

application/json

merchantCode

string

obrigatório

Your merchant account identifier. Validated against the Bearer key's merchant; required if the key maps to more than one merchant account.

reference

string

Optional internal reference for this operation.

Resposta

200 - application/json

Reverse result

Result of a capture, refund, cancel or cancel_or_refund.

string

The Therius payment id.

merchantCode

string

orderCode

string

paymentCode

string

Therius receipt ID.

amount

object

Show child attributes

status

enum<string>

Outcome of the operation.

Opções disponíveis:

captured,

refunded,

cancelled,

failed

curl -X POST https://api.therius.io/v1/payment/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e/cancel_or_refund \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001"
  }'

{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "cancelled",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-002",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 9900, "exponent": 2 }
}

Pagamentos

Tokenização

Assinaturas

Planos

Sessão do SDK

Reverta um pagamento

Identificar o pagamento

Exemplo

Reverter um pagamento sem conhecer o estado dele

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta

​Identificar o pagamento

​Exemplo

​Reverter um pagamento sem conhecer o estado dele

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta

Identificar o pagamento

Exemplo

Reverter um pagamento sem conhecer o estado dele