Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cheqpay.mx/llms.txt

Use this file to discover all available pages before exploring further.

​
Create a Refund

Issue full or partial refunds easily. Process returns, cancellations, and adjustments with a simple API call. 
POST /v2/payment-orders/:id/refund
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Partial Refund

Refund part of the original payment amount: 
{
  "amount": 5000,
  "reason": "Customer requested partial refund"
}
Response: 
{
  "paymentOrder": {
    "id": "ord_abc123",
    "status": "PARTIALLY_REFUNDED",
    "amount": 10000,
    "refundedAmount": 5000,
    "netAmount": 5000
  },
  "refund": {
    "id": "ref_xyz789",
    "amount": 5000,
    "status": "COMPLETED",
    "reason": "Customer requested partial refund",
    "createdAt": "2025-10-30T13:00:00.000Z"
  }
}

​
Full Refund

Omit the amount to refund the full payment: 
{
  "reason": "Order cancelled"
}
Response: 
{
  "paymentOrder": {
    "id": "ord_abc123",
    "status": "REFUNDED",
    "amount": 10000,
    "refundedAmount": 10000,
    "netAmount": 0
  },
  "refund": {
    "id": "ref_xyz789",
    "amount": 10000,
    "status": "COMPLETED",
    "reason": "Order cancelled",
    "createdAt": "2025-10-30T13:00:00.000Z"
  }
}

​
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.
1

Refund Requested

You create a refund via the API.
2

Instant Processing

Cheqpay processes the refund immediately (status: COMPLETED).
3

Bank Processing

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

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
Refund 1:          $25.00 → Status: PARTIALLY_REFUNDED
Refund 2:          $25.00 → Status: PARTIALLY_REFUNDED
Refund 3:          $50.00 → Status: REFUNDED (complete)

​
Example

# First partial refund
curl -X POST https://prod.cheqpay.mx/pos/payment-orders/ord_abc123/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"amount": 2500, "reason": "Partial return"}'

# Second partial refund
curl -X POST https://prod.cheqpay.mx/pos/payment-orders/ord_abc123/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"amount": 2500, "reason": "Additional return"}'

# Final refund
curl -X POST https://prod.cheqpay.mx/pos/payment-orders/ord_abc123/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"amount": 5000, "reason": "Complete order cancellation"}'

​
Refund Status

StatusDescription
PENDINGRefund is being processed
COMPLETEDRefund processed successfully
FAILEDRefund failed (rare)
Most refunds complete instantly with status COMPLETED. The delay is on the banking side, not the refund processing.

​
Important Rules

You can only refund payments with status COMPLETED. Pending or failed payments cannot be refunded.
Once processed, refunds cannot be cancelled or reversed. Make sure to verify the amount before refunding.
Total refunds cannot exceed the original payment amount. Attempting to over-refund will result in an error.
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

{
  "error": {
    "code": "NOT_REFUNDABLE",
    "message": "Payment cannot be refunded",
    "details": "Only completed payments can be refunded"
  }
}

​
Refund Amount Exceeds Available

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Refund amount exceeds available balance",
    "details": {
      "originalAmount": 10000,
      "alreadyRefunded": 8000,
      "maxRefundable": 2000,
      "requested": 5000
    }
  }
}

​
Testing Refunds

​
Sandbox Behavior

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

Create Test Payment

Process a payment with a test card.
2

Issue Refund

Call the refund endpoint.
3

Instant Completion

Refund status immediately shows COMPLETED.

​
Test Scenarios

# Test full refund
curl -X POST https://api.cheqpay.dev/pos/payment-orders/ord_test123/refund \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{"reason": "Test full refund"}'

# Test partial refund
curl -X POST https://api.cheqpay.dev/pos/payment-orders/ord_test123/refund \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{"amount": 5000, "reason": "Test partial refund"}'

​
Best Practices

Integrate refunds into your order management system for seamless returns processing.
Define clear refund policies and timeframes. Communicate these to customers.
Monitor refund rates to identify issues with products, services, or payment experience.
Tell customers when to expect refunds in their account (5-10 days for cards).
Store refund reasons and details for accounting and dispute resolution.

​
Tracking Refunds

You can track the status of refunds by retrieving the payment order or viewing the refund history. Refund status updates are reflected immediately in your payment order queries.

​
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