Ví điện tử VinID Pay

Ví điện từ VinID Pay là giải pháp giúp khách hàng không phải lo lắng quản lý giao dịch chi tiêu hay mang theo quá nhiều tiền mặt theo người mà vẫn có thể tự do mua sắm, thanh toán hóa đơn, dịch vụ một cách nhanh chóng và an toàn, mọi lúc mọi nơi.

Trở thành đối tác của Ví điện tử VinID Pay là cơ hội để tăng doanh thu của bạn với tập khách hàng trung thành và tiềm năng của VinID cũng như hệ sinh thái Vingroup.

Lợi ích cho doanh nghiệp khi tích hợp dịch vụ thanh toán VinID Pay

Khách hàng của bạn được gì ?

Các hình thức tích hợp dịch vụ thanh toán VinID Pay

Transaction QR: 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…). Xem thêm

App to App: Là giải pháp thanh toán áp dụng cho đối tác có ứng dụng di dộng (Android/iOS) muốn hỗ trợ thanh toán trực tiếp qua ứng dụng VinID. Xem thêm

Web Payment: Là giải pháp hỗ trợ các đơn vị kinh doanh, đối tác có sở hữu website thanh toán riêng. Xem thêm

Merchant QR: Là giải pháp thanh toán tiện lợi cho các đối tác của VinID Pay bằng mã QR định danh cửa hàng (MerchantQR) do VinID Pay cung cấp giúp quản lý dòng tiền và đơn hàng 1 cách rõ ràng và hiệu quả. Xem thêm

VinID là ứng dụng trợ lý thông minh của công ty OneID thuộc tập đoàn One Mount Group.

Ứng dụng VinID chạy trên 2 nền tảng Android và iOS, kết nối tất cả các mảng trong hệ sinh thái rộng lớn của tập đoàn Vingroup.

VinID sở hữu mạng lưới đối tác doanh nghiệp hàng đầu. Khách hành có thể sở hữu nhiều ưu đãi hấp dẫn từ mạng lưới đối tác từ hàng ngàn thương hiệu được yêu thích nhất.

Với nguồn dữ liệu đa dạng, VinID nhận diện và thấu hiểu chân dung khách hàng mục tiêu của đối tác, từ đó cung cấp các giải pháp nhân hoá phù hợp với từng cá nhân trên ứng dụng VinID.

Ứng dụng VinID tích hợp nhiều tính năng hữu ích giúp cho cuộc sống của người sử dụng trở nên dễ dàng hơn, thuận tiện hơn.

• Voucher - sở hữu mã ưu đãi từ hàng trăm đối tác uy tín

• Shopping qua các tính năng Đi chợ / Mua sắm / Ăn uống

• Tính năng Mua vé với các sự kiện thể thao, giải trí nổi bật

• Giải pháp thanh toán tiện lợi, an toàn thông qua Ví điện từ VinID Pay

• Tích và tiêu điểm VinID khi thanh toán hóa đơn tại Vinmec / Vinmart / Vinpearl ... và hàng ngàn điểm chấp nhận thanh toán khác.

VinID sở hữu tập khách hàng tiềm năng lớn với dữ liệu hành vi phong phú với gần 10 triệu khách hàng thân thiết của tập đoàn VinGroup.

Nền tảng công nghệ đáng tin cậy, kiến trúc linh hoạt, cho phép phát triển các tính năng phức tạp trong thời gian ngắn.

Để có thể thực hiện tích hợp vào hệ thống VinID, đối tác cần tuân thủ các quy tắc kĩ thuật chung sau :

1. API Host

2. Chuẩn bị X-Key-Code

3. ​Dữ liệu trong Request Header

4. Signature - chữ kí điện tử

VinID cung cấp cho các đối tác 2 môi trường để tích hợp vào hệ thống bao gồm :

• UAT: Sử dụng trong quá trình tích hợp bao gồm xây dựng tính năng, kiểm thử, debug, v.v..

• Production: Sử dụng để triển khai cho người dùng cuối có thể sử dụng dịch vụ.

API Host

Địa chỉ host server cho các API

• UAT: https://api-merchant-uat.vinid.dev/{api_path}

• Production: https://api-merchant.vinid.net/{api_path}

Merchant Website

Là trang web dành riêng cho đối tác phục vụ việc tra cứu giao dịch và quản lý các thông tin kết nối (keycode, store, pos, ...).

Bên cạnh đó VinID cũng cung cấp ứng dụng dành cho đối tác trên mobile (Android/iOS) với các chức năng tương tự trên Merchant Website.

Xem thêm:

Mobile App

Các bước cơ bản để tích hợp với VinID

1. Đối tác có thể đăng ký tài khoản doanh nghiệp hoặc liên hệ và cung cấp e-mail nhận thông tin với bộ phận phát triển kinh doanh của VinID để ký hợp đồng tích hợp với VinID.

   Hotline PTKD: 02471015888

   Email PTKD: hotro.mc@vinid.net

2. Bộ phận hỗ trợ kinh doanh của VinID sẽ tạo và gửi cho đối tác một tài khoản khách hàng thông qua email mà khách hàng cung cấp.

   Đối tác cần hoàn thành quá trình đăng ký với đầy đủ thông tin. Thông tin tích hợp mặc định là môi trường Sandbox.

3. Đối tác sử dụng tài khoản được cung cấp đăng nhập vào Merchant Site do VinID cung cấp để khởi tạo các thông tin cần thiết.

4. Đối tác tiến hành tích hợp theo tài liệu tích hợp kỹ thuật của VinID. Phía VinID sẽ có người support đối tác trong quá trình tích hợp.

5. Sau khi phía đối tác hoàn thành tích hợp và kiểm thử trên môi trường Sandbox, VinID sẽ xác thực dịch vụ của bạn trên môi trường Sandbox trước khi đưa lên môi trường Production.

6. Sau khi tích hợp hoàn thành, VinID sẽ tiến hành nghiệm thu dịch vụ trước khi triển khai Production.

7. VinID cung cấp thông số kỹ thuật trên môi trường production, đối tác tiến hành cấu hình trên hệ thống.

8. Triển khai dịch vụ thanh toán cho khách hàng. VinID và đối tác thỏa thuận các chương trình khuyến mại cho khách hàng (nếu có).

9. Hỗ trợ giải đáp các vấn đề phát sinh (nếu có).

Điểm VinID

Điểm VinID hay còn gọi là Vinpoint là điểm được tích lũy từ các giao dịch mua sắm hàng hoá, hoặc dịch vụ tại các địa điểm kinh doanh thuộc Tập đoàn Vingroup.

Điểm VinID có thể được sử dụng để chi tiêu ở rất nhiều nơi trong hệ sinh thái đa dạng của Vingroup mang lại giá trị sử dụng lớn, dễ dàng, tiện lợi cho khách hàng, giúp bạn đơn giản hơn trong các giao dịch thanh toán bởi ngay cả khi không còn tiền trong Ví hoặc quên mang theo tiền mặt, bạn vẫn có thể mua hàng và thanh toán thành công.

1 điểm Vinpoint được quy đổi giá trị tương đương 1.000 đồng khi thanh toán tại các điểm giao dịch thuộc hệ thống Vingroup, cụ thể như:

• Mua sắm từ xa tại siêu thị ảo VinMart 4.0 bằng tính năng Scan & Go trên ứng dụng VinID

• Mua sắm hàng hoá tại hơn 1500 siêu thị VinMart và các cửa hàng VinMart+

• Đóng học phí tại Vinschool

• Khám bệnh tại Vinmec

• Du lịch, nghỉ dưỡng tại Vinpearl

• Thanh toán phụ tùng, chi phí sửa chữa tại Vinfast

Lợi ích cho doanh nghiệp khi ích hợp dịch vụ Loyalty với VinID Point

Ngoài giá trị về thanh toán như việc tích hợp VinID Pay, điểm Vinpoint còn có ý nghĩa về mặt trải nghiệm người dùng cho các đối tác doanh nghiệp thuộc lĩnh vực tiếp thị liên kết (Affiliate Marketing), trung gian thanh toán hoặc đối tác có hệ thống Loyalty riêng cho khách hàng của mình đang tìm kiếm đầu ra cho các giá trị tích lũy trong hệ thống.

Nếu khách hàng trong hệ thống loyalty của bạn đang chờ đợi những sản phẩm quy đổi hấp dẫn hơn bên cạnh thẻ điện thoại, vé xem phim, thì VinID Point chính là điều mà bạn cần. Còn gì tiện lợi hơn cho khách hàng của bạn bằng một đơn vị điểm loyalty với khả năng sử dụng tại hàng ngàn địa điểm trong hệ sinh thái Vingroup trên toàn quốc như VinID Point?

Đối tác có toàn quyền triển khai và quản lý nghiệp vụ loyalty trên hệ thống của mình (về hình thức, cơ chế, tỷ lệ quy đổi ....) và VinID sẽ chỉ tham gia như một nhà cung cấp điểm Vinpoint tới khách hàng theo hình thức mà đối tác yêu cầu. Chỉ cần khách hàng đã sở hữu thẻ thành viên VinID hoặc đăng ký tài khoản trên ứng dụng VinID là có thể sử dụng được Vinpoint với vô vàn tiện ích.

Các hình thức tích hợp dịch vụ loyalty VinID Point

Hiện tại VinID cung cấp Vinpoint cho đối tác tích hợp qua 2 hình thức:

• Mã Giftcode: VinID cung cấp mã nạp điểm theo mệnh giá mà đối tác yêu cầu. Đối tác nhận mã và phân phối cho khách hàng. Xem chi tiết

• Topup điểm: VinID nạp điểm trực tiếp đến số điện thoại của khách hàng mà đối tác yêu cầu. Xem chi tiết

Bước 1: Đăng nhập vào Merchant Site bằng tài khoản do VinID cung cấp.

Bước 2: Tìm đến phần API Key trong mục Tích hợp thanh toán.

Bước 3: Bấm vào nút TẠO MỚI và nhập các thông tin cần thiết.

• Tên Key : để phân biệt các X-Key-Code trong danh sách

• Ngày hết hạn : nếu không chỉ định thì X-Key-Code sẽ có hạn sử dụng là vĩnh viễn.

• Tự Động Tạo Key : mặc định hệ thống sẽ tự động sinh ra Public key và cấp Private key tương ứng cho merchant. Trường hợp merchant muốn sử dụng Public key của mình thì có thể bỏ check ở option này và điền Public key của mình vào ô Public key ở bên phải.

Bước 4: Bấm nút XÁC NHẬN để thực hiện tạo X-Key-Code

Nếu ở Bước 3, merchant sử dụng tính năng Tự động tạo key thì hệ thống sẽ trả lại Private key tương ứng. Vui lòng lưu giữ Private key này để thực hiện việc tạo signature trong các API request gửi đến với X-Key-Code mà bạn vừa tạo.

Bước 5: X-Key-Code mới được tạo ra sẽ hiển thị trong danh sách API Keys. Merchant sử dụng Mã Key để truyền vào header của API request theo quy chuẩn request header của VinID.

VinID sử dụng chữ ký điện tử (signature) để xác thực dữ liệu đầu vào và ra trên mỗi HTTP Request.

Hệ thống VinID sử dụng thuật toán SHA256 RSA ( key size = 2048 bit) để tạo signature.

Tạo chữ ký điện tử

openssl genrsa -out RS256-2048-Private.rsa 2048
openssl rsa -in RS256-2048-Private.rsa -pubout > RS256-2048-Public.rsa

brew update
brew install openssl
echo 'export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

openssl genrsa -out RS256-2048-Private.rsa 2048
openssl rsa -in RS256-2048-Private.rsa -pubout > RS256-2048-Public.rsa

openssl genrsa -out RS256-2048-Private.rsa 2048
openssl rsa -in RS256-2048-Private.rsa -pubout > RS256-2048-Public.rsa

Format chữ ký điện tử

• PrivateKey: do merchant tự generate ra theo định dạng SHA256 RSA ( 2048 )

• URL: Endpoint API

RawData = {url};{method};{X-Nonce};{X-Timestamp};{X-Key-Code};{body}
X-Signature = ​SHA256WithRSA(PrivateKey, RawData)

RawData = {url};{method};{X-Nonce};{X-Timestamp};{X-Key-Code};
X-Signature = ​SHA256WithRSA(PrivateKey, RawData)

Ví dụ:

url: '/merchant-integration/v1/qr/gen-transaction-qr'
method: 'POST'
X-Nonce: '00a81e60-2684-4cf9-878d-f37559213059'
X-Timestamp: 1570723375
X-Key-Code: 'b7bdf002-4948-44d2-99d1-99c8c81c3f47'
Body: {"callback_url":"https://webhook.site/17d9577f-70ca-4918-8388-1d6d53d8bc69","description":"Kiểm thử thanh toán","order_amount":10000,"order_currency":"VND","pos_code":"IPOS002","service_type":"PURCHASE","store_code":"ISTORE002"}
RawData: /merchant-integration/v1/qr/gen-transaction-qr;POST;00a81e60-2684-4cf9-878d-f37559213059;1570723375;b7bdf002-4948-44d2-99d1-99c8c81c3f47;{"callback_url":"https://webhook.site/17d9577f-70ca-4918-8388-1d6d53d8bc69","description":"Kiểm thử thanh toán","order_amount":10000,"order_currency":"VND","pos_code":"IPOS002","service_type":"PURCHASE","store_code":"ISTORE002"}
X-Signature: SHA256WithRSA(PrivateKey, RawData)
=> X-Signature: ERSt3cZoijwJf8QIZdcpHPygcDQJ+tA7l/2EVyJyhO8fwpp6mbrYWsyhyqDjD4zkhGwcXVJ7zJQUDWFpCPitG9GlmssEnkp57YK94/6GR54x6COzPqOlJjoQ4Lq6Fvw99QVmjiL+WjGWSOTUkusXh9dr871vCrjcYmyFSCZ9Ydfw6l4iv2evOnibUtalIkdsNM6evrVa7qW28Uno5t8fmz68QJeXd0dqL4lm2tsFAr9094jbWh/zlynqAW9MOIIYjXQC7XwEVKiBEmoZyTnSd8SLITLNIXvLCJjjVT5XYqZAMNIyoNYZKom8dUjLuirBBurcUpXuxlu01O8dU9qHdg==

url: '/merchant-integration/v2/qr/query/20200623T0017FB54CBB'
method: 'GET'
X-Nonce: '00a81e60-2684-4cf9-878d-f37559213059'
X-Timestamp: 1570723375
X-Key-Code: 'b7bdf002-4948-44d2-99d1-99c8c81c3f47'
RawData: /merchant-integration/v2/qr/query/20200623T0017FB54CBB;GET;00a81e60-2684-4cf9-878d-f37559213059;1570723375;b7bdf002-4948-44d2-99d1-99c8c81c3f47;
X-Signature: SHA256WithRSA(PrivateKey, RawData)
=> X-Signature: ERSt3cZoijwJf8QIZdcpHPygcDQJ+tA7l/2EVyJyhO8fwpp6mbrYWsyhyqDjD4zkhGwcXVJ7zJQUDWFpCPitG9GlmssEnkp57YK94/6GR54x6COzPqOlJjoQ4Lq6Fvw99QVmjiL+WjGWSOTUkusXh9dr871vCrjcYmyFSCZ9Ydfw6l4iv2evOnibUtalIkdsNM6evrVa7qW28Uno5t8fmz68QJeXd0dqL4lm2tsFAr9094jbWh/zlynqAW9MOIIYjXQC7XwEVKiBEmoZyTnSd8SLITLNIXvLCJjjVT5XYqZAMNIyoNYZKom8dUjLuirBBurcUpXuxlu01O8dU9qHdg==

Code mẫu tạo Signature

// GenerateSignature util to generate signature form Auth Claim of merchant
func GenerateSignature(claim *dtos.AuthClaims, privKey []byte) (string, error) {
    block, _ := pem.Decode(privKey)
    privateKey, err := x509.ParsePKCS1PrivateKey(block.Bytes)
    if err != nil {
        fmt.Printf("Error ParsePKCS1PrivateKey: %v", err)
        return "", err
    }
    hash := generateHash(claim.URL, claim.Method, claim.Nonce, claim.Timestamp, claim.KeyCode, claim.Body)
    signature, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, hash[:])
    if err != nil {
        fmt.Printf("Error from signing: %s\n", err)
        return "", err
    }
    claim.Signature = base64.StdEncoding.EncodeToString(signature)
    return claim.Signature, nil
}

function generateSignature($url, $method, $nonce, $timestamp, $apiKey, $requestBody, $privateKey)
{
    $data = $url . ";" . $method . ";" . $nonce . ";" . $timestamp . ";" . $apiKey . ";" . $requestBody;
    $p = openssl_pkey_get_private($privateKey);
    if (!$p) {
        trigger_error("Invalid private key\n".$privateKey, E_USER_WARNING);
        throw new InvalidPrivateKeyException($privateKey);
    }
    $signSuccess = openssl_sign($data, $signature, $p, OPENSSL_ALGO_SHA256);
    $encodedSignature = base64_encode($signature);
    openssl_free_key($p);
    return $encodedSignature;
}

def generateSign():
    requestBody = json.dumps(params, default=lambda o:o.__dict__, ensure_ascii=False,separators=(',', ':'))
    data = url+";"+method+";"+nonce+";"+str(int(timestamp))+";"+keyCode+";"+requestBody
    f = open("/home/vid/Documents/leo/sb_private.pem", "r")
    pkey = crypto.load_privatekey(crypto.FILETYPE_PEM, f.read())
    sign = OpenSSL.crypto.sign(pkey, data, "sha256")
    encodedSign = base64.b64encode(sign)
    return encodedSign

import java.io.File;
import java.nio.file.Files;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;

public class VinIDSignature {

    //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);
    }
}

using System.Text;
using System.IO;
using java.security.spec;
using java.security;
using System;
using System.Security.Cryptography;

namespace OneID
{
    class Security
    {
        public string sign(string url, string method, string nonce, string timestamp, string keycode, string requestBody, string keyfile)
        {
            string data = url + ";" + method + ";" + nonce + ";" + timestamp + ";" + keycode + ";" + requestBody;
            RSACryptoServiceProvider ras = PemKeyUtils.GetRSAProviderFromPemFile(keyfile);
            return System.Convert.ToBase64String(ras.SignData(Encoding.ASCII.GetBytes(data), CryptoConfig.MapNameToOID("SHA256")));
        }
    }
}

Ví dụ minh họa với hình thức thanh toán Transaction QR

Request

POST https://api-merchant-sandbox.vinid.dev/merchant-integration/v1/qr/gen-transaction-qr
Accept: 'application/json',
Content-Type: 'application/json',
X-Key-Code: '28f04867-c6d5-425f-9108-0d90a0c0b09e',
X-Nonce: '1583122246',
X-Timestamp: 1583122246,
X-Signature: 'IrAHA7RAxGVRfu8TyM+VVtuNwzbvSZFQ6BUSHxBZHV1o7m5uJpr4CIuor6Ku2tSvWM5VHGGQkvqHXmpo7uwceVJorpey9v8sJE+pgtanRO8fnHDbXWrW4JNL6MgrNZwXZU5qh8GMnCxNmToXTqFoFrB5vilekyDlFKzWdz/PDIju2HdTeJgNMWm54zqtoq6L1qc8vc5earylaFspWlaI+qDvK93cklDOAaJinxK0m+4EQtjkdAvL1D4LuI4mnvvwXoMo69W3ZUZp/KLCRTKDvvfHCwpNsqJDv7vQLBDKMbzFSNECu+CIG2z9e2lXpLwSxIoDdh+bYS831QPQK4nQnQ==',

{
  "callback_url": null,
  "description": "Test trans QR",
  "extra_data": "",
  "order_amount": 10000,
  "order_currency": "VND",
  "order_reference_id": "",
  "pos_code": "POSCODE01",
  "service_type": "PURCHASE",
  "store_code": "STORECODE01"
}

Response

HTTP/1.1 200 OK
Date: Mon, 02 Mar 2020 04:15:43 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: close
Set-Cookie: __cfduid=d17ef257bc41217c6cc999b06d6f8b8f21583122543; expires=Wed, 01-Apr-20 04:15:43 GMT; path=/; domain=.vinid.dev; HttpOnly; SameSite=Lax; Secure
X-Request-ID: eb79bbea-77cd-455a-82ff-a33041671914#1098
CF-Cache-Status: DYNAMIC
Expect-CT: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
Alt-Svc: h3-27=":443"; ma=86400, h3-25=":443"; ma=86400, h3-24=":443"; ma=86400, h3-23=":443"; ma=86400
Server: cloudflare
CF-RAY: 56d84c563ceea366-HKG
Content-Encoding: gzip

{
  "meta": {
    "code": 200,
    "message": "OK"
  },
  "data": {
    "qr_url": "",
    "qr_data": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAACTklEQVR42uyYPW7kOhCES1DAkEfgUXgxQxLhi/EoPAJDBoTqoVp6nrF3Nx5ydzowYOILpqGq/sM73vFPxkKSp2MHXF4LfG6BNeo1TwQ0AJvL8KfTa40Ne40A/FRAYN0cu08kQiJbSDXqYTRAP/pA7OG4ZDQr0KWtjp2cEzBFkRUAy4Y/SO61wGXe3H1qcS2bzJt+4+6xgSuU5kKuPL3MUX8pp8MD5u4Mn5hNUQ3wbNi/0nw9sLCsdWlYVYdMUfoMBD6+etYMQAumKH2LfPv2kDk+ntw9PiAdJWWWGrp5Wr5AOGYC4Mpq7lah6pexk1XToQBKUdF8AXNDILMqPyYCELrMvFYb1fZ7iED4fNh/fEBNzR/u+mctZo79uZAOAZDdn4BmhLgWS+v0ZPmfmgJQctX+7DLvXtE0r7XwUNQMgKPcQFazxCm7b4jyfB4HAFaaovYWVx4+u6LBZy5gabBWa6Oa0lShx/dlcALAelaLd8o76YqmoEcJGgBQeI0HaqyaijUkq7seT2VoeGBhMXOo82YDnB6eh5wZgBbgT0koXdrShiKfH2MB5KGNFaL0GbB998UUgBRl1V4vy32ocTz8XIC525bBHrSchNNnS30m4GtbtELlecdnHQd47N07s/UsdWGYg+cBrhsIIm0q5qnq811RUwB2j9JXSlJUYhbwnOYQwHVlxXVusu1Qk1v5+HGGnQLQVByvs7wKqQa4+YBsirpb2eZ/NLXXA6ao2GH3YC0gpijOBdzmhT8Aluvg5+l+nGEHB97xjr8s/gsAAP//tq28Lpz6etIAAAAASUVORK5CYII=",
    "qr_code": "https://qr.id.vin/TX.20200302T00100015912",
    "order_id": "20200302T00100015912",
    "expiration": 1583123381
  }
}

/oauth2/token

POST https://oauth-qc.vinid.net/oauth2/token

API này được sử dụng cho Authorization code (PKCE) để exchange token từ authorization code có được từ Auth endpoint.

Headers

Request Body

{
  "access_token": "string",
  "expires_in": 0,
  "id_token": 0,
  "refresh_token": "string",
  "scope": 0,
  "token_type": "string"
}

/oauth2/auth

GET https://oauth-qc.vinid.dev/oauth2/auth

API Này sử dụng cho luồng Authorization code (PKCE), sau khi authentication thành công, một authorization code (query parameter) sẽ được redirect về callback endpoint của ứng dụng.

Query Parameters

/oauth2/token

POST https://oauth-qc.vinid.dev/oauth2/token

Request Body

{
    "access_token": "string",
    "expires_in": 3600,
    "id_token": "string",
    "refresh_token": "string",
    "scope": "openid offline some_scope",
    "token_type": "bearer"
}

curl --location --request POST 'https://oauth2-dev.vinid.dev/oauth2/token' \
--form 'grant_type=refresh_token' \
--form 'refresh_token={refresh_token}' \
--form 'client_id={client_id}' \
--form 'redirect_uri=https://your-home-page'

Thời gian hết hạn của refresh_token mặc định là 720 giờ

Mọi request đến hệ thống VinID đều tuân thủ theo Request Header sau :

/user-management/user-info

GET https://oauth-qc.vinid.dev/user-management/user-info

Headers

{
    "data": {
        "full_name": "string",
        "email": "string",
        "phone_number": "string",
        "dob": "string",
        "gender": "int",
        "nationality": "string",
        "identity_documents": [
            {
                "identity_number": "string",
                "identity_type": "CMT|HC|CCCD",
                "issue_place": "string",
                "issue_date": "string",
            }
        ],
        "addresses": [
            {
                "city": "string",
                "commune": "string",
                "address": "string",
                "type": "int",
                "district": "string"
            }
        ]
    },
    "meta": {
        "code": 200
    }
}

/.well-known/openid-configuration

GET https://oauth-qc.vinid.dev/.well-known/openid-configuration

​Cấu hình tích hợp OneID

Sử dụng trong trường hợp đối tác muốn bổ sung thêm thông tin cho 01 giao dịch.

Hệ thống VinID sẽ đọc theo format sau:

{
    "partner_code": "YOUR-PARTNER-CODE-HERE",
    // thông tin thêm mà đối tác muốn bổ sung cho giao dịch.
    "order_info": "your-json-string"
}

Ví dụ:

// request body với extra data dạng array key-value
{
    "callback_url": "your-callback-url",
    "description": "Mua hàng tại quầy",
    "order_amount": "10000",
    "order_currency": "VND",
    "order_reference_id": "DOITAC-DON-01",
    "pos_code": "POS-CUA-HANG-01",
    "service_type": "PURCHASE",
    "store_code": "CUA-HANG-01",
    "extra_data": {
        "partner_code": "MERCHANT-01",
        "order_info": "[{\"topping\":\"pho mai\",\"ship_method\":\"ship b\u1eb1ng m\u00e1y bay\"}]"
    }
}
// request body với extra data dạng object
{
    "callback_url": "your-callback-url",
    "description": "Mua hàng tại quầy",
    "order_amount": "10000",
    "order_currency": "VND",
    "order_reference_id": "DOITAC-DON-01",
    "pos_code": "POS-CUA-HANG-01",
    "service_type": "PURCHASE",
    "store_code": "CUA-HANG-01",
    "extra_data": {
        "partner_code": "MERCHANT-01",
        "order_info": "{\"customer\":\"joker\",\"sent_to\":\"batman\",\"is_a_bomb\":true}"
    }
}

Step 1 - Determined the platform

OneID SSO support many type of platform including:

1. Native/Mobile App (Mobile or Desktop app that support web browser web-view)

2. Single-Page App (JavaScript web app that runs in the browser)

3. Regular Web App (Traditional web app that runs on the server)

4. Backend/API (An API or service protected)

Step 2 - Pick the SDK

Select the SDK that match with your project programing language

Step 3 - Create Client

Contact us to create/register Client: VUPNA@Onemount.com

Tenant & Client is the identity of the 3rd party service which use OneID SSO. Required information for registering including:

1. client_id - ID of the 3rd party app

2. client_secret - optional

3. redirect_uris - the redirect url after the process complete

4. owner - owner of the 3rd party app

5. contacts - email of the owner

6. client_name - name of the 3rd party app. This information is required for white label

7. logo_uri - logo of the 3rd party app. This information is required for white label

8. client_uri - home page URL of 3rd party app. This information is required for white label

9. policy_uri - policy page. This information is required for white label

10. tos_uri - term & condition page. This information is required for white label

11. post_logout_redirect_uri - Hyperlink when click on 3rd party app logo image

12. frontchannel_logout_uri - Logout URL for frontent

13. backchannel_logout_uri - Logout URL for backend

14. metadata - json format data which contain additional data such as:

    1. background image

    2. hotline - phone number

    3. support email

Step 4 - Working Flow

Make the login button.

Assuming step 2 & 3 is completed.

1. User click the login button on 3rd app

2. SDK it will generate code_verifier and code_challenge (from code_verifier).

3. SDK send authorization_code and code_challenge to /auth endpoint GET https://oauth-qc.vinid.dev/oauth2/auth?client_id={client_id}&redirect_uri={callback_url}&response_type=code&scope={scope}&state={state}&code_challenge={code_challenge}&code_challenge_method=S256

4. OneID redirect to OneID login form

5. User login and consent scope

6. OneID callback authorization_code to 3rd app

7. SDK call /token endpoint with authorization_code and code_verifier

8. OneID validate code_verifier

9. OneID return access_token, id_token & access_token

Get resource with authorization code

10. 3rd party app uses access_token to access resource server (ex: /userinfo endpoint). 11. Resource server return data.

Hiện tại VinID Pay đã hỗ trợ các hình thức thanh toán khác nhau, phục vụ cho cả In-store Payment và Online Payment.

In-store Payment/QR Pay

Online Payment

Giới thiệu dịch vụ

Loại hình dịch vụ App to App là giải pháp thanh toán áp dụng cho đối tác có ứng dụng di dộng (Android/iOS) muốn hỗ trợ thanh toán trực tiếp qua ứng dụng VinID.

Khách hàng mua hàng trên ứng dụng của đối tác và chọn VinID Pay là phương thức thanh toán. Hệ thống sẽ tự động kết nối với ví VinID Pay và tiến hành thanh toán cho giao dịch của khách hàng.

Quá trình thanh toán sẽ diễn ra liên tục mà khách hàng không cần phải tự mở nhiều ứng dụng cùng lúc.

Sơ đồ luồng trải nghiệm người dùng

Sequence diagram

APIs

Create Order

POST {API-HOST}/merchant-integration/v1/qr/create-transaction-order

API to create new order

Request Body

{
    "meta": {
        "code": 200,
        "message": "OK"
    },
    "data": {
        "signature": "",
        "order_id": "20190101T00300000001",
        "expired_at": 0
    }
}

Query Order Status

GET {API-HOST}/merchant-integration/v1/qr/query/{order_id}

API to check current order status

Path Parameters

{
  "data": {
    "created_at": 0,
    "merchant_user_id": "string",
    "order_amount": 0,
    "order_id": "string",
    "pay_status": "string",
    "point_amount": 0,
    "transaction_id": "string",
    "updated_at": 0,
    "vnd_amount": 0
  },
  "meta": {
    "code": 0,
    "message": "string"
  }
}

Thông tin thêm:

• API Host

• Extra Data

• Request Header

• Callback

• Ví dụ Request / Response

Bảng mã lỗi

Tham khảo Bảng mã lỗi

Mobile SDK

/oauth2/sessions/logout

GET https://oauth-qc.vinid.dev/oauth2/sessions/logout

Query Parameters

post_logout_redirect_uri = urlencode(https://your_redirect_page?state=example)

• frontchannel_logout_uri được sử dụng để OneID hủy token đối với frontend app.

GET https://yourapp.test/frontchannel_logout?iss=https://oauth-dev.vinid.dev/&sid=08a5019c-17e1-4977-8f42-65a12843ea02

• backchannel_logout_uri được sử dụng để OneID hủy token đối với backend app.

POST /backchannel_logout HTTP/1.1
Host: yourapp.test
Content-Type: application/x-www-form-urlencoded

logout_token=eyJhbGci ... .eyJpc3Mi ... .T3BlbklE ...

Giới thiệu dịch vụ

Là giải pháp thanh toán tiện lợi cho các đối tác của VinID Pay bằng mã QR định danh cửa hàng (MerchantQR) do VinID Pay cung cấp giúp quản lý dòng tiền và đơn hàng 1 cách rõ ràng và hiệu quả.

Khách hàng chỉ cần thực hiện với 3 bước đơn giản: 1- Dùng tính năng "Quét mã" trên ứng dụng VinID, quét QR cửa hàng (thường đặt ở quầy thu ngân, tại bàn…); 2- Nhập số tiền cần thanh toán. 3- Xác nhận thanh toán bằng ví điện tử VinID Pay.

Hệ thống sẽ tự động cập nhật số dư và chuyển tiền về ví của đối tác. Đối tác được cung cấp công cụ app/web để nhận thông tin giao dịch.

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

Sau khi ký hợp đồng, đơn vị kinh doanh, đối tác sẽ được VinID Pay hỗ trợ toàn diện về kỹ thuật và công nghệ. Đối tác không cần phải kết nối về kỹ thuật. Các bước hợp tác giữa VinID Pay - Đối tác:

Bước 1: Đối tác kí kết hợp đồng hợp tác với VinID Pay.

Bước 2: Đối tác được VinID Pay hỗ trợ tạo mã QR thanh toán và POSM tại cửa hàng.

Bước 3: Đối tác được cung cấp tài khoản và công cụ trên app/web để kiểm tra thông tin số dư và lịch sử giao dịch.

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

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

Giới thiệu dịch vụ

Là giải pháp hỗ trợ các đơn vị kinh doanh, đối tác có sở hữu website.

Khách hàng mua hàng tại website của đối tác, chọn VinID Pay là phương thức thanh toán, hệ thống sẽ điều hướng khách hàng sang cổng thanh toán VinID Pay.

Tại đây, khách hàng có quyền lựa chọn giữa 2 hình thức thanh toán sau:

• Sử dụng tài khoản VinID của khách hàng để đăng nhập trên cổng thanh toán và tiến hành thanh toán mà không cần mở ứng dụng VinID.

• Dùng tính năng quét mã trên ứng dụng VinID để quét mã QR hóa đơn được tạo trên cổng thanh toán để tiến hành thanh toán như các hình thức khác.

Hướng dẫn người dùng sử dụng dịch vụ

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

Sequence diagram

APIs

Create order

POST {API-HOST}/merchant-integration/v1/orders/web-payment

API to request payment via Payment Web

Request Body

Thông tin thêm:

Thông tin mã lỗi

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

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

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

{
    "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"
}

Thông tin thêm:

• API Host

• Request Header

• Callback

• Extra Data

• Ví dụ Request / Response

Thông tin mã lỗi

Tham khảo Mã lỗi chung

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;

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());
}

Giới thiệu dịch vụ

Dịch vụ chi hộ là giải pháp chuyển tiền dành cho các đối tác là tổ chức, doanh nghiệp, đơn vị kinh doanh đã đăng ký tại VinID có nhu cầu chuyển tiền cho cá nhân qua ví điện tử VinID Pay (nhân viên, khách hàng, đối tác...)

Dịch vụ chi hộ cung cấp cho đối tác phương thức chuyển tiền đơn giản, nhanh chóng. Người nhận sẽ nhận được tiền tức thời 24/7. Bên cạnh đó, lịch sử giao dịch sẽ được lưu lại, đảm bảo tra cứu hiệu quả, an toàn và bảo mật.

Đối tác sau khi ký hợp đồng sẽ được VinID hỗ trợ tích hợp kỹ thuật trong cả trong quá trình tích hợp và triển khai, sử dụng để đảm bảo vận hành trơn tru.

Lưu ý: Đối tác cần nạp tiền vào tài khoản ví khả dụng của mình trên VinID Pay. Cách nạp tiền:

• Bước 1: Đối tác chuyển tiền vào tài khoản của VinID Pay nội dung được VinID Pay cung cấp

• Bước 2: VinID Pay ghi tăng số dư Tài khoản ví của đối tác trên VinID Pay

• Bước 3: VinID Pay thông báo kết quả nạp tiền thành công

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

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

APIs

Create Money transfer request

POST {API-HOST}/merchant-integration/v1/money-transfer/b2c

Request Body

Mã lỗi

Thông tin thêm:

Giới thiệu dịch vụ

Dịch vụ Hoàn lại giao dịch (Refund) cho phép merchant trả lại số tiền/điểm mà người dùng đã thanh toán qua ví VinID Pay.

Merchant có thể thực hiện hoàn lại một phần hoặc toàn bộ giá trị của giao dịch tùy thuộc vào nghiệp vụ của mình. Người dùng sẽ được thông báo trên ứng dụng VinID về số tiền/điểm mà merchant hoàn trả.

VinID Pay cung cấp dịch vụ Refund thông qua 2 phương thức sử dụng:

• User Frontend (Merchant Site/Merchant App): merchant đăng nhập bằng tài khoản merchant vào trang web/ ứng dụng của VinID cung cấp để hoàn tiền cho giao dịch. Xem hướng dẫn tại đây

• Backend-to-Backend: merchant tích hợp kết nối hệ thống thanh toán của VinID và sử dụng API để yêu cầu hoàn tiền cho giao dịch.

Luồng người dùng

1. User thực hiện trả lại mặt hàng đã mua tại Merchant

2. Merchant tạm giữ lại hàng và gửi yêu cầu refund giao dịch tới VinID

3. VinID kiểm tra yêu cầu của Merchant:

   a. Nếu các thông tin yêu cầu hợp lệ, VinID sẽ thực hiện refund theo yêu cầu của Merchant

   b. Nếu các thông tin yêu cầu không hợp lệ, VinID sẽ từ chối yêu cầu và báo lỗi cho Merchant.

4. VinID thông báo kết quả xử lý refund cho Merchant

5. Dựa vào kết quả phản hồi của VinID, Merchant đưa ra quyết định việc trả hàng của User.

APIs

Refund

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

Tạo yêu cầu refund giao dịch

Request Body

{
    "meta": {
        "code": 200,
        "string": "OK"
    },
    "data": {
        "original_loyalty_transaction_id": "string",
        "refund_transaction_id": "string",
        "refund_loyalty_transaction_id": "string",
        "refund_transaction_wallet_id": "string"
    }
}

{
    "meta": {
        "code": 2000801,
        "message": "Refund thành công. Khách hàng đã nhận lại tiền. Phần điểm hoàn lại sẽ được cập nhật trong thời gian sớm nhất."
    },
    "data": {
        "refund_transaction_id": "string",
        "refund_transaction_wallet_id": "string",
    }
}

{
    "meta": {
        "code": 2000802,
        "message": "Refund thành công. Khách hàng đã nhận lại điểm. Phần tiền hoàn lại sẽ được cập nhật trong thời gian sớm nhất"
    },
    "data": {
        "original_loyalty_transaction_id": "string",
        "refund_loyalty_transaction_id": "string",
        "refund_transaction_wallet_id": "string"
    }
}

{
    "meta": {
        "code": 4004009,
        "message": "Số tiền có thể refund còn lại không đủ"
    }
}

{
    "meta": {
        "code": 4000812,
        "message": "Giao dịch gốc không được thanh toán bằng điểm"
    }
}

Mã lỗi

Thông tin thêm:

• API Host

• Mã lỗi chung

Về thông tin dịch vụ, vui lòng xem bài viết về Dịch vụ loyalty VinID Point

Về thông tin tích hợp, vui lòng xem thông tin cụ thể trong các bài viết dưới đây:

• Dịch vụ VinID Giftcode

• Dịch vụ Topup VinID Point

• Dịch vụ lấy hạng thành viên trung thành

Giới thiệu dịch vụ

Là giải pháp giúp các bên đối tác lấy hạng của thành viên trung thành (vàng, bạc đồng) của VinID.

Khách hàng mua hàng, sử dụng dịch vụ của đối tác VinID khi đối tác không có hệ thống loyalty, khi thực hiện thanh toán bằng VinID, hệ thống sẽ lấy hạng thành viên của khách hàng. Theo đó, khách hàng sẽ được giảm giá dựa theo thứ hạng thành viên của mình trong VinID.

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

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

APIs

Lấy thông tin hạng thành viên

GET {API_HOST}/merchant-integration/v1/loyalty/membership?id_type=string&identity=string&business_code=string&program_code=string

Path Parameters

{
  "data": {
    "member": {
      "member_code": "string",
      "full_name": "string"
    },
    "tier_info": {
      "tier_code": "string",
      "tier_name": "string",
      "description": "string"
    } 
  },
  "meta": {
    "code": int,
    "message": "string"
  }
}

Những mã lỗi có thể xảy ra

• 401005: identity_type not supported

• 400002: invalid phone_number format

• 401006: invalid customer id

• 401007: invalid loyalty business

• 401008: invalid loyalty program

• 500503: generic OLS error

APIs

Check quantity

POST {API-HOST}/merchant-integration/v1/loyalty/gift-code/quantity

API để kiểm tra số lượng giftcode còn lại trong kho của merchant.

Request Body

{
  "meta": {
    "code": 200,
    "message": "OK"
  },
  "data": [
    {
      "card_type": "string",
      "quantity": 0
    }
  ]
}

Withdraw Giftcode

POST {API-HOST}/merchant-integration/v1/loyalty/gift-code/orders

API để lấy giftcode ra khỏi kho

Request Body

{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "created_at": 0,
    "extra_data: "string"
    "merchant_order_id": "string",
    "order_info": [
      {
        "card_type": "string", //Mệnh giá giftcode
        "cards": [
          {
            "code": "string", //Mã nạp của giftcode
            "expire_date": "string", //Ngày hết hạn
            "serial": "string" //Mã tra soát
          }
        ]
      }
    ]
  }

{
  "store_code": "string",
  "pos_code": "string",
  "merchant_order_id": "string",
  "order_info": [
    {
      "card_type": "string",
      "quantity": 10
    }
  ],
  "extra_data": "string"
}

Check giftcode

POST {API-HOST}/merchant-integration/v1/loyalty/gift-code/check

API để kiểm tra trạng thái của giftcode

Request Body

{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "status": "USED", //“USED” hoặc “ACTIVE”
    "expire_date": "yyyy-MM-dd" //Hạn sử dụng
  }
}

{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": }

Get order detail

GET {API-HOST}/merchant-integration/v1/loyalty/gift-code/orders?{parameters}

API để yêu cầu lấy thông tin của đơn hàng đã thực hiện

Path Parameters

{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "created_at": 0,
    "extra_data": "string",
    "merchant_order_id": "string",
    "order_info": [
      {
        "card_type": "string",
        "cards": [
          {
            "code": "string", //Mã nạp của giftcode
            "expire_date": "string", //Ngày hết hạn
            "serial": "string" //Mã tra soát
          }
        ]
      }
    ]   
  }

{API-HOST}/merchant-integration/v1/loyalty/giftcode/orders?merchant_order_id=string&store_code=string&pos_code=string

Mã lỗi

Tham khảo bảng Mã lỗi chung

Xem thêm:

• API Host

• Quy tắc kết nối

Phía đối tác cần chuẩn bị Callback API để nhận về kết quả giao dịch thành công từ phía VinID Pay. (Với thanh toán thất bại, VinID Pay sẽ không thực hiện callback)

VinID sẽ cung cấp một Public Key cho đối tác để có thể thực hiện xác thực request do VinID gọi qua theo format sau :

Giới thiệu dịch vụ

Dịch vụ Topup VinID Point cho phép các đối tác tích hợp thực hiện nạp điểm VinID trực tiếp tới số điện thoại của người dùng. Chỉ cần số điện thoại đã đăng ký tài khoản VinID là người dùng sẽ nhận được điểm Vinpoint ngay vào tài khoản VinID mà không cần thực hiện bất cứ thao tác gì.

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

Đối tác có thể sử dụng Dịch vụ Topup VinID Point cho nhiều mục đích khác nhau tùy thuộc vào nghiệp vụ của mình như: mua bán điểm, trao đổi/tặng thưởng, … từ hệ thống của mình. Sơ đồ dưới đây minh họa cho nghiệp vụ Đổi điểm VinID của đối tác có hệ thống điểm loyalty riêng.

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

APIs

Get user info by phone number

POST {API-HOST}/merchant-integration/v1/gateway

API cho merchant để kiểm tra thông tin của số điện thoại người dùng.

Headers

Request Body

{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "full_name":        string,
    "phone_number":     string,
    "dob":              string,
    "gender":           string,
    "identify":         string,  // Số điện thoại cá nhân
    "status":           string,  // A: Active | I: Inactive | B: Block
    "card_status":      string   // A: Active | I: Inactive
  }
}

Top-up points to phone number

POST {API-HOST}/merchant-integration/v1/gateway

API để nạp điểm cho số điện thoại người dùng

Headers

Request Body

{
  "meta": {
    "code": 200,
    "message": "OK"
  }
}

{
  "phone_no": "01118281123", 				// 	optional,numeric,min=10,max=11
  "point_amount": 2, 						//	required,numeric,min=0,should be < 20000 when send_reciept is true
  "invoice_no": "string", 				//	required,max length=23
  "send_receipt": true | false,			//	required
  "receipt_info": {						//	All receipt info fields is required if send_receipt is true
    "name": "string",            		//	max length=50
    "address":"string",					//	max length=100
    "email":"string",					//  Email format,max length=50
    "tax_code":"string"         		// 	max=32
  },
  "send_sms": true | false,				// optional, default value: true
  "id_type": "string",					// optional, valid value:  MOBILE, CARD, USER_ID
  "id": "string"                      // optional, 
}

Query order status

POST {API-HOST}/merchant-integration/v1/gateway

API để kiểm tra trạng thái đơn hàng

Headers

Request Body

{
    "meta": {
        "code": 200,
        "message": "Success"
    },
     "data": {
        "type":                     string,     //  TXN_EARN
        "status":                   string,     //  "S": success |  "E" : error
    }
}

Mã lỗi

Tham khảo bảng Mã lỗi chung

Xem thêm:

• API Host

• Quy tắc kết nối

APIs

Get user info by phone number

GET {API-HOST}/merchant-integration/v1/loyalty/topup/member?{parameters}

API cho merchant để kiểm tra thông tin của số điện thoại người dùng.

Path Parameters

{
  "meta": {
    "code": int,
    "message": "string"
  },
  "data": {
    "full_name":        string,
    "phone_number":     string,
    "dob":              string,
    "gender":           string,
    "identify":         string,  // Số điện thoại cá nhân
    "status":           string,  // A: Active | I: Inactive | B: Block
    "card_status":      string   // A: Active | I: Inactive
  }
}