Dynamic QR payment

Generate a per-transaction QR code for Raast payments.

Dynamic QR codes encode order-specific metadata so you can present a scannable Raast request at checkout. Each QR is single-use and maps to a specific aggregator merchant.

Prerequisites

• {{aggregator_id}} and {{secret_key}}
• aggregator_merchant_identifier for the merchant collecting funds
• Optional order metadata and amount

Flow summary

1. Load merchant identifiers

   Retrieve the aggregator_merchant_identifier from the merchant creation response.

2. Create the dynamic QR

   Call POST /v1/aggregators/{{aggregator_id}}/qrs with type: DYNAMIC and the order details.

3. Render the QR

   Render the returned data.code string as a QR image in your checkout UI.

4. Track the outcome

   Listen for payment webhooks or poll the payment endpoint to confirm settlement.

Set {{base_url}} to https://dev.api.getsafepay.com/raastwire in Sandbox or https://api.getsafepay.com/raastwire in Production.

request_id must be a UUID v4 (exactly 36 characters with hyphens), for example 550e8400-e29b-41d4-a716-446655440000. Do not pad order_id or use arbitrary strings — those fail validation.

Dynamic QR

Request Fields

type · string · required

Use DYNAMIC to create a single-use QR code.

aggregator_merchant_identifier · string · required

Token returned from merchant creation (data.token).

request_id · string · required

UUID v4 that enforces idempotency (exactly 36 characters with hyphens). Reuse only when retrying the same payload. Generate with UUID v4 library.

order_id · string

Optional order reference surfaced in webhook payloads.

amount · integer

Amount in paisa to embed in the QR; omit to let the payer choose the amount.

expiry_in_minutes · integer

Optional expiry window (defaults to 180) after which the QR is invalid.

API Example

cURL

curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/qrs" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "DYNAMIC",
    "aggregator_merchant_identifier": "{{aggregator_merchant_identifier}}",
    "order_id": "ORDER-4921",
    "request_id": "{{request_id}}",
    "amount": 7500,
    "expiry_in_minutes": 180
  }'

Sample Response

{
  "api_version": "v1",
  "data": {
    "token": "qr_4076ad61-75cf-44a3-97a1-b66643ea3bf2",
    "aggregator_merchant_id": "am_be454a50-7612-4dc6-a97e-284ebbe7ae93",
    "type": "DYNAMIC",
    "code": "0002010102122876003285bc899c1dd443e3b3beb24631aef093...",
    "created_at": "2025-04-28T10:26:48Z"
  }
}

Render the QR

Feed data.code into your preferred QR library (for example, qrcode.react, qr-image, or qrcodejs). The returned string is EMVCo-compliant and ready for Raast banking apps.

Webhook events to expect

• payment.created
• payment.completed
• payment.settled
• payment.failed
• payment.rejected

When the customer pays, monitor the associated payment token via GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}} or your webhook handler to confirm settlement.

See also

• Payment lifecycle guide
• QR codes
• Webhooks delivery
• Create QR