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.
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 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 Status Description 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):
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 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
Automate Refund Workflows
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.
Provide Clear Communication
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 