Refund a Payment

This guide provides a comprehensive overview of Codapay's Refund API. It describes how merchants can programmatically issue refunds, retrieve refund statuses, and handle refund notifications.

Refund API requires special approval, and is only available to payments that are made via Codapay APIs. Please contact your Account Manager or our integration support team for approval.

Overview of Refund Scenarios

Codapay supports Refunds for Completed Payments. If the payment is incomplete or cancelled when refund is requested, it will return an error response.

1. Refund Integration Flow

Refund for Completed Payments

Refund for Cancelled Payments

2. Create Refund

Endpoint

POST {domain}/airtime/api/restful/v2.0/Payment/createRefund.json

Sample Body

{
  "refundRequest": {
    "apiKey": "<your_api_key>",
    "txnId": 1234567890,
    "country": "360",
    "projectId": 100,
    "customerEmail": "[e-mail]"
  }
}

Request Parameters

Parameter	Type	Mandatory	Description
refundRequest	Object	Yes	Valid JSON object
refundRequest.apiKey	String	Yes	API key provided by Coda
refundRequest.txnId	Numeric	Yes	The transaction ID to refund
refundRequest.country	String	No	ISO 3166 country code
refundRequest.projectId	Numeric	Yes	Unique project ID
refundRequest.customerEmail	String	No	Customer's email address

Sample Response

{
  "refundResult": {
    "id": "rfl_sg195468b7c6c0000",
    "createdAt": "2023-03-08T15:30:00.000000000Z",
    "statusCode": "accepted",
    "type": "full",
    "txnId": 1234567890,
    "amountValue": 40000,
    "amountCurrency": "IDR"
  }
}

Response Fields

Parameter	Type	Description
refundResult	Object	JSON object
refundResult.id	String	Refund ID
refundResult.createdAt	String	Timestamp (ISO 8601 format) Possible formats: YYYY-MM-DDThh:mm:ss.ssssssZ (up to microseconds) YYYY-MM-DDThh:mm:ss.sssssssssZ (up to nanoseconds)
refundResult.statusCode	String	Status: accepted, succeeded, or failed
refundResult.finalizedAt	String	Optional timestamp when refund is finalized Possible formats: YYYY-MM-DDThh:mm:ss.ssssssZ (up to microseconds) YYYY-MM-DDThh:mm:ss.sssssssssZ (up to nanoseconds) *If null, this field will not be included in response
refundResult.type	String	Type of refund, always "full"
refundResult.txnId	Numeric	Refunded transaction ID
refundResult.amountValue	Numeric	Amount refunded
refundResult.amountCurrency	String	Currency of the refund

Sample Error Response

{
  "refundResult": {
    "resultCode": 551
    "resultDesc": "Duplicate Refund Request"
  }
}

Error Response Fields

Parameter	Type	Description
refundResult	Object	JSON object
refundResult.resultCode	Numeric	Error code
refundResult.resultDesc	String	Description of the error

Error Codes

Code	Description
103	Invalid API Key, Merchant Not Found, or Invalid Email
206	Transaction Not Found, Invalid Transaction
551	Duplicate Refund Request
102	Internal Server Error

3. Retrieve Refund Status

Endpoint

POST {domain}/airtime/api/restful/v2.0/Payment/retrieveRefund.json

Sample Body

{
  "retrieveRefundRequest": {
    "apiKey": "<your_api_key>",
    "country": "360",
    "projectId": 100,
    "refundId": "rfl_sg1955a7330200033"
  }
}

Request Parameters

Parameter	Type	Mandatory	Description
refundRequest	Object	Yes	Valid JSON object
refundRequest.apiKey	String	Yes	API key provided by Coda
refundRequest.country	String	No	ISO 3166 country code
refundRequest.projectId	Numeric	Yes	Unique project ID
refundRequest.refundId	String	Yes	The ID of the refund request to retrieve

Response

Same as the refundResult object in the createRefund response.

4. Refund Notification Callback

Codapay sends a webhook to the configured notification URL with the refund status.

Request from Codapay

GET {merchantCallbackUrl}?EventType=refund&Id=<refund_id>&CreatedAt=<ts>&StatusCode=accepted&FinalizedAt=<ts>&Type=full&TxnId=<txn_id>&AmountValue=<amount>&AmountCurrency=<currency>&OrderId=<orderId>&ResultCode=0&Checksum=<checksum>

Expected Response from webhook

ResultCode=0

Key Fields

Field	Type	Description
EventType	String	The type of event being sent. In this case it will be "refund"
Id	String	Refund ID
CreatedAt	String	Timestamp of when the refund was created (ISO 8601 format). Possible formats: YYYY-MM-DDThh:mm:ss.ssssssZ (up to microseconds) YYYY-MM-DDThh:mm:ss.sssssssssZ (up to nanoseconds)
StatusCode	String	Status: accepted, succeeded, or failed
FinalizedAt	String	Timestamp of when the refund was finalized (ISO 8601 format). Possible formats: YYYY-MM-DDThh:mm:ss.ssssssZ (up to microseconds) YYYY-MM-DDThh:mm:ss.sssssssssZ (up to nanoseconds)
Type	String	Type of refund, always "full"
TxnId	String	Transaction ID of this refund object
AmountValue	Float	Refunded amount
AmountCurrency	String	Currency of the refund
OrderId	String	Unique order identifier from merchant
ResultCode	Integer	Indicates payment success (0 for success). 0: Success 431: Pending 216: Pending 481: Pending Others: Failure
Checksum	String	Checksum for validation

Checksum Generation

MD5(eventType + apiKey + txnId + orderId + resultCode + statusCode)

5. Testing in Sandbox

Refunds

1. Complete a payment in sandbox

2. Use the transaction ID to request a refund

3. Verify refund status using the retrieveRefund endpoint

4. Notify Codapay support to simulate final status if needed

Example Requests

Create Refund

curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/createRefund.json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "refundRequest": {
    "country": "360",
    "apiKey": "<test_key>",
    "txnId": "740976157910166864",
    "projectId": 43
  }
}'

Retrieve Refund

curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/retrieveRefund.json' \
--header 'Content-Type: application/json' \
--data '{
  "retrieveRefundRequest": {
    "country": "360",
    "apiKey": "<test_key>",
    "projectId": 43,
    "refundId": "rfl_sg1955a7330200033"
  }
}'