Skip to main content
You can refund charges made against saved payment methods. Refunds are always for the full charge amount and are processed through Compago’s infrastructure. The funds are returned to the customer’s original payment method.

​
Endpoint

POST /api/payment-method/{id}/payment/{paymentId}/refund
API reference: POST /payment-method/{id}/payment/{paymentId}/refund

​
Authentication

Include your API key in the request headers: 
x-api-key: YOUR_API_KEY
Content-Type: application/json

​
Path Parameters

​
id
string
required
The unique identifier of the payment method (UUID).
​
paymentId
string
required
The unique identifier of the payment to refund (UUID).

​
Request Body

{
  "reason": "Customer requested refund"
}
FieldTypeRequiredDescription
reasonstringNoReason for the refund. Useful for accounting and auditing purposes.

​
Response

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": "REFUNDED",
  "amount": 500,
  "currency": "MXN"
}
FieldTypeDescription
idstringUnique identifier of the payment.
statusstringPayment status after refund (REFUNDED).
amountnumberThe refunded amount.
currencystringCurrency code.

​
Code Examples

The entire original charge amount will be refunded. 
curl -X POST https://api.harmony.compago.com/api/payment-method/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/payment/11111111-2222-3333-4444-555555555555/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer requested cancellation"
  }'

​
Refund Rules

Only CONFIRMED payments can be refunded. Attempting to refund a payment with any other status (NOT_INITIALIZED, PENDING, CANCELLED, REFUNDED) will result in a 400 error.
Refunds are permanent. Once a refund is processed, it cannot be reversed. The payment status changes to REFUNDED.

​
Error Handling

Status CodeErrorSolution
400Payment not CONFIRMEDOnly payments with CONFIRMED status can be refunded.
401UnauthorizedCheck your API key is valid and included in headers.
404Payment method not foundVerify the payment method ID is correct.
404Payment not foundVerify the payment ID is correct.

​
Best Practices

Always check that the payment status is CONFIRMED before attempting a refund to avoid unnecessary API errors.
const payment = await fetchPayment(paymentMethodId, paymentId);
if (payment.status !== 'CONFIRMED') {
  console.error('Cannot refund - payment status is', payment.status);
  return;
}
// Proceed with refund
Always include a reason field when processing refunds. This helps with accounting, auditing, and customer service.
{
  "reason": "Customer returned item #SKU-1234"
}
Protect against duplicate refund requests by checking if the payment has already been refunded before making the API call.
const payment = await fetchPayment(paymentMethodId, paymentId);
if (payment.status === 'REFUNDED') {
  console.log('Payment already refunded');
  return;
}
Refund processing times depend on the customer’s bank. Let customers know that while the refund is processed immediately on Compago’s side, it may take a few business days to appear on their statement.

​
Next Steps

Manage Payment Methods

List, retrieve, and revoke saved payment methods.

Payment Methods Overview

Review payment method statuses, use cases, and how the feature works.