Refund API

POST

/api/merchant-portal/merchant-access/online-transaction/refund

You can use the Refund API to issue full or partial refunds within 30 days after the transaction was created. ABA PAY and KHQR refunds are immediate, while Card, WeChat, and Alipay refunds follow your agreement with PayWay. This API works both for instore transaction and online transaction.

Eligible Transactions: Only transactions with a status of COMPLETED can be refunded.

Time Frame: Refunds must be requested within 30 days of the payment created date.

Pending Settlements: Refunds can be issued even if the settlement is still pending (Alipay, WeChat, Card).

Partial Refunds: Multiple partial refunds can be issued until the total amount paid is refunded.

Rate limit: Request limit 500 reqeusts/second

Request

Header Params

Content-Type

string

required

Example:

application/json

Body Params application/json

request_time

string

required

Request date and time in UTC format as YYYYMMDDHHmmss.

merchant_id

string

required

A unique merchant key which provided by ABA Bank.

<= 20 characters

merchant_auth

string

required

The JSON-encoded object containing mc_id, tran_id, and refund_amount using RSA public key encryption in chunks. The encrypted data is then concatenated and encoded in Base64 format.

mc_id string mandatory
A unique merchant key which provided by ABA Bank. Same value as merchant_id

tran_id string mandatory
Purcahse transaction id to refund.

refund_amount decimal mandatory
Amount to refund back to payer.

PHP Sample Code

hash

string

required

Base64 encode of hash hmac sha512 encryption of concatenates values request_time, merchant_id and merchant_auth with public_key.

PHP Sample Code

Example

{
    "request_time": "20200728093403",
    "merchant_id": "ec000002",
    "merchant_auth": "884113079983a...2c3e460be35f2a3",
    "hash": "3nd/2Z4g45...wnA2WA/M/Qg=="
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST '/api/merchant-portal/merchant-access/online-transaction/refund' \
--header 'Content-Type: application/json' \
--data-raw '{
    "request_time": "20200728093403",
    "merchant_id": "ec000002",
    "merchant_auth": "884113079983a...2c3e460be35f2a3",
    "hash": "3nd/2Z4g45...wnA2WA/M/Qg=="
}'

Responses

🟢200OK

application/json

Body

grand_total

number <double>

optional

Example: A customer pays 20USD by card. A 2USD discount is applied, so the final amount is 18USD.

total_refunded

number <double>

optional

Total of refunded amount. If the purchase transactions has refunded 3 times, and each time was 1USD, to total_refunded = 3USD.

currency

string

optional

Original currency of the transaction.

transaction_status

string

optional

Either it's full refund or partial refund the status here is REFUNDED

status

object

optional

code

string

optional

00 : Success

PTL02 : Invalid hash

PTL04 : Parameter validation required

PTL05 : Parameter invalid format

PTL06 : The request_time value is missing or incorrectly formatted.

PTL37 : Refund amount cannot exceed the original purchase amount.

PTL57 : Unable to refund

PTL58 : Fail to refund

PTL62 : Invalid merchant information

PTL63 : Merchant have no security config file

PTL168 : Concurrent requests are not allowed for this operation. Please try again in a few seconds

PTL169 : The merchant profile cannot accept payment because its settlement account is closed

PTL181 : The available balance is not enough to refund the customer

PTL186 : Invalid amount format

PTL187 : Amount is below the minimum allowed

message

string

optional

Please see the property reponse code for the details.

Examples

SuccessException

{
    "grand_total": 1.5,
    "total_refunded": 0.09,
    "currency": "USD",
    "transaction_status": "REFUNDED",
    "status": {
        "code": "00",
        "message": "Success!"
    }
}

Check transaction

Get transaction list