I. Tổng quan

1. Mục đích

- Hướng dẫn từng bước để kết nối với API cổng thanh toán trung gian

2. Phạm vi

- Hệ thống kỹ thuật của người bán

3. Môi trường

Sandbox: ...Tìm hiểu thêm
Production: ...Tìm hiểu thêm

4. Tài khoản test

ClientID: ...Tìm hiểu thêm
Secret Key: ...Tìm hiểu thêm

5. Định dạng

a, Kết quả trả về
Tất cả kết quả sẽ trả về dưới dạng json với định dạng :

Thành công

Thất bại

II. Tích hợp

1. Xác thực

Thêm các tham số bên dưới vào header trong mỗi lần gọi api

Tên

Kiểu dữ liệu

Bắt buộc

Mặc định

Mô tả

Authorization

string

có

Định dạng:

Signature<dấucách>Algorithm=<algorithm>,

Credential=<credential>,SignedHeaders=<signedheaders>,Signature=<signature>

<algorithm> = “HS256” : chữ ký bằng HMAC-SHA256
<algorithm>= “RS256” : chữ ký bằng RSA-SHA256

( Xem 3.Chữ ký điện tử để biết rõ hơn)

Date

number

có

Request timestamp/unix time

2. Thanh toán

2.1 Tạo yêu cầu thanh toán

2.1.1 URL

/payments/create

2.1.2 Phương thức

POST

2.1.3 Tham số yêu cầu (form-data)

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
amount	number	có
return_url	string	có
invoice_no	string	có		ID giao dịch của người bán . Là duy nhất cho mỗi yêu cầu
method	string	có		'CREDIT_CARD','ATM_CARD'
card_brand	string	không		Truyền theo các mã của ngân hàng ở mục V. Danh sách ngân hàng hỗ trợ nếu phương thức giao dịch là ATM_CARD
description	string	có
currency	string	không		“USD”,”VND”. Mặc định là VND
client_ip	string	có
save_token	number	không	0	0 : giao dịch không lưu token 1 : giao dịch có lưu token
card_token	string	không		Truyền lên nếu muốn thanh toán bằng token
note_to_payer	string	không
payer_name	string	không
payer_phone	string	không

2.1.4 Kết quả tạo đơn hàng

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
code	number	có		Mã lỗi
message	string	không
data	json array	không		* Mảng dữ liệu

* Dữ liệu :

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
payment_no	string	có		Mã thanh toán của 9pay
redirect_url	string	có		Redirect URL

2.1.5 Nhận kết quả giao dịch

ĐVBH (Đơn vị bán hàng) sẽ nhận được kết quả trả về cho luồng giao dịch theo 2 đường sau (lưu ý xử lý chống trùng khi nhận được kết quả cho 1 giao dịch theo cả 2 đường ) :

Return: data sẽ được trả vào địa chỉ RETURN URL mà gửi kèm trong yêu cầu thanh toán. ĐVBH 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.

IPN: Json data được post vào địa chỉ IPN ĐVBH đã đăng ký với 9Pay. ĐVBH sử dụng kết quả này để xử lý nghiệp vụ backend.IPN sẽ chỉ được bắn khi giao dịch thành công

IPN sẽ trả về :

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
result	string	có		Thông tin giao dịch
checksum	string	có

Return url sẽ trả về :

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
result	string	có		Thông tin giao dịch sau khi json_encode và base64_encode
checksum	string	có

Giá trị trong result sau khi decode về sẽ là :

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
payment_no	number	có
invoice_no	string	có		ID giao dịch của người bán . Là duy nhất cho mỗi yêu cầu
currency	string	có
amount	number	có
description	string	có
method	string	có		'CREDIT_CARD','ATM_CARD'
card_brand	string	có
card_info	array	không		nếu thanh toán lưu token , sẽ trả thêm về mảng card_info
status	number	có
failure_reason	string	có
created_at	date/time	có

Giá trị trong card_info sẽ là :

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
name	string	có		tên chủ thẻ được in trên thẻ
issuer	string	có		tổ chức phát hành thẻ
brand	string	có		nhãn hiệu thẻ
scheme	string	có		loại thẻ
card_number	string	có		số thẻ dạng 99xxx999
expire_date	string	có		ngày hết hạn
token	string	có		token của thẻ

2.2 Truy vấn thanh toán

2.2.1 URL

/payments/{invoice_no}/inquire

2.2.2 Phương thức

GET

2.2.3 Kết quả trả về

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
code	number	có		Mã lỗi
message	string	không
data	json array	không		* Mảng dữ liệu

* Dữ liệu:

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
payment_no	string	có
invoice_no	string	có
currency	string	có		‘VND’,’USD’
amount	number	có
description	string	có
method	string	có
card_brand	string	có
status	number	có
failure_reason	string	không
created_at	datetime	có

2.3 Hoàn trả thanh toán

2.3.1 URL

payments/{payment_no}/refunds

2.3.2 Phương thức

POST

2.3.3 Tham số yêu cầu (form-data)

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
reason	string	có		Lý do hoàn tiền

2.3.4 Kết quả trả về

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
code	number	có		Mã lỗi
message	string	không
data	json array	không		* Mảng dữ liệu

* Dữ liệu:

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
refund_no	number	có		Mã refund
payment_no	string	có		Mã thanh toán của cổng 9pay
amount	number	có
currency	string	có
reason	string	có
status	number	có		0 : Đã khởi tạo 1 : Hoàn Thành 2 : Thất bại

2.4 Hoàn thành thanh toán

2.4.1 URL

payments/{payment_no}/claim

2.4.2 Phương thức

POST

2.4.3 Kết quả trả về

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
code	number	có		Mã lỗi
message	string	không

2.5 Xóa token thanh toán

2.5.1 URL

card_token/{token}/delete

2.5.2 Phương thức

POST

2.5.3 Kết quả trả về

Tên	Kiểu dữ liệu	Bắt buộc	Mặc định	Mô tả
code	number	có		Mã lỗi
message	string	không

3. Chữ ký điện tử

* Lưu ý : Chọn UTF-8 cho tất cả mã hóa

3.1 Chữ ký khi tạo yêu cầu

a, Chữ ký bằng HMAC-SHA256:

Signature =base64_encode(HMACSHA256( <Http request method> +”\n”+<uri> +”\n”+<timestamp> +”\n”+<canonicalized resources>))

b, Chữ ký bằng RSA-SHA256:
Signature =base64_encode(RSA-SHA256( <Http request method> +”\n”+<uri> +”\n”+<timestamp> +”\n”+<canonicalized resources>))

<canonicalized resources> mô tả :

1) Liệt kê tất cả các tham số yêu cầu, sắp xếp theo tên tham số , theo thứ tự bảng chữ cái

2) Nối tên tham số và giá trị tương ứng với ký tự ‘=’ và nối mỗi cặp tham số bằng ký tự ‘&’

Vui lòng tham khảo mã mẫu

3.2 Xác thực dữ liệu nhận về

Vui lòng tham khảo mã mẫu

III. Trạng thái thanh toán

STATUS	DESCRIPTION
1	Giao dịch đã được khởi tạo
2	Giao dịch đang xử lý
3	Giao dịch sẽ được review vì bị đánh dấu khả nghi
4	Giao dịch thành công nhưng merchant chưa được cộng số dư
5	Giao dịch thành công và merchant đã được cộng số dư
6	Giao dịch thất bại
7	Giao dịch đã được hoàn tiền
8	Giao dịch bị hủy do khách hàng
10	Giao dịch đã bị hoàn trả
12	Giao dịch bị giữ tiền do bị đánh dấu khả nghi
14	Giao dịch gặp lỗi
15	Quá thời gian xử lý

IV. Mã lỗi

CODE	NAME	DESCRIPTION
00	OK	Thành công
01	FAIL	Thất bại
07	NOT_FOUND	Không tồn tại dữ liệu cho yêu cầu
08	NOT_ACCEPTABLE_PAYMENT_AMOUNT	Không chấp nhận số tiền thanh toán
09	NOT_ACCEPTABLE_PAYMENT_METHOD	phương thức thanh toán gửi lên không được hỗ trợ
16	BLACK_LIST	IP hoặc Device ID đang nằm trong danh sách đen , không thể tạo yêu cầu thanh toán
18	INVALID_CARD_TOKEN	Token thanh toán truyền lên không hợp lệ
19	MERCHANT_INVALID_METHOD	Method không hợp lệ với merchant
20	UNIQUE_INVOICE_NO	Mã hóa đơn đã tồn tại
21	PAYMENT_REFUNDED	Giao dịch đã được hoàn tiền
22	INVALID_STATUS	Trạng thái không hợp lệ

V. Danh sách ngân hàng hỗ trợ

Ngân hàng Nông nghiệp và Phát triển Nông thôn (AGRIBANK)
Ngân hàng TMCP Đầu tư và Phát triển Việt Nam (BIDV)
Ngân hàng TMCP Công thương Việt Nam (VIETINBANK)
Ngân hàng TMCP Á Châu (ACB)
Ngân hàng TMCP Đông Nam Á (SEABANK)
Ngân hàng TMCP Sài Gòn Thương tín(SACOMBANK)
Ngân hàng TMCP Sài Gòn Công thương(SAIGONBANK)
Ngân hàng TMCP An Bình(ABBANK)
Ngân hàng Phát triển nhà Đồng bằng song Cửu Long (MHB)
Ngân hàng TMCP Nhà Hà Nội (HABUBANK)
Ngân hàng TMCP Đại Dương (OCEANBANK)
Ngân hàng TMCP Phương Tây( WESTERNBANK)
Ngân hàng Xăng dầu Petrolimex(PGBANK)
Ngân hàng liên doanh Việt Nga(VRB)
Ngân hàng TMCP Đại Tín (TRUSTBank)
Ngân hàng TMCP Nam Á (NAMABANK)
Quĩ Tín dụng Nhân dân Trung Ương (CCF)
Ngân hàng Thương mại TNHH Một Thành Viên Dầu khí Toàn cầu (GPBANK)
Ngân hàng TMCP Đại Á (DAIABANK)
Ngân hàng Ngoại thương Việt Nam (VIETCOMBANK)
Ngân hàng TMCP Kỹ thương (TECHCOMBANK)
Ngân hàng TMCP Sài Gòn (SCB)
Ngân hàng TMCP Nam Việt (NAVIBANK)
Ngân hàng TMCP Tiên Phong (TIENPHONGBANK)
Ngân hàng TMCP Phương Nam (SOUTHERNBANK)
Ngân hàng TMCP Việt Á (VIETABANK)
Ngân hàng TMCP Quốc tế (VIBANK)
Ngân hàng TMCP Thịnh Vượng (VPBANK)
Ngân hàng TMCP Xuất nhập khẩu (EIB)
Ngân hàng TMCP Hàng Hải (MSB)
Ngân hàng Phát triển nhà tp Hồ Chí Minh (HDBANK)
Ngân hàng TNHH Indo Vina Bank (IVB)
Ngân hàng TMCP Sài Gòn Hà Nội (SHB)
Ngân hàng Liên doanh VID Public(VIDPUBLICBANK)
Ngân hàng TMCP Bắc Á (NASBANK)
Ngân hàng TMCP Phương Đông (OCB)
Ngân hàng TNHH MTV Standard Chartered (SCVN)
Ngân hàng TNHH MTV Hong Leong VN (HLBVN)
Ngân hàng TMCP Liên Việt (LVB)
Ngân hàng TMCP Đông Á (DONGABANK)