Refunds API
Process full or partial refunds for completed transactions
Refunds API
Process refunds for completed transactions. Supports both full and partial refunds with configurable options.
This API endpoint is currently under development. Documentation will be updated once the feature is available.
Overview
The Refunds API allows you to:
- Process full refunds for transactions
- Issue partial refunds
- Track refund status
- Handle refund webhooks
- Query refund history
Create Refund
Initiate a refund for a completed transaction.
Endpoint
POST /api/v2/payments/refund
Request Headers
Content-Type: application/json
X-Merchant-API-Key: YOUR_API_KEY
Request Body
{
"transaction_id": "TXN_1234567890",
"refund_amount": 500.00,
"refund_reason": "Customer request",
"refund_type": "partial",
"notify_customer": true,
"metadata": {
"order_id": "ORD_123",
"refund_request_id": "REF_456"
}
}
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
transaction_id | string | Yes | Original transaction ID to refund |
refund_amount | decimal | No | Amount to refund (omit for full refund) |
refund_reason | string | Yes | Reason for the refund |
refund_type | string | No | full or partial (default: full ) |
notify_customer | boolean | No | Send refund notification to customer |
metadata | object | No | Additional metadata for the refund |
Response
Success Response (200 OK)
{
"success": true,
"data": {
"refund_id": "REF_9876543210",
"transaction_id": "TXN_1234567890",
"refund_amount": 500.00,
"refund_status": "processing",
"estimated_completion": "2024-12-20T10:00:00Z",
"created_at": "2024-12-18T15:30:00Z"
}
}
Error Response (400 Bad Request)
{
"success": false,
"error": {
"code": "REFUND_EXCEEDED",
"message": "Refund amount exceeds original transaction amount"
}
}
Get Refund Status
Check the status of a refund request.
Endpoint
GET /api/v2/payments/refund/{refund_id}
Request Headers
X-Merchant-API-Key: YOUR_API_KEY
Response
{
"success": true,
"data": {
"refund_id": "REF_9876543210",
"transaction_id": "TXN_1234567890",
"refund_amount": 500.00,
"refund_status": "completed",
"completed_at": "2024-12-19T14:20:00Z",
"created_at": "2024-12-18T15:30:00Z"
}
}
Refund Status Values
Status | Description |
---|---|
pending | Refund request received |
processing | Refund being processed |
completed | Refund successfully completed |
failed | Refund failed |
cancelled | Refund cancelled |
List Refunds
Get a list of all refunds for your account.
Endpoint
GET /api/v2/payments/refunds
Query Parameters
Parameter | Type | Description |
---|---|---|
page | integer | Page number (default: 1) |
limit | integer | Results per page (default: 20, max: 100) |
status | string | Filter by refund status |
from_date | string | Start date (YYYY-MM-DD) |
to_date | string | End date (YYYY-MM-DD) |
Response
{
"success": true,
"data": {
"refunds": [
{
"refund_id": "REF_9876543210",
"transaction_id": "TXN_1234567890",
"refund_amount": 500.00,
"refund_status": "completed",
"created_at": "2024-12-18T15:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"pages": 3
}
}
}
Cancel Refund
Cancel a pending refund request.
Endpoint
POST /api/v2/payments/refund/{refund_id}/cancel
Request Headers
X-Merchant-API-Key: YOUR_API_KEY
Response
{
"success": true,
"message": "Refund cancelled successfully",
"data": {
"refund_id": "REF_9876543210",
"refund_status": "cancelled"
}
}
Batch Refunds
Process multiple refunds in a single request.
Endpoint
POST /api/v2/payments/refunds/batch
Request Body
{
"refunds": [
{
"transaction_id": "TXN_1234567890",
"refund_amount": 500.00,
"refund_reason": "Customer request"
},
{
"transaction_id": "TXN_0987654321",
"refund_amount": 300.00,
"refund_reason": "Product defect"
}
]
}
Response
{
"success": true,
"data": {
"batch_id": "BATCH_123456",
"total_refunds": 2,
"successful": 2,
"failed": 0,
"refunds": [
{
"transaction_id": "TXN_1234567890",
"refund_id": "REF_111",
"status": "processing"
},
{
"transaction_id": "TXN_0987654321",
"refund_id": "REF_222",
"status": "processing"
}
]
}
}
Refund Webhooks
Receive notifications about refund status changes.
Webhook Events
Event | Description |
---|---|
refund.initiated | Refund request created |
refund.processing | Refund being processed |
refund.completed | Refund successfully completed |
refund.failed | Refund failed |
refund.cancelled | Refund cancelled |
Webhook Payload Example
{
"event": "refund.completed",
"timestamp": "2024-12-19T14:20:00Z",
"data": {
"refund_id": "REF_9876543210",
"transaction_id": "TXN_1234567890",
"refund_amount": 500.00,
"refund_status": "completed",
"original_amount": 1000.00,
"remaining_amount": 500.00
}
}
Testing Refunds
Sandbox Testing
Use these test scenarios in sandbox:
Transaction Amount | Refund Amount | Result |
---|---|---|
Any | Same as transaction | Full refund success |
Any | Less than transaction | Partial refund success |
Any | More than transaction | Error: exceeds limit |
999.00 | Any | Refund fails |
Test Card Behaviors
Different test cards produce different refund behaviors:
4111111111111111
: Instant refund5555555555554444
: 24-hour refund delay378282246310005
: Refund failure
Error Codes
Code | Description | Solution |
---|---|---|
REFUND_EXCEEDED | Refund amount exceeds transaction | Check refund amount |
ALREADY_REFUNDED | Transaction already fully refunded | Verify transaction status |
REFUND_WINDOW_EXPIRED | Refund period expired (180 days) | Contact support for manual processing |
INSUFFICIENT_BALANCE | Merchant balance insufficient | Add funds to account |
REFUND_NOT_ALLOWED | Payment method doesn't support refunds | Manual processing required |
Best Practices
- Idempotency: Use idempotency keys to prevent duplicate refunds
- Validation: Verify refund amount before processing
- Webhooks: Implement webhook handlers for refund status
- Monitoring: Track refund rates and patterns
- Customer Communication: Notify customers of refund status
FAQ
Q: How long do refunds take? A: Typically 5-7 business days depending on payment method.
Q: Can I refund more than the original amount? A: No, refunds cannot exceed the original transaction amount.
Q: Is there a time limit for refunds? A: Refunds can be processed within 180 days of the original transaction.
Q: Can I cancel a refund? A: Only pending refunds can be cancelled. Once processing, they cannot be stopped.