Giới thiệu

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

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>

  • <algorithm> = “HS256” : chữ ký bằng HMAC-SHA256
  • <algorithm>= “RS256” : chữ ký bằng RSA-SHA256

( 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

 

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ợ

  1. Ngân hàng Nông nghiệp và Phát triển Nông thôn (AGRIBANK)
  2. Ngân hàng TMCP Đầu tư và Phát triển Việt Nam (BIDV)
  3. Ngân hàng TMCP Công thương Việt Nam (VIETINBANK)
  4. Ngân hàng TMCP Á Châu (ACB)
  5. Ngân hàng TMCP Đông Nam Á (SEABANK)
  6. Ngân hàng TMCP Sài Gòn Thương tín(SACOMBANK)
  7. Ngân hàng TMCP Sài Gòn Công thương(SAIGONBANK)
  8. Ngân hàng TMCP An Bình(ABBANK)
  9. Ngân hàng Phát triển nhà Đồng bằng song Cửu Long (MHB)
  10. Ngân hàng TMCP Nhà Hà Nội (HABUBANK)
  11. Ngân hàng TMCP Đại Dương (OCEANBANK)
  12. Ngân hàng TMCP Phương Tây( WESTERNBANK)
  13. Ngân hàng Xăng dầu Petrolimex(PGBANK)
  14. Ngân hàng liên doanh Việt Nga(VRB)
  15. Ngân hàng TMCP Đại Tín (TRUSTBank)
  16. Ngân hàng TMCP Nam Á (NAMABANK)
  17. Quĩ Tín dụng Nhân dân Trung Ương (CCF)
  18. Ngân hàng Thương mại TNHH Một Thành Viên Dầu khí Toàn cầu (GPBANK)
  19. Ngân hàng TMCP Đại Á (DAIABANK)
  20. Ngân hàng Ngoại thương Việt Nam (VIETCOMBANK)
  21. Ngân hàng TMCP Kỹ thương (TECHCOMBANK)
  22. Ngân hàng TMCP Sài Gòn (SCB)
  23. Ngân hàng TMCP Nam Việt (NAVIBANK)
  24. Ngân hàng TMCP Tiên Phong (TIENPHONGBANK)
  25. Ngân hàng TMCP Phương Nam (SOUTHERNBANK)
  26. Ngân hàng TMCP Việt Á (VIETABANK)
  27. Ngân hàng TMCP Quốc tế (VIBANK)
  28. Ngân hàng TMCP Thịnh Vượng (VPBANK)
  29. Ngân hàng TMCP Xuất nhập khẩu (EIB)
  30. Ngân hàng TMCP Hàng Hải (MSB)
  31. Ngân hàng Phát triển nhà tp Hồ Chí Minh (HDBANK)
  32. Ngân hàng TNHH Indo Vina Bank (IVB)
  33. Ngân hàng TMCP Sài Gòn Hà Nội (SHB)
  34. Ngân hàng Liên doanh VID Public(VIDPUBLICBANK)
  35. Ngân hàng TMCP Bắc Á (NASBANK)
  36. Ngân hàng TMCP Phương Đông (OCB)
  37. Ngân hàng TNHH MTV Standard Chartered (SCVN)
  38. Ngân hàng TNHH MTV Hong Leong VN (HLBVN)
  39. Ngân hàng TMCP Liên Việt (LVB)
  40. Ngân hàng TMCP Đông Á (DONGABANK)