LogoLogo
  • Ứng dụng VinID
  • Giới thiệu chung
    • Dịch vụ thanh toán VinID Pay
    • Dịch vụ loyalty VinID Point
    • Quy trình tích hợp
  • Tài liệu tích hợp
    • Môi trường tích hợp
    • Quy tắc kết nối chung
      • Request Header
      • X-Key-Code
      • Signature - chữ kí điện tử
      • Ví dụ Request / Response
      • Extra Data
    • OneID SSO Integration (PKCE)
      • Auth endpoint
      • Token endpoint
      • Refresh token
      • Logout endpoint
      • Profile endpoint
      • OpenID Configuration
    • Tích hợp với VinID Pay
      • Thanh toán Merchant QR
      • Thanh toán Transaction QR
      • Thanh toán App to App
      • Thanh toán Web Payment
      • Thanh toán Linked Account
      • Dịch vụ chi hộ
      • Callback / IPN
      • Refund giao dịch
    • Tích hợp với VinID Loyalty
      • Dịch vụ lấy hạng thành viên trung thành
      • Dịch vụ VinID Giftcode
        • Deprecated APIs
      • Dịch vụ Topup VinID Point
        • Deprecated APIs
    • Tích hợp với VinID Voucher
      • Dịch vụ E-Voucher
    • Mã lỗi chung
  • Đối soát
    • Đối soát Ví điện tử VinID Pay
  • Khác
    • Thuật ngữ
    • Câu hỏi thường gặp
    • Ứng dụng quản lý
      • Merchant Mobile App
      • Merchant Website
    • Thông tin hỗ trợ
Powered by GitBook
On this page
  • Giới thiệu dịch vụ
  • Luồng người dùng sử dụng dịch vụ
  • Trải nghiệm tính năng thanh toán
  • Sequence diagram
  • APIs
  • Generate Transaction QR
  • Thông tin mã lỗi
  • Code mẫu

Was this helpful?

Export as PDF
  1. Tài liệu tích hợp
  2. Tích hợp với VinID Pay

Thanh toán Transaction QR

PreviousThanh toán Merchant QRNextThanh toán App to App

Last updated 4 years ago

Was this helpful?

Giới thiệu dịch vụ

Là giải pháp hỗ trợ cho các đơn vị kinh doanh, đối tác thanh toán qua các thiết bị có thể hiển thị mã QR hoá đơn (máy POS/ web/ app/ in hoá đơn…)

Khi khởi tạo hóa đơn, đối tác gửi thông tin đến hệ thống VinID Pay để tạo mã. Khách hàng sử dụng tính năng “Quét mã” trên ứng dụng VinID để quét mã do nhân viên cửa hàng cung cấp và tiến hành thanh toán mà không cần nhập thêm bất cứ thông tin nào.

Để sử dụng Transaction QR, đối tác có thể lựa chọn 1 trong 2 phương án như sau:

  • Chủ động tích hợp với hệ thống thanh toán VinID Pay.

  • Sử dụng máy POS của các đối tác đã tích hợp thanh toán với VinID Pay như KiotViet, mPOS, iPOS.

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

Trải nghiệm tính năng thanh toán

Sequence diagram

APIs

Generate Transaction QR

POST {API-HOST}/merchant-integration/v1/orders/tqr

New API return generated QR for payment. For old endpoint, please read note below

Request Body

Name
Type
Description

expired_in

integer

Order timeout in minute. Can be set from 3 to 15. Default value is 15 if not defined

callback_url

string

Callback URL to merchant's backend

description

string

Description for order

extra_data

string

Extra information for order.

order_amount

integer

Amount of order. Value must be large than 0

order_currency

string

Currency code. Default value is VND

order_reference_id

string

Order id from merchant system. For partial refund with transaction paid by VinID Point, this is required parameter, maximum 35 characters length and need to be unique.

pos_code

string

POS code

service_type

string

Default value is PURCHASE

store_code

string

Store code

{
    "meta": {
        "code": 200,
        "message": "OK"
    },
    "data": {
        "qr_url": "",
        "qr_data": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAACWUlEQVR42uyZzY0jIRSEq8WBIyEQComN+keTGKEQAkcOyLWqR8/akgMY2DUHq936Loj3qurR+KzP+i/XRpIPpB4ePjueIbfImvQ2LwQ0ADuSnhKAkBGvej8tBETWHXBk009NXrv27BMCCFdLPV7V3q4J6P+J5AqAFh8LAlZRQCDZ4xnoC/Becr8LWPP63HUWruxq3uu9uycHxvKZVEXhYG446pucTg9EvWbH0RLLjsRy0E5sHmBjYd0aXD3sLAAdA4GvlQAAkqDUw+nJclTtNWTyuy4FxFFR9WiQXUFGjBY7VgJUXLunfrLjVeF52WHdGjUDsLEgXMysQOqSz4ZN8eDgYoBCjlNqwLCrR3jRoTUANTY8VUDJle1NSGcA4Dk2EEx4tppkxSr7vyW3ALCxDNOt8mCpj1fqfM0PSwDEMLWNGZHMXp7gi+NUAFVRpkN9ZB4yt3i+DIPTAxJSmwOrCemYA2vyxdWlADqOilJDjAAU2OL3RMAmC7Vj2H3u8VJFaYx6VtQKAHxRReUxd8cTSUJqT1gH0DYDm6IaoMSsCUV9fj6nxV8HAPOsTJ4y1qumFu225ny61gKAxP1osOYg75EWLFgJUE+HSyFia8nZcBIfwXa9EACgK6opcMJGWl/Mg/EsuRkAG0CcEn3HVscU8ryoWQL4uQOxbD8mKEmQ57kUcN9HjewcH4H3Nr85E2D3k0rFDeZZbezsRe1XASyltaSjyW3cbzvmFQGTz42UE7xEtTmAn4raPUdCVshh+cJKwP0dx3bFu2UD/duHnqmBz/qsf2z9CQAA//87GIM+C12YZwAAAABJRU5ErkJggg==",
        "qr_code": "https://qr.id.vin/TX.20200217T00100018959",
        "order_id": "20200217T00100018959",
        "expiration": 1581914928
    }
}
//REQUEST TEMPLATE
{
  "callback_url": "string",
  "description": "string",
  "expired_in": 0,
  "extra_data": "string",
  "order_amount": 0,
  "order_currency": "string",
  "order_reference_id": "string",
  "pos_code": "string",
  "service_type": "string",
  "store_code": "string"
}

The old endpoint of this API is deprecated.

{API-HOST}/merchant-integration/v1/qr/gen-transaction-qr

Although we will keep it work, but we recommend merchants should move to the new one ASAP.

Please note that the order_reference_id is no more optional in the new endpoint. You should input a unique value every request to make sure the refund process can work correctly.

Thông tin thêm:

Thông tin mã lỗi

Code mẫu

function getSign($url, $method, $nonce, $timestamp, $keyCode, $requestBody, $pem_private_key)
{
    $data = $url.";".$method.";".$nonce.";".$timestamp.";".$keyCode.";".$requestBody;
    try {
        $p = openssl_pkey_get_private($pem_private_key);
        $signSuccess = openssl_sign($data, $signature, $p, OPENSSL_ALGO_SHA256);
        if (!$signSuccess) {
            print("False");
            return "";
        }
        $encodedSignature = base64_encode($signature);
        openssl_free_key($p);
        return $encodedSignature;
    } catch (Exception $e) {
        print_r($e->getMessage());
    }
}

$url = '/merchant-integration/v1/qr/gen-transaction-qr';
$method = 'POST';
$timestamp = time();
$nonce = (string)$timestamp;

$params = [
    'callback_url' => 'http://merchant-site/vinid/result',
    'description' => 'test qr code',
    'extra_data' => '',
    'order_amount' => '1000',
    'order_currency' => 'VND',
    'order_reference_id' => 'merchant-order-id-01',
    'pos_code' => 'merchant-pos-code',
    'service_type' => 'PURCHASE',
    'store_code' => 'merchant-store-code'
];
$requestBody = json_encode($params);
$apiKey = 'Your api key';
$privateKey = 'Your private key';
$sign = getSign($url, $method, $nonce, $timestamp, $apiKey, $requestBody, $privateKey);
$headers = [
    'Accept: application/json',
    'Content-Type: application/json',
    'X-Key-Code: '.$apiKey,
    'X-Nonce: '.$nonce,
    'X-Timestamp: '.$timestamp,
    'X-Signature: '.$sign,
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api-merchant-sandbox.vinid.dev'.$url);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
curl_close($ch);

print_r($result);
return $result;

( Đang cập nhật )

import com.google.gson.Gson;

//The method that signs the data using the private key that is stored in keyFile path
public String generateSign(String url, String method, String nonce, String timestamp, String keyCode, String requestBody, String keyFile) throws Exception {
    String body = requestBody == null || "".equals(requestBody) ? "" : requestBody;
    String data = url + ";" + method + ";" + nonce + ";" + timestamp + ";" + keyCode + ";" + body;
    java.security.Signature rsa = java.security.Signature.getInstance("SHA256withRSA");
    rsa.initSign(getPrivate(keyFile));
    rsa.update(data.getBytes());
    return new String(Base64.getEncoder().encode(rsa.sign()));
}

//Method to retrieve the Private Key from a file
private PrivateKey getPrivate(String filename) throws Exception {
    byte[] keyBytes = Files.readAllBytes(new File(filename).toPath());
    PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
    KeyFactory kf = KeyFactory.getInstance("RSA");
    return kf.generatePrivate(spec);
}

// Generate Transaction QR
public static void main(String... args){
    String timeStamp = String.valueOf(System.currentTimeMillis() / 1000);
    UUID uuid = UUID.randomUUID();
    String nonce = uuid.toString();
    String host = "https://api-merchant-sandbox.vinid.dev";
    String url = "/merchant-integration/v1/qr/gen-transaction-qr";
    String method = "POST";
    String sig = generateSign(url, method, nonce, timeStamp, "your-key-code-here", getJsonSerdes().toJson(reqBody)), "/path/to/private-key");
    Map<String, String> headers = new HashMap<>();
    headers.put("X-Key-Code", callCtx.getKeyCode());
    headers.put("X-Nonce", nonce);
    headers.put("X-Timestamp", timeStamp);
    headers.put("X-Signature", sig);
    HttpClient httpClient = new HttpClient.HttpClientBuilder()
        .setEndpoint(host + url)
        .setMethod(method)
        .setHeader(headers)
        .setBody(reqBody)
        .build();
    
    System.out.println(httpClient.response());
}

Trải nghiệm tính năng thanh toán Transaction QR bằng ví điện tử VinID tại

Tham khảo

đây
Request Header
Callback
Extra Data
Ví dụ Request / Response
Mã lỗi chung
API Host
Luồng người dùng sử dụng dịch vụ Transaction QR trên ứng dụng VinID