Create a refund
Creates a full or partial refund for a successful charge. Target: provide EXACTLY ONE of `chargeId` or `paymentIntentId`. When `paymentIntentId` is supplied the server resolves it to the unique succeeded charge under that intent; the request is rejected if the intent has zero or multiple succeeded charges. Features: - Full or partial refunds - Ledger reversal (double-entry bookkeeping) - Balance updates (debits available funds) - Updates `charge.amountRefunded` - Updates `paymentIntent.amountRefunded` Refund behaviour: - Hits available balance immediately (no hold period) - Creates negative balance transactions - Reverses the original charge's ledger entries - Platform keeps fees (business decision)
Creates a full or partial refund for a successful charge.
Target: provide EXACTLY ONE of chargeId or paymentIntentId. When paymentIntentId is supplied the server resolves it to the unique succeeded charge under that intent; the request is rejected if the intent has zero or multiple succeeded charges.
Features:
- Full or partial refunds
- Ledger reversal (double-entry bookkeeping)
- Balance updates (debits available funds)
- Updates
charge.amountRefunded - Updates
paymentIntent.amountRefunded
Refund behaviour:
- Hits available balance immediately (no hold period)
- Creates negative balance transactions
- Reverses the original charge's ledger entries
- Platform keeps fees (business decision)
Authorization
api-key API key for merchant integrations. Send as Authorization: Bearer <your key>.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/refunds" \ -H "Content-Type: application/json" \ -d '{}'{
"id": "re_abc123",
"chargeId": "ch_xyz789",
"amount": "50000",
"currency": "EGP",
"status": "succeeded",
"reason": "requested_by_customer",
"balanceTransactionId": "bt_def456",
"createdAt": "2024-01-01T00:00:00.000Z"
}{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "Invalid value for parameter.",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#parameter_invalid"
},
"request_id": "req_abc123def456"
}{
"error": {
"type": "authentication_error",
"code": "authentication_required",
"message": "No valid API key provided.",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#authentication_required"
},
"request_id": "req_abc123def456"
}{
"error": {
"type": "invalid_request_error",
"code": "permission_denied",
"message": "The API key does not have permission to perform this action.",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#permission_denied"
},
"request_id": "req_abc123def456"
}{
"error": {
"type": "invalid_request_error",
"code": "resource_missing",
"message": "No such charge: ch_abc123",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_missing"
},
"request_id": "req_abc123def456"
}{
"error": {
"type": "invalid_request_error",
"code": "resource_invalid_state",
"message": "The resource is in a state that does not allow this operation.",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_invalid_state"
},
"request_id": "req_abc123def456"
}{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "An unexpected error occurred. Please try again or contact support.",
"doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#internal_error"
},
"request_id": "req_abc123def456"
}