Thanh toán Linked Account

Giới thiệu dịch vụ

Là giải pháp thanh toán hỗ trợ các đối tác, đơn vị kinh doanh có website hoặc ứng dụng di động (Android, iOS).

Khách hàng sau khi đã liên kết tài khoản ví VinID Pay với ứng dụng của đối tác, tại bước chọn phương thức thanh toán, khách hàng chỉ cần chọn VinID Pay để thanh toán trực tiếp ở ứng dụng đối tác mà không cần phải thực hiện thêm thao tác gì hay mở ứng dụng VinID.

Luồng người dùng sử dụng dịch vụ

Sơ đồ xử lý kỹ thuật

1.Liên kết

2. Thanh toán

Giải thích sơ đồ

Liên kết

1. Khách hàng chọn liên kết tài khoản ví VinID Pay làm phương thức thanh toán trên hệ thống của Merchant.

2. Merchant Backend kiểm tra yêu cầu liên kết và gửi yêu cầu liên kết cho VinID Pay Backend.

3. VinID Pay Backend kiểm tra và thực hiện khởi tạo liên kết, trả về ID và url cho Merchant Backend.

4. Merchant Backend lưu thông tin và thực hiện: a. Trên thiết bị di động, mở url đã nhận → Hệ thống sẽ mở web hoặc app VinID Pay để khách hàng xác nhận. b. Trên các thiết bị IoT, generate mã QR liên kết và hiển thị mã QR cho khách hàng.

5. Khách hàng thực hiện xác nhận nếu liên kết trên thiết bị di động hoặc sử dụng app VinID Pay để quét mã QR.

6. Khách hàng xác nhận liên kết

7. Sau khi xác nhận liên kết thành công, VinID Pay Backend gọi API của Merchant Backend để thực hiện thông báo kết quả liên kết đồng thời quay lại ứng dụng của Merchant. Merchant Backend gọi API kiểm tra trạng thái liên kết nếu không nhận được kết quả.

8. Merchant hiển thị kết quả liên kết trên ứng dụng của Merchant.

Thanh toán

1. Khách hàng lựa chọn sản phẩm/dịch vụ trên ứng dụng của Merchant và lựa chọn thanh toán qua liên kết tài khoản VinID Pay.

2. Merchant Backend yêu cầu khách hàng xác nhận trước khi thực hiện thanh toán

3. Sau khi khách hàng xác nhận thanh toán, Merchant Backend kiểm tra và gửi yêu cầu thanh toán cho VinID Pay Pay Backend.

4. VinID Pay Backend kiểm tra yêu cầu thanh toán và thực hiện: a. Nếu số tiền thanh toán nằm trong hạn mức ko cần xác thực, VinID Pay Backend thực hiện trừ tiền của ví khách hàng và trả về kết quả giao dịch cho Merchant Backend. b. Nếu số tiền thanh toán nằm trong hạn mức yêu cầu xác thực, VinID Pay Backend thực hiện khởi tạo giao dịch và trả về thông tin giao dịch cho Merchant Backend.

5. Merchant Backend nhận thông tin giao dịch: a. Nếu giao dịch không yêu cầu xác thực, Merchant Backend thực hiện lưu thông tin và thông báo kết quả cho khách hàng b. Nếu giao dịch yêu cầu xác thực (OTP), Merchant Frontend mở màn hình nhập OTP để khách hàng xác nhận. Sau khi khách hàng nhập OTP, Merchant Backend gửi thông tin xác thực cho VinID Pay Backend. VinID Backend kiểm tra thông tin, thực hiện trừ tiền ví khách hàng và trả về kết quả giao dịch.

6. Kết quả giao dịch: a. Với trường hợp merchant muốn xác nhận lại trạng thái đơn hàng, VinID Pay sẽ trừ tiền ví user trước và thực hiện HOLD tiền và báo lại đã HOLD tiền. Merchant sẽ thực hiện confirm lại đơn hàng đã thanh toán và VinID Pay sẽ update giao dịch thành công và báo lại. b. Với trường hợp không cần xác nhận từ phía merchant, VinID Pay sẽ thực hiện trừ tiền ví, ghi nhận giao dịch thành công luôn và báo lại cho merchant.

7. Merchant Frontend hiển thị kết quả giao dịch cho khách hàng.

APIs

Create link request

POST https://api-payment-uat.vinid.dev/oh-integration/account/v1/link-wallet

Request Body

Name	Type	Description
signature	string	signature = sign(<partner_user_id>|<partner_code>|<callback_url>) Cần thực hiện ký số (SHA 256, RSA 2048) bằng private_key
callback_url	string	URL của API callback sau khi liên kết thành công. Trong API Callback VinID sẽ gửi thông tin token sau liên kết và thông tin điện thoại của user
partner_type	string	Default value = MERCHANT
partner_code	string	Mã định danh của Merchant tại VinID Pay
partner_user_id	string	Unique user identify on merchant system (user name, email, phone_number...)

200

{
    "data": {
        "web_url": "string",
        "link_id": "string",
        "expiry_duration": int       //expire time (minute)
    }
    "meta": {
    }
}

Check link status

POST https://api-payment-uat.vinid.dev/oh-integration/account/v1/check-status-link-wallet

Request Body

Name	Type	Description
signature	string	Signature = sign (<partner_user_id>|<partner_code>|<callback_url>) Cần thực hiện ký số (SHA 256, RSA 2048) bằng private_key
partner_code	string	Mã định danh của Merchant tại VinID Pay
link_reference_id	string	unique user indentity on merchant system (user name, email, phone_number...)

200

{
    "data": {
                "link_reference_id": "String",
                "user_token":"string",
                "phone_number": "string" //masked và hiển thị 3 số cuối: *******xxx
            }
    "meta": {
        "code": 200
    }
}

Create payment transaction

POST https://api-payment-uat.vinid.dev/oh-integration/transaction/purchase/v1/online-transactions

Request Body

Name	Type	Description
signature	string	signature = (<user_token>|<merchant_code>|<merchant_id>|<terminal_id>|<invoice_no>|<order_create_at>|<bill_amount>|<amount_currency=VND>|<amount_currency=OE POINT>) Cần thực hiện ký số (SHA 256, RSA 2048) bằng private_key
holding_enabled	boolean	Nếu Merchnat cần check lại trạng thái đơn hàng (trừ tiền user, hold tiền vào tài khoản merchant) > holding_enable=true nếu Merchant không cần check lại trạng thái đơn hàng > holding_enable=false
invoice_no	string	Số hóa đơn (mã đơn hàng)
currency	string	VNĐ
amount	string	Số tiền cần thanh toán (VNĐ)
payment_request_list	array	Thông tin thanh toán
bill_amount	string	Số tiền hóa đơn gốc
order_created_at	number	Ngày tạo đơn hàng
transaction_reference_number	string	Mã giao dịch phía merchant
description	string	Mô tả đơn hàng
terminal_id	string	pos code (mã pos)
merchant_id	string	store code (mã cửa hàng)
merchant_code	string	Mã định danh của merchant tại VinID
partner_code	string	Mã định danh của Merchant tại VinID Pay
user_token	string	User token sau khi đăng ký tài khoản

200

{
    "data": {
        "transaction_id": "string",
        "transaction_ref_number": "string",
        "transaction_status": "string",
        "transaction_wallet_number": "string", //for reconciliation
        "verification_methods" : number, // 0: By pass; 2: OTP;
    }
    "meta": {
    }
}

Confirm payment transaction

POST https://api-payment-uat.vinid.dev/oh-integration/transaction/purchase/v1/online-transactions-confirm

Request Body

Name	Type	Description
signature	string	signature = sign(<user_token>|<transaction_id>|<transaction_reference_id>) Cần thực hiện ký số (SHA 256, RSA 2048) bằng private_key
otp	string	Mã OTP khách nhận được
transaction_reference_number	string	Mã giao dịch phía đối tác
transaction_id	string	Mã giao dịch
partner_code	string	Mã định danh của merchant tại VinID Pay
user_token	string	User token sau khi liên kết tài khoản

200

{
    "data": {
        "transaction_id": "string",
        "transaction_ref_number": "string",
        "transaction_status": "string",
        "transaction_wallet_number": "string", //for reconciliation
    }
    "meta": {
    }
}

Confirm order transaction

POST https://api-payment-uat.vinid.dev/oh-integration/transaction/purchase/v1/confirmOrder

Request Body

Name	Type	Description
signature	string	signature = sign(<invoice_no>|<parter_code>|<order_status>) Cần thực hiện ký số (SHA 256, RSA 2048) bằng private_key
order_status	string	Trạng thái đơn hàng
partner_code	string	Mã định danh của merchant tại VinID Pay
invoice_no	string	Mã hóa đơn (mã đơn hàng)

200

{
    "meta": {
        "request_id": "string",
        "code": 200
    },
    "data": {
        "transaction_status": "FAIL", // FAIL, SUCCESS
    }
}

Unlink VinID Pay Wallet

POST https://api-payment-uat.vinid.dev/oh-integration/account/v1/unlink-wallet

Request Body

Name	Type	Description
signature	string	signature = sign(<user_token>|<partner_code>) Cần thực hiện ký số (SHA 256, RSA 2048) bằng private_key
partner_code	string	Mã định danh của Merchnat tại VinID Pay
user_token	string	User token sau khi liên kết tài khoản

200

{
    "data": {}
    "meta": {
          "code": 200
    }
}

Hướng dẫn test

Case	Description / Steps to procedure	Expect Behavior
Thanh toán thành công với trường hợp số tiền nhỏ hơn X (không yêu cầu khách hàng xác nhận)	Trên Merchant app, chọn thanh toán 1 đơn hàng sử dụng VinID Pay làm phương thức thanh toán Thanh toán thành công không cần xác nhận	Thông báo thanh toán thành công trên 3rd-party app Thông báo thanh toán thành công trên ứng dụng VinID
Thanh toán thành công với số tiền >= X (yêu cầu khách hàng xác nhận OTP)	Trên Merchant app, chọn thanh toán 1 đơn hàng sử dụng VinID Pay làm phương thức thanh toán 3rd-party hiển thị màn hình nhập OTP Nhập OTP và xác nhận thanh toán thành công	Thông báo thanh toán thành công trên Merchant app Thông báo thanh toán thành công trên ứng dụng VinID