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

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

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ử.
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: `amount=$amount&cancelUrl=$cancelUrl&description=$description&orderCode=$orderCode&returnUrl=$returnUrl`.

Responses

Request samples

Payload

Content type

application/json

{"orderCode": 123,
"amount": 56000000,
"description": "VQRIO123",
"buyerName": "Nguyen Van A",
"buyerEmail": "buyer-email@gmail.com",
"buyerPhone": "090xxxxxxx",
"buyerAddress": "số nhà, đường, phường, tỉnh hoặc thành phố",
"items": [{"name": "Iphone",
"quantity": 2,
"price": 28000000
}
],
"cancelUrl": "https://your-cancel-url.com",
"returnUrl": "https://your-success-url.com",
"expiredAt": 1696559798,
"signature": "string"
}

Response samples

200

Content type

application/json

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",
"checkoutUrl": "https://pay.payos.vn/web/a7a9454060cd48909864b3747289ff38",
"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

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

Content type

application/json

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:

(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

Content type

application/json

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:

(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

Success - Thành công

{"code": "00",
"desc": "success"
}