Payment request

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)
amount	required	Integer	Payment amount	min: 10000
customer_phone_number	optional	String	Customer phone number	max: 20

Example Request

{
  "partner_ref_id": "igVSoghODYwBgJEbQdTj",
  "order_info": "Appota test",
  "terminal_id": "TID-5094322012",
  "payment_method": "QR",
  "amount": 12000,
  "customer_phone_number": "0989898657"
}

Response Params

Success

Http Status Code 200 - OK

Parameter	Data types	Description	Notes
transaction	Object	Transaction information
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)
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 is default)

Example Response Success

{
  "transaction": {
    "transaction_id": "01KFWSXKTKA645GHJMM27DWEBT",
    "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-01-26T16:24:49",
    "paid_at": ""
  },
  "payment_info": {
    "qr_content": "00020101021238630010A000000727013300069704320119MQQ0759866wrYqzPLw70208QRIBFTTA5204549953037045405120005802VN5916QRPAYMENT UAT 216011HO CHI MINH62430109wrYqzPLw70708Q07598660814AP26146183702063042A9D",
    "qr_url": "",
    "qr_type": "VIETQR"
  }
}

Failure

HTTP Status Code != 200

Parameter	Data type	Description
error_code	String	Error code
error_message	String	Error code description

Example

Code Example

curl --location 'https://pos-gw.dev.appotapay.com/api/v2/partner/orders/payment/create' \
  --header 'Content-Type: application/json' \
  --header 'X-AppotaPay-Auth: JWT_TOKEN' \
  --header 'X-Request-Id: Your_Unique_id' \
  --header 'X-Signature: Your signature' \
  -d '{
  "partner_ref_id": "igVSoghODYwBgJEbQdTj",
  "order_info": "Appota test",
  "terminal_id": "TID-5094322012",
  "payment_method": "QR",
  "amount": 12000,
  "customer_phone_number": "0989898657"
}'

Request

REQUEST

Base URL

https://pos-gw.dev.appotapay.com

Development server

Path

Auth REQUIRED

Bearer Token

Parameters

Body REQUIRED

Example (from schema)

{ "partner_ref_id": "igVSoghODYwBgJEbQdTj", "order_info": "Appota test", "terminal_id": "TID-5094322012", "payment_method": "QR", "amount": 12000, "customer_phone_number": "0989898657" }