Danh sách API

1. Tạo chữ ký điện tử #

Thông tin kết nối (Key Credential) #

9Pay sẽ cung cấp cho đối tác ĐVCNTT các thông tin kết nối để định danh trong quá trình tích hợp bao gồm:

  • Merchant Key: Thông tin định danh Đối tác
  • Merchant Secret Key: Thông tin dùng để tạo chữ ký điện tử (Signature)

 

Chữ ký điện tử #

Lưu ý: Chọn UTF-8 cho tất cả mã hóa

 

Chữ ký khi tạo yêu cầu (Signature) 

Chữ ký bằng HMAC-SHA256

Signature = base64_encode(HMACSHA256( <Http request method> +”\n”+<URI>+”\n”+<timestamp> +”\n”+<canonicalized resources>, <merchant_secret_key>))
Key Description
<Http request method>

phương thức gọi đến “POST” or “GET”

<URI>

URI bên 9pay mà đối tác gọi đến

<timestamp>

Unixtimestamp độ dài10

<merchant_secret_key>

Mã Secret key sẽ được cấp bởi 9pay

<canonicalized resources>

B1) Liệt kê tất cả các tham số yêu cầu
B2) Nối tên tham số và giá trị tương ứng với ký tự ‘=’ và nối mỗi cặp tham số bằng ký tự ‘&’
Example:
merchantKey=NGuTdi&invoice_no=92938380&amount=10000&description=Thanh toán đơn hàng&return_url=https://sand-payment.9pay.com

Ví dụ

Signature = base64_encode(HMACSHA256( “POST”+”\n”+https://sand-business.9pay.vn/payments/create+”\n”+1611135904 +”\n”+merchantKey=”NGuTdi”&invoice_no=92938380&amount=10000&description=”Thanh toán đơn hàng”&return_url=https://sand-payment.9pay.com, “pe1asmBPtPBZo8o6SIIwPFbDXTEvuKwTLlD”))

 

Xác nhận dữ liệu trả về 

a. Chữ ký bằng HMAC-SHA256

Kết quả trả về luôn có 3 giá trị là result (dữ liệu được mã hóa), checksum (checksum được tạo ra từ dữ liệu mã hóa và key checksum của đối tác), version

$ninePayResult = [
	'result' => 'string result',
	'checksum' => 'string checksum',
	'version' => 'v1',
];

b. Kiểm tra mã checksum và lấy dữ liệu thông tin thanh toán

Sử dụng hash sha256 kết quả và key checksum(được cung cấp khi tích hợp) tạo ra mã xác thực checksum. So sánh mã này với giá trị checksum nhận được để xác định tính hợp lệ của dữ liệu

Ví dụ PHP:
$secretKeyCheckSum (yêu cầu cung cấp dùng riêng để checksum) 

$hashChecksum = strtoupper(hash('sha256', $ninePayResult['result'] . $secretKeyCheckSum));
//  Kiểm tra mã checksum
if ($hashChecksum === $ninePayResult[' checksum']) {
	// Thông tin payment nhận về
	$arrayParams = json_decode(base64_decode($ninePayResult['result']), true);	
}

 

Xác thực #

Thêm các tham số bên dưới vào header mỗi lần gọi API

Tên Kiểu dữ liệu Bắt buộc Mô tả
Authorization string có

Signature<dấucách>Algorithm=<algorithm>,
Credential=<merchantKey>,SignedHeaders=<signedHeaders>,Signature=<merchantSignature>

với <algorithm> = “HS256”
<merchantKey> là key nhận được khi tích hợp
<signHeaders> để rỗng
<merchantSignature> được tạo ra ở mục Chữ ký khi tạo yêu cầu (Signature)

Date number có Định dang timestamp/unix time - độ dài10

 

Ví dụ header sẽ có thêm 2 key này khi request đến 9pay

Date 1611135904
Authorization

Signature Algorithm=HS256,Credential=X4cWcr,SignedHeaders=,Signature=Up0g/RzufgzrX+U2RjSEHtPjl7Q3NIlgtRcKi9lWe6o=

2. Tạo URL thanh toán #

Tích hợp qua Portal chỉ cần build signature mà không cần phải build toàn bộ header

Ví dụ #

Ngôn ngữ Link
PHP https://gitlab.com/9pay-sample/sample-php
JAVA https://gitlab.com/9pay-sample/sample-java
NodeJS https://gitlab.com/9pay-sample/sample-javascript

 

Tham số yêu cầu #

Tên Kiểu dữ liệu Bắt buộc Mô tả
amount number có

Số tiền cần thanh toán

method string không

Nếu có thì hệ thống enable phương thức theo method: ATM_CARD, CREDIT_CARD, 9PAY, BANK_TRANSFER, QR_PAY, BUY_NOW_PAY_LATER

return_url string có

Url redirect về trang mua hàng của đối tác sau khi giao dịch thành công

invoice_no string | 30 có

ID giao dịch của người bán. Định danh cho mỗi yêu cầu, tối đa 30 ký tự

description string | 64 có

Mô tả thông tin đơn hàng

currency string | 10 không

“USD”, VND”, “EUR”, “GBP”, “CNY”. Mặc định là VND

time int | 10

Ví dụ : 1335939007 (UTC+0, length=10)

merchantKey string

Chuỗi định danh khách hàng, được 9Pay cung cấp.

lang string không

Ngôn ngữ hiển thị trên các màn hình giao dịch cho khách hàng. Có 2 giá trị: ‘vi’, ‘en’. Mặc định là ‘vi’.

card_token string không

Chuỗi token dùng để thanh toán do 9Pay trả cho khách hàng sau khi thực hiện save token

save_token number không

Xác định tạo token để thực hiện các giao dịch sau bằng token. Giá trị: 0 hoặc 1
Với 0: false, 1: true

bank_code string không

Truyền vào mã ngân hàng ở đây nếu muốn vào thẳng form nhập thẻ của ngân hàng. 

profile_id int không

Lấy từ mục danh sách Profile. Trong trường hợp muốn thay đổi thông tin thanh toán theo từng profile

extra_data json không

Dữ liệu bổ sung (Lưu ý bỏ qua tham số này kho tạo chữ ký)

Các phương thức thanh toán cần truyền thêm tham số này:

- Thanh toán thẻ quốc tế

- Mua trước trả sau

* Sau khi build link hệ thống của khách hàng sẽ redirect sang link vừa build

 

3. IPN giao dịch #

Đối tác sẽ nhận được kết quả trả về cho luồng giao dịch theo 2 phương thức

* Lưu ý xử lý chống trùng khi nhận được kết quả cho 1 giao dịch theo cả 2 phương thức.

  • Return: data sẽ được trả vào địa chỉ return_url mà gửi kèm trong yêu cầu thanh toán. Đối tác sử dụng kết quả này để hiển thị thông báo giao dịch đã thành công/không thành công cho khách hàng (Nằm trong query string khi quay lại liên kết của đối tác).
  • IPN: Data được POST (x-www-form-data) vào địa chỉ ipn_url đối tác đã đăng ký với 9Pay. Đối tác sử dụng kết quả này để xử lý nghiệp vụ backend. IPN sẽ chỉ được bắn khi giao dịch thành công  (Gửi yêu cầu POST đến IPN url của đối tác).

 

Dữ liệu trả về từ IPN #

Tên Kiểu dữ liệu Bắt buộc Mô tả
result string có Thông tin giao dịch
checksum string có Mã checksum tạo ra bằng result và key checksum của đối tác

 

Dữ liệu của trường result sau khi decode #

Tên Kiểu dữ liệu Bắt buộc Mô tả
payment_no number có

Mã thanh toán của cổng 9pay

invoice_no string có

ID giao dịch của người bán. Là duy nhất cho mỗi yêu cầu, tối đa 30 ký tự

currency string có

“USD”, VND”, “EUR”, “GBP”, “CNY”.

amount number có

Số tiền cần thanh toán

description string có

Mô tả thông tin đơn hàng

method string có

Phương thức thanh toán (ATM_CARD, CREDIT_CARD, 9PAY, COLLECTION, QR_PAY, BUY_NOW_PAY_LATER)

card_brand string có

Thương hiệu thẻ

status number có

Trạng thái giao dịch

failure_reason string Lý do thất bại
created_at date/time có

Thời gian tạo giao dịch (UTC+0)

card_info array không

Dữ liệu trả thêm

 

Dữ liệu của trường card_info # 

Tên Kiểu dữ liệu Mô tả
card_name string Tên chủ thẻ được in trên thẻ
issuer string Tổ chức phát hành thẻ
card_brand string Thương hiệu thẻ
card_number string Số thẻ dạng 999999xxxx9999
expire_date string Ngày hết hạn
token string Token của thẻ (Với trường hợp đăng ký thanh toán tạo token)

 

Ví dụ # 

Tham số Dữ liệu
result

ewogICJhbW91bnQiOiAiMTAwMCIsCiAgImNhcmRfYnJhbmQiOiAiVENCIiwKICAiY2FyZF9pbmZvIjogbnVsbCwKICAiY3JlYXRlZF9hdCI6ICIxOTAwLTAxLTAxIDEx

OjUxOjUxIiwKICAiY3VycmVuY3kiOiAiVk5EIiwKICAiZGVzY3JpcHRpb24iOiAiTW8gdGEgZ2lhbyBkaWNoIiwKICAiZmFpbHVyZV9yZWFzb24iOiAiIiwKICAiaW52b2l

checksum 4F7065A4CC82A12EAC366AE4E5F0C278EE35CCE99806461E575D71CB393B6D5F

Sau khi xác thực checksum và giải mã result sẽ được dữ liệu 
 

{
  "amount": "1000",
  "card_brand": "TCB",
  "card_info": null,
  "created_at": "1900-01-01 11:51:51",
  "currency": "VND",
  "description": "Thanh toan đon hang",
  "failure_reason": "",
  "invoice_no": "1626332596",
  "lang": null,
  "method": "ATM_CARD",
  "payment_no": "916266966289",
  "status": 5
}

 

4. Truy vấn trạng thái giao dịch #

Thực hiện truy vấn thanh toán khi đối tác muốn kiểm tra trạng thái của giao dịch

Đặc tả #

Phương thức End point
GET /v2/payments/{invoice_no}/inquire

*Phương thức này cần build header theo hướng dẫn tại đây

 

Kết quả trả về #

Tên Kiểu dữ liệu Bắt buộc Mô tả
payment_no number có

Mã thanh toán của cổng 9pay

invoice_no string có

ID giao dịch của người bán. Là duy nhất cho mỗi yêu cầu, tối đa 18 ký tự

currency string có

Loại tiền tệ ‘VND’ hoặc ’USD’

amount number có

Số tiền cần thanh toán

description string có

Mô tả thông tin đơn hàng

method string có

Phương thức thanh toán (ATM_CARD, CREDIT_CARD, 9PAY, BANK_TRANSFER, QR_PAY, BUY_NOW_PAY_LATER)

card_brand string có

Thương hiệu thẻ

status number có

Trạng thái giao dịch

failure_reason string không Lý do thất bại
created_at datetime có

Thời gian tạo giao dịch

5. Hoàn tiền giao dịch #

Đặc tả #

Phương thức Endpoint
POST /v2/refunds/create

*Phương thức này cần build header theo hướng dẫn tại đây

Tham số yêu cầu #

Tên Kiểu dữ liệu Bắc buộc Mô tả
request_id string Mã giao dịch riêng của merchant
payment_no number Mã giao dịch gốc của 9Pay
amount number Giá trị hoàn
description string | 150 Mô tả giao dịch hoàn
bank string không Tên ngân hàng (*)
account_number string | 20 không Số tài khoản nhận tiền (*)
customer_name String | 50 không Tên chủ tài khoản (*)

* Trường này là bắt buộc nếu loại hình giao dịch là chuyển khoản ngân hàng (Bank transfer)

 

Kết quả trả về #

Tên Kiểu dữ liệu Bắt buộc Mô tả
status number có Trạng thái
error_code number không Mã lỗi của giao dịch refund
failure_reason string không Mô tả mã lỗi
message string không Chi tiết mã lỗi
payment_no number có Mã giao dịch gốc của 9Pay
refund_no number không Mã giao dịch hoàn của 9Pay
request_id string có Mã giao dịch riêng của đối tác
amount number có Giá trị giao dịch hoàn

6. Truy vấn trạng thái giao dịch hoàn #

Đặc tả #

Phương thức Endpoint
GET /v2/refunds/{request_id}/inquire

*Phương thức này cần build header theo hướng dẫn tại đây

 

Tham số yêu cầu #

Tên Kiểu dữ liệu Bắt buộc Mô tả
request_id string Mã giao dịch riêng của đối tác

 

Kết quả trả về #

Tên Kiểu dữ liệu Bắt buộc Mô tả
status number có Trạng thái
error_code number không Mã lỗi của giao dịch refund
failure_reason string không Mô tả mã lỗi
message string không Chi tiết mã lỗi
payment_no number Mã giao dịch gốc của 9Pay
refund_no number không Mã giao dịch hoàn của 9Pay
request_id string Mã giao dịch riêng của đối tác
amount number Giá trị giao dịch hoàn