Create a VietQR payment request.

Args: amount: Amount in VND, minimum 1 000. description: Short description for the payer (e.g. "Order #123 — 2 kg coffee"). ttl_minutes: QR validity window in minutes (5–1 440, default 60). metadata_note: Internal note from the agent (order id, conversation id, etc.) — echoed back in webhook events.

Returns: id, pay_code, QR image URL, and checkout page URL. Send qr_image_url or checkout_url to the payer, then call await_settlement(id) to wait for the money to arrive.

Check the current status of a payment request.

Returns: One of: pending | settled | underpaid | expired | cancelled, along with the amount received so far. Only treat a payment as complete when status=settled.

Wait for a payment request to be settled (polls on behalf of the agent).

Polls every 5 seconds until status != pending or the timeout is reached (maximum 600 s). Call this after sending the QR to the payer. If the timeout expires while still pending, ask the user whether to keep waiting or cancel.

Args: payment_request_id: The id returned by create_payment_request. timeout_seconds: How long to wait in seconds (10–600, default 180).

List the most recently settled transactions (quick reconciliation).

Args: limit: Number of transactions to return (1–50, default 10).