Process Refunds

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

string

required

The unique identifier of the payment method (UUID).

string

required

The unique identifier of the payment to refund (UUID).

Request Body

{
  "reason": "Customer requested refund"
}

Field	Type	Required	Description
`reason`	string	No	Reason for the refund. Useful for accounting and auditing purposes.

Response

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": "REFUNDED",
  "amount": 500,
  "currency": "MXN"
}

Field	Type	Description
`id`	string	Unique identifier of the payment.
`status`	string	Payment status after refund (`REFUNDED`).
`amount`	number	The refunded amount.
`currency`	string	Currency code.

Code Examples

These examples call the production host. While you build, replace https://api-harmony.compago.com with https://demo-api-harmony.compago.com and use a key from the Demo dashboard. See Environments.

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"
  }'

const response = await fetch(
  `https://api-harmony.compago.com/api/payment-method/${paymentMethodId}/payment/${paymentId}/refund`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.COMPAGO_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reason: 'Customer requested cancellation'
    })
  }
);

const refund = await response.json();
console.log('Refund status:', refund.status);
console.log('Refunded amount:', refund.amount, refund.currency);

response = requests.post(
    f'https://api-harmony.compago.com/api/payment-method/{payment_method_id}/payment/{payment_id}/refund',
    headers={
        'x-api-key': os.environ['COMPAGO_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'reason': 'Customer requested cancellation'
    }
)

refund = response.json()
print('Refund status:', refund['status'])
print('Refunded amount:', refund['amount'], refund['currency'])

<?php
$ch = curl_init("https://api-harmony.compago.com/api/payment-method/{$paymentMethodId}/payment/{$paymentId}/refund");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: ' . getenv('COMPAGO_API_KEY'),
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'reason' => 'Customer requested cancellation'
]));

$response = curl_exec($ch);
$refund = json_decode($response, true);
curl_close($ch);

echo "Refund status: {$refund['status']}" . PHP_EOL;
echo "Refunded amount: {$refund['amount']} {$refund['currency']}" . PHP_EOL;
?>

uri = URI("https://api-harmony.compago.com/api/payment-method/#{payment_method_id}/payment/#{payment_id}/refund")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['x-api-key'] = ENV['COMPAGO_API_KEY']
request['Content-Type'] = 'application/json'
request.body = {
  reason: 'Customer requested cancellation'
}.to_json

response = http.request(request)
refund = JSON.parse(response.body)

puts "Refund status: #{refund['status']}"
puts "Refunded amount: #{refund['amount']} #{refund['currency']}"

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.

Holds Cannot Be Refunded

A hold is not a charge: the money was reserved on the card, never taken, so there is nothing to give back. Calling refund on a payment whose status is HELD, HOLD_RELEASED, or HOLD_EXPIRED returns 409 with the error code PAYMENT_IS_HOLD.

The hold is	What to do instead
`HELD` (still live)	Call the release endpoint. It returns the reserved funds to the customer.
`HOLD_RELEASED` or `HOLD_EXPIRED`	Nothing to do. The funds were already returned when the hold was released or when it expired.

Once a hold has been captured, it stops being a hold: the payment is CONFIRMED and refunds work exactly as they do for any other charge. If the capture was partial, the refund returns the captured amount (amount), not the amount that was held (heldAmount).

Refund Window

Refunds are only possible within 24 hours of the payment, and only before 10:30 PM (Mexico City time) on that same day. After the daily settlement runs, the processor can no longer reverse the charge.

For a captured hold, the window runs from the capture date, not from the hold date. A hold placed on Monday and captured on Thursday reaches the bank on Thursday, so Thursday is when its refund window opens and closes. The capturedAt field on the payment tells you the exact starting point.

Error Handling

Status Code	Error	Solution
400	Payment not CONFIRMED	Only payments with `CONFIRMED` status can be refunded.
400	Outside the refund window	Refunds are only possible within 24 hours of the payment (or of its capture) and before 10:30 PM Mexico City time on that day.
401	Unauthorized	Check your API key is valid and included in headers.
404	Payment method not found	Verify the payment method ID is correct.
404	Payment not found	Verify the payment ID is correct.
409	`PAYMENT_IS_HOLD`	The payment is a hold that was never captured. Use the release endpoint instead.

Best Practices

Verify Payment Status Before Refunding

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

Track Refund Reasons

Always include a reason field when processing refunds. This helps with accounting, auditing, and customer service.

{
  "reason": "Customer returned item #SKU-1234"
}

Implement Idempotent Refund Logic

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;
}

Communicate Refund Timelines to Customers

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.

Hold Funds

Hold funds on a saved card, then capture them (in full or in part) or release them within 7 natural days.

Payment Methods Overview

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

Get Started

Core Concepts

Developer API

Accept Payments

Integrations

Process Refunds

Endpoint

Authentication

Path Parameters

Request Body

Response

Code Examples

Refund Rules

Holds Cannot Be Refunded

Refund Window

Error Handling

Best Practices

Next Steps

Manage Payment Methods

Hold Funds

Payment Methods Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Code Examples

​Refund Rules

​Holds Cannot Be Refunded

​Refund Window

​Error Handling

​Best Practices

​Next Steps

Manage Payment Methods

Hold Funds

Payment Methods Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Code Examples

Refund Rules

Holds Cannot Be Refunded

Refund Window

Error Handling

Best Practices

Next Steps