API Request Payment

EndPoint

POST /api/v2/ewallet/payment

Header Params

Parameters	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: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	Reference transaction code	max: 50, alphanumeric
orderInfo	required	String	Order information	max: 150, alphanumeric
extraData	optional	String	Additional information	max: 1000
amount	required	Integer	The payment amount	min: 1000, max: 500000000
currency	required	String	The currency unit	Value: VND
signature	required	String	Signature for data verification	signature = hash_hmac('sha256', 'amount={amount}&currency={currency}&extraData={extraData}&orderId={orderId}&orderInfo={orderInfo}' , SECRET_KEY).

Example Request

{
  "orderId": "123",
  "orderInfo": "test",
  "amount": 120000,
  "currency": "VND",
  "extraData": "test",
  "signature": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
}

Response Params

{
  "transaction": {
    "orderId": "123728435",
    "partnerCode": "TEST",
    "transactionId": "233728435",
    "status": "success",
    "amount": 120000,
    "currency": "VND",
    "orderVersion": "1.0",
    "verificationMethod": "NONE",
    "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	The transaction code from AppotaPay
transaction.partnerCode	String	Partner code
transaction.orderId	Integer	The partner's order code
transaction.status	String	Transaction status	pending = Transaction pending. processing = Transaction processing. success = Transaction success. error = Transaction error.
transaction.amount	Integer	The payment amount
transaction.currency	String	The currency unit
transaction.orderVersion	String	The payment version
transaction.errorCode	Integer	Error code (only returned when status != success)
transaction.errorMessage	String	Details of the error code (only returned when status != success)
transaction.verificationMethod	String	Authentication method (only returned when status != error)	Value: OTP, NONE
transaction.createdAt	String	The transaction creation time (in RFC-3339 standard format)
transaction.updatedAt	String	The 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.
30	Mã đơn hàng đã bị trùng, vui lòng thực hiện lại giao dịch
32	Số tiền không hợp lệ
33	Transaction failed.
34	The transaction is being processed, please check again later.
52	Invalid payment method
70	You have exceeded the daily transaction limit, please try again later.
75	Insufficient funds for payment
84	The transaction amount exceeds the allowed limit, please contact support for assistance.
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.