Skip to main content
POST
Generate a bank transfer QR code
Authenticate with OAuth or a Pirehub API key with the bank-qr:generate scope. This endpoint creates the EMV payload and SVG locally on Pirehub infrastructure; it does not forward the bank, account number, amount, or memo to an external QR image service. See the Bank transfer QR guide for the complete integration flow, input constraints, QR types, warning handling, and security limitations. Use GET /api/v1/tools/bank-qr/banks to obtain accepted BINs, bank codes, short names, transfer-support metadata, and allowlisted public logo URLs. The server refreshes this metadata from an upstream bank-directory service and uses a versioned local snapshot if that directory is temporarily unavailable. Payment details are never included in this metadata request. Keep accountNumber as a JSON string so leading zeroes are preserved. Review the bank directory endpoint for its complete response schema and cache behavior.
The response contains:
  • data.qr.payload: the complete bank-transfer QR payload;
  • data.qr.image.dataUrl: a self-contained SVG data URI suitable for an <img>;
  • data.transfer: values after normalization;
  • data.warnings: compatibility notices that should be shown to operators.
Generating a QR code does not verify that the account exists, that the displayed beneficiary name is correct, or that a transfer succeeded. Always ask the payer to confirm the recipient in their banking app. Payment confirmation requires a separate, authenticated bank or payment-provider integration.

Server integration

Keep API credentials on your server. Administrator-issued API keys use per-key minute and monthly request limits, reported through X-ApiKey-*. Honor Retry-After after a 429.
Memo text is folded to ASCII, unsupported characters are replaced, consecutive spaces are collapsed, and the encoded value is limited to 25 characters for broad banking-app compatibility. When normalization changes the submitted value, the API returns a MEMO_NORMALIZED warning. A LIMITED_TRANSFER_SUPPORT warning means the directory has limited compatibility metadata for that institution; test the QR before publishing it.

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.

Authorizations

Authorization
string
header
required

OAuth 2.0 Authorization Code with PKCE, issued by Pirehub's Clerk authorization server. Request only the scopes required by the operation.

Headers

Idempotency-Key
string

Self-service keys only. Owner-scoped operation identifier; reuse after admission returns 409 without another debit or execution. USAGE_CONCURRENCY_EXCEEDED retains no new reservation: wait and retry with the same identifier and payload. No response replay. Video jobs use requestId instead.

Required string length: 1 - 80
Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json
bank
string
required

A six-digit BIN, bank code, or short name returned by the bank-directory endpoint.

Required string length: 2 - 64
accountNumber
string
required

Beneficiary account number. Keep this as a JSON string so leading zeroes are preserved.

Pattern: ^[0-9]{6,19}$
amount
integer

Optional amount in VND. Omit to create an open-amount QR.

Required range: 1 <= x <= 9999999999999
memo
string

Optional transfer memo. It is folded to ASCII, sanitized, and truncated to 25 characters for compatibility.

Maximum string length: 200
imageSize
integer
default:512

SVG width and height in pixels.

Required range: 160 <= x <= 1024

Response

The normalized transfer details, EMV payload, and locally rendered SVG data URI.

success
boolean
required
data
object
required