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-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "X-Language": "vi"
}

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

Response

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"
    }
  ]
}

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