QRCharge

A QRCharge represents the QR code encoding of a payment. It is the visual and data artifact that bridges the digital payment intent with the physical (or on-screen) scanning action. Every PaymentIntent of type "one_time" or "subscription" produces exactly one QRCharge.

QRCharge objects are generated by the payment channel provider (e.g. Alipay, WeChat Pay) and returned to the ItPay gateway, which then makes them available to the payer agent for display.

Fields

Field	Type	Description
`id`	`string` (UUIDv7)	Globally unique QR charge identifier
`payment_intent_id`	`string`	The PaymentIntent this QR code belongs to
`channel`	`string`	Payment channel that generated the QR (e.g. `"alipay"`, `"wechat"`)
	`qr_standard`	`string`
`qr_data`	`string`	Raw QR payload string (what the scanner reads)
`qr_image_url`	`string` (URL)	PNG image URL of the QR code
`qr_image_svg`	`string` (SVG)	Inline SVG markup of the QR code
`display`	`DisplayInfo`	Human-readable display fields shown alongside the QR
`scan_url`	`string` (URL)	Deep link URL — opens the payer's wallet app directly
`expires_at`	`string` (ISO 8601)	Timestamp after which the QR code is invalid
`status`	`string`	Current status — `"active"`, `"scanned"`, `"expired"`, `"consumed"`

DisplayInfo

Field	Type	Description
`amount`	`string`	Formatted amount shown to the payer (e.g. `"CNY 6.99"`)
`merchant_name`	`string`	Business name displayed on the payment screen
`reference`	`string`	Short reference string shown in the payer's transaction history

JSON Example

{
  "id": "qr_01J7XZ2C3D4E5F6G7H8I9J0K",
  "payment_intent_id": "pi_01J7XZ1A2B3C4D5E6F7G8H9IK",
  "channel": "alipay",
  "qr_standard": "EMVCo",
  "qr_data": "00020101021226850014A0000006150001021567000000...",
  "qr_image_url": "https://pay.summarybot.ai/qr/qr_01J7XZ2C3D4E5F6G7H8I9J0K.png",
  "qr_image_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\" shape-rendering=\"crispEdges\"><rect width=\"256\" height=\"256\" fill=\"white\"/><path d=\"M0 0h28v28H0z...\" fill=\"black\"/></svg>",
  "display": {
    "amount": "CNY 6.99",
    "merchant_name": "SummaryBot Inc.",
    "reference": "SM-42PGS-20260527"
  },
  "scan_url": "alipay://pay?qr=01J7XZ2C3D4E5F6G7H8I9J0K",
  "expires_at": "2026-05-27T09:15:05Z",
  "status": "active"
}

Display Flow

The typical QR display flow proceeds as follows:

┌──────────────────┐     ┌───────────────────┐     ┌──────────────────┐
│  Agent shows QR  │ ──► │  Payer scans with  │ ──► │  Wallet displays  │
│  on screen       │     │  mobile wallet     │     │  payment details  │
│                  │     │                    │     │                   │
│  ┌──────────┐    │     │  ┌──────┐          │     │  Amount: ¥6.99   │
│  │ ██ █ ██ │    │     │  │████ │          │     │  Merchant: ...    │
│  │ ██ █ ██ │    │     │  │ ██  │          │     │  Confirm? [YES]  │
│  └──────────┘    │     │  └──────┘          │     └──────────────────┘
│  ¥6.99           │     │                    │
│  SummaryBot      │     │                    │
└──────────────────┘     └───────────────────┘     └──────────────────┘

QR Data Encoding (EMVCo)

The qr_data field follows the EMVCo Merchant Presented QR (MPQR) specification. The payload is a TLV (Tag-Length-Value) structure that encodes:

Payload Format Indicator (tag 00)
Point of Initiation Method (tag 01) — 11 for static, 12 for dynamic
Merchant Account Information (tag 26–51) — network-specific data (Alipay, WeChat, etc.)
Merchant Category Code (tag 52)
Transaction Currency (tag 53) — ISO 4217 numeric code
Transaction Amount (tag 54)
Country Code (tag 58)
Merchant Name (tag 59)
Merchant City (tag 60)
CRC (tag 63) — 16-bit CCITT CRC of the entire payload

ItPay uses dynamic QR codes (Point of Initiation Method 12) by default, meaning a unique QR is generated per PaymentIntent and cannot be reused.

note

WeChat Pay does not follow the EMVCo standard. Its qr_data is a proprietary weixin://wxpay/bizpayurl/up?pr=... URL scheme. The merchant renders this as a standard QR Code image; WeChat's app recognizes the weixin:// scheme when scanned. For WeChat Pay transactions, the qr_standard field is "WeChat" rather than "EMVCo".

QRCode Lifecycle

Status	Description
`active`	QR code is valid and waiting to be scanned
`scanned`	QR code has been scanned; the associated PaymentIntent is in `scanning` state
`expired`	The QR code's validity period has ended
`consumed`	The associated PaymentIntent has reached a terminal state (`succeeded`, `cancelled`, or `expired`) and the QR is no longer usable

Key Behaviors

One QR per intent: Each PaymentIntent produces at most one active QRCharge. Generating a new QR charge for the same intent invalidates the previous one.
Short-lived by design: QR codes expire in sync with their PaymentIntent (expires_at). Do not cache QR images beyond this time.
SVG for inline display: The qr_image_svg field provides a self-contained SVG string that can be rendered directly in an MCP client UI or browser without an extra network request.
Scan URL: The scan_url is a platform-specific deep link (e.g. alipay://, weixin://). Agents on mobile can open it directly to launch the wallet app. Desktop agents should display the QR image for the user to scan with their phone.
EMVCo compliance: Alipay and SEA channel QRs follow EMVCo TLV format, scannable by any EMVCo-compliant wallet. WeChat Pay QRs use a proprietary weixin:// URL — only the WeChat app can process them.

Fields​

DisplayInfo​

JSON Example​

Display Flow​

QR Data Encoding (EMVCo)​

QRCode Lifecycle​

Key Behaviors​