Deeplink Payments
A deeplink lets your mobile app open MULTICAIXA Express directly for a QR Code Payment — the customer does not need to scan a QR code. GPO creates the underlying charge and returns a URL that carries the encoded QR Code Payment payload.
mcxwallet://purchaseOpens MULTICAIXA Expressqrref={qrRef}Encoded QR Code Payment payloadcallback_url={app-return-url}Optional — return to your appReturning to your app is not a payment confirmation
Complete the order only after your backend receives the transaction notification with status: ACCEPTED.
Integration flow
Create a deeplink charge
http
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
merchantId | path | string | Yes | Merchant identifier. |
includeQrImage | query | boolean | No | Default false. When true, includes the QR Code image as Base64. |
callbackUrlScheme | query | string | No | URL registered by your mobile app, for example merchantapp://payment-result. MULTICAIXA Express can use it to return control to the app. |
Request
json
Request rules
amountmust be greater than or equal to1.config.viewTypemust beQR_CODE. Any other value returns400 Bad Request.posIdmust be a terminal associated with the merchant.- GPO replaces any client-supplied
notify.callbackUrlwith the callback URL configured by IZI Pay. callbackUrlSchemeis an application return URL, not your server's payment-notification URL. It must be registered and handled by your Android or iOS app.
Response
json
| Field | Type | Description |
|---|---|---|
chargeId | string | Unique identifier of the created charge. |
qrRef | string | Complete QR Code Payment payload. Not the charge ID or order reference. |
deeplinkUrl | string | URL that opens MULTICAIXA Express. |
deeplinkUrlWithCallback | string | null | Deeplink with the application return URL. Only when callbackUrlScheme is supplied. |
qrCodeBase64 | string | null | Base64 QR Code image. Only when includeQrImage=true. |
amount | number | Charge amount. |
reference | string | Merchant reference supplied in the request. |
expectedStatuses | object | Status names used by the optional app-return flow. |
Using the response
- Open
deeplinkUrlWithCallbackwhen your app supplied and registeredcallbackUrlScheme; otherwise opendeeplinkUrl. - Do not modify
qrRefor build your own deeplink from the charge ID. - Do not mark the order as paid just because the customer returned to your app.
Backend payment confirmation
Deeplink and QR Code Payment share the same notification path. After an accepted transaction, IZI Pay forwards the transaction JSON to the callback configured for your merchant or terminal.
http
json
orderOrigin: QR_CODE is expected — a deeplink uses the QR Code Payment mechanism.
Process every notification as follows:
- Validate the configured
Access-Key. - Use the transaction
idas the primary duplicate-detection key. - Confirm that
statusisACCEPTED. - Match the notification to your order using the stored charge and reference data.
- Process it idempotently — duplicates must not fulfil an order twice.
- Mark the order as paid and return a successful HTTP response.
To refund a deeplink payment, use Refund QR Code payment with the transaction id.
App return statuses
When MULTICAIXA Express returns to your app through callbackUrlScheme, it reports one of these values. They are separate from the backend transaction payload.
SUCCESSThe app return reports success.Wait for the backend ACCEPTED confirmation.INDETERMINATEThe app cannot determine the result.Show “Confirming payment” and wait for the backend.ERROR_NO_USERThe customer is not active in MULTICAIXA Express.Inform the customer and offer another payment method.ERRORThe payment was cancelled or failed.Do not fulfil the order.Error responses
| HTTP status | Scenario |
|---|---|
400 | config.viewType is not QR_CODE, or the request is invalid. |
401 / 403 | The access token is missing, invalid or lacks permission. |
| Upstream status | The underlying GPO charge creation was rejected. |
500 | No charge ID in the upstream response, the QR payload could not be retrieved, or an internal step failed. |
json
Retry and recovery
No idempotency key
The endpoint does not accept an idempotency key, and a charge may already exist when a later step fails. After a timeout or an uncertain response, do not retry automatically — reconcile first with IZI Pay support or the transaction query.
Production checklist
Not part of the merchant integration
The placeholder endpoints POST /v1/deeplink/callback and GET /v1/deeplink/callback/{chargeId}/status are not the production payment-confirmation path and must not be called by merchants.