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

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.

Error Handling

Status Code	Error	Solution
400	Payment not CONFIRMED	Only payments with `CONFIRMED` status can be refunded.
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.

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.

Get Started

One-time payment

Payment Methods

Payment Links

Payment Intents

Odoo Integration

Process Refunds

Endpoint

Authentication

Path Parameters

Request Body

Response

Code Examples

Refund Rules

Error Handling

Best Practices

Next Steps

Manage Payment Methods

Payment Methods Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Code Examples

​Refund Rules

​Error Handling

​Best Practices

​Next Steps

Manage Payment Methods

Payment Methods Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Code Examples

Refund Rules

Error Handling

Best Practices

Next Steps