Bank transfer QR codes

Pirehub can generate a Vietnamese bank-transfer QR payload and a self-contained SVG image. The QR is rendered on Pirehub infrastructure; bank account details, amount, and memo are not sent to an external QR image provider.

Integration flow

Load the current bank directory from GET /api/v1/tools/bank-qr/banks.
Let the payer select a bank and retain its bin, code, or shortName.
Send the selected identifier and beneficiary account number to POST /api/v1/tools/bank-qr.
Display data.qr.image.dataUrl or store data.qr.payload for another standards-compatible QR renderer.
Display any entries in data.warnings, then ask the payer to verify the beneficiary in their banking app before confirming the transfer.

Authentication

Authenticate integrations with OAuth or a Pirehub API key. Generation requires bank-qr:generate; reading the directory requires bank-qr:banks. Send an API key in x-pirehub-api-key or a bearer header, and keep the credential on your server. Invalid credentials return 401; revoked, expired, or under-scoped credentials return 403. Administrator-issued API keys use the key’s per-minute and monthly request limits. Inspect X-ApiKey-* headers and honor Retry-After after a 429.

Load the bank directory

Use the directory instead of maintaining a bank list in application code. The response contains accepted identifiers, transfer-support metadata, and optional allowlisted logo URLs.

curl --request GET \
  --url https://www.ntanduy.com/api/v1/tools/bank-qr/banks \
  --header "x-pirehub-api-key: $PIREHUB_API_KEY"

An abbreviated response looks like this:

{
  "success": true,
  "data": {
    "banks": [
      {
        "bin": "970422",
        "code": "MB",
        "shortName": "MBBank",
        "name": "Ngân hàng TMCP Quân đội",
        "transferSupported": true
      },
      {
        "bin": "970436",
        "code": "VCB",
        "shortName": "Vietcombank",
        "name": "Ngân hàng TMCP Ngoại Thương Việt Nam",
        "transferSupported": true
      }
    ],
    "count": 2,
    "updatedAt": "2026-08-21T00:00:00.000Z"
  }
}

The example is shortened to two entries. A real response returns the complete directory and a matching count. updatedAt identifies the directory snapshot, not the time of the client request. Cache the response according to its Cache-Control header. A bank logo is optional, so always provide a local fallback and do not treat an image-load failure as a directory failure. Logo URLs point to allowlisted bank-logo asset hosts. Rendering one directly causes the user’s browser to contact that host; cache or self-host permitted assets when your privacy requirements prohibit that request.

transferSupported is compatibility metadata. It does not prove that a beneficiary account exists or can currently receive a transfer.

Generate a QR code

curl --request POST \
  --url https://www.ntanduy.com/api/v1/tools/bank-qr \
  --header 'Content-Type: application/json' \
  --header "x-pirehub-api-key: $PIREHUB_API_KEY" \
  --data '{
    "bank": "MB",
    "accountNumber": "0123456789",
    "amount": 100000,
    "memo": "Thanh toán DH 1028",
    "imageSize": 512
  }'

bank is case-insensitive and may be the six-digit bin, code, or shortName returned by the directory. Keep accountNumber as a JSON string; converting it to a number can remove leading zeroes.

Request fields

Field	Required	Constraints
`bank`	Yes	Directory BIN, code, or short name; 2 to 64 characters
`accountNumber`	Yes	String containing 6 to 19 decimal digits
`amount`	No	Integer from `1` to `9999999999999` VND
`memo`	No	Up to 200 input characters; normalized to at most 25 encoded characters
`imageSize`	No	Integer from `160` to `1024`; defaults to `512` pixels

Unknown fields are rejected, and the complete JSON request body must not exceed 4 KiB.

Static and dynamic QR codes

Request	`data.qr.type`	Payer experience
Omit `amount`	`static`	The banking app asks the payer to enter an amount
Include `amount`	`dynamic`	The amount is encoded in the QR payload

The optional memo can be included in either type.

Successful response

{
  "success": true,
  "data": {
    "bank": {
      "bin": "970422",
      "code": "MB",
      "shortName": "MBBank",
      "name": "Ngân hàng TMCP Quân đội",
      "transferSupported": true
    },
    "transfer": {
      "accountNumber": "0123456789",
      "amount": 100000,
      "memo": "Thanh toan DH 1028"
    },
    "qr": {
      "type": "dynamic",
      "payload": "00020101021238540010A00000072701240006970422011001234567890208QRIBFTTA530370454061000005802VN62220818Thanh toan DH 102863042442",
      "image": {
        "format": "svg",
        "mimeType": "image/svg+xml",
        "dataUrl": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iLi4u",
        "size": 512
      }
    },
    "warnings": [
      {
        "code": "MEMO_NORMALIZED",
        "message": "The transfer memo was normalized for banking-app compatibility."
      }
    ]
  }
}

The SVG data URL above is truncated for readability. The API returns the complete image. data.transfer contains the normalized values actually encoded in the QR, so use it instead of redisplaying unprocessed request input. Assign the data URL to an image src. Do not decode the SVG and inject it into the page as HTML.

Memo normalization and warnings

The API folds Vietnamese diacritics to ASCII, replaces unsupported characters, collapses consecutive spaces, and limits the encoded memo to 25 characters. It returns MEMO_NORMALIZED when the encoded value differs from the submitted memo. LIMITED_TRANSFER_SUPPORT means the institution has limited bank-transfer QR compatibility metadata. Generation still succeeds, but you should test the QR with the intended banking apps before publishing it. Warnings are successful outcomes, not API errors. Handle them by code rather than parsing the human-readable message.

Server example

const response = await fetch('https://www.ntanduy.com/api/v1/tools/bank-qr', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-pirehub-api-key': process.env.PIREHUB_API_KEY,
  },
  body: JSON.stringify({
    bank: '970422',
    accountNumber: '0123456789',
    amount: 100000,
    memo: 'DH 1028',
  }),
})

const body = await response.json()
if (!response.ok) {
  console.error(body.error?.code, body.data?.requestId)
  throw new Error(body.error?.message ?? 'Bank QR generation failed.')
}

console.log(body.data.qr.image.dataUrl)

Failures and safe handling

HTTP status	Code	Action
`400`	`VALIDATION_ERROR`	Correct the bank identifier or request field before retrying
`401`	`UNAUTHORIZED`	Supply a valid OAuth access token or scoped API key
`403`	`FORBIDDEN`	Activate the key and grant the `bank-qr:generate` scope
`413`	`PAYLOAD_TOO_LARGE`	Reduce the JSON body below 4 KiB
`429`	`RATE_LIMITED` or `MONTHLY_QUOTA_EXCEEDED`	Wait for `Retry-After`; monthly quota cannot recover before its reset
`500`	`INTERNAL_ERROR`	Retry with bounded backoff and contact support if it persists
`503`	`SERVICE_UNAVAILABLE`	Retry with bounded backoff when authenticated quota enforcement is unavailable

Every JSON error includes data.requestId. Record that opaque value for support, but branch only on error.code.

QR generation does not validate the beneficiary account, encode or verify an account-holder name, move money, or confirm a transfer. The payer must verify the recipient and amount in their banking app. Payment confirmation requires a separate authenticated bank or payment-provider integration.

Avoid placing real account numbers or generated payloads in application logs, analytics, URLs, or long-lived browser storage. The generation response uses Cache-Control: no-store.

Next steps

Bank directory endpoint

Review the directory response and bank metadata schema.

Generate QR endpoint

Review the complete generation request and response schema.

Errors and retries

Handle failures safely and predictably.

Subscription-backed API keys

Paid self-service keys use shared owner credits and the plan’s per-second and concurrent-job limits. Successful results, including cache hits, consume the configured action cost; errors release the reservation. Video jobs settle at completion. Inspect X-ApiKey-Credit-* and X-ApiKey-RateLimit-*. An optional Idempotency-Key prevents repeated synchronous execution/debits; repeated operations return 409 rather than replaying a response. Job starts use requestId instead. See API plans and idempotency for costs, billing periods, headers, error codes and retry rules.

Getting started

Network intelligence

Video tools

Payment utilities

Screenshot tools

Social embeds

Web data

Integration flow

Authentication

Load the bank directory

Generate a QR code

Request fields

Static and dynamic QR codes

Successful response

Memo normalization and warnings

Server example

Failures and safe handling

Next steps

Bank directory endpoint

Generate QR endpoint

Errors and retries

Subscription-backed API keys

​Integration flow

​Authentication

​Load the bank directory

​Generate a QR code

​Request fields

​Static and dynamic QR codes

​Successful response

​Memo normalization and warnings

​Server example

​Failures and safe handling

​Next steps

Bank directory endpoint

Generate QR endpoint

Errors and retries

​Subscription-backed API keys

Integration flow

Authentication

Load the bank directory

Generate a QR code

Request fields

Static and dynamic QR codes

Successful response

Memo normalization and warnings

Server example

Failures and safe handling

Next steps

Subscription-backed API keys