Skip to main content

QR Interoperable

  POST https://api-sandbox.epag.io/qrInteroperable/simple

Overview​

This process is designed to facilitate payments through QR Interoperable, the interoperable QR code standard in Peru. It allows your customers to pay quickly and securely by scanning a single QR code with any compatible banking app or digital wallet, optimizing the user experience and conversion rates.

The process offers:

  • Immediate display of a QR code, without the need for complex preliminary data collection. To use this process, simply send the required fields as indicated in the documentation.
  • A streamlined checkout experience. The customer scans the QR code, confirms the amount in their banking or wallet app, and completes the payment. This simplicity contributes to a higher conversion rate.
info

QR Interoperable is currently available via API only. Checkout support is not yet available for this payment method.

QR Interoperable Flow​

Authorization​

HeaderValue
X-Auth-TokenMY_ACCESS_TOKEN

Request description​

  • contract_id (required/string): Merchant's contract id.
  • notification_url (required/string): URL to post callbacks to for this payment.
  • reference_id (required/string/max 45 chars): External code created by the merchant to reference this payment (e.g., order number).
  • ip_address (optional/string): Remote IP Address (IPv4/IPv6).
  • extra_data (optional/object): Optional extra data that you can use with the transaction.
  • payment (required/object): The payment data:
    • amount (required/float): Total amount of the payment. The value must have a maximum of two decimal places.
    • asset (required/string): Reference code for the asset for the sale's amount.
    • country (required/string): Country code in ISO 3166-2.
    • currency (required/string): Currency code in ISO-4217.
    • qr_interoperable (optional/object): QR Interoperable specific data:
      • expiration_date (optional/string): Expiration date of the QR code in YYYY-MM-DD format. The QR code expires at the end of the informed day (23:59:59).
  • person (required/object): The person data:
    • email (required/string): Person’s email provided to the merchant.

Response Description​

  • transaction_status (string): Current status of the payment.
  • payment_token (string): Unique payment identification for this payment.
  • refresh_token (string): Updated access token for future calls.
  • reference_id (string): External code created by the merchant to reference this payment.
  • qr_code (string): Base64 encoded zipped PNG of the QR code to be scanned.
  • amount (string): Amount of this payment.
  • expiration_date (string): ISO 8601 timestamp indicating when the QR code will expire.
  • totals (object): The payment totals.
    • amount (float): Amount in the default region asset.
    • asset (string): Asset used in this amount.
    • original_amount (float): Amount as informed by the merchant.
    • original_asset (string): Asset used in this originalAmount.
    • customer_fees (float): Total calculated fee assigned to the customer.
    • customer_amount (float): Total amount for the customer (amount + customer_fees).
  • customer_fees (object): List of incident customer fees and their respective values.

Example Request​

Example Request​

200 - Success
    curl --location 'https://api-sandbox.epag.io/qrInteroperable/simple' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --data-raw '{
        "contract_id": "MY_CONTRACT_ID",
        "notification_url": "https://my.notification.url",
        "reference_id": "MY_REFERENCE_ID",
        "ip_address": "0.0.0.0",
        "payment": {
            "amount": 100.00,
            "asset": "PEN",
            "country": "PE",
            "currency": "PEN",
            "qr_interoperable": {
                "expiration_date": "2026-10-31"
            }
        },
        "person": {
            "email": "[email protected]"
        },
        "extra_data": {
            "my-conciliation-number": "xxxxxx"
        }
    }'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "transaction_status": "PROCESSING",
      "payment_token": "4b408433-e70c-4f4b-8ea9-b6eec806b7c5",
      "reference_id": "ecc7070b-b719-46f1-9fd1-982153886a6c",
      "qr_code": "BASE64_ZIPPED_PNG",
      "amount": "100.00",
      "expiration_date": "2026-10-31T23:59:59",
      "totals": {
        "amount": 100,
        "original_amount": 100,
        "original_asset": "PEN",
        "customer_fees": 0,
        "customer_amount": 100,
        "asset": "PEN"
      },
      "customer_fees": {},
      "refresh_token": "MY_ACCESS_TOKEN"
    }

Notification & Callback​

For status notifications, callback payloads, and how to query updates for this transaction, see Payments - Status Maps & Updates.