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 Ví điện tử TrueMoney, 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 và click nút thanh toán.
- Khách hàng được điều hướng tới Website của TrueMoney Pay, hoặc mở ứng dụng Ví điện tử TrueMoney (nếu ứng dụng được cài đặt trên thiết bị di động). Tại đây, khách hàng có thể đăng nhập tài khoản Ví và 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.
- Trong cùng thời gian đó, TrueMoney Pay cũng gửi thông báo kết quả giao dịch IPN (Instant Payment Notification) tới doanh nghiệp. IPN được xây dựng và gửi để phòng ngừa trường hợp kết quả giao dịch được gửi khi điều hướng lại trang của Merchant bị gián đoạn.
2. Mô hình
Bước 1: End-user mua hàng trên Website/App của Merchant và lựa chọn thanh toán qua Ví điện tử TrueMoney.
Bước 2: End-user được chuyển hướng tới trang thanh toán của TrueMoney Pay và được yêu cầu nhập thông tin xác thực tài khoản TrueMoney.
Bước 3: End-user đăng nhập tài khoản thành công, nhập OTP được gửi tới số điện thoại để xác nhận.
Bước 4: 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.
- Trong một số trường hợp, end-user muốn hoàn tiền hoặc hủy giao dịch. End-user gửi yêu cầu hoàn tiền tới merchant. Trong trường hợp này, Merchant có thể gọi web service refund để yêu cầu hoàn tiền giao dịch. TrueMoney Pay sau khi nhận yêu cầu hoàn tiền sẽ phối hợp với phía nhà cung cấp để hoàn tiền cho end-user.
4. APIs kết nối
(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í). Giá trị cố định: TRUEMONEY |
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 Wallet Charging thì truyền giá trị 2. |
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, refund 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. (Giao dịch Ví không trả kết quả này) |
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":"[2]","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. |
(8) API hoàn tiền
Merchant thực hiện lệnh để hoàn tiền (Trong trường hợp cần hoàn tiền):
POST https://partner.truemoney.com.vn/paymentgw/api/v1/refund
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. |
refund_info* | Lý do hoàn tiền. Tiếng Việt không dấu, không quá 100 kí tự. (A-z, 0-9, space). |
refund_type* | 0: hoàn tiền toàn phần, 1: hoàn tiền một phần (Hiện tại chỉ hỗ trợ hỗ trợ hoàn tiền toàn phần cho thanh toán qua Ví, chưa hỗ trợ hoàn tiền một phần, toàn phần cho bank visa). |
refund_amount | Trong trường hợp hoàn tiền 1 phần, cần truyền cụ thể giá trị hoàn |
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 |
(8′) Response Refund Transaction
Sau khi TrueMoney Pay nhận được request sẽ trả về kết quả cho Merchant dưới dạng sau:
Chưa hỗ trợ hoàn tiền 1 phần
{"response_code":"[code]","response_message":"[message]", "data":{"trans_ref":"[Mã giao dịch gốc]","refund_ref":"[Mã giao dịch hoàn tiền]","refund_info":"[Lý do hoàn tiền]","refund_type":"[Kiểu hoàn tiền]","refund_amount":"[Số tiền hoàn]","refund_time":"[Thời gian hoàn]","refund_code":"[Mã kết quả]","refund_message":"[Chi tiết hoàn tiền]"},"signature":"[Chữ kí]"}
Tham số | Mô tả |
---|---|
response_code | Mã lỗi bảng 4 |
response_message | Miêu tả chi tiết lỗi. |
data | Object giao dịch hoàn tiền |
trans_ref | Mã giao dịch gốc |
refund_ref | Mã giao dịch hoàn tiền |
refund_info | Lý do hoàn tiền |
refund_type | 0: hoàn tiền toàn phần, 1: hoàn tiền 1 phần |
refund_amount | Số tiền hoàn. |
refund_time | Thời gian hoàn tiền(định dạng hh:mm:ss dd-mm-yyyy) |
refund_code | Mã kết quả giao dịch hoàn tiền (Map với bảng mã lỗi giao dịch hoàn tiền). |
refund_message | Chi tiết message hoàn tiền |
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 Ví.
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 | Chữ ký không hợp lệ. |
04 | Khách hàng nhập sai thông tin đăng nhập quá số lần cho phép. |
05 | Tài khoản khách hàng không đủ điều kiện thanh toán. |
06 | Tài khoản khách hàng không đủ số dư thanh toán. |
07 | Số tiền giao dịch không hợp lệ(nhỏ hơn hoặc vượt quá hạn mức). |
08 | Giao dịch nhỏ hơn hạn mức tối thiểu một lần thanh toán. |
09 | Giao dịch vượt quá hạn mức tối đa một lần thanh toán. |
10 | Giao dịch vượt quá hạn mức tối đa thanh toán ngày/tuần/tháng. |
11 | Khách hàng nhập sai OTP/PIN quá số lần cho phép. |
12 | Số lần gửi lại OTP quá số lần cho phép. |
13 | Khách hàng hủy giao dịch. |
14 | Giao dịch không thành công do quá thời gian quy định. |
15 | Giao dịch chờ xác nhận từ hệ thống Ví. |
16 | Lỗi kết nối đến nhà cung cấp. |
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. |
23 | Số lần giao dịch vượt quá hạn mức tối đa ngày/tuần/tháng. |
25 | Giao dịch thất bại do nằm ngoài hạn mức 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 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 | Giao dịch đã đượ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. |
03 | 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. Mã lỗi hoàn tiền
Kết quả giao dịch | Mô tả |
---|---|
00 | Hoàn tiền 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 | Chữ ký không hợp lệ. |
16 | Lỗi kết nối đến nhà cung cấp. |
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. |
20 | Giao dịch được yêu cầu hoàn tiền không thành công. |
21 | Giao dịch đã được hoàn tiền trước đó. |
22 | Giao dịch đã yêu cầu hoàn tiền trước đó, đang được xử lý. |
24 | Giao dịch đã hết hạn hoàn tiền. |
99 | Lỗi không xác định được nguyên nhân,vui lòng liên hệ để tra soát. |
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
Tài khoản test case thành công, đủ số dư, đủ điều kiện thanh toán:
- Tài khoản: 0987654000
- Mật khẩu: 123456
- OTP: 999999
Tài khoản không đủ số dư:
- Tài khoản: 0987654001
- Mật khẩu: 123456