Overview Authentication Request Body Refund Reason Codes Code Examples Response Parameters Error Responses Important Notes

Refund

Initiate a full or partial refund for any successfully paid live transaction. Once submitted, the refund enters a refund-initiated state and is processed by OnePay's banking partner. Only one active refund request is allowed per transaction.

Full refund

Returns the entire transaction amount to the customer's card. Set is_partially to false and omit the amount field. OnePay uses the original transaction amount automatically.

Partial refund

Returns a specific portion of the transaction. Set is_partially to true and provide an amount. Useful for split-order cancellations and overcharge corrections.

POSThttps://api.onepay.lk/v3/transaction/refund/

AUTHENTICATION

HEADER	VALUE	REQUIRED
`Authorization`	Your merchant App Token	Yes
`Content-Type`	`application/json`	Yes

REQUEST BODY

PARAMETER	TYPE	DESCRIPTION
`app_id` required	string	Your App ID. Must belong to the same app identified by the `Authorization` token.
`onepay_transaction_id` required	string	The OnePay transaction ID to refund. Must be a successful, live transaction that belongs to your app.
`refund_reason` required	string	One of the predefined refund reason codes. See the Refund Reasons table below.
`is_partially` optional	boolean	`true` for a partial refund; `false` for a full refund. Defaults to `false`.
`amount` conditional	decimal	The partial refund amount. Required when `is_partially` is `true`. Ignored for full refunds.
`refund_note` optional	string	A free-text note describing the reason for this refund. Useful for internal records and customer service.

Refund reason codes

VALUE	DESCRIPTION
`DUPLICATED`	Transaction was a duplicate charge.
`FRAUDULENT`	Transaction was identified as fraudulent.
`OUT_OF_ORDER`	Service or product was unavailable or out of order.
`REQUESTED_BY_CUSTOMER`	Customer requested the refund directly.
`OTHER`	Any other reason. Use `refund_note` to provide detail.

Code examples

// Full refund
$ch = curl_init('https://api.onepay.lk/v3/transaction/refund/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: YOUR_APP_TOKEN',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'app_id'                => 'YOUR_APP_ID',
        'onepay_transaction_id' => 'ONP2026072800001',
        'is_partially'          => false,
        'refund_reason'         => 'REQUESTED_BY_CUSTOMER',
        'refund_note'           => 'Customer requested a full refund',
    ]),
]);
$res = json_decode(curl_exec($ch), true);

if ($res['status'] === 200) {
    update_order_status($res['data']['ipg_transaction_id'], 'REFUND INITIATED');
}

// Partial refund: add amount and set is_partially to true
// 'is_partially' => true, 'amount' => 500.00

RESPONSE PARAMETERS

FIELD	TYPE	DESCRIPTION
`status`	number	`200` on success.
`message`	string	`"Successfully initiated refund request"`
`data.ipg_transaction_id`	string	The OnePay transaction ID that was refunded.
`data.refund_id`	number	Unique identifier for this refund request. Store this for tracking.
`data.status`	string	`"refund-initiated"`. The transaction's status is updated to `REFUND INITIATED` at this point.
`data.is_partially`	boolean	Whether this was a partial refund.
`data.requested_amount`	string	The refund amount as a string. For full refunds, this is automatically set to the original transaction amount.
`data.refund_reason`	string	The reason code submitted with the request.

Error responses

STATUS	ERROR	CAUSE
401	`"Please provide request headers"`	The `Authorization` header is missing.
400	`"refund_reason: This field is required."`	The `refund_reason` field was omitted from the request body.
400	`"amount: Amount is required for a partial refund."`	`is_partially` was `true` but no `amount` was provided.
400	`"Invalid app credentials"`	The `app_id` does not match the app identified by the `Authorization` token.
400	`"Transaction not found"`	No matching transaction exists, or it belongs to a different app, or it is not a successful live transaction.
400	`"Refund already requested for this transaction"`	A refund has already been initiated for this transaction. Only one active refund is allowed per transaction.

Important notes

Live transactions only.

Refunds can only be initiated for transactions where both status = true (paid) and is_live = true. Test or sandbox transactions are not refundable via this endpoint.

One refund per transaction.

Only one active refund request is permitted per transaction. A subsequent refund attempt on the same transaction will be rejected until the existing refund record is resolved.

On This Page