Skip to main content
The /api/payment-gateway/refund endpoint allows you to reverse a captured transaction either in full or in part. Full refunds return the entire charged amount to the buyer, while partial refunds let you specify an exact amount in centavos — useful for scenarios such as retroactive discounts, cancelled line-items, or pro-rated returns. Refunds can only be issued against transactions in the CAPTURED or PAID state.

​
Base URL

https://v2.certopaybrasil.com/api

​
Endpoint

POST /payment-gateway/refund

​
Request Headers

​
X-Api-Key
string
required
Your secret API key. Keep this server-side and never expose it in client-facing code.
​
Content-Type
string
required
Must be application/json.

​
Request Body & Examples

A full refund reverses the entire original charge amount. Omit the amount field entirely — CertoPay will automatically use the total transaction value.

​
Request Fields

​
transactionId
string
required
The unique identifier of the transaction to refund. This is the transactionId returned by POST /api/payment-gateway/process.
​
reason
string
A human-readable explanation for the refund. Stored for audit purposes and visible in your CertoPay dashboard. Example: "Customer request".

​
Example Request

curl -X POST https://v2.certopaybrasil.com/api/payment-gateway/refund \
  -H "X-Api-Key: sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "uuid-da-transacao",
    "reason": "Customer request"
  }'

​
Response Fields

​
transactionId
string
The identifier of the refunded transaction.
​
status
string
Updated transaction status. A successful full refund sets this to "REFUNDED".
​
method
string
The original payment method ("PIX", "BOLETO", or "CARD").
​
amount
integer
The original charged amount in centavos.
​
refundedAmount
integer
The total amount refunded in centavos. For a full refund this equals amount.
​
reason
string
The reason string provided in the request, if any.
​
refundedAt
string
ISO 8601 timestamp of when the refund was processed.

​
Example Response

{
  "transactionId": "uuid-da-transacao",
  "status": "REFUNDED",
  "method": "CARD",
  "amount": 29700,
  "refundedAmount": 29700,
  "reason": "Customer request",
  "refundedAt": "2026-06-26T14:32:00Z"
}

​
Refund Eligibility by Payment Method

MethodFull RefundPartial RefundNotes
CARD✅✅Refunds are processed immediately; settlement timeline depends on the buyer’s issuing bank (typically 5–10 business days).
PIX✅✅PIX refunds (devoluções) are processed in real time via the Banco Central do Brasil infrastructure.
BOLETO✅❌Boleto refunds require the buyer’s bank account details to be provided and are processed manually. Contact CertoPay support for boleto refund instructions.

​
Error Responses

HTTP StatusMeaning
400 Bad RequestA required field is missing or the amount exceeds the refundable balance.
401 UnauthorizedThe X-Api-Key header is missing or invalid.
404 Not FoundNo transaction was found for the provided transactionId.
409 ConflictThe transaction has already been fully refunded or is in a non-refundable state (e.g. PENDING, DECLINED).
500 Internal Server ErrorAn unexpected error occurred on CertoPay’s side. Retry with exponential back-off.
Refunds can only be issued against transactions in a captured or paid state. Attempting to refund a PENDING, DECLINED, or already REFUNDED transaction will return a 409 Conflict error. Always verify the transaction status via GET /api/payment-gateway/transaction/{transactionId} before initiating a refund.