Danh sách API
payOS API
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
Tạo link thanh toán
API dùng để tạo link thanh toán đơn hàng
Authorizations:
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ử. |
| buyerEmail | string 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ử. |
| buyerAddress | string Địa chỉ 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ử. |
Array of objects Danh sách các sản phẩm thanh toán | |
| cancelUrl required | string URL nhận dữ liệu khi người dùng chọn Huỷ đơn hàng. |
| returnUrl required | string URL nhận dữ liệu khi đơn hàng thanh toán thành công |
| expiredAt | number 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:
|
Responses
Request samples
- Payload
{- "orderCode": 123,
- "amount": 56000000,
- "description": "VQRIO123",
- "buyerName": "Nguyen Van A",
- "buyerPhone": "090xxxxxxx",
- "buyerAddress": "số nhà, đường, phường, tỉnh hoặc thành phố",
- "items": [
- {
- "name": "Iphone",
- "quantity": 2,
- "price": 28000000
}
], - "expiredAt": 1696559798,
- "signature": "string"
}Response samples
- 200
Success - Thành công
{- "code": "00",
- "desc": "Success - Thành công",
- "data": {
- "bin": "970422",
- "accountNumber": "113366668888",
- "accountName": "QUY VAC XIN PHONG CHONG COVID",
- "amount": 3000,
- "description": "VQRIO12546 Thanh toan iphone",
- "orderCode": 1254,
- "curency": "VND",
- "paymentLinkId": "a7a9454060cd48909864b3747289ff38",
- "status": "PENDING",
- "qrCode": "00020101021238570010A00000072701270006970422011371045208946240208QRIBFTTA5303704540430005802VN62180814TT1BQG8F khanh6304D4F6"
}, - "signature": "8d8640d802576397a1ce45ebda7f835055768ac7ad2e0bfb77f9b8f12cca4c7f"
}Lấy thông tin link thanh toán
API dùng để lấy thông tin của link thanh toán
Authorizations:
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
Success - Thành công
{- "code": "00",
- "desc": "Success - Thành công",
- "data": {
- "id": "10b79503da974af09761be84fd0664232",
- "orderCode": 3019,
- "amount": 3000,
- "amountPaid": 3000,
- "amountRemaining": 0,
- "status": "PAID",
- "createdAt": "2023-07-31T15:33:31.000Z",
- "transactions": [
- {
- "reference": "FT23212323232323",
- "amount": 3000,
- "accountNumber": "113366668888",
- "description": "TTY23V15",
- "transactionDateTime": "2023-08-01T19:44:15.000Z",
- "virtualAccountName": "NGUYEN VAN A",
- "virtualAccountNumber": null,
- "counterAccountBankId": null,
- "counterAccountBankName": null,
- "counterAccountName": null,
- "counterAccountNumber": null
}
], - "cancellationReason": null,
- "canceledAt": null
}, - "signature": "64319f6c98c01e5cb254f4304b95c8f3339bfcbb30c8b6e5831902f98c03b094"
}Huỷ link thanh toán
API dùng để hủy link thanh toán
Authorizations:
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
{- "cancellationReason": "Changed my mind"
}Response samples
- 200
Success - Thành công
{- "code": "00",
- "desc": "Success - Thành công",
- "data": {
- "id": "10b79503da974af09761be84fd0664dd",
- "orderCode": 3019,
- "amount": 3000,
- "amountPaid": 0,
- "amountRemaining": 3000,
- "status": "CANCELLED",
- "createdAt": "2023-08-01T16:12:21.000Z",
- "transactions": [ ],
- "cancellationReason": "Changed my mind",
- "canceledAt": "2023-08-01T17:12:21.000Z"
}, - "signature": "64319f6c98c01e5cb254f4304b95c8f3339bfcbb30c8b6e5831902f98c03b094"
}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:
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
{
}Response samples
- 200
- 400
- 401
- 5XX
Success - Thành công
{- "code": "00",
- "desc": "success"
}