vietqr-core-sdk

Hướng Dẫn Tích Hợp SDK Đa Ngôn Ngữ

Hệ thống VietQR Core SDK hỗ trợ tích hợp trực tiếp không phụ thuộc (zero external API call) trên 9 ngôn ngữ lập trình phổ biến.


1. Rust SDK (sdks/rust)

Thêm vào Cargo.toml:

[dependencies]
vietqr = { path = "sdks/rust" }

Ví dụ sử dụng:

use vietqr::{EMVCoBuilder, BankCatalog, QuickLink, Deeplink};

fn main() {
    // 1. Sinh chuỗi EMVCo QR chuẩn NAPAS 247
    let qr = EMVCoBuilder::new("970436", "1234567890")
        .amount(100_000)
        .memo("Don hang 101")
        .account_name("NGUYEN VAN A")
        .build();
    println!("EMVCo QR: {}", qr);

    // 2. Tạo link ảnh tự host với domain riêng
    let quicklink = QuickLink::new("970436", "1234567890")
        .domain("qr.yourdomain.com")
        .amount(100_000)
        .memo("Don hang 101")
        .template("compact2")
        .build();
    println!("QuickLink: {}", quicklink);

    // 3. Tạo link Deeplink Hub
    let deeplink = Deeplink::new("970436", "1234567890")
        .domain("qr.yourdomain.com")
        .amount(100_000)
        .build_web_hub();
    println!("Deeplink Hub: {}", deeplink);
}

2. Go SDK (sdks/golang)

package main

import (
    "fmt"
    "github.com/vietqr/vietqr-core-sdk/sdks/golang"
)

func main() {
    // 1. Sinh EMVCo QR
    qr, _ := vietqr.New("970436", "1234567890").
        WithAmount(100000).
        WithMemo("Don hang 101").
        WithAccountName("NGUYEN VAN A").
        Build()
    fmt.Println("EMVCo QR:", qr)

    // 2. QuickLink ảnh theo domain riêng
    imgLink := vietqr.NewQuickLink("970436", "1234567890").
        WithDomain("qr.yourdomain.com").
        WithAmount(100000).
        WithTemplate("compact2").
        Build()
    fmt.Println("Image URL:", imgLink)
}

3. Node.js & TypeScript SDK (sdks/nodejs)

import { VietQR, QuickLink, Deeplink } from 'vietqr-core-sdk';

// 1. Sinh EMVCo QR
const qr = new VietQR('970436', '1234567890')
    .setAmount(100000)
    .setMemo('Don hang 101')
    .setAccountName('NGUYEN VAN A')
    .build();
console.log('EMVCo QR:', qr);

// 2. Tạo link ảnh tự host
const imgUrl = new QuickLink('970436', '1234567890')
    .setDomain('qr.yourdomain.com')
    .setAmount(100000)
    .setTemplate('compact2')
    .build();
console.log('Image URL:', imgUrl);

4. PHP SDK (sdks/php)

<?php
require_once __DIR__ . '/vendor/autoload.php';

use VietQR\VietQR;
use VietQR\QuickLink;
use VietQR\Deeplink;

// 1. Sinh chuỗi EMVCo
$qr = (new VietQR('970436', '1234567890'))
    ->setAmount(100000)
    ->setMemo('Don hang 101')
    ->setAccountName('NGUYEN VAN A')
    ->build();
echo "EMVCo QR: " . $qr . "\n";

// 2. Sinh QuickLink
$link = (new QuickLink('970436', '1234567890'))
    ->setDomain('qr.yourdomain.com')
    ->setAmount(100000)
    ->setTemplate('compact2')
    ->build();
echo "Image URL: " . $link . "\n";

5. Python SDK (sdks/python)

from vietqr import VietQR, QuickLink, Deeplink

# 1. Sinh chuỗi EMVCo
qr = (VietQR("970436", "1234567890")
      .set_amount(100000)
      .set_memo("Don hang 101")
      .set_account_name("NGUYEN VAN A")
      .build())
print("EMVCo QR:", qr)

# 2. Sinh QuickLink ảnh
link = (QuickLink("970436", "1234567890")
        .set_domain("qr.yourdomain.com")
        .set_amount(100000)
        .set_template("compact2")
        .build())
print("Image URL:", link)

6. Java SDK (sdks/java)

import io.vietqr.VietQR;
import io.vietqr.QuickLink;

public class App {
    public static void main(String[] args) {
        // 1. Sinh EMVCo
        String qr = new VietQR("970436", "1234567890")
            .amount(100000)
            .memo("Don hang 101")
            .accountName("NGUYEN VAN A")
            .build();
        System.out.println("EMVCo QR: " + qr);

        // 2. Sinh link ảnh
        String imgUrl = new QuickLink("970436", "1234567890")
            .domain("qr.yourdomain.com")
            .amount(100000)
            .template("compact2")
            .build();
        System.out.println("Image URL: " + imgUrl);
    }
}

7. .NET C# SDK (sdks/dotnet)

using VietQR.Core;

// 1. Sinh EMVCo QR
var qr = new VietQRBuilder("970436", "1234567890")
    .WithAmount(100000)
    .WithMemo("Don hang 101")
    .WithAccountName("NGUYEN VAN A")
    .Build();
Console.WriteLine($"EMVCo QR: {qr}");

// 2. Sinh QuickLink URL
var imgUrl = new QuickLink("970436", "1234567890")
    .WithDomain("qr.yourdomain.com")
    .WithAmount(100000)
    .WithTemplate("compact2")
    .Build();
Console.WriteLine($"Image URL: {imgUrl}");

8. C SDK (C99) (sdks/c)

#include "vietqr.h"
#include <stdio.h>

int main() {
    vietqr_t qr;
    vietqr_init(&qr, "970436", "1234567890");
    vietqr_set_amount(&qr, 100000);
    vietqr_set_memo(&qr, "Don hang 101");
    vietqr_set_account_name(&qr, "NGUYEN VAN A");

    char buffer[1024];
    vietqr_build_emvco(&qr, buffer, sizeof(buffer));
    printf("EMVCo: %s\n", buffer);

    char url[512];
    vietqr_build_quicklink(&qr, "qr.yourdomain.com", "compact2", url, sizeof(url));
    printf("QuickLink: %s\n", url);
    return 0;
}

9. C++ SDK (C++17) (sdks/cpp)

#include "vietqr.hpp"
#include <iostream>

int main() {
    auto qr = vietqr::VietQR("970436", "1234567890")
        .amount(100000)
        .memo("Don hang 101")
        .account_name("NGUYEN VAN A")
        .build();
    std::cout << "EMVCo: " << qr << std::endl;

    auto img = vietqr::QuickLink("970436", "1234567890")
        .domain("qr.yourdomain.com")
        .amount(100000)
        .template_name("compact2")
        .build();
    std::cout << "Image URL: " << img << std::endl;
    return 0;
}

10. Chuyển Khoản Qua Số Thẻ (QRIBFTTC) & Giải Mã Chuỗi QR (decodePayload)

Tất cả các SDK chính đều hỗ trợ chuẩn Chuyển tiền nhanh NAPAS 247 tới Số thẻ (QRIBFTTC) bên cạnh Số tài khoản (QRIBFTTA), cùng tính năng giải mã và phân tích chuỗi TLV EMVCo:

Node.js / TypeScript:

import { VietQR, decodePayload, QRPay } from 'vietqr-core-sdk';

// 1. Chuyển tiền tới Số thẻ (QRIBFTTC)
const cardQr = new VietQR('970422', '9704229988776655')
    .setServiceType('QRIBFTTC')
    .setAmount(50000)
    .build();

// 2. Phân tích & Giải mã TLV
const decoded = decodePayload(cardQr);
console.log(decoded.bankBin);       // 970422
console.log(decoded.accountNumber); // 9704229988776655
console.log(decoded.serviceCode);   // QRIBFTTC
console.log(decoded.amount);        // 50000

// 3. Hoặc sử dụng lớp QRPay
const qrPay = new QRPay(cardQr);
console.log(qrPay.isValid);         // true

Python:

from vietqr import VietQR, decode_payload, QRPay

# Chuyển khoản số thẻ
qr = VietQR("970422", "9704229988776655").set_service_type("QRIBFTTC").set_amount(50000).build()

# Giải mã
data = decode_payload(qr)
print(data.bank_bin, data.account_number, data.amount, data.is_card_transfer())

Go:

qr, _ := vietqr.New("970422", "9704229988776655").
    WithServiceType(vietqr.ServiceCard).
    WithAmount(50000).
    Build()

decoded, err := vietqr.DecodePayload(qr)
fmt.Println(decoded.BankBin, decoded.AccountNumber, decoded.Amount)

PHP:

use VietQR\VietQR;
use VietQR\EMVCo;

$qr = (new VietQR('970422', '9704229988776655'))
    ->setServiceType(VietQR::SERVICE_CARD)
    ->setAmount(50000)
    ->build();

$data = EMVCo::decode($qr);
echo $data['bank_bin'] . ' - ' . $data['account_number'] . ' - ' . $data['amount'];

Rust:

use vietqr::{EMVCoBuilder, decode_payload};

let qr = EMVCoBuilder::new("970422", "9704229988776655")
    .service_type("QRIBFTTC")
    .amount(50_000)
    .build();

let decoded = decode_payload(&qr).unwrap();
println!("{} - {} - {:?}", decoded.bank_bin, decoded.account_number, decoded.amount);

.NET C#:

using VietQR.Core;

var qr = new VietQRBuilder("970422", "9704229988776655")
    .WithServiceType("QRIBFTTC")
    .WithAmount(50000)
    .Build();

var decoded = VietQRBuilder.Decode(qr);
Console.WriteLine($"{decoded.BankBin} - {decoded.AccountNumber} - {decoded.Amount}");