PagaLeve

This guide explores how to integrate PagaLeve, a Pix-based payment provider for Brazil, into your checkout. Yuno supports both the Yuno SDK (recommended) and Direct API workflows. You’ll learn how to:

Make one-time Pix payments with PagaLeve
Make Pix Parcelado (installment Pix) payments with PagaLeve

Requirements

Before starting, you need:

A Yuno account with Dashboard access
API keys and an account_id (found in the dashboard)
A PagaLeve connection set up in your Yuno account (see Connections)

Create and manage customers

Create the customer once using your external merchant_customer_id, then retrieve by Yuno id or by merchant_customer_id as needed.

Use the Create Customer endpoint and provide your own merchant_customer_id (the unique id of the customer in your system). The response returns id which is the Yuno customer id.
Use Retrieve Customer with the Yuno id.
Use Retrieve Customer by External Id with query parameter merchant_customer_id.

Creating a Yuno customer record first is not required. PagaLeve accepts customer info (CPF, email, name, phone, birth date, address) directly in the Create Payment call, the same as plain Pix. Creating the customer up front is still recommended for consistency with your other payment methods.

One-time Pix payment

Use PagaLeve to accept a standard, single Pix payment.

Yuno SDK
Direct API

Step 1: Create a checkout session

Start by creating a checkout session using the Create Checkout Session endpoint.

{
  "account_id": "{{account_id}}",
  "country": "BR",
  "customer_id": "{{customer_id}}",
  "merchant_order_id": "order-0000024",
  "payment_description": "One-time Pix Payment with PagaLeve",
  "amount": {
    "currency": "BRL",
    "value": 15000
  }
}

The response returns a checkout_session ID.

Step 2: Initialize the SDK

Initialize Yuno’s SDK (Web, Android, or iOS) with the checkout_session ID. PagaLeve renders as an available payment option in the SDK interface, using payment method type "PIX" for a one-time payment.

The customer completes the payment on PagaLeve’s hosted checkout page. If your PagaLeve connection has TRANSPARENT_CHECKOUT enabled, the customer completes it inside the SDK instead, through a checkout URL. Either way, PagaLeve confirms the result to Yuno through a webhook. See Status transitions below.

Step 1: Create a payment

Use Create payment with the Direct workflow.

{
  "description": "One-time Pix Payment with PagaLeve",
  "account_id": "{{account_id}}",
  "merchant_order_id": "0000024",
  "country": "BR",
  "amount": {
    "currency": "BRL",
    "value": 150
  },
  "customer_payer": {
    "id": "{{customer_id}}"
  },
  "callback_url": "https://your-callback.com",
  "workflow": "DIRECT",
  "payment_method": {
    "type": "PIX"
  }
}

The response returns the checkout’s redirect_url in the payment method detail. Redirect the customer there to complete the payment; PagaLeve confirms the result to Yuno via webhook. See Status transitions below for how PagaLeve’s states map to Yuno’s.

Step 2: Confirm payment

Use Retrieve payment by id to confirm the final status.

Pix Parcelado (installment) payment

PagaLeve supports Pix Parcelado, letting customers split a Pix payment into installments. The customer picks the installment plan on PagaLeve’s own checkout page — Yuno doesn’t return available plans up front, and no plan or installments data is sent in the Create Payment call.

Yuno SDK
Direct API

Step 1: Create the payment

Create the payment with payment_method.type "PIX_PARCELADO". Pass the order’s line items in additional_data.order.items so PagaLeve can build the installment offer.

{
  "description": "Pix Parcelado Payment with PagaLeve",
  "account_id": "{{account_id}}",
  "merchant_order_id": "0000023",
  "country": "BR",
  "amount": {
    "currency": "BRL",
    "value": 250
  },
  "customer_payer": {
    "id": "{{customer_id}}"
  },
  "workflow": "SDK_CHECKOUT",
  "checkout": {
    "session": "{{checkout_session_id}}"
  },
  "payment_method": {
    "type": "PIX_PARCELADO"
  },
  "additional_data": {
    "order": {
      "items": [
        {
          "id": "{{sku}}",
          "name": "{{item_name}}",
          "quantity": 1,
          "unit_amount": 250,
          "category": "{{item_category}}"
        }
      ]
    }
  }
}

The response returns the redirect at payment_method.payment_method_detail.bank_transfer.redirect_url — Pix Parcelado is categorized as BANK_TRANSFER internally, so it uses the same detail object as other bank transfer methods. installments and installments_plan_id come back empty at creation; the customer chooses the installment count on PagaLeve’s hosted checkout page after the redirect. The payment starts out Created, and the final Successful or declined status arrives through the webhook. See Status transitions below.

Step 1: Create payment

Use Create payment with the Direct workflow and payment_method.type "PIX_PARCELADO". Pass the order’s line items in additional_data.order.items, the same shape shown in the SDK tab above.

See Status transitions below for how PagaLeve reports status changes, and the SDK tab above for where the redirect URL comes back in the response and where the customer chooses the installment plan.

Step 2: Retrieve payment

Use Retrieve payment by id to confirm the final status.

Limitations

Currency is limited to BRL.
Pix and Pix Parcelado share the same refund flow, both are refundable the same way, including DUPLICATE, FRAUDULENT, and REQUESTED_BY_CUSTOMER reasons.
PagaLeve doesn’t use an enrollment/vaulting pattern, unlike NuPay. Every payment is a one-time checkout.

Status transitions

PagaLeve reports payment status through webhooks, processed asynchronously. For CANCELED and EXPIRED, the webhook publishes the status directly. For the other success states, it first captures the payment via the ProcessPayment endpoint.

PagaLeve state	Yuno status
`NEW`	Created
`ACCEPTED`	Pending provider confirmation
`AUTHORIZED`	Successful
`COMPLETED`	Successful
`RELEASED`	Successful
`CAPTURED`	Successful
`CANCELED`	Cancelled by user
`EXPIRED`	Expired by provider
`PAYMENT_DECLINED`	Declined by provider

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

Requirements

Create and manage customers

One-time Pix payment

Step 1: Create a checkout session

Step 2: Initialize the SDK

Step 1: Create a payment

Step 2: Confirm payment

Pix Parcelado (installment) payment

Step 1: Create the payment

Step 1: Create payment

Step 2: Retrieve payment

Status transitions

Endpoints

​Requirements

​Create and manage customers

​One-time Pix payment

​Step 1: Create a checkout session

​Step 2: Initialize the SDK

​Step 1: Create a payment

​Step 2: Confirm payment

​Pix Parcelado (installment) payment

​Step 1: Create the payment

​Step 1: Create payment

​Step 2: Retrieve payment

​Status transitions

​Endpoints

Requirements

Create and manage customers

One-time Pix payment

Step 1: Create a checkout session

Step 2: Initialize the SDK

Step 1: Create a payment

Step 2: Confirm payment

Pix Parcelado (installment) payment

Step 1: Create the payment

Step 1: Create payment

Step 2: Retrieve payment

Status transitions

Endpoints