Thanh Toán Liên Kết Thẻ
Luồng Xử Lý
Sơ đồ hoạt động
Diễn giải sơ đồ
Thanh toán lần đầu và lưu thẻ
- Bước 1: Khách hàng (người dùng) tiến hành thanh toán bằng hình thức thanh toán qua thẻ thanh toán quốc tế do MoMo cung cấp.
- Bước 2: Hệ thống đối tác khởi tạo đơn hàng với thông tin đơn hàng cùng mã đơn hàng (orderid) duy nhất để yêu cầu phương thức thanh toán phù hợp nhất.
- Bước 3: Sau khi xác thực thông tin đối tác, MoMo trả về URL thanh toán (payUrl).
- Bước 4: Thanh toán bằng payUrl được trả về khi người dùng thực hiện trên trang của đối tác. Đối tác điều hướng người dùng tới website của MoMo thông qua payUrl lấy được từ bước 3.
- Bước 5,6: Khách hàng tiến hành nhập thông tin thẻ Credit và thanh toán.
- Bước 7:MoMo xử lý thanh toán, sau đó trả về kết quả thanh toán giao dịch, đồng thời điều hướng người dùng về lại web/app của đối tác.
- Bước 8: Đối tác nhận kết quả thanh toán của mã đơn hàng và callbackToken từ MoMo thông qua callback/response/ipn, sau đó hiển thị kết quả cho user.
- Bước 9: Đối tác dùng cbToken nhận được gọi hàm lần nữa để lấy token thanh toán (recurring token) từ MoMo. Token này được sử dụng cho những lần thanh toán sau.
- Bước 10: MoMo response recuring token as aesToken & return to merchant
- Bước 11: Sau khi nhận, đối tác giải mã aesToken, lấy thông tin token thanh toán để lưu trữ trong hệ thống, và sử dụng token này cho những thanh toán sau.
Thanh toán tiếp theo
- Bước 12: Khách hàng thêm sản phẩm vào giỏ hàng và lựa chọn thanh toán bằng thẻ.
- Bước 13: Hệ thống đối tác khởi tạo phiên thanh toán, gửi yêu cầu thanh toán kèm aesToken tới MoMo.
- Bước 14: MoMo xử lý thanh toán, sử dụng hashToken (token được mã hóa). MoMo thông báo kết quả tới đối tác và điều hướng người dùng về lại trang của đối tác.
- Bước 15: Đối tác kiểm tra kết quả thanh toán và hiển thị hoặc cập nhật kết quả này trên web/app của mình.
Cấu Hình API
Phương thức thiết lập liên kết
HTTP RequestPOST /v2/gateway/api/create
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String(20) | Mã đối tác Thông tin tích hợp | |
requestId | String(50) | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency | |
amount | String(20) | Số tiền cần thanh toán Nhỏ Nhất: 1.000 VND Tối đa: 10.000.000 VND Tiền tệ: VND Kiểu dữ liệu: Long | |
orderId | String(50) | Mã đơn hàng của đối tác | |
orderInfo | String(200) | Thông tin đơn hàng | |
redirectUrl | String(200) | Một URL của đối tác. URL này được sử dụng để chuyển trang (redirect) từ MoMo về trang mua hàng của đối tác sau khi khách hàng thanh toán. Hỗ trợ: AppLink and WebLink | |
ipnUrl | String(200) | API của đối tác. Được MoMo sử dụng để gửi kết quả thanh toán theo phương thức IPN (server-to-server) | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
extraData | String | Giá trị mặc định là rỗng"" Encode base64 theo định dạng Json: {"key": "value"} Ví dụ với dữ liệu: {"username": "momo"} thì data extraData : eyJ1c2VybmFtZSI6ICJtb21vIn0= | |
userInfo | Object | Thông tin người dùng. Trong đó email là bắt buộc. | |
requestType | String(20) | payWithCC | |
lang | String(20) | Ngôn ngữ của message được trả về (vi hoặc en ) | |
signature | String(65) | HMAC_SHA256accessKey=$accessKey&amount=$amount &extraData=$extraData&ipnUrl=$ipnUrl&orderId=$orderId &orderInfo=$orderInfo&partnerClientId=$partnerClientId &partnerCode=$partnerCode&redirectUrl=$redirectUrl &requestId=$requestId&requestType=$requestType, secretKey) |
Chi tiết nội dung của userInfo
:
Attribute | Type | Required | Description |
---|---|---|---|
name | String | Tên của người dùng | |
phoneNumber | String | Số điện thoại của người dùng | |
String | Email của người dùng |
{
"partnerCode": "MOMOIQA420180417",
"accessKey": "SvDmj2cOTYZmQQ3H",
"requestId": "1516771499398",
"amount": "0",
"orderId": "1516771499398",
"userInfo": {
"email": "email_add@domain.com",
}
"ipnUrl": "http://example.com",
"redirectUrl": "http://example.com",
"partnerClientId": "abc@gmail.com",
"requestType": "payWithCC",
"lang": "vi",
"extraData": "eyJlbWFpbCI6ICJleGFtcGxlQGdtYWlsLmNvbSJ9",
"signature": "ca3c203f0c16873e688fada17…ee116b636ff407d6fe39"
}
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
requestId | String | Giống với yêu cầu ban đầu | |
orderId | String | Mã đơn hàng của đối tác | |
payUrl | String | URL để chuyển từ trang mua hàng của đối tác sang trang thanh toán của MoMo | |
resultCode | int | Error code | |
message | String | Mô tả trạng thái, ngôn ngữ dựa trên lang | |
responseTime | Long | Thời gian trả kết quả thanh toán về đối tác. Định dạng: timestamp | |
partnerClientId | String(50) | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo |
Example
{
"partnerCode": "MOMOIOLD20190129",
"requestId": "1616577794003",
"orderId": "1616577794003:0123456778",
"amount": 10000,
"responseTime": 1616577795018,
"message": "Thành công",
"resultCode": 0,
"payUrl": "https://test-payment.momo.vn/gateway/pay?t=TU9NT...NTY3Nzg=",
"partnerClientId": "932024090117"
}
Xử lý kết quả thanh toán
Tìm hiểu thêm về Payment Notification.
Mô tả tham số
Bảng mô tả các tham số được MoMo đính kèm trong trong URL redirectUrl
và nội dung body của ipnUrl
.
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
orderId | String | Mã đơn hàng của đối tác | |
requestId | String | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency | |
amount | Long | Giống với số tiền yêu cầu thanh toán ban đầu | |
partnerUserId | String | Định danh duy nhất của MoMo cho mỗi tài khoản ví MoMo. | |
orderInfo | String | Thông tin hóa đơn | |
orderType | String | momo_wallet | |
transId | Long | transaction ID của MoMo | |
resultCode | Integer | Result Code | |
message | String | Mô tả trạng thái giao dịch, ngôn ngữ dựa trên lang | |
payType | String | Loại thanh toán: credit | |
responseTime | Long | Thời gian trả kết quả thanh toán về đối tác Định dạng:: timestamp | |
extraData | String | Extra Data. Mặc định: "" | |
signature | String | Chữ ký để xác nhận giao dịch. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng được sort từ a-z : accessKey=$accessKey&amount=$amount&extraData=$extraData &message=$message&orderId=$orderId&orderInfo=$orderInfo &orderType=$orderType&partnerCode=$partnerCode&payType= $payType&requestId=$requestId&responseTime= $responseTime&resultCode=$resultCode&transId=$transId |
Example
{
"partnerCode": "123456",
"requestId": "1527246504579",
"orderId": "1527246478428",
"partnerClientId": "MoMoAccountTest",
"lang": "vi",
"signature": "13be80957a5ee32107198920fa26aa85a4ca238a29f46e292e8c33dd9186142a"
}
Attribute | Type | Description |
---|---|---|
partnerCode | String | Mã đối tác |
requestId | String | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency |
orderId | String | Mã đơn hàng của đối tác |
callbackToken | String | Callback token được khởi tạo bởi MoMo |
resultCode | int | Mã trạng thái giao dịch |
message | String | Mô tả kết quả giao dịch dựa trên lang |
responseTime | long | Thời gian phản hồi |
Example
{
"partnerCode": "123456",
"requestId": "1527246504579",
"orderId": "1527246478428",
"callbackToken ": "u7YYQZnAbLQivB0p5SHT9LIhjshqarXyobE_WzCCa4vDt58r",
"resultCode": 0,
"message": "Success",
"signature": "d4affc86b0894aa5e6ec48c43144b9c86bf770fe2e9fcc3cfb5e27871135806f",
"responseTime": 127264428
}
Lấy token thanh toán (recurring token)
Sau khi nhận callbackToken
từ kết quả giao dịch, bên đối tác sẽ gởi yêu cầu đến MoMo để lấy thông tin token của user
POST /v2/gateway/api/tokenization/bind
Parameter | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
callbackToken | String | callbackToken token được sử dụng gọi bind để lấy được token thanh toán | |
requestId | String | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency | |
orderId | String | Phải trùng với orderId gọi payWithCC | |
partnerClientId | String | Phải trùng với partnerClientId gọi payWithCC | |
lang | String | Ngôn ngữ của message được trả về (vi hoặc en ) | |
signature | String | Chữ ký để xác nhận giao dịch. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng được sort từ a-z : accessKey=$accessKey&callbackToken=$callbackToken&orderId= $orderId&partnerClientId=$partnerClientId&partnerCode= $partnerCode&requestId=$requestId |
Example request
{
"partnerCode": "MOMO_ATM_DEV",
"requestId": "03dc5a00-b37c-11e9-b3a3-2f10f50d933d",
"callbackToken": "v2/qml0PbOlrBYjFlZv…8StiawfZPiKoUGvywNHV",
"orderId": "03dc32f0-b37c-11e9-b3a3-2f10f50d933d",
"partnerClientId": "user@momo.vn",
"signature": "fa8b66df31cc7045783323f1e4492d7b71c1de4c9e1b71002f95a1aa869e885a",
"lang": "vi"
}
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
requestId | String | requestId của đối tác | |
orderId | String | Mã đơn hàng của đối tác | |
aesToken | String | token object json encrypted using AES | |
resultCode | Integer | Result Code | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
responseTime | Long | Thời gian trả kết quả thanh toán về đối tác. Định dạng: timestamp | |
message | String | Mô tả lỗi, ngôn ngữ dựa trên lang |
Data of token after decrypted
Attribute | Type | Required | Description |
---|---|---|---|
value | String | dùng để thanh toán bằng token | |
cardNumber | String | Số thẻ (chỉ hiển thị 4 số thẻ cuối) | |
cardType | String | MASTERCARD , VISA or JCB |
Example response
{
"timestamp": 1600678154664,
"partnerCode": "MOMO_ATM_DEV",
"requestId": "03dc5a00-b37c-11e9-b3a3-2f10f50d933d",
"orderId": "03dc32f0-b37c-11e9-b3a3-2f10f50d933d",
"partnerClientId": "user@momo.vn",
"resultCode": 0,
"responseTime": 145784525,
"message": "Success",
"aesToken": "NplHKEhGuFoo5o5vbMeJwrsk7wXEPnCjSZv6DgivW1a8JKw1gdXq2WS7UsPwoJv0yf6rbGiVV6nOKAxU8kTNg4SZraqJnf7GAq9OSE2LiNs="
}
Sau khi nhận aesToken từ MoMo, Server bên đối tác phải giải mã aesToken để lấy giá trị ban đầu của token và lưu trữ nó trong hệ thống bên phía đối tác. Việc giải mã token thanh toán bằng thuật toán AES thì cần có secrect key
có thể được tìm thấy ở https://business.momo.vn
Example:
private static String decrypt_AES(String sercretKey, String encryptData) {
try {
IvParameterSpec iv = new IvParameterSpec(new byte[16]);
SecretKeySpec skeySpec = new SecretKeySpec(sercretKey.getBytes("UTF-8"), "AES");
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5PADDING");
cipher.init(Cipher.DECRYPT_MODE, skeySpec, iv);
byte[] original = cipher.doFinal(Base64.decodeBase64(encryptData));
return new String(original);
} catch (Exception ex) {
ex.printStackTrace();
}
return "";
}
Thanh toán bằng Token
Đối tác có thể dùng token đã lấy trước đó để thực hiện thanh toán
HTTP RequestPOST /v2/gateway/api/tokenization/pay
Parameter | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
partnerName | String | Tên đối tác | |
storeId | String | Mã cửa hàng | |
orderId | String | Mã đơn hàng của đối tác | |
amount | Long | Số tiền cần thanh toán Nhỏ Nhất: 1.000 VND Tối đa: 10.000.000 VND Tiền tệ: VND Kiểu dữ liệu: Long | |
requestId | String(50) | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency | |
token | String | Token Json object đã được mã hóa bằng RSA sử dụng public Key RSA Encryption | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
orderInfo | String | Mô tả chi tiết | |
autoCapture | Boolean | Nếu giá trị là false thì cần bên đối tác gọi api confirm để thực hiện capture cho việc thanh toán. | |
redirectUrl | String | Một URL của đối tác. URL này được sử dụng để chuyển trang (redirect) từ MoMo về trang mua hàng của đối tác sau khi khách hàng thanh toán. Hỗ trợ: AppLink and WebLink | |
ipnUrl | String | API của đối tác. Được MoMo sử dụng để gửi kết quả thanh toán theo phương thức IPN (server-to-server) | |
extraData | String | Giá trị mặc định "" Encode base64 theo Jsonformat: {"key": "value"} Ví dụ với data: {"username": "momo"} => được encode sang extraData : eyJ1c2VybmFtZSI6ICJtb21vIn0= | |
lang | String | Ngôn ngữ của message được trả về (vi hoặc en ) | |
signature | String | Chữ ký để xác nhận giao dịch. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng được sort từ a-z : accessKey=$accessKey&amount=$amount&extraData=$extraData &orderId=$orderId&orderInfo=$orderInfo&partnerClientId= $partnerClientId&partnerCode=$partnerCode&requestId= $requestId&token=$token |
Dữ liệu của token trước khi được mã hõa
Attribute | Type | Required | Description |
---|---|---|---|
value | String | giá trị của token | |
requireSecurityCode | Boolean | Nếu giá trị là false khi tham số security code không được dùng thì nó sẽ không điều hướng đến trang chứa form để điền security code, mà thanh toán sẽ được gửi trực tiếp đến bên cung cấp |
Example request
{
"token": "sa5s4a54s5a4s5a4s5",
"partnerCode": "MOMO_ATM_DEV",
"partnerName": "Test",
"storeId": "MoMo test store",
"ipnUrl": "abc.com",
"redirectUrl": "abc.com",
"orderId": "12545465654656",
"amount": "20000",
"lang": "vi",
"autoCapture": true,
"orderInfo": "Thanh toan MoMo",
"requestId": "365656d56sd",
"extraData": "",
"partnerClientId": "test@momo.vn",
"signature": "2512s1d2s1ds21d2s1d1ce5d1a251#@"
}
Nếu nhận được resultCode 8000
thì sẽ được cung cấp payUrl ở kết quả trả về, payUrl đó sẽ dùng để điều hướng khách đến trang thanh toán
HTTP Response
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
orderId | String | Mã đơn hàng của đối tác | |
requestId | String | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency | |
amount | Long | Amount to pay | |
transId | Long | Mã giao dịch của MoMo | |
responseTime | Long | Thời gian trả kết quả thanh toán về đối tác. Định dạng: timestamp | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
resultCode | Integer | Result Code | |
message | String | Mô tả kết quả, ngôn ngữ dựa trên lang | |
payUrl | String | URL để chuyển từ trang mua hàng của đối tác sang trang thanh toán của MoMo |
Example response
{
"partnerCode": "MOMO_ATM_DEV",
"requestId": "1599645548172",
"orderId": "1599645548172:0123456778",
"amount": 50000,
"responseTime": 145758545,
"partnerClientId": "user@momo.vn",
"resultCode": 0,
"message": "Success"
}
Xóa token
Đối tác có thể tạo request để xóa token đã lưu bên MoMo
HTTP RequestPOST /v2/gateway/api/tokenization/delete
Parameter | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
requestId | String(50) | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency | |
orderId | String | Mã đơn hàng của đối tác | |
storeId | String | Mã cửa hàng | |
token | String | Token Json object đã được mã hóa bằng RSA sử dụng public Key RSA Encryption | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
lang | String | Ngôn ngữ của message được trả về (vi hoặc en ) | |
signature | String | Chữ ký](/docs/payment/api/other/signature) để xác nhận giao dịch. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng được sort từ a-z : accessKey=$accessKey&orderId=$orderId&partnerClientId= $partnerClientId&partnerCode=$partnerCode&requestId= $requestId&token=$token |
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Thông tin tích hợp | |
requestId | String | Each Request’s Identification | |
message | String | Mô tả kết quả, ngôn ngữ dựa trên lang | |
resultCode | Integer | Result Code | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
responseTime | Long | Thời gian trả kết quả thanh toán về đối tác. Định dạng: timestamp |
Example response
{
"partnerCode": "MOMO_ATM_DEV",
"orderId": "1600838954650:0123456778",
"requestId": "1600838954650",
"resultCode": 0,
"message": "Success",
"partnerClientId": "test@momo.vn",
"responseTime": 14548754653232
}
Hủy liên kết
Request header:
application/jsonResponse header:
application/json
MoMo cho phép xóa thẻ từ UI nhà MoMo.
Đối tác phải cung cấp endpoint để nhận thông báo về liên kết được hủy từ MoMo, sử dụng HTTP POST.
HTTP RequestAttribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Mã đối tác | |
requestId | String | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý | |
orderId | String | Mã đơn hàng đã gọi payWithCC | |
partnerClientId | String | Định danh của mỗi user (e.g.: user ID hoặc email). Id này sẽ được dùng để liên kết với user của MoMo | |
tokenType | String | credit | |
requestType | String | remove | |
signature | String | Chữ ký để xác nhận giao dịch. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng được sort từ a-z : accessKey=$accessKey&orderId=$orderId&partnerClientId=$partnerClientId &partnerCode=$partnerCode&requestId=$requestId &requestType=$requestType&tokenType=$tokenType |
Ví dụ
{
"partnerCode": "MOMOIQA420180417",
"requestId": "0e0ceb2a-ea06-4ca7-b63a-e5c8948a5bfc",
"orderId": "012457855:231454545",
"partnerClientId": "sang@momo.com.vn",
"requestType": "remove",
"tokenType": "credit",
"signature": "bd4df3f3bad6815a9a7be1f1f5c8576f3f97eab25327247425f12a3fb4a78873"
}
Bạn cần phản hồi với HTTP code 204 (No Content)!
Truy vấn CallbackToken
Hệ thống đối tác không thể nhận hoặc lưu callbackToken có thể gửi yêu cầu đến MoMo để truy vấn callbackToken.
Request header:
application/json - Response header:
application/json
POST /v2/gateway/api/tokenization/cbQuery
Attribute | Type | Required | Description |
---|---|---|---|
partnerCode | String | Mã đối tác | |
requestId | String | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency | |
orderId | String | Phải trùng với orderId gọi payWithCC | |
partnerClientId | String | phải trùng với partnerClientId gọi payWithCC | |
lang | String | vi hoặc en | |
signature | String | Chữ ký để xác nhận giao dịch. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng được sort từ a-z : accessKey=$accessKey&orderId=$orderId &partnerClientId=$partnerClientId&partnerCode=$partnerCode &requestId=$requestId |
Result Codes & Messages
Các result codes và mô tả tương ứng này được chỉ định riêng cho luồng Thanh toán Liên kết Thẻ của Thanh toán thẻ Quốc tế. Ngoài ra, vui lòng tìm kiếm những mã khác trong danh sách result codes tổng hợp ở đây.
Result code | Description | Final Status | Recommended actions | Type |
---|---|---|---|---|
0 | Thành công. | Yes | ||
1002 | Giao dịch bị từ chối do nhà phát hành tài khoản thanh toán. | Yes | Sự từ chối xảy ra khi thẻ được dùng để thanh toán hiện không còn khả dụng, hoặc kết nối đến hệ thống của nhà phát hành thẻ bị gián đoạn. Vui lòng tạm thời sử dụng phương thức thanh toán khác. | User error |
2001 | Giao dịch thất bại do sai thông tin liên kết. | Yes | Token liên kết không tồn tại hoặc đã bị xóa, vui lòng cập nhật dữ liệu của bạn. | Merchant error |
2007 | Giao dịch thất bại do liên kết hiện đang bị tạm khóa. | Yes | Token liên kết hiện đang ở trạng thái không hoạt động, do người dùng đã chủ động tạm khóa liên kết. | User error |
2012 | Yêu cầu bị từ chối vì token không khả dụng. | Yes | Token không tồn tại hoặc đã bị xóa. Không thể cập nhật trạng thái token. | Merchant error |
4010 | Quá trình xác minh OTP thất bại. | Yes | Quá trình xác minh người dùng thất bại. Vui lòng gửi một yêu cầu xác minh người dùng khác để thử lại. | User error |
4011 | OTP chưa được gửi hoặc hết hạn. | Yes | Vui lòng yêu cầu gửi một mã OTP khác. | User error |
4015 | Quá trình xác minh 3DS thất bại. | Yes | Quá trình xác minh người dùng thất bại. Vui lòng gửi một yêu cầu xác minh người dùng khác để thử lại. | User error |