Payment request
Payment request
Chat with AI▼
EndPoint
POST /api/v2/partner/orders/payment/create
Header Params
| Parameter | Requirement | Data types | Description |
|---|---|---|---|
| X-AppotaPay-Auth | required | String | How to generate a JWT_TOKEN |
| Content-Type | required | String | Value: application/json |
| X-Request-Id | required | String | UUIDv4 format. Request ID is used to trace and verify the request in case of issues. |
| X-Signature | required | String | - The signature is generated using the HMAC SHA256 algorithm. Ex: Signature = HMAC_SHA256(body, SECRET_KEY) , body: JSON string passed in the request. |
{
"Content-Type": "application/json",
"X-AppotaPay-Auth": "JWT_TOKEN",
"X-Request-Id": "Your_Unique_id",
"X-Signature": "Your Signature"
}
Request Params
| Requirement | Requirement | Data types | Description | Notes |
|---|---|---|---|---|
| partner_ref_id | required | String | Partner reference transaction ID, unique (regex: a-z, A-Z, 0-9, _, -) | max: 26 |
| order_info | required | String | Order information | max: 100 |
| terminal_id | required | String | Terminal ID (provided by AppotaPay) | max: 20 |
| payment_method | required | String | Payment methods (POS, QR) | |
| feature_code | optional | String | Feature code: Set the value to QR_PAY when using QR PAY | |
| amount | required | Integer | Payment amount | min: 10000 |
| customer_phone_number | optional | String | Customer phone number | max: 20 |
Example Request
// Example: Creating a Card Swipe Payment
{
"partner_ref_id": "hadjUBSDjbfjaBBFNM",
"order_info": "Appota test Card swipe",
"terminal_id": "TID-5094322012",
"payment_method": "POS",
"amount": 12000,
"customer_phone_number": "0989898657"
}
// Example: Creating a QR Code Payment
{
"partner_ref_id": "igVSoghODYwBgJEbQdTj",
"order_info": "Appota test QR Code",
"terminal_id": "TID-5094322012",
"payment_method": "QR",
"amount": 12000,
"customer_phone_number": "0989898657"
}
// Example: Creating a QR Pay Payment
{
"partner_ref_id": "kdsvjhdbsAHHfbafbch",
"order_info": "Appota test QR PAY",
"terminal_id": "TID-5094322012",
"payment_method": "QR",
"feature_code": "QR_PAY",
"amount": 12000,
"customer_phone_number": "0989898657"
}
Response Params
Success
Http Status Code
200-OK
| Parameter | Data types | Description | Notes |
|---|---|---|---|
| transaction | Object | Transaction information | |
| transaction.order_id | String | Order ID generated by AppotaPay | |
| transaction.transaction_id | String | Transaction ID AppotaPay | |
| transaction.partner_ref_id | String | Partner reference transaction ID | |
| transaction.status | String | Transaction status | pending = The transaction is pending. processing = The transaction is being processed. success = The transaction is successful. error = The transaction has failed. void = The transaction has been refunded. |
| transaction.amount | Integer | Transaction amount | |
| transaction.error_code | Integer | Transaction error code (Note: returned only if status != success) | |
| transaction.error_message | String | Transaction status details (Note: returned only if status != success) | |
| transaction.payment_method | String | Payment methods | |
| transaction.created_at | String | Transaction creation time (ISO 8601 format) | |
| transaction.paid_at | String | Transaction payment time (ISO 8601 format) | |
| transaction.updated_at | String | Transaction update time (ISO 8601 format) | |
| transaction.is_sett | Boolean | Settlement status | |
| payment_info | Object | Payment information (when using the QR payment method) | |
| payment_info.qr_content | string | Base64-encoded QR payment image | |
| payment_info.qr_url | string | QR payment link | |
| payment_info.qr_type | string | QR Link: VIETQR for QR Code or VIETQR_PAY for QR PAY |
Example Response Success
// Example Response: Card Swipe Payment
{
"transaction": {
"order_id": "711773203426177024",
"transaction_id": "01M5NX632VNDEGJX3KJXPAHKKX",
"partner_ref_id": "hadjUBSDjbfjaBBFNM",
"status": "pending",
"amount": 12000,
"error_code": "34",
"error_message": "Giao dịch đang chờ xử lý",
"payment_method": "POS",
"created_at": "2026-10-24T09:52:35",
"paid_at": "",
"is_sett": false,
"updated_at": "2026-10-24T09:52:35"
},
"payment_info": {
"qr_content": "",
"qr_url": "",
"qr_type": ""
}
}
// Example Response: QR Code Payment
{
"transaction": {
"order_id": "711773778087768064",
"transaction_id": "01M5NXA9RR4F5N4SH02XWYKKQK",
"partner_ref_id": "igVSoghODYwBgJEbQdTj",
"status": "pending",
"amount": 12000,
"error_code": "34",
"error_message": "Giao dịch đang chờ xử lý",
"payment_method": "QR",
"created_at": "2026-10-24T09:54:52",
"paid_at": "",
"is_sett": false,
"updated_at": "2026-10-24T09:54:53"
},
"payment_info": {
"qr_content": "00020101021238590010A0000007270129000697041801159630120002883540208QRIBFTTA53037045802VN54051300262540309APPOTAPAY0823Tran ref AP2614682244480910DYNAMIC_QR6304FD06",
"qr_url": "",
"qr_type": "VIETQR"
}
}
// Example Response: QR Pay Payment
{
"transaction": {
"order_id": "711773569622470656",
"transaction_id": "01M5NX8SDD692V05B0X0KX7FHR",
"partner_ref_id": "kdsvjhdbsAHHfbafbch",
"status": "pending",
"amount": 12000,
"error_code": "34",
"error_message": "Giao dịch đang chờ xử lý",
"payment_method": "QR",
"created_at": "2026-10-24T09:54:03",
"paid_at": "",
"is_sett": false,
"updated_at": "2026-10-24T09:54:04"
},
"payment_info": {
"qr_content": "00020101021238630010A00000072701330006971031011912073010900000040250208QRIBFTTA5204581253037045405130025802VN5905CTEST6015ARAGATSOTN REGI626501187117735696224706560514AP2614682243790821UPDATE API PARTNER V263041CF8",
"qr_url": "",
"qr_type": "VIETQR_PAY"
}
}
Failure
HTTP Status Code !=
200
| Parameter | Data type | Description |
|---|---|---|
| error_code | String | Error code |
| error_message | String | Error code description |