QR Image API v1 Guide | VietQR PNG

01 / QUICK START

All you need is one image URL

Replace the demo BIN and account with verified details. The BIN must exist in the Go service’s local supported directory.

01

Choose a bank

Use the six-digit bank BIN (e.g. MBBank: 970422), not a SWIFT code or short bank name.

02

Pass payment details

Only bank and account are required. Optionally provide amount, purpose and size as query parameters.

03

Embed the image

Put the URL in an img src attribute. The browser loads the PNG via CDN, Nginx and the Go QR Service.

02 / LIVE PLAYGROUND

Build a URL and preview the QR

The playground sends a request only when you click Generate image. The HTML, URL and curl snippets will update automatically.

QR parameters

These example details are for testing only. Do not send real money.

PNG preview

The image loads only after you click Generate image.

Your QR image will appear here.

Generated URL

https://vietnam-bank.com/qr/v1/image.png?bank=970422&account=00123456789&amount=150000&purpose=TEST&size=320

03 / EMBEDDING

Copy an example into your site

Use an img tag for websites, or curl to test the HTTP response. In HTML markup, write & as & within attributes.

https://vietnam-bank.com/qr/v1/image.png?bank=970422&account=00123456789&amount=150000&purpose=TEST&size=320

<img
  src="https://vietnam-bank.com/qr/v1/image.png?bank=970422&amp;account=00123456789&amp;amount=150000&amp;purpose=TEST&amp;size=320"
  width="320" height="320"
  alt="VietQR bank transfer"
  loading="lazy" referrerpolicy="no-referrer"
>

curl -L --fail --output vietqr.png 'https://vietnam-bank.com/qr/v1/image.png?bank=970422&account=00123456789&amount=150000&purpose=TEST&size=320'

No script tag or CORS is needed to display an image with img. Use URLSearchParams or encodeURIComponent when building queries from JavaScript.

04 / PARAMETERS

Supported query parameters

The endpoint is GET /qr/v1/image.png. Unknown parameters and duplicate names are rejected.

Parameter	Required	Example	Validation rules
`bank`	Yes	`970422`	Exactly six digits; must exist in the Go Service’s local bank BIN registry.
`account`	Yes	`00123456789`	1–19 ASCII letters/digits without spaces; normalized to uppercase.
`amount`	No	`150000`	Positive integer VND (1–13 digits). 1.234.567 grouping is accepted; commas and decimals are not.
`purpose`	No	`THANH TOAN DH123`	Up to 25 characters after accent removal and whitespace collapsing; non-ASCII-untranslatable characters are rejected.
`size`	No	`320`	Integer from 128 to 1024; defaults to 320 if omitted.

v1 has no account holder/name or QR logo parameter. An incorrect BIN may generate a PNG but still lead to an unusable payment code.

05 / HTTP RESPONSES

Response types and errors

Success returns image/png; errors are JSON objects with error, message and sometimes field.

200Success

PNG response body with Content-Type: image/png. HEAD returns the same headers without a body.

400Invalid parameters

Missing bank/account, invalid values, duplicate fields or unsupported bank BIN.

404Unknown path

A route other than /image.png (or a public route that was not configured).

405Unsupported method

Only GET and HEAD are supported; others return Allow: GET, HEAD.

422QR encoding failed

Payload exceeds capacity or the requested image is too small for the QR density.

503Service busy

Concurrency/queue limit reached; response may include Retry-After: 1.

414URL too long

The URI exceeds the service’s limit; shorten the query.

{"error":"Bad Request","field":"account","message":"account must have 1 to 19 letters/digits"}

06 / INTEGRATION NOTES

Account data and CDN caching

The server-side Go image API behaves differently from our browser-only JavaScript QR generator.

bank, account, amount and purpose are included in the URL and sent to the CDN/server. They may appear in shared URLs or third-party logs/analytics. Use the API only for details you intend to expose. Never include passwords, verification codes or sensitive information in purpose. The CDN must vary its cache key by the complete query string to prevent mismatched QR images. The Go origin and Nginx do not cache images.

A QR image does not verify account ownership or confirm a completed transfer. Check the recipient and amount in your banking app before paying.

07 / FREQUENTLY ASKED QUESTIONS

Before publishing on your website

Do I need JavaScript, an SDK or an API key?

No. An img tag and a valid URL are enough to display the PNG. This API version does not require an API key.

Do I need CORS to embed QR images on another site?

No for standard img rendering. CORS can matter if you read image pixels through canvas or call fetch from a different domain.

Why does a six-digit BIN still trigger an error?

The BIN must also exist in the Go Service’s local registry. Verify the bank and its VietQR receiving capability before publishing.

Can amount and purpose be omitted?

Yes. Only bank and account are required; without amount, the QR does not fix the transfer amount.

Can I use v1 image API alongside the JavaScript VietQR tool?

Yes. The image API runs on the server for use in img tags; the existing JavaScript generator runs in the browser and is a better choice when account/amount data must stay on-device.

Prefer generating QR codes on-device?

Use the JavaScript VietQR generator instead; it does not submit your account or amount to our QR Image API.

Open VietQR generator