Payment Confirmation API

The API used to authenticate payment transactions in cases where multi-factor authentication is required

EndPoint

POST /api/v2/ewallet/payment/confirm

Header Params

Parameters	Requirement	Data type	Description	Note
X-APPOTAPAY-AUTH	required	String	To create a JWT_TOKEN
Authorization	required	String	User Access Token
Content-Type	required	String	Value: application/json
X-Request-ID	optional	String	Format is UUIDv4. Request ID for troubleshooting purposes	max:42
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": "Bearer JWT_TOKEN",
  "Authorization": "Bearer ACCESS_TOKEN",
  "Content-Type": "application/json",
  "X-Request-ID": "Your_Unique_id",
  "X-Language": "vi",
  "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Request Params

Parameters	Requirement	Data type	Description	Note
orderId	required	String	Partner's orderId
verificationMethod	required	String	The authentication method (OTP) received at the verificationMethod field Payment Request API	Value: OTP, NONE
verificationCode	required	String	Verification code (OTP)	min:1, max: 10
signature	required	String	Data verification signature	signature = hash_hmac('sha256', 'orderId={orderId}&verificationCode={verificationCode}' , SECRET_KEY))

Example Request

{
  "orderId": "241698338917842945",
  "verificationMethod": "OTP",
  "verificationCode": "123456",
  "signature": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
}

Response Params

{
  "transaction": {
    "orderId": "123728435",
    "partnerCode": "TEST",
    "transactionId": "233728435",
    "status": "success",
    "amount": 120000,
    "currency": "VND",
    "orderVersion": "1.0",
    "createdAt": "2024-01-29T11:36:03+07:00",
    "updatedAt": "2024-01-29T11:36:03+07:00"
  }
}

Success

Http Status Code 200 - OK

Parameters	Data type	Description	Note
transaction	Object	Transaction information
transaction.transactionId	String	Transaction code from AppotaPay
transaction.partnerCode	String	Partner code
transaction.orderId	Integer	Partner's order code
transaction.status	String	Transaction status	pending = Transaction pending. processing = Transaction processing. success = Transaction success. error = Transaction error.
transaction.amount	Integer	Payment amount
transaction.currency	String	Currency unit
transaction.orderVersion	String	Payment version
transaction.errorCode	Integer	Error code (returned only when status != success)
transaction.errorMessage	String	Detailed error code information (returned only when status != success)
transaction.createdAt	String	Transaction creation time (in RFC-3339 standard format)
transaction.updatedAt	String	Transaction update time (in RFC-3339 standard format)

Error

HTTP Status Code != 200

Parameters	Data type	Description
errorCode	Integer	Error code
message	String	Description about the error

Common error code table

The full error code is available, please see tại đây

Error code	Description
1	Request information missing or invalid
2	The signature parameter is incorrect.
21	The OTP code is incorrect.
22	The OTP code has expired, please perform the transaction again.
33	Transaction failed.
34	The transaction is being processed, please check again later.
36	The transaction does not exist.
39	The user has entered the OTP code incorrectly too many times.
40	The transaction has been refunded.
41	The transaction was successful previously.
42	The request to obtain the OTP code has exceeded the specified number of attempts
52	Invalid payment method
70	You have exceeded the daily transaction limit, please try again later.
75	Insufficient funds for payment
94	The system is under maintenance, please try again later.
99	Unknown error, please check the transaction again later
162	You have exceeded the monthly transaction limit, please try again later.
401	Authentication error
500	The system encountered an error, please try again later.