1. Giới thiệu
Cùng với sự phát triển nhanh chóng của thương mại điện tử, nhu cầu mua sắm online của người tiêu dùng ngày càng tăng cao. Để đáp ứng nhu cầu thanh toán online này, TrueMoney phát triển hệ thống Cổng thanh toán online TrueMoney Pay, cung cấp các dịch vụ thanh toán thông qua Thẻ ATM nội địa, Thẻ thanh toán quốc tế (VISA, Master, JCB) và Ví điện tử TrueMoney. Không chỉ đem đến sự tiện lợi trong thanh toán cho người tiêu dùng, chúng tôi còn cung cấp sự tiện lợi trong tích hợp, vận hành, đối soát và thanh toán cho doanh nghiệp.
Đối với phương thức thanh toán qua Thẻ ATM nội địa, sau khi tích hợp, website/ứng dụng của doanh nghiệp có thể hiển thị nút thanh toán TrueMoney Pay để khách hàng hoàn tất thanh toán chỉ trong vài bước đơn giản:
- Khách hàng lựa chọn phương thức thanh toán qua Thẻ ATM nội địa và click nút thanh toán.
- Khách hàng được điều hướng tới Website của TrueMoney Pay và lựa chọn ngân hàng. Tại đây, tùy theo ngân hàng, khách hàng có thể nhập số thẻ/số tài khoản hoặc đăng nhập tài khoản internet banking để xác nhận thanh toán đơn hàng.
- Sau khi thanh toán hoàn tất, khách hàng sẽ được điều hướng trở lại trang mua hàng của doanh nghiệp cùng với kết quả thanh toán. Doanh nghiệp có thể kiểm tra kết quả thanh toán và thực hiện các bước tiếp theo.
2. Mô hình
TrueMoney Pay cung cấp Dịch vụ thanh toán thông qua ATM. Sau khi tích hợp thành công, Merchant có thể cung cấp phương thức thanh toán cho End-user qua các bước đơn giản sau.
Bước 1: End-user mua hàng trên Website/App của Merchant và lựa chọn thanh toán qua Thẻ ATM nội địa.
Bước 2: End-user được chuyển hướng tới trang thanh toán của TrueMoney Pay và lựa chọn ngân hàng thanh toán.
Bước 3: End-user nhập thông tin cá nhân.
Bước 4: Tùy theo ngân hàng, end-user được yêu cầu nhập Số thẻ/Số tài khoản và tài khoản Internet Banking để thực hiện các bước xác thực giao dịch.
Bước 5: End-user nhập OTP xác thực giao dịch.
Bước 6: End-user nhận thông báo thanh toán thành công và được chuyển hướng về trang mua hàng của Merchant.
3. Hướng dẫn
Các bước thực hiện:
- End-user click nút Thanh toán trên website/app của Merchant để thanh toán đơn hàng.
- Merchant thực hiện gọi web service (2) do-payment để lấy payment_url và trans_ref.
- Merchant chuyển hướng end-user tới payment_url (được TrueMoney Pay trả về khi gọi request do-payment).
- TrueMoney Pay hiển thị trang thanh toán, thực hiện giao dịch với end-user và hiển thị kết quả giao dịch cho end-user. TrueMoney Pay sẽ chuyển hướng end-user về return_url, đồng thời trả kết quả giao dịch cho Merchant qua return_url sau khi giao dịch kết thúc.
- TrueMoney Pay trả kết quả cho server của merchant qua IPN_url.
- Trong trường hợp quá 15 phút không nhận được kết quả giao dịch, Merchant có thể thực hiện gọi request transaction-detail tới TrueMoney Pay để kiểm tra kết quả giao dịch.
4. APIs kết nối
Mô tả chi tiết
(*): Những tham số bắt buộc phải truyền giá trị.
Tham số truyền dưới dạng Json Object.
(2) Request Do-payment
Địa chỉ nhận Request Charging:
POST https://partner.truemoney.com.vn/paymentgw/api/v1/do-payment
Max request time out: 30 giây
Tham số | Mô tả |
---|---|
access_key* string(255) |
Đại diện cho sản phẩm của merchant khai báo trong hệ thống TrueMoney Pay. |
amount* Bigdecimal |
Số tiền thanh toán hóa đơn. Yêu cầu số tiền thanh toán chẵn đồng. |
order_id* String(50) |
Mã hóa đơn là duy nhất, đại diện cho giao dịch, không vượt quá 50 kí tự. Tiếng Việt không dấu (A-z, 0-9). |
order_info* String(100) |
Mô tả hóa đơn. Tiếng Việt không dấu, không quá 100 kí tự. (A-z,0-9 space). |
return_url String(255) |
Địa chỉ url sau khi thực hiện thanh toán sẽ được redirect về, merchant cần xây dựng để nhận kết quả từ TrueMoney Pay gửi sang. Request do hệ thống TrueMoney Pay System gửi sang sẽ ở dạng HTTP GET. Nếu không có dữ liệu thì sẽ lấy theo setting của merchant với TrueMoney Pay. |
bank_code String(50) |
Mã ngân hàng do TrueMoney Pay định nghĩa(Sử dụng trong trường hợp chọn phương thức thanh qua ATM). Kết nối Wallet Charging thì truyền giá trị rỗng. |
wallet_code String(50) |
Mã ví do TrueMoney Pay định nghĩa(Sử dụng trong trường hợp chọn phương thức thanh toán qua ví). |
payment_type* Int |
0 (Nếu thanh toán bằng thẻ atm), 1 (Nếu thanh toán bằng thẻ quốc tế), hoặc 2 (thanh toán qua ví). Đối với kết nối Bank Charging thì truyền giá trị 0. |
customer_name String(255) |
Tên người thanh toán. |
customer_email String(50) |
Email người thanh toán. |
customer_phone String(50) |
Số điện thoại người thanh toán. |
language String(2) |
vi(Việt Nam),en(English). Nếu Merchant không yêu cầu ngôn ngữ thì sẽ hiển thị ngôn ngữ mặc định là Tiếng Việt |
signature* String(255) |
Chữ ký, merchant có thể sử dụng signature để kiểm soát an ninh Signature là một chuỗi string access_key=$access_key&amount=$amount&order_id=$order_id&order_info=$order_info&return_url=$return_url được hmac bằng thuật toán SHA256. |
(2′) Response Do-payment
Là một chuỗi json có chứa các giá trị sau:
{"response_code":"[code]","response_message":"[message]", "data":{"payment_url":"[url]","trans_ref":"[Mã giao dịch]"},"signature":"[Chữ kí]"}
Trong đó
Tham số | Mô tả |
---|---|
response_code | Map với bảng mã lỗi. Bảng 1 |
response _message | Thông báo chi tiết trạng thái kết nối. (sai chữ kí, sai access_key…) |
payment_url | Địa chỉ url để thực hiện submit request (redirect). |
trans_ref | Mã do TrueMoney Pay sinh ra. Mã giao dịch dùng để commit request, recheck và lưu lại trên hệ thống |
signature | Chữ ký, merchant có thể sử dụng signature để kiểm soát an ninh Signature là một chuỗi string response_code=$response_code&response_message=$response_message được hmac bằng thuật toán SHA256. |
(3) Submit(redirect) request
Thực hiện redirect request đến địa chỉ payment_url nhận được từ (2′), hệ thống TrueMoney Pay sẽ hiển thị nhập thông tin thẻ và thực hiện giao dịch với end user.
TrueMoney Pay sẽ trả kết quả giao dịch đồng thời qua link return_url và IPN
(3′) Response to return_url
Sau khi end user thực hiện thanh toán thẻ, TrueMoney Pay sẽ trả kết quả về cho Merchant qua địa chỉ return_url khai báo ở (2).
Tham số | Mô tả |
---|---|
access_key String(255) |
Đại diện cho sản phẩm của merchant khai báo trong hệ thống TrueMoney Pay. |
order_id String(50) |
Mã hóa đơn. |
trans_ref String(50) |
Mã do TrueMoney Pay. |
payment_type Int |
0 (Nếu thanh toán bằng Thẻ ATM nội địa), 1 (Nếu thanh toán bằng Thẻ quốc tế), hoặc 2 (thanh toán qua Ví). |
result_code String(10) |
Mã kết quả của giao dịch. (Bảng mã lỗi 1) |
description String(255) |
Mô tả thông tin giao dịch. |
language String(2) |
vi (Việt Nam), en (English). |
wallet_id String(50) |
Mã Ví thực hiện thanh toán (được trả về trong trường hợp thanh toán qua Ví TrueMoney). |
signature String(255) |
Chữ ký, merchant có thể sử dụng signature để kiểm soát an ninh Signature là một chuỗi string access_key=$access_key &order_id=$order_id&trans_ref=$trans_ref&payment_type=$payment_type&result_code=$result_code được hmac bằng thuật toán SHA256. |
(5) Send IPN (Instance Payment Notification)
Sau khi end user thực hiện thanh toán thẻ, TrueMoney Pay sẽ trả kết quả về cho Merchant qua địa chỉ IPN đã khai báo trên form đăng kí (Qua phương thức POST).
TrueMoney Pay sẽ gọi IPN của merchant tối đa 3 lần, mỗi lần cách nhau 5 phút.
Tham số | Mô tả |
---|---|
access_key String(255) |
Đại diện cho sản phẩm của merchant khai báo trong hệ thống TrueMoney Pay. |
trans_ref String(50) |
Mã do TrueMoney Pay. |
amount Bigdecimal |
Số tiền thanh toán. |
order_id String(50) |
Mã hóa đơn do Merchant truyền sang khi request tạo giao dịch. |
order_info String(100) |
Mô tả hóa đơn do Merchant truyền sang. |
payment_type Int |
0 (Nếu thanh toán bằng Thẻ ATM nội địa), 1 (Nếu thanh toán bằng Thẻ quốc tế), hoặc 2 (thanh toán qua Ví). |
bank_code String(50) |
Mã ngân hàng thanh toán. (Bảng mã lỗi 4) |
wallet_code String(50) |
Mã ví thanh toán |
payment_time String(50) |
Thời gian hoàn thành giao dịch(định dạng hh:mm:ss dd-mm-yyyy) |
result_code String(10) |
Map với bảng mã lỗi kết quả giao dịch bảng 1 |
description String(255) |
Miêu tả chi tiết lỗi. |
language String(2) |
vi (Việt Nam), en (English). |
wallet_id String(50) |
Mã Ví thực hiện thanh toán (được trả về trong trường hợp thanh toán qua Ví TrueMoney). |
signature | Chữ ký, merchant có thể sử dụng signature để kiểm soát an ninh Signature là một chuỗi string access_key=$access_key&order_id=$order_id&trans_ref=$trans_ref&payment_type=$payment_type&result_code=$result_code được hmac bằng thuật toán SHA256. |
(5′) Response IPN
Merchant sau khi nhận được kết quả qua IPN. merchant trả về cho TrueMoney Pay một kết quả là một chuỗi json có chứa các giá trị sau:
{"response_code":"[code]","response _message":"[message]"}
Trong đó
Tham số | Mô tả |
---|---|
response_code | Merchant cần gửi lại response để hệ thống TrueMoney Pay nhận biết trạng thái ghi nhận kết quả giao dịch của Merchant. Yêu cầu sử dụng mã lỗi được định nghĩa cho IPN (Bảng mã lỗi 2). Nếu Merchant trả lại mã 00 hoặc 01, TrueMoney sẽ dừng gửi IPN. Nếu không, TrueMoney sẽ gửi IPN cho Merchant tất cả 3 lần, mỗi lần cách nhau 5 phút. |
response _message | Miêu tả chi tiết lỗi. |
(6) Request Transaction- Detail
Thực hiện lệnh để lấy kết quả (trong trường hợp không nhận được kết quả giao dịch):
POST https://partner.truemoney.com.vn/paymentgw/api/v1/transaction-detail
Tham số | Mô tả |
---|---|
access_key* | Đại diện cho sản phẩm của merchant khai báo trong hệ thống TrueMoney Pay. |
trans_ref* | Mã giao dịch do TrueMoney Pay sinh ra. |
signature* | Chữ ký, merchant có thể sử dụng signature để kiểm soát an ninh. Signature là một chuỗi string: access_key=$access_key&trans_ref=$trans_ref được hmac bằng thuật toán SHA256. |
Là một chuỗi json có chứa các giá trị bao gồm
{"response_code":"[code]","response_message":"[message]", "data":{"trans_ref":"[Mã giao dịch]","amount":"[Số tiền]","order_id":"[Mã hóa đơn]","order_info":"[Mô tả]","payment_type":"[0]","bank_code":"[Mã ngân hàng]","wallet_code":"[Mã ví thanh toán]","status":"[Trạng thái]","refund_status":"[Trạng thái hoàn tiền]","request_time":"[Thời gian bắt đầu]","finish_time":"[Thời gian kết thúc]","result_code":"[Mã kết quả]","description":"[Chi tiết]"},"signature":"[Chữ kí]"}
Trong đó
Tham số | Mô tả |
---|---|
response_code | Mã lỗi bảng 3. |
response_message | Thông báo chi tiết . |
trans_ref | Mã giao dịch do TrueMoney Pay sinh ra. |
amount | Số tiền giao dịch . |
order_id | Mã hóa đơn . |
order_info | Mô tả hóa đơn . |
payment_type | 0 (Nếu thanh toán bằng Thẻ ATM nội địa), 1 (Nếu thanh toán bằng Thẻ quốc tế), hoặc 2 (thanh toán qua Ví). |
bank_code | Mã ngân hàng thanh toán. |
wallet_code | Mã ví thanh toán |
status | init(khởi tạo), processing(đang xử lý), success(thành công), fail(lỗi), timeout(hết hạn giao dịch). |
refund_status | Trạng thái refund: init(khởi tạo) ,success(thànhcông),fail(lỗi),timeout(hết hạn giao dịch). |
request_time | Thời gian bắt đầu(định dạng hh:mm:ss dd-mm-yyyy). |
finish_time | Thời gian hoàn thành giao dịch(định dạng hh:mm:ss dd-mm-yyyy) . |
result_code | Mã kết quả của giao dịch. (Bảng mã lỗi 1). |
description | Chi tiết message kết quả giao dich. |
signature* | Chữ ký, merchant có thể sử dụng signature để kiểm soát an ninh. Signature là một chuỗi string: response_code=$response_code&response_message=$response_message được hmac bằng thuật toán SHA256. |
Bảng mã lỗi thanh toán qua Thẻ nội địa,Thẻ quốc tế.
Bảng 1. Mã lỗi kết quả giao dịch
Kết quả giao dịch | Mô tả |
---|---|
00 | Giao dịch thành công. |
01 | Merchant không hợp lệ (Sai access key). |
02 | Dữ liệu gửi sang không đúng định dạng. |
03 | Ngân hàng không được hỗ trợ. |
04 | Chữ ký không hợp lệ. |
05 | Tài khoản khách hàng không đủ điều kiện thanh toán. |
06 | Số tiền giao dịch không hợp lệ(nhỏ hơn hoặc vượt quá hạn mức). |
07 | Giao dịch nhỏ hơn hạn mức tối thiểu một lần thanh toán. |
08 | Giao dịch vượt quá hạn mức tối đa một lần thanh toán. |
09 | Giao dịch vượt quá hạn mức tối đa thanh toán ngày/tuần/tháng. |
10 | Khách hàng nhập sai OTP quá số lần cho phép. |
11 | Giao dịch vượt quá số lần tối đa bỏ qua xác thực OTP trong ngày cho một dịch vụ. |
12 | Khách hàng hủy giao dịch. |
13 | Giao dịch không thành công do quá thời gian quy định. |
14 | Lỗi giao dịch,cần kiểm tra lại với ngân hàng. |
15 | Giao dịch chờ xác nhận từ ngân hàng. |
16 | Lỗi kết nối đến ngân hàng. |
17 | Hệ thống đang bảo trì. |
18 | Địa chỉ IP không được phép truy cập. |
19 | Không tìm thấy giao dịch. |
24 | Số lần giao dịch vượt quá hạn mức tối đa ngày/tuần/tháng. |
25 | Ngân hàng từ chối giao dịch. |
26 | Thẻ thanh toán nằm trong dánh sách nghi vấn,giao dịch bị tạm giữ tiền để kiểm tra. |
99 | Lỗi không xác định được nguyên nhân,vui lòng liên hệ để tra soát. |
Bảng 2. Mã lỗi Merchant trả kết quả cập nhật Instant Payment Notification.
Kết quả giao dịch | Mô tả |
---|---|
00 | Ghi nhận kết quả giao dịch thành công. |
01 | Yêu cầu đã được xử lý trước đó. |
02 | Không tìm thấy mã đơn hàng. |
99 | Lỗi không xác định được nguyên nhân,vui lòng liên hệ để tra soát. |
Bảng 3. Mã lỗi kiểm tra kết quả giao dịch
Kết quả giao dịch | Mô tả |
---|---|
00 | Thành công. |
01 | Merchant không hợp lệ (Sai access key). |
02 | Dữ liệu gửi sang không đúng định dạng. |
04 | Chữ ký không hợp lệ. |
17 | Hệ thống đang bảo trì. |
18 | Địa chỉ IP không được phép truy cập. |
19 | Không tìm thấy giao dịch. |
99 | Lỗi không xác định được nguyên nhân,vui lòng liên hệ để tra soát. |
Bảng 4. Bảng danh sách Ngân hàng hỗ trợ
5. Code mẫu
6. Sandbox
API URL môi trường Sandbox:
POST https://payment.truemoney.com.vn/sandbox/api/v1/do-payment
Tra cứu giao dịch Test trên môi trường Sandbox:
POST https://payment.truemoney.com.vn/sandbox/ui/v1/transaction-log
Chọn ngân hàng thanh toán qua TPBank:
Tài khoản test case thành công, đủ số dư, đủ điều kiện thanh toán
- Tài khoản: 9704 2300 0000 0001
- Tên chủ thẻ: NGUYEN VAN A
- Ngày phát hành: 09/2018
- OTP: 123456
Tài khoản không đủ số dư
- Tài khoản: 9704 2300 0000 0002
- Tên chủ thẻ: NGUYEN VAN A
- Ngày phát hành: 09/2018