Refunds

Create a Refund

Issue full or partial refunds for card and SPEI payments. Process returns, cancellations, and adjustments with a simple API call.

POST /v2/payment-orders/:id/refund
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
Content-Type: application/json

PayCash and CIE Cash Net do not support API refunds. Handle returns at merchant level. Card and SPEI support refunds via the API below.

The amount field is required on every refund request and is expressed in minor units (centavos) — e.g. 5000 refunds $50.00 MXN. There is no “omit for full refund” shorthand: to refund the full payment, pass the full amount.

Partial Refund

Refund part of the original payment amount:

{
  "amount": 5000,
  "reason": "Customer requested partial refund"
}

Response:

{
  "id": "cbea8cd4-79f3-43aa-9375-4eef021dda10",
  "status": "COMPLETED",
  "amount": "10000",
  "refundedAmount": "5000",
  "paymentMethodType": "CARD",
  "createdAt": "2025-10-30T12:00:00.000Z",
  "updatedAt": "2025-10-30T13:00:00.000Z"
}

The refund is processed asynchronously. The status in the response is the payment order status at the time of the request and may not yet reflect the refund — poll the payment order or subscribe to the payment.refund.success webhook to confirm the final PARTIALLY_REFUNDED / REFUNDED status.

Full Refund

Pass the full remaining amount to refund the payment completely:

{
  "amount": 10000,
  "reason": "Order cancelled"
}

Split-Tender Orders

If the payment order was created with allowPartials: true (multiple payments on one order), you must also pass the paymentId of the specific payment to refund:

{
  "amount": 5000,
  "paymentId": "9cc9b665-8230-47aa-b3ed-c419ab20e24a",
  "reason": "Customer requested refund"
}

If paymentId is omitted on a split-tender order, the API responds with a validation error listing the available payment IDs.

Refund Timeline

Card Refunds

Funds typically appear in the customer’s account within 5-10 business days. This is standard bank processing time and outside of Cheqpay’s control.

Refund Requested

You create a refund via the API.

Instant Processing

Cheqpay processes the refund immediately (status: COMPLETED).

Bank Processing

Card network and issuing bank process the refund (5-10 days).

Funds Available

Customer sees the refund in their account.

Multiple Partial Refunds

Issue multiple partial refunds up to the original payment amount:

Original payment:  $100.00 MXN (amount: 10000)
Refund 1:          $25.00 (amount: 2500) → Status: PARTIALLY_REFUNDED
Refund 2:          $25.00 (amount: 2500) → Status: PARTIALLY_REFUNDED
Refund 3:          $50.00 (amount: 5000) → Status: REFUNDED (complete)

Example

# First partial refund
curl -X POST https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/cbea8cd4-79f3-43aa-9375-4eef021dda10/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID" \
  -d '{"amount": 2500, "reason": "Partial return"}'

# Second partial refund
curl -X POST https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/cbea8cd4-79f3-43aa-9375-4eef021dda10/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID" \
  -d '{"amount": 2500, "reason": "Additional return"}'

# Final refund
curl -X POST https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/cbea8cd4-79f3-43aa-9375-4eef021dda10/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID" \
  -d '{"amount": 5000, "reason": "Complete order cancellation"}'

Refund Status

Refund progress is reflected in the payment order status:

Status	Description
`REFUND_PROCESSING`	Refund is being processed
`PARTIALLY_REFUNDED`	Part of the payment has been refunded
`REFUNDED`	The full payment has been refunded

Refunds are processed asynchronously — retrieve the payment order or listen for the payment.refund.success webhook to confirm completion. The 5-10 day delay for the customer to see the funds is on the banking side.

Important Rules

Only Paid Payments

You can only refund payments that have been authorized or captured (order status COMPLETED or PARTIALLY_REFUNDED for further partial refunds). Pending or failed payments cannot be refunded.

Refunds Are Final

Once processed, refunds cannot be cancelled or reversed. Make sure to verify the amount before refunding.

Maximum Refund Amount

Total refunds cannot exceed the original payment amount. Attempting to over-refund will result in an error.

Processing Fees

Processing fees are typically not refunded. You’ll still pay the original transaction fee even after issuing a refund.

Customer Notifications

Customers are automatically notified when refunds are processed (if notifications are enabled):

{
  "notificationOptions": {
    "notifyEmail": true,
    "notifyPhone": false
  }
}

The notification includes:

Refund amount
Original payment reference
Estimated timeframe for funds to appear
Support contact information

Disable automatic notifications if you prefer to send refund notifications from your own system.

Refund Reasons

Always include a reason for tracking and reporting:

{
  "reason": "Customer returned product"
}

Common Reasons:

Customer requested refund
Order cancelled
Product returned
Duplicate payment
Item out of stock
Service not delivered
Quality issues

Error Handling

Payment Not Refundable

Refunding an order that is not in a refundable state returns a 400 with error code INVALID_OPERATION:

{
  "error": {
    "code": "INVALID_OPERATION",
    "message": "Payment order is not in a refundable state"
  }
}

Refund Amount Exceeds Available

Attempting to refund more than the remaining refundable amount fails with a message indicating the refund amount exceeds the captured amount. Total successful refunds can never exceed the original captured amount.

Missing or Invalid Amount

Omitting amount, or sending a non-positive value, returns a 400 validation error — amount is always required, as an integer in minor units.

Testing Refunds

Sandbox Behavior

Refunds in sandbox process instantly (instead of 5-10 days in production):

Create Test Payment

Process a payment with a test card.

Issue Refund

Call the refund endpoint.

Instant Completion

Refund status immediately shows COMPLETED.

Test Scenarios

# Test full refund (pass the full amount)
curl -X POST https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/YOUR_ORDER_ID/refund \
  -H "x-api-key: YOUR_SANDBOX_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID" \
  -d '{"amount": 10000, "reason": "Test full refund"}'

# Test partial refund
curl -X POST https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/YOUR_ORDER_ID/refund \
  -H "x-api-key: YOUR_SANDBOX_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID" \
  -d '{"amount": 5000, "reason": "Test partial refund"}'

Best Practices

Automate Refund Workflows

Integrate refunds into your order management system for seamless returns processing.

Set Refund Policies

Define clear refund policies and timeframes. Communicate these to customers.

Track Refund Metrics

Monitor refund rates to identify issues with products, services, or payment experience.

Provide Clear Communication

Tell customers when to expect refunds in their account (5-10 days for cards).

Keep Records

Store refund reasons and details for accounting and dispute resolution.

Tracking Refunds

You can track refunds by retrieving the payment order (GET /v2/payment-orders/:id) and checking its status and refundedAmount, or by subscribing to the payment.refund.pending and payment.refund.success webhook events. Because refunds are processed asynchronously, allow a short delay before the order status reflects the refund.

Next Steps

View Payment Orders

Track payments eligible for refunds

Process Card Payments

Learn about payment processing

Error Handling

Handle refund errors gracefully

Best Practices

Learn refund workflow best practices

Getting Started

Essentials

Features

Testing

Guides

API Reference

Payment Orchestrator API

Link Product API

Create a Refund

Partial Refund

Full Refund

Split-Tender Orders

Refund Timeline

Card Refunds

Multiple Partial Refunds

Example

Refund Status

Important Rules

Customer Notifications

Refund Reasons

Error Handling

Payment Not Refundable

Refund Amount Exceeds Available

Missing or Invalid Amount

Testing Refunds

Sandbox Behavior

Test Scenarios

Best Practices

Tracking Refunds

Next Steps

View Payment Orders

Process Card Payments

Error Handling

Best Practices

​Create a Refund

​Partial Refund

​Full Refund

​Split-Tender Orders

​Refund Timeline

​Card Refunds

​Multiple Partial Refunds

​Example

​Refund Status

​Important Rules

​Customer Notifications

​Refund Reasons

​Error Handling

​Payment Not Refundable

​Refund Amount Exceeds Available

​Missing or Invalid Amount

​Testing Refunds

​Sandbox Behavior

​Test Scenarios

​Best Practices

​Tracking Refunds

​Next Steps

View Payment Orders

Process Card Payments

Error Handling

Best Practices

Create a Refund

Partial Refund

Full Refund

Split-Tender Orders

Refund Timeline

Card Refunds

Multiple Partial Refunds

Example

Refund Status

Important Rules

Customer Notifications

Refund Reasons

Error Handling

Payment Not Refundable

Refund Amount Exceeds Available

Missing or Invalid Amount

Testing Refunds

Sandbox Behavior

Test Scenarios

Best Practices

Tracking Refunds

Next Steps