Nhảy tới nội dung
Phiên bản: Lastest

API Yêu Cầu Thanh Toán

EndPoint​

POST /api/v2/partner/orders/payment/create

Header Params​

Tham sốYêu cầuKiểu dữ liệuMô tả
X-AppotaPay-AuthrequiredString Cách tạo JWT_TOKEN
Content-TyperequiredStringGiá trị: application/json
X-Request-IdrequiredStringĐịnh dạng UUIDv4. Request ID để kiểm tra yêu cầu khi xảy ra sự cố
X-SignaturerequiredString

- Signature được tạo bởi thuật toán HMAC SHA256

Ví dụ: Signature = HMAC_SHA256(body, SECRET_KEY) , body là JSON String được truyền vào Request

{
  "Content-Type": "application/json",
  "X-AppotaPay-Auth": "JWT_TOKEN",
  "X-Request-Id": "Your_Unique_id",
  "X-Signature": "Your Signature"
}

Request Params​

Tham sốYêu cầuKiểu dữ liệuMô tảLưu ý
partner_ref_idrequiredStringMã giao dịch tham chiếu của partner, unique (regex: a-z, A-Z, 0-9, _, -)max: 26
order_inforequiredStringThông tin đơn hàngmax: 100
terminal_idrequiredStringMã định danh thiết bị (cung cấp bởi AppotaPay)max: 20
payment_methodrequiredStringPhương thức thanh toán (POS, QR)
amountrequiredIntegerSố tiền thanh toánmin: 10000
customer_phone_numberoptionalStringSố điện thoại khách hàngmax: 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​

Thành công​

Http Status Code 200 - OK

Tham sốKiểu dữ liệuMô tảLưu ý
transactionObjectThông tin giao dịch
transaction.transaction_idStringMã giao dịch AppotaPay
transaction.partner_ref_idStringMã tham chiếu Partner
transaction.statusStringTrạng thái GD

pending = Giao dịch đang chờ xử lý.

processing = Giao dịch đang tiến hành xử lý.

success = Giao dịch thành công.

error = Giao dịch thất bại.

void = Giao dịch hoàn tiền.

transaction.amountIntegerSố tiền thanh toán
transaction.error_codeIntegerMã lỗi giao dịch (Lưu ý: chỉ trả về trong trường hợp status != success)
transaction.error_messageStringThông tin chi tiết trạng thái giao dịch (Lưu ý: chỉ trả về trong trường hợp status != success)
transaction.payment_methodStringPhương thức thanh toán
transaction.created_atStringThời gian tạo giao dịch (định dạng chuẩn ISO_8601)
transaction.paid_atStringThời gian thanh toán (định dạng chuẩn ISO_8601)
payment_infoObjectThông tin thanh toán (khi sử dụng phương thức thanh toán QR)
payment_info.qr_contentstringẢnh base64 QR thanh toán
payment_info.qr_urlstringLink QR thanh toán
payment_info.qr_typestringLink QR(mặc định VIETQR)

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

Thất bại​

HTTP Status Code != 200

Tham sốKiểu dữ liệuMô tả
error_codeStringMã lỗi
error_messageStringChi tiết mã lỗi

Ví dụ​

Ví dụ Code​

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

Development server
Example (from schema)