payOS API (latest)

payOS support: [email protected] URL: https://payos.vn Terms of Service

Danh sách các API payOS hỗ trợ.

Trước khi bắt đầu

Bạn đã tạo một tài khoản https://my.payos.vn.
Bạn đã xác thực một doanh nghiệp hoặc cá nhân trên https://my.payos.vn, xem hướng dẫn
Bạn đã tạo một kênh thanh toán, xem hướng dẫn.

Môi trường

Production: https://api-merchant.payos.vn

Đăng ký chương trình đối tác tích hợp payOS Tại đây

Link thanh toán

Tạo link thanh toán

API dùng để tạo link thanh toán đơn hàng

Authorizations:

(x-client-idx-api-key)

header Parameters

x-partner-code

string

Partner Code tham gia chương trình tích hợp đối tác payOS Tại đây

Request Body schema: application/json

orderCode required	integer Mã đơn hàng
amount required	integer Số tiền thanh toán
description required	string Mô tả thanh toán, với tài khoản ngân hàng không phải liên kết qua payOS thì giới hạn ký tự là 9
buyerName	string Tên của người mua hàng. Thông tin dùng trong trường hợp tích hợp tạo hoá đơn điện tử.
buyerCompanyName	string Tên đơn vị mua hàng. Thông tin dùng trong trường hợp tích hợp tạo hoá đơn điện tử.
buyerTaxCode	string Mã số thuế của đơn vị mua hàng. Thông tin dùng trong trường hợp tích hợp tạo hoá đơn điện tử.
buyerAddress	string Địa chỉ của đơn vị mua hàng. Thông tin dùng trong trường hợp tích hợp tạo hoá đơn điện tử.
buyerEmail	string <email> Email của người mua hàng. Thông tin dùng trong trường hợp tích hợp tạo hoá đơn điện tử.
buyerPhone	string Số điện thoại người mua hàng. Thông tin dùng trong trường hợp tích hợp tạo hoá đơn điện tử.
	Array of objects Danh sách các sản phẩm thanh toán
cancelUrl required	string <uri> URL nhận dữ liệu khi người dùng chọn Huỷ đơn hàng.
returnUrl required	string <uri> URL nhận dữ liệu khi đơn hàng thanh toán thành công
	object Thông tin hóa đơn
expiredAt	number <timestamp> Thời gian hết hạn của link thanh toán, là Unix Timestamp và kiểu Int32
signature required	string Chữ ký kiểm tra thông tin không bị thay đổi trong qua trình chuyển dữ liệu từ hệ thống của bạn sang payOS. Bạn cần dùng checksum key từ Kênh thanh toán và HMAC_SHA256 để tạo signature và data theo định dạng được sort theo alphabet: `amount=$amount&cancelUrl=$cancelUrl&description=$description&orderCode=$orderCode&returnUrl=$returnUrl`.

Responses

Request samples

Payload

Content type

application/json

{"orderCode": 0,
"amount": 0,
"description": "string",
"buyerName": "string",
"buyerCompanyName": "string",
"buyerTaxCode": "string",
"buyerAddress": "string",
"buyerEmail": "[email protected]",
"buyerPhone": "string",
"items": [{"name": "string",
"quantity": 0,
"price": 0,
"unit": "string",
"taxPercentage": -2
}
],
"cancelUrl": "http://example.com",
"returnUrl": "http://example.com",
"invoice": {"buyerNotGetInvoice": true,
"taxPercentage": -2
},
"expiredAt": 0,
"signature": "string"
}

Response samples

200
401

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "success",
"data": {"bin": "string",
"accountNumber": "string",
"accountName": "string",
"currency": "string",
"paymentLinkId": "string",
"amount": 0,
"description": "string",
"orderCode": 0,
"expiredAt": 0,
"status": "PAID",
"checkoutUrl": "http://example.com",
"qrCode": "string"
},
"signature": "string"
}

Lấy thông tin link thanh toán

API dùng để lấy thông tin của link thanh toán

Lưu ý: Hiện tại thông tin tài khoản đối ứng trong các trường counterAccount chỉ được hỗ trợ bởi các ngân hàng sau:

MB Bank
ACB
KienlongBank

Authorizations:

(x-client-idx-api-key)

path Parameters

id

required

number or string

Example: 3019

Mã đơn hàng của cửa hàng hoặc mã link thanh toán của payOS

Responses

Response samples

200
401

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "success",
"data": {"id": "string",
"orderCode": 0,
"amount": 0,
"amountPaid": 0,
"amountRemaining": 0,
"status": "PAID",
"createdAt": "2019-08-24T14:15:22Z",
"transactions": [{"amount": 0,
"description": "string",
"accountNumber": "string",
"reference": "string",
"transactionDateTime": "2019-08-24T14:15:22Z",
"counterAccountBankId": "string",
"counterAccountBankName": "string",
"counterAccountName": "string",
"counterAccountNumber": "string",
"virtualAccountName": "string",
"virtualAccountNumber": "string"
}
],
"canceledAt": "2019-08-24T14:15:22Z",
"cancellationReason": "string"
},
"signature": "string"
}

Huỷ link thanh toán

API dùng để hủy link thanh toán

Authorizations:

(x-client-idx-api-key)

path Parameters

id

required

number or string

Example: 3019

Mã đơn hàng của cửa hàng hoặc mã link thanh toán của payOS

Request Body schema: application/json

cancellationReason

string

Responses

Request samples

Payload

Content type

application/json

{"cancellationReason": "Changed my mind"
}

Response samples

200
401

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "success",
"data": {"id": "string",
"orderCode": 0,
"amount": 0,
"amountPaid": 0,
"amountRemaining": 0,
"status": "PAID",
"createdAt": "2019-08-24T14:15:22Z",
"transactions": [{"amount": 0,
"description": "string",
"accountNumber": "string",
"reference": "string",
"transactionDateTime": "2019-08-24T14:15:22Z",
"counterAccountBankId": "string",
"counterAccountBankName": "string",
"counterAccountName": "string",
"counterAccountNumber": "string",
"virtualAccountName": "string",
"virtualAccountNumber": "string"
}
],
"canceledAt": "2019-08-24T14:15:22Z",
"cancellationReason": "string"
},
"signature": "string"
}

Lấy thông tin hóa đơn

API dùng để lấy thông tin hóa đơn của link thanh toán

Authorizations:

(x-client-idx-api-key)

path Parameters

id

required

number or string

Example: 3019

Mã đơn hàng của cửa hàng hoặc mã link thanh toán của payOS

Responses

Response samples

200
401

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "success",
"data": {"invoices": [{"invoiceId": "string",
"invoiceNumber": "string",
"issuedTimestamp": 0,
"issuedDatetime": "2019-08-24T14:15:22Z",
"transactionId": "string",
"reservationCode": "string",
"codeOfTax": "string"
}
]
},
"signature": "string"
}

Tải hóa đơn

API dùng để lấy tải hóa đơn của link thanh toán

Authorizations:

(x-client-idx-api-key)

path Parameters

id required	number or string Example: 3019 Mã đơn hàng của cửa hàng hoặc mã link thanh toán của payOS
invoice-id required	string Example: 3733ea88-5131-429c-8863-6ee986133fa8 Mã hóa đơn của link thanh toán

Responses

Response samples

200
401

Content type

application/pdf

PDF file content

Webhook thanh toán

Webhook nhận thông tin thanh toán Webhook

Webhook của cửa hàng dùng để nhận dữ liệu thanh toán từ payOS, Dữ liệu mẫu

Request Body schema: application/json

code required	string Mã lỗi
desc required	string Thông tin lỗi
success required	boolean
required	object
signature required	string Chữ kí để kiểm tra thông tin, chi tiết dữ liệu mẫu

Responses

Request samples

Payload

Content type

application/json

{"code": "00",
"desc": "success",
"success": true,
"data": {"orderCode": 123,
"amount": 3000,
"description": "VQRIO123",
"accountNumber": "12345678",
"reference": "TF230204212323",
"transactionDateTime": "2023-02-04 18:25:00",
"currency": "VND",
"paymentLinkId": "124c33293c43417ab7879e14c8d9eb18",
"code": "00",
"desc": "Thành công",
"counterAccountBankId": "",
"counterAccountBankName": "",
"counterAccountName": "",
"counterAccountNumber": "",
"virtualAccountName": "",
"virtualAccountNumber": ""
},
"signature": "8d8640d802576397a1ce45ebda7f835055768ac7ad2e0bfb77f9b8f12cca4c7f"
}

Kiểm tra và thêm hoặc cập nhật Webhook url

API dùng để xác thực webhook url của một kênh thanh toán đồng thời thêm hoặc cập nhật webhook url cho Kênh thanh toán đó nếu thành công.

Authorizations:

(x-client-idx-api-key)

Request Body schema: application/json

webhookUrl

required

string

Đường dẫn webhook nhận dữ liệu ngân hàng từ payOS của bạn, lưu ý: payOS.vn sẽ gửi một dữ liệu mẫu kèm thông tin giao dịch ngân hàng mẫu để kiểm tra xem webhook có hoạt động hay không, dùng "signature" được mã hóa bằng HMAC_SHA256 để check xem cách tạo tại đây

Responses

Request samples

Payload

Content type

application/json

{"webhookUrl": "https://your-server.com/webhook-url"
}

Response samples

200
400
401
5XX

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "success",
"data": {"webhookUrl": "http://example.com",
"accountNumber": "string",
"accountName": "string",
"name": "string",
"shortName": "string"
}
}

Lệnh chi

Tạo lệnh chi đơn

API dùng để tạo lệnh chi đơn

Authorizations:

(x-client-idx-api-key)

header Parameters

x-idempotency-key required	string Khóa để đảm bảo tính duy nhất của request
x-signature required	string Chữ ký xác thực request

Request Body schema: application/json
required

referenceId required	string Mã tham chiếu của lệnh chi
amount required	integer Số tiền thanh toán
description required	string Mô tả thanh toán
toBin required	string Mã ngân hàng đích
toAccountNumber required	string Số tài khoản đích
category	Array of strings Danh mục thanh toán

Responses

Request samples

Payload

Content type

application/json

{"referenceId": "payout_123",
"amount": 100000,
"description": "Thanh toán lương",
"toBin": "970415",
"toAccountNumber": "123456789",
"category": {"0": "salary"
}
}

Response samples

200
401
403
500

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "Success",
"data": {"id": "string",
"referenceId": "string",
"transactions": [{"id": "string",
"referenceId": "string",
"amount": 0,
"description": "string",
"toBin": "string",
"toAccountNumber": "string",
"toAccountName": "string",
"reference": "string",
"transactionDatetime": "2019-08-24T14:15:22Z",
"errorMessage": "string",
"errorCode": "string",
"state": "SUCCEEDED"
}
],
"category": ["string"
],
"approvalState": "APPROVED",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Lấy danh sách lệnh chi

API dùng để lấy danh sách các lệnh chi

Authorizations:

(x-client-idx-api-key)

query Parameters

limit	integer Default: 10 Example: limit=10 Số lượng kết quả trên mỗi trang
offset	integer Default: 0 Vị trí bắt đầu
referenceId	string Example: referenceId=payout_1752139775150 Mã tham chiếu để lọc
approvalState	string Example: approvalState=SUCCEEDED Trạng thái phê duyệt để lọc
category	string Example: category=salary,bonus Danh mục để lọc (phân cách bằng dấu phẩy)
fromDate	string <date-time> Example: fromDate=2025-06-12T11:24:55Z Lọc từ ngày
toDate	string <date-time> Example: toDate=2025-08-12T11:24:55Z Lọc đến ngày

Responses

Response samples

200
403

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "Success",
"data": {"payouts": [{"id": "string",
"referenceId": "string",
"transactions": [{"id": "string",
"referenceId": "string",
"amount": 0,
"description": "string",
"toBin": "string",
"toAccountNumber": "string",
"toAccountName": "string",
"reference": "string",
"transactionDatetime": "2019-08-24T14:15:22Z",
"errorMessage": "string",
"errorCode": "string",
"state": "SUCCEEDED"
}
],
"category": ["string"
],
"approvalState": "APPROVED",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"pagination": {"limit": 0,
"offset": 0,
"total": 0,
"count": 0,
"hasMore": true
}
}
}

Tạo lệnh chi hàng loạt

API dùng để tạo lô lệnh chi hàng loạt

Authorizations:

(x-client-idx-api-key)

header Parameters

x-idempotency-key required	string Khóa để đảm bảo tính duy nhất của request
x-signature required	string Chữ ký xác thực request

Request Body schema: application/json
required

referenceId required	string Mã tham chiếu của lệnh chi
category	Array of strings Danh mục thanh toán
validateDestination	boolean Xác thực tài khoản đích
required	Array of objects (PayoutItem)

Responses

Request samples

Payload

Content type

application/json

{"referenceId": "batch_payout_123",
"category": {"0": "salary",
"1": "bonus"
},
"validateDestination": true,
"payouts": [{"referenceId": "payout_123",
"amount": 100000,
"description": "Thanh toán lương tháng 1",
"toBin": "970415",
"toAccountNumber": "123456789"
}
]
}

Response samples

200
401
403
500

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "Success",
"data": {"id": "string",
"referenceId": "string",
"transactions": [{"id": "string",
"referenceId": "string",
"amount": 0,
"description": "string",
"toBin": "string",
"toAccountNumber": "string",
"toAccountName": "string",
"reference": "string",
"transactionDatetime": "2019-08-24T14:15:22Z",
"errorMessage": "string",
"errorCode": "string",
"state": "SUCCEEDED"
}
],
"category": ["string"
],
"approvalState": "APPROVED",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Lấy thông tin lệnh chi

API dùng để lấy thông tin chi tiết của một lệnh chi

Authorizations:

(x-client-idx-api-key)

path Parameters

payoutId

required

string

Example: payout_123

ID của lệnh chi

Responses

Response samples

200
401
403

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "Success",
"data": {"id": "string",
"referenceId": "string",
"transactions": [{"id": "string",
"referenceId": "string",
"amount": 0,
"description": "string",
"toBin": "string",
"toAccountNumber": "string",
"toAccountName": "string",
"reference": "string",
"transactionDatetime": "2019-08-24T14:15:22Z",
"errorMessage": "string",
"errorCode": "string",
"state": "SUCCEEDED"
}
],
"category": ["string"
],
"approvalState": "APPROVED",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Ước tính chi phí

API dùng để ước tính phí cho lệnh chi

Authorizations:

(x-client-idx-api-key)

header Parameters

x-signature

required

string

Chữ ký xác thực request

Request Body schema: application/json
required

referenceId required	string Mã tham chiếu của lệnh chi
category	Array of strings Danh mục thanh toán
validateDestination	boolean Xác thực tài khoản đích
required	Array of objects (PayoutItem)

Responses

Request samples

Payload

Content type

application/json

{"referenceId": "batch_payout_123",
"category": {"0": "salary",
"1": "bonus"
},
"validateDestination": true,
"payouts": [{"referenceId": "payout_123",
"amount": 100000,
"description": "Thanh toán lương tháng 1",
"toBin": "970415",
"toAccountNumber": "123456789"
}
]
}

Response samples

200
401
403

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "Success",
"data": {"estimateCredit": 5000
}
}

Tài khoản chi

Lấy thông tin số dư tài khoản chi

API dùng để lấy thông tin số dư tài khoản chi

Authorizations:

(x-client-idx-api-key)

Responses

Response samples

200
401
403

Content type

application/json

Example

SUCCESS

{"code": "00",
"desc": "Success",
"data": {"accountNumber": "123456789",
"accountName": "CONG TY ABC",
"currency": "VND",
"balance": "1000000"
}
}

payOS API (latest)

Trước khi bắt đầu

Môi trường

Link thanh toán

Tạo link thanh toán

Authorizations:

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Lấy thông tin link thanh toán

Authorizations:

path Parameters

Responses

Response samples

Huỷ link thanh toán

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Lấy thông tin hóa đơn

Authorizations:

path Parameters

Responses

Response samples

Tải hóa đơn

Authorizations:

path Parameters

Responses

Response samples

Webhook thanh toán

Webhook nhận thông tin thanh toán Webhook

Request Body schema: application/json

Responses

Request samples

Kiểm tra và thêm hoặc cập nhật Webhook url

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Lệnh chi

Tạo lệnh chi đơn

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Lấy danh sách lệnh chi

Authorizations:

query Parameters

Responses

Response samples

Tạo lệnh chi hàng loạt

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Lấy thông tin lệnh chi

Authorizations:

path Parameters

Responses

Response samples

Ước tính chi phí

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Tài khoản chi

Lấy thông tin số dư tài khoản chi

Authorizations:

Responses

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required