I. Tổng quan
1. Mục đích
- Hướng dẫn từng bước để kết nối với API cổng thanh toán trung gian
2. Phạ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. Định dạng
a, Kết quả trả về
Tất cả kết quả sẽ trả về dưới dạng json với định dạng :
- Thành công
- Thất bại
II. Tích hợp
1. Xác thực
Thêm các tham số bên dưới vào header trong mỗi lần gọi api
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
Authorization |
string |
có |
Định dạng: Signature<dấucách>Algorithm=<algorithm>, Credential=<credential>,SignedHeaders=<signedheaders>,Signature=<signature>
( Xem 3.Chữ ký điện tử để biết rõ hơn) |
|
Date |
number |
có |
Request timestamp/unix time |
2. Thanh toán
2.1 Tạo yêu cầu thanh toá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 định |
Mô tả |
amount |
number |
có |
||
return_url |
string |
có |
||
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 |
|
method |
string |
có |
'CREDIT_CARD','ATM_CARD' |
|
card_brand |
string |
không |
Truyền theo các mã của ngân hàng ở mục V. Danh sách ngân hàng hỗ trợ nếu phương thức giao dịch là ATM_CARD |
|
description |
string |
có |
||
currency |
string |
không |
“USD”,”VND”. Mặc định là VND |
|
client_ip |
string |
có |
|
|
save_token |
number |
không |
0 |
0 : giao dịch không lưu token 1 : giao dịch có lưu token |
card_token |
string |
không |
Truyền lên nếu muốn thanh toá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 quả tạo đơn hàng
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
code |
number |
có |
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 định |
Mô tả |
payment_no |
string |
có |
Mã thanh toán của 9pay |
|
redirect_url |
string |
có |
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 trả 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 sẽ chỉ được bắn khi giao dịch thành công
- IPN sẽ trả về :
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
result |
string |
có |
Thông tin giao dịch |
|
checksum |
string |
có |
- Return url sẽ trả về :
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
result |
string |
có |
Thông tin giao dịch sau khi json_encode và base64_encode |
|
checksum |
string |
có |
- Giá trị trong result sau khi decode về sẽ là :
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
payment_no |
number |
có |
||
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 |
|
currency |
string |
có |
||
amount |
number |
có |
||
description |
string |
có |
||
method |
string |
có |
'CREDIT_CARD','ATM_CARD' |
|
card_brand |
string |
có |
||
card_info |
array |
không |
nếu thanh toán lưu token , sẽ trả thêm về mảng card_info |
|
status |
number |
có |
||
failure_reason |
string |
có |
||
created_at |
date/time |
có |
- Giá trị trong card_info sẽ là :
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
name |
string |
có |
tên chủ thẻ được in trên thẻ |
|
issuer |
string |
có |
tổ chức phát hành thẻ |
|
brand |
string |
có |
nhãn hiệu thẻ |
|
scheme |
string |
có |
loại thẻ |
|
card_number |
string |
có |
số thẻ dạng 99xxx999 |
|
expire_date |
string |
có |
ngày hết hạn |
|
token |
string |
có |
token của thẻ |
2.2 Truy vấn thanh toán
2.2.1 URL
/payments/{invoice_no}/inquire
2.2.2 Phương thức
GET
2.2.3 Kết quả trả về
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
code |
number |
có |
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 định |
Mô tả |
payment_no |
string |
có |
||
invoice_no |
string |
có |
||
currency |
string |
có |
‘VND’,’USD’ |
|
amount |
number |
có |
||
description |
string |
có |
||
method |
string |
có |
||
card_brand |
string |
có |
||
status |
number |
có |
||
failure_reason |
string |
không |
||
created_at |
datetime |
có |
2.3 Hoàn trả thanh toá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 định |
Mô tả |
reason |
string |
có |
Lý do hoàn tiền |
2.3.4 Kết quả trả về
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
code |
number |
có |
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 định |
Mô tả |
refund_no |
number |
có |
Mã refund |
|
payment_no |
string |
có |
Mã thanh toán của cổng 9pay |
|
amount |
number |
có |
||
currency |
string |
có |
||
reason |
string |
có |
||
status |
number |
có |
0 : Đã khởi tạo 1 : Hoàn Thành 2 : Thất bại |
2.4 Hoàn thành thanh toán
2.4.1 URL
payments/{payment_no}/claim
2.4.2 Phương thức
POST
2.4.3 Kết quả trả về
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
code |
number |
có |
Mã lỗi |
|
message |
string |
không |
2.5 Xóa token thanh toán
2.5.1 URL
card_token/{token}/delete
2.5.2 Phương thức
POST
2.5.3 Kết quả trả về
Tên |
Kiểu dữ liệu |
Bắt buộc |
Mặc định |
Mô tả |
code |
number |
có |
Mã lỗi |
|
message |
string |
không |
3. Chữ ký điện tử
* Lưu ý : Chọn UTF-8 cho tất cả mã hóa
3.1 Chữ ký khi tạo yêu cầu
a, Chữ ký bằng HMAC-SHA256:
Signature =base64_encode(HMACSHA256( <Http request method> +”\n”+<uri> +”\n”+<timestamp> +”\n”+<canonicalized resources>))
b, Chữ ký bằng RSA-SHA256:
Signature =base64_encode(RSA-SHA256( <Http request method> +”\n”+<uri> +”\n”+<timestamp> +”\n”+<canonicalized resources>))
<canonicalized resources> mô tả :
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ố và giá trị tương ứng với ký tự ‘=’ và nối mỗi cặp tham số bằng ký 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. Trạng thái thanh toán
STATUS |
DESCRIPTION |
1 |
Giao dịch đã được khởi tạo |
2 |
Giao dịch đang xử lý |
3 |
Giao dịch sẽ được review vì bị đánh dấu khả nghi |
4 |
Giao dịch thành công nhưng merchant chưa được cộng số dư |
5 |
Giao dịch thành công và merchant đã được cộng số dư |
6 |
Giao dịch thất bại |
7 |
Giao dịch đã được hoàn tiền |
8 |
Giao dịch bị hủy do khách hàng |
10 |
Giao dịch đã bị hoàn trả |
12 |
Giao dịch bị giữ tiền do bị đánh dấu khả nghi |
14 |
Giao dịch gặp lỗi |
15 |
Quá thời gian xử lý |
IV. Mã lỗi
CODE |
NAME |
DESCRIPTION |
00 |
OK |
Thành công |
01 |
FAIL |
Thất bại |
07 |
NOT_FOUND |
Không tồn tại dữ liệu cho yêu cầu |
08 |
NOT_ACCEPTABLE_PAYMENT_AMOUNT |
Không chấp nhận số tiền thanh toán |
09 |
NOT_ACCEPTABLE_PAYMENT_METHOD |
phương thức thanh toán gửi lên không được hỗ trợ |
16 |
BLACK_LIST |
IP hoặc Device ID đang nằm trong danh sách đen , không thể tạo yêu cầu thanh toán |
18 |
INVALID_CARD_TOKEN |
Token thanh toá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 |
Mã hóa đơn đã tồn tại |
21 |
PAYMENT_REFUNDED |
Giao dịch đã được hoàn tiền |
22 |
INVALID_STATUS |
Trạng thái không hợp lệ |
V. Danh sách ngân hà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)