QR Wallet Payment

Accept Yassir Wallet payments by showing a QR code to your customer.

Overview#

QR wallet payment follows the same Payment Intents API as other payment methods, with two important differences: create the intent with transactionType: QR_CODE, then display the QR image returned by the proceed response.

Do not fulfill on QR generation

Creating the QR image does not mean the customer has paid. Fulfill only when the payment reaches statusCode: 2.

Base URL#

Use the environment base URL from the API Reference. See the Payment Intents API Reference for complete endpoint parameters, request bodies, and responses.

Flow Summary#

Create a payment intent with transactionType: QR_CODE.
Proceed the intent with paymentMethodCode: WALLET_V2.
Display data.metadata.qrImageUrl to the customer.
The customer scans the QR code and confirms the payment in the Yassir app.
Wait for webhook notification or call the check endpoint until the payment is terminal.

Sequence Diagram#

Loading diagram...

QR Proceed Response Difference#

A QR proceed response returns require3DS: false and a qrImageUrl in metadata. Display this URL to the customer.

QR proceed response

{
  "code": 200,
  "status": "success",
  "data": {
    "require3DS": false,
    "metadata": {
      "qrImageUrl": "https://storage.googleapis.com/.../qr-codes/2fddefa2-f137-4afd-b6a8-b1623d86b115.png?..."
    }
  },
  "message": "payment proceeded successfully"
}

{
  "code": 200,
  "status": "success",
  "data": {
    "require3DS": false,
    "metadata": {
      "qrImageUrl": "https://storage.googleapis.com/.../qr-codes/2fddefa2-f137-4afd-b6a8-b1623d86b115.png?..."
    }
  },
  "message": "payment proceeded successfully"
}

QR Payload#

Display data.metadata.qrImageUrl exactly as returned. The QR image contains a Yassir Wallet payload and should not be parsed or modified by the merchant.

The QR image filename is based on the wallet QR transaction identifier:

<walletQrTransactionId>.png

Status Handling#

QR payments use the same payment states as other payment intents. Refer to the Payment States guide for the canonical status list.

The merchant order should remain pending while the payment is still processing. Fulfill the order only when the payment reaches the successful state.

Merchant Webhook#

To receive automatic completion notifications, share your webhook URL with the Yassir E-Payment team so it can be configured for your merchant service.

Webhook payload

{
  "actionId": "merchant-order-123",
  "remoteStatus": "SUCCESS",
  "remoteStatusCode": 2,
  "contextType": "ORDER",
  "additionalData": {
    "paymentCheckoutId": "checkout-123"
  },
  "orderId": "2fddefa2-f137-4afd-b6a8-b1623d86b115"
}

{
  "actionId": "merchant-order-123",
  "remoteStatus": "SUCCESS",
  "remoteStatusCode": 2,
  "contextType": "ORDER",
  "additionalData": {
    "paymentCheckoutId": "checkout-123"
  },
  "orderId": "2fddefa2-f137-4afd-b6a8-b1623d86b115"
}

Cancellation#

Keep the merchant order pending while the payment is still processing.
Do not reuse the same QR image after the checkout session expires.
If the customer wants to retry, create a new payment intent and generate a new QR image.

Error Handling#

For 400, fix the request payload before retrying.
For 401, check service credentials, x-service, and environment.
For 5xx, retry with the same Idempotency-Key when retrying /proceed.
While the payment is processing, do not retry /proceed; use /check or wait for the webhook.