Refund transaction

Endpoint: POST /api/v2/transaction/refund

Header Params

Params	Requirement	Data type	Description	Note
X-APPOTAPAY-AUTH	required	String	To create a JWT_TOKEN
Content-Type	required	String	Value: application/json
X-Request-ID	optional	String	Format is UUIDv4. Request ID for troubleshooting purposes	max:40
X-Language	optional	String	Value vi or en,The value corresponding to the payment link can be in Vietnamese or English (default: vi)	in:vi,en
X-Account-Ref-ID	optional	String	Iidentifier of the sub account provided by AppotaPay. Mandatory be passed over when processing payment for transactions of owner-type sub account

{
    "X-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "X-Language": "vi",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Params

Params	Requirement	Data type	Description	Format
partnerRefId	required	String	The partner's transaction reference code for AppotaPay (must be unique)	max:50,alphanumeric
transactionId	required	String	The payment transaction code returned from AppotaPay	alphanumeric
amount	required	Integer	The refunded amount	min:1000
currency	required	String	Currency unit (accepts VND)	in:VND
reason	required	String	Reason for refund	max:100,alphanumeric

Response

Params	Requirement	Data type	Description
refundId	required	String	Refund transaction code on AppotaPay's side
transactionId	required	String	Payment transaction code on AppotaPay's side
partnerRefId	required	String	Partner's refund transaction reference code
amount	required	Integer	The refunded amount
currency	required	String	Currency unit (accepts VND)
reason	required	String	Reason for refund
status	required	String	Refund status
createdAt	required	String	Transaction execution time. (in RFC-3339 standard format)
refundedAt	optional	String	Refund execution time if the refund transaction is successful. (in RFC-3339 standard format)

Refund transaction status code table

Status	Description
pending	Payment transactions do not support automatic refunds. AppotaPay will receive and manually process refund requests within 1 day. Partners can call the API to check the transaction status. If after 1 day the transaction has not changed to its final status (success, error), please contact customer support for assistance
processing	Payment transactions support automatic refunds. AppotaPay receives and is processing the refund request. Partners can call the API to check the transaction status. If after 1 day the transaction has not changed to its final status (success, error), please contact customer support for assistance.
success	Refund transaction successful.
error	Refund transaction failed.

Example

Request

{
    "partnerRefId": "5f61cf4f41e2b",
    "transactionId": "AP241453209745",
    "amount": 10000,
    "currency": "VND",
    "reason": "test refund"
}

Response

{
    "refundId": "f28a4ac3-e407-45f1-902b-bc05c6c50dfa",
    "transactionId": "AP241453209745",
    "partnerRefId": "5f61cf4f41e2b",
    "amount": 10000,
    "currency": "VND",
    "reason": "test refund",
    "status": "success",
    "createdAt": "2024-09-11T11:21:17+07:00",
    "refundedAt": ""
}

Error

HTTP Status Code != 200 With the returned errorCode, please refer to the error code table here

Error response params

Params	Requirement	Data type	Description
errorCode	required	Integer	error code
message	required	String	Error description
errors	optional	Array of Object	Detailed error description of each field if available
errors.field	required	Object	Field with error
errors.reason	required	Object	Description of the field with error

{
  "errorCode": 1,
  "message": "Invalid Params",
  "errors": [
    {
      "field": "transaction.amount",
      "reason": "Field amount is required"
    },
    {
      "field": "transaction.currency",
      "reason": "Field currency is required"
    }
  ]
}

List of suppliers supporting refunds

Vendor code	Refund support time	Auto via API	Partial refund	Refund many times	Full refund	Time the user receives money
Napas	1 year	Yes	Yes	Yes		5 - 7 working days
Vpbank Visa - Mastercard	6 months	Yes	Yes	Yes		10 - 15 working days
VnptPay		Yes	No	No	Yes
ONEPAY			No	No
EBILL			No	No
SHOPEE	90 days	Yes	Yes	Yes	Yes	Real time
MOCA	1 month	Yes	No	No	Yes	Real time
APPOTA WALLET		Yes	No	No	Yes	Real time
ZaloPay	180 days	Yes	Yes	Yes	Yes	Real time
VA		No	No	No
VNpay		Yes	Yes	No
Cybersource	No	No	No	No	No	No

Error code table

Error code	Description
1	Missing or invalid request information
31	Duplicated transaction code
36	The transaction does not exist
129	Please wait {times} to create a new refund request.
135	The transaction does not support refunds
401	Unauthorized
500	The system encountered an error, please try again later