Kết nối thanh toán

Api kết nối thanh toán

Chat với AI▼

Thanh toán ATM/Visa/Mastercard có hỗ trợ thanh toán lưu token (lưu thông tin thẻ cho các lần thanh toán sau)

(chỉ hỗ trợ 1 số provider)

EndPoint

POST /api/v2/orders/payment

Header Params

Tham số	Yêu cầu	Kiểu dữ liệu	Mô tả	Lưu ý
X-APPOTAPAY-AUTH	required	String	Cách tạo JWT_TOKEN
Content-Type	required	String	Giá trị: application/json
X-Request-ID	optional	String	Định dạng UUIDv4. Request ID để kiểm tra yêu cầu khi xảy ra sự cố	max:42
X-Language	optional	String	Giá trị vi hoặc en tương ứng với link thanh toán sẽ là tiếng việt hoặc tiếng anh, (mặc định: vi)	in:vi,en
X-MC-Category-Code	optional	String	Mã ngành phía AppotaPay cung cấp cho Partner
X-Account-Ref-ID	optional	String	Mã định danh của tài khoản Sub account do AppotaPay cung cấp. Bắt buộc truyền khi thanh toán giao dịch của Sub account loại owner

{
    "X-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "X-Language": "vi",
    "X-MC-Category-Code": "1234",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Request Params

Tham số	Yêu cầu	Kiểu dữ liệu	Mô tả	Lưu ý
transaction	required	Object	Thông tin giao dịch
transaction.amount	required	Integer	Số tiền thanh toán
transaction.currency	required	String	Đơn vị tiền tệ (VND)	Chấp nhận: VND
transaction.bankCode	optional	String	Tham khảo Bảng mã Ngân hàng
transaction.paymentMethod	required	String	Tham khảo Bảng mã phương thức thanh toán
transaction.action	required	String	Hành động thanh toán muốn thực hiện
transaction.token	optional	String	Token sử dụng để thanh toán (trong trường hợp dùng token)
partnerReference	required	Object	Thông tin phía đối tác
partnerReference.order.id	required	String	Mã đơn hàng phía đối tác	50
partnerReference.order.info	required	String	Thông tin đơn hàng (tối đa 150 kí tự)	150
partnerReference.order.extraData	optional	String	Thông tin tuỳ chọn bổ sung	200
partnerReference.notificationConfig.notifyUrl	required	String	URL nhận kết quả giao dịch	100
partnerReference.notificationConfig.redirectUrl	required	String	URL chuyển hướng trên trình duyệt	100
partnerReference.notificationConfig.deeplinkUrl	optional	String	URL chuyển hướng đến app nếu thanh toán bằng app mobile	100
partnerReference.notificationConfig.installmentNotifyUrl	optional	String	IPN thông báo giao dịch chuyển đổi trả góp	100

Example Request

{
  "transaction": {
    "amount": 10000,
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY"
  },
  "partnerReference": {
    "order": {
      "id": "5f61cf4f41e2b",
      "info": "test thanh toan",
      "extraData": ""
    },
    "notificationConfig": {
      "notifyUrl": "https://devtool.vn/ipn",
      "redirectUrl": "https://devtool.vn/redirect",
      "installmentNotifyUrl": "https://devtool.vn/redirect"
    }
  }
}

Response Params

Tham số	Yêu cầu	Kiểu dữ liệu	Mô tả
transaction	required	Object	Thông tin giao dịch
transaction.transactionId	required	String	Mã giao dịch phía Appotapay
transaction.status	required	String	Trạng thái giao dịch
transaction.errorCode	required	Integer	Bảng mã lỗi
transaction.errorMessage	required	String	Mô tả lỗi
transaction.partnerCode	required	String	Mã đối tác
transaction.orderAmount	required	Integer	Số tiền thanh toán (Min: 1000, Max: 500000000)
transaction.currency	required	String	Đơn vị tiền tệ
transaction.bankCode	required	String	Mã Ngân hàng khách hàng đã chọn
transaction.paymentMethod	required	String	Phương thức thanh toán
transaction.action	required	String	Loại thanh toán
transaction.createdAt	required	String	Thời gian tạo giao dịch. (định dạng chuẩn RFC-3339)
transaction.updatedAt	required	String	Thời gian cập nhật giao dịch. (định dạng chuẩn RFC-3339)
payment	required	Object
payment.url	required	String	URL thanh toán, tham số lang trên link thanh toán có thể thay đổi thành vi hoặc en tương ứng với ngôn ngữ khách hàng mong muốn
payment.qrCode	optional	Object	Trả về trong trường hợp thanh toán có QR code
payment.qrCode.url	optional	String	URL QR thanh toán
payment.qrCode.content	optional	String	QR content để tạo mã QR thanh toán
payment.qrCode.expiry	optional	String	Thời gian hết hạn thanh toán QR. (định dạng chuẩn RFC-3339)
payment.deepLinkUrl	optional	String	Liên kết mở app thanh toán nếu có

Thành công

Http Status Code 200 - OK

{
  "transaction": {
    "transactionId": "AP123",
    "status": "pending",
    "errorCode": 35,
    "errorMessage": "Giao dịch đang chờ xử lý",
    "partnerCode": "TEST",
    "orderAmount": 10000,
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY",
    "createdAt": "2024-04-01T14:46:20.000",
    "updatedAt": "2023-04-01T14:46:20.000"
  },
  "payment": {
    "url": "https://payment.dev.appotapay.com/v2/bank/payment/process?tran=dGlkPUFQMjMxNDQwNDkwODI0Jm9yZGVySWQ9YVY2a01uakR2JnRzPTE2OTkyMzYwNTQ&sign=bfff37df0d919ac1ea9d7163934bbc8ce785c6bbf7a210fb12696c8e531532ed&lang=vi",
    "qrCode": null,
    "deepLinkUrl": ""
  }
}

Thất bại

HTTP Status Code != 200 Với errorCode trả về, vui lòng tham khảo bảng mã lỗi tại đây

Error response params

Tham số	Yêu cầu	Kiểu dữ liệu	Mô tả
errorCode	required	Integer	Mã lỗi
message	required	String	Mô tả lỗi
errors	optional	Array of Object	Mô tả lỗi chi tiết các trường nếu có
errors.field	required	Object	Trường dữ liệu bị lỗi
errors.reason	required	Object	Mô tả trường dữ liệu bị lỗi

{
  "errorCode": 1,
  "message": "Invalid Params",
  "errors": [
    {
      "field": "transaction.amount",
      "reason": "Field amount is required"
    },
    {
      "field": "transaction.currency",
      "reason": "Field currency is required"
    }
  ]
}

Bảng mã lỗi

Mã lỗi	Mô tả
1	Thông tin yêu cầu thiếu hoặc không hợp lệ
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ệ
140	Partner không có quyền sử dụng paymentMethod
141	Partner không có quyền sử dụng bankCode
500	Hệ thống gặp lỗi, vui lòng thử lại sau

Ví dụ Code

curl -X POST "https://gateway.dev.appotapay.com/api/v2/orders/payment" \
  -H "X-APPOTAPAY-AUTH: JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: Your_Unique_id" \
  -H "X-Language: vi" \
  -d '{
  "transaction": {
    "amount": 10000,
    "currency": "VND",
    "bankCode": "VCB",
    "paymentMethod": "ATM",
    "action": "PAY"
  },
  "partnerReference": {
    "order": {
      "id": "5f61cf4f41e2b",
      "info": "test thanh toan",
      "extraData": ""
    },
    "notificationConfig": {
      "notifyUrl": "https://devtool.vn/ipn",
      "redirectUrl": "https://devtool.vn/redirect",
      "installmentNotifyUrl": "https://devtool.vn/redirect"
    }
  }
}'

Request

REQUEST

Base URL

https://gateway.dev.appotapay.com

Development server

Path

Auth REQUIRED

Bearer Token

X-Language — header

vien

Giá trị tương ứng với payment link có thể là tiếng Việt hoặc tiếng Anh (mặc định: vi)

Body REQUIRED

Example (from schema)

{ "transaction": { "amount": 10000, "currency": "VND", "bankCode": "VCB", "paymentMethod": "ATM", "action": "PAY" }, "partnerReference": { "order": { "id": "5f61cf4f41e2b", "info": "test thanh toan", "extraData": "" }, "notificationConfig": { "notifyUrl": "https://devtool.vn/ipn", "redirectUrl": "https://devtool.vn/redirect", "installmentNotifyUrl": "https://devtool.vn/redirect" } } }