Create a Checkout with Peru interoperable QR Code

This integration enables merchants to process payments in Peru through the PagSeguro Payment Page using QR code-based digital wallets. Customers scan a QR code displayed at checkout using their preferred wallet app to authorize the payment.

The following wallets are supported:

• Yape
• Plin
• BBVA Wallet
• Scotiabank
• Interbank
• Ligo
• BanBif
• Izipay Ya+

How it works

1. The merchant creates a checkout session through the Payment Page API.
2. The merchant redirects the customer to the Payment Page URL returned in the response.
3. The customer opens their preferred wallet app, scans the QR code displayed on the Payment Page, and authorizes the payment.
4. PagSeguro sends a notification to the merchant's notification_url when the transaction status changes.

🚧

QR code expiry

The checkout URL (expires_at) is valid for 1 hour after the session is created — the customer must access the page within this window. Once the customer accesses the Payment Page and the QR code is generated, the QR code remains valid for 2 days.

Step 1: Build the request

Send a POST request to the Create a Payment Page endpoint.

The only difference from a standard Payment Page request is the charge.e_wallet field, which must be set to NIUBIZ_WALLET.

📘

For Payment Page checkouts, the display language is specified in checkout.language. The integration object does not accept a language field for this flow.

POST /v3/checkouts

Headers

• Authorization: Basic {base64(merchant_id:secret_key)}
• Content-Type: application/json

Request body

{
  "integration": {
    "reference": "REF-XXX-1234567890",
    "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
    "project": 1
  },
  "order": {
    "currency": "PEN",
    "items": [
      {
        "quantity": 1,
        "description": "Pants",
        "unit_price": 50.00
      },
      {
        "quantity": 1,
        "description": "Tshirt",
        "unit_price": 50.00
      }
    ]
  },
  "checkout": {
    "language": "es_ES",
    "redirect_urls": {
      "success": "https://www.merchantwebsite.com/success"
    }
  },
  "charge": {
    "country": "PE",
    "e_wallet": "NIUBIZ_WALLET"
  },
  "payer": {
    "email": "[email protected]",
    "person": {
      "name": "Tiago Silva Santos",
      "birth_date": "1988-06-15",
      "phone": {
        "country_code": "51",
        "number": "999999999"
      }
    }
  }
}

📘

Reference pages

For additional requirements and options, refer to:

• Maximum and Minimum Supported Amounts
• Supported Currencies
• Supported Languages

Step 2: Process the API response

On success, the API returns the checkout session details.

{
  "code": "2bd81fda-c77c-436c-8a4a-4855b9fadec7",
  "url": "https://checkout.international.pagseguro.com/2bd81fda-c77c-436c-8a4a-4855b9fadec7",
  "created_at": "2026-05-12T19:22:36Z",
  "expires_at": "2026-05-12T20:22:36Z"
}

Redirect the customer to the url returned in the response. The checkout URL is valid for 1 hour (expires_at). Once the customer accesses the Payment Page, the QR code generated remains valid for 2 days.

Step 3: Handle transaction status

When the transaction status changes, PagSeguro sends a notification to your notification_url. After receiving the notification, call the transaction status endpoint to retrieve the full details using the transaction code.

GET /transactions/{code}

{
  "transaction-result": {
    "store-id": "10",
    "transactions": [
      {
        "transaction-code": "1224025387",
        "order-id": "REF-XXX-1234567890",
        "order-description": "Pants",
        "status": "COMPLETE",
        "currency": "PEN",
        "amount": "100.00",
        "customer-email": "[email protected]",
        "customer-country": "PE",
        "notify-url": "https://www.merchantwebsite.com/notify?type=transaction",
        "payment-country": "PE",
        "payment-id": "238",
        "payment-name": "niubiz wallet",
        "order-date": "2026-05-12T19:22:36-03:00",
        "payment-date": null,
        "last-status-change-date": "2026-05-12T19:23:40-03:00",
        "chargeback-date": null,
        "refundable": false,
        "refunds": [],
        "payment-response": null,
        "payment": {
          "payment-method": {
            "type": "e_wallet",
            "sub-type": "niubiz wallet"
          }
        }
      }
    ]
  },
  "metadata": {
    "found": "1",
    "page-results": 1,
    "current-page": 1,
    "total-pages": 1
  }
}

For a description of all possible status values, see Transaction Status Description.

You can also monitor status without waiting for a notification by polling the status endpoint directly using the code returned in the checkout response.

Field reference

The payer object is optional. When provided, payer.person.name and payer.person.phone are required.

Error handling

If the request fails, the API returns an HTTP status code other than 201 and an errors array describing the problem.

{
  "errors": [
    {
      "message": "The value provided for charge.e_wallet is not valid.",
      "location": "body.charge.e_wallet"
    }
  ]
}

For the complete list of error codes and descriptions, see the Error Codes and Reason Codes reference pages.

Testing

Use the Payment Page Sandbox Environment to test the Niubiz Wallet integration before going live.