Before you begin
Use an API credential and a valid access token. Sendx-client-id and x-auth-token with each request.
If you manage a connected sub-account, use x-on-behalf-of to select the authorized sub-account. Use the same target account when creating, retrieving, listing, or updating a code. Omitting the header uses the account associated with your credential.
Check available options
Call Get static QR options for the target account. Revieweligible and ineligible_reasons alongside the setup requirements of your selected methods. Inclusion in payment_methods does not establish that channel configuration is complete. Missing configuration for one method does not necessarily prevent creation with another method. The create response determines whether your specific request is accepted. Contact UQPAY support for configuration assistance.
Choose payment methods and a currency from the returned payment_methods and currencies. Available options depend on the target account; a method listed for another account does not establish availability for yours.
Create a code
Call Create a static QR code with the selected payment methods, currency, and amount mode. Use a newx-idempotency-key for each new creation; retry the same request with the same key after an uncertain response. Reusing a key with different parameters returns HTTP 409.
DYNAMIC describes the amount mode of the static code; it does not mean you must generate a new QR code for every payment. Do not send null, an empty string, or "0.00" as amount in this mode.
You can provide a store name and a custom code_no. If omitted or empty, the store name defaults to the target account name and a code number is generated. A new custom code number has at most 10 ASCII letters or digits; options and requests are reserved. Treat code_no as a case-sensitive string and preserve leading zeros. Store names have a 25-byte limit. Optional text fields do not accept null.
Use extension for your own reference information. It is not encoded into the QR payment parameters.
Retrieve and display the code
Save the returnedcode_no. A create response with status: INITIATED means that creation has started; it does not mean that the code is ready for display or that a customer has paid.
Use Retrieve a static QR code to check the resource. Use Retrieve static QR code details to obtain qr_payload. While creation is INITIATED, details may return 404; wait and retry instead of creating another code. Set a retry limit and contact UQPAY support if the code does not become ready. Display the QR code only after creation succeeds and the payload is available. Encode the returned payload unchanged with your QR rendering library.
The static code’s SUCCEEDED status describes code creation. Use payment notifications to determine whether a particular payment succeeded.
Receive and reconcile payments
Configure PaymentIntent Result and PaymentAttempt Result notifications. Static QR payments use these acquiring events. Identify the transaction account withdata.account_id, associate it with a static code using the code number, and track each payment with data.payment_intent_id and data.payment_attempt_id (in PaymentAttempt notifications). A code number can be reused across payments and must not replace a payment identifier.
In the table, <method> is the payment-method details object named by data.payment_method.type, such as paynow. Static QR association fields are returned only when the transaction contains that information.
Amount mode, store name, city, code creation status, and code creation time describe the static QR resource. Do not treat them as same-named payment notification fields. Notification timestamps and statuses describe the transaction.
See the static QR payment example in PaymentIntent Result for the notification structure. A failed PaymentAttempt alone does not establish that its PaymentIntent has failed.
Find codes and update reference information
Use List static QR codes to search within the target account. Filters include code number, currency, payment method, and creation time. Preserve leading zeros when filtering bycode_no. The list returns items in data, the total number of matching codes in total_items, and the total number of pages in total_pages. Request the next page while page_number is less than total_pages.
Supply both create_start_time and create_end_time in YYYY-MM-DDTHH:mm:ss+08:00 format when filtering by time. Start must be earlier than end, with a maximum range of 30 days. Encode the plus sign in query strings as %2B.
Use Update static QR code extension to change extension. The limit is 512 characters. An empty string clears the value; null is not accepted. An idempotency key is not required and does not replay an earlier update. This operation updates reference information; it does not change the code’s payment methods, currency, amount mode, or amount.