Create a Checkout with Niubiz

This integration enables merchants to leverage the PagSeguro Checkout in Peru to offer payments via digital wallets using QR code technology. Through this integration, the following wallets are supported: Yape, Plin, BBVA Wallet, Scotiabank, Interbank, Ligo, BanBif, and Izipay Ya+.

To complete a payment, the end customer must open their preferred digital wallet application, scan the QR code presented at checkout, and authorize the transaction directly within the selected wallet. QR code expires after 2 days.

How it works

The merchant creates a checkout through the Payment Page API.
The customer is redirected to the PagSeguro Payment Page, where a QR code is displayed.
The customer opens their preferred wallet app, scans the QR code, and authorizes the payment.
PagSeguro sends a notification to the merchant's notification_url with the final status.

🚧
The QR code expires 2 days after creation.

Request

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

POST /v3/checkouts

{
  "integration": {
    "reference": "REF-XXX-1778529330143",
    "notification_url": "https://yoururlnotification",
    "project": 1
  },
  "order": {
    "currency": "PEN",
    "items": [
      {
        "quantity": 1,
        "description": "Pants",
        "unit_price": 1000
      },
      {
        "quantity": 1,
        "description": "T-shirt",
        "unit_price": 1000
      }
    ]
  },
  "checkout": {
    "language": "es_ES",
    "redirect_urls": {
      "success": "http://yoururlnotificationsuccess"
    }
  },
  "charge": {
    "country": "PE",
    "e_wallet": "NIUBIZ_WALLET"
  },
  "payer": {
    "email": "********@test.com",
    "person": {
      "name": "Tiago ******** ******",
      "birth_date": "1988-**-**",
      "phone": {
        "country_code": "51",
        "number": "*****999999"
      }
    }
  }
}

Response

{
  "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"
}

Notification

GET /transactions/2bd81fda-c77c-436c-8a4a-4855b9fadec7

{
  "transaction-result": {
    "store-id": "10",
    "transactions": [
      {
        "transaction-code": "1224025387",
        "order-id": "TEST_1778164567134",
        "order-description": "produto teste",
        "status": "COMPLETE",
        "currency": "PEN",
        "amount": "10.00",
        "customer-email": "********@uolinc.com",
        "customer-country": "PE",
        "notify-url": "https://yoururlnotification",
        "payment-country": "PE",
        "payment-id": "238",
        "payment-name": "niubiz wallet",
        "order-date": "2026-05-07T11:36:19-03:00",
        "payment-date": null,
        "last-status-change-date": "2026-05-07T11:37:23-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
  }
}

Field reference

Field	Required	Description
integration.reference	Required	Merchant's unique reference for the transaction
integration.notification_url	Required	URL that receives status updates
integration.project	Optional	Integration project identifier (≥ 1)
order.currency	Required	ISO code, e.g. `PEN`, `BRL`
order.items[].quantity	Required	Quantity of the item
order.items[].description	Required	Description of the item
order.items[].unit_price	Required	Unit price (minor units)
checkout.language	Required	`en_US`, `es_ES`, `pt_BR`, `pt_PT`, `tr_TR`
checkout.redirect_urls.success	Required	URL the customer is redirected to on success
charge.country	Required	Country of charge, e.g. `PE`
charge.e_wallet	Required	`NIUBIZ_WALLET`
payer.email	Optional	Customer's email
payer.person.name	Required	Customer's full name
payer.person.birth_date	Optional	`YYYY-MM-DD`
payer.person.phone.country_code	Required	Peru: `51`
payer.person.phone.number	Required	Local phone number