The Initiate Refund endpoint allows merchants to create refund transactions that disperse funds from their account. The refund amount is automatically derived from the original successful collection transaction being refunded. This endpoint establishes a new refund transaction by referencing an existing collection transaction. The system uses the original transaction’s details to process the refund.
Prerequisites
- The refund request must reference a previously successful collection transaction.
- Only Collection transactions with a successful status can be refunded
- The merchant account must have sufficient balance or credit to process the refund
Request
Endpoint: POST
v1/payment/refundRequest Body
{
"correlatorId": "string",
"systemTransactionId": "string"
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| correlatorId | string | yes | Merchant transaction identifier. The unique reference assigned by the merchant to the original collection transaction. |
| systemTransactionId | string | yes | Payment gateway transaction identifier. The unique reference assigned by the payment system to the original collection transaction. |
Processing
The system uses the provided correlatorId and systemTransactionId to:
- Query for the matching collection transaction
- Validate that the transaction exists and has a successful status
- Extract the transaction amount and details
- Create a new refund transaction with the extracted amount
- Disperse funds from the merchant’s account
Important Notes
- Refund transactions can only be initiated on Collection transactions with a successful status
- The refund amount is fixed and cannot be modified, as it matches the original transaction amount.
Response
Success Response (200 ok)
{
"data": {
"astragateTransactionId": "83c6ab2f-dcd3-405b-a54d-a95599e4079e",
"correlatorId": "70674d9f-2356-4b66-a5cc-350a92dc4d4a",
"statusCode": 4001,
"statusDescription": "Transaction received and processing"
}
"message": "SUCCESS",
"statusCode": 200,
"success": true
}
Response Fields
| Field | Type | Description |
|---|---|---|
| data.astragateTransactionId | string (UUID) | The unique transaction identifier assigned by the payment gateway to the refund transaction. Use this ID to track and query the refund status. |
| data.correlatorId | string (UUID) | The merchant transaction identifier from the request, provided for reference and correlation. |
| data.statusCode | integer | The transaction processing status code. 4001 indicates the transaction has been received and is processing. |
| data.statusDescription | string | Human-readable description of the transaction status. |
| message | string | Overall API response message. Returns "SUCCESS" on successful refund initiation. |
| statusCode | integer | HTTP status code. 200 indicates the refund request was accepted and is being processed. |
| success | boolean | Flag indicating whether the API request was successful. true confirms the refund transaction was initiated. |
Transaction Status
The statusCode of 4001 indicates the refund transaction has been accepted by the system and is undergoing processing. The actual refund disbursement will follow asynchronously. To track the refund progress, use the astragateTransactionId returned in the response to query the transaction status.