> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# PagaLeve

> Set up a PagaLeve integration in the Payrails Portal to accept Pix Parcelado BNPL payments in Brazil through PagaLeve's hosted checkout.

<picture noZoom>
  ![PagaLeve logo](https://assets.payrails.io/img/logos/pagaleve/logo-full-bleed.svg)
</picture>

> [!NOTE]
>
> **Who should use this guide**
>
> This guide is intended for merchants who:
>
> * Use **Payrails** as a payment orchestrator
> * Use **PagaLeve** to accept **Pix Parcelado** (Buy Now, Pay Later) payments in Brazil
> * Accept payments through PagaLeve's **hosted checkout page**
>
> PagaLeve uses a hosted checkout (redirect) integration: your shopper goes to PagaLeve to pay the first installment with Pix and complete the BNPL agreement, so no payment credentials pass through your checkout.

## Create and configure a PagaLeve integration in Payrails

Follow these steps to set up PagaLeve:

1. Log in to the **Payrails** portal.
2. Go to **Settings → Integrations → Payments**.
3. Select **Add instance** to create a new PagaLeve integration configuration.
4. Select the **workspaces** where this integration should be available.

> [!NOTE]
>
> **About workspaces**
>
> Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

## Step 1: Choose the integration type

Select **Payment** and continue to the next step.

![A screenshot showing the integration type selection form.](https://mintcdn.com/payrails-42074109/To59SEkYYPq19nmx/images/docs/orchestration/integrations/shared/integration-type-selection.png?fit=max\&auto=format\&n=To59SEkYYPq19nmx\&q=85\&s=2a1afe79c3ac25f3a8437846a1d36ffb)

## Step 2: Choose the provider

Select **PagaLeve** and continue to the next step.

![Payrails provider selection set to PagaLeve](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/pagaleve-image-01.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=0fb277d3488d6a8f6c7417598af4d95e)

## Step 3: Configure your PagaLeve integration

> [!TIP]
>
> **What you'll need from PagaLeve**
>
> Before you begin, make sure you have access to your PagaLeve account and the following:
>
> * **Public Key**
> * **Secret Key** (used to authenticate requests to PagaLeve's API)
> * *Optional:* **Subsidiary ID** — only needed if a holding company transacts on behalf of a subsidiary.

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for each provider based on region, currency, or business needs. Choose a clear, consistent name, since it's used in routing.

**In Payrails**

* Enter an **Instance name** for your integration.

![Payrails integration instance name field for PagaLeve](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/pagaleve-image-02.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=caea5e7c5b9bc6be1a19b4e0093890a4)

### Public Key & Secret Key

**In PagaLeve**

* In your PagaLeve account, locate and copy your **Public Key & Secret Key**.

**In Payrails**

* Paste the value into the **Public Key & Secret Key** fields.

![Payrails Public Key and Secret Key fields for PagaLeve](https://mintcdn.com/payrails-42074109/yf-DMcCRiMaVxlBA/images/docs/integrations/orchestration/pagaleve-image-03.png?fit=max\&auto=format\&n=yf-DMcCRiMaVxlBA\&q=85\&s=5e887c08765ca18b6e0278a2e4558fa1)

### Subsidiary ID (optional)

**In Payrails**

* If a holding company is transacting on behalf of a subsidiary, enter the **Subsidiary ID**. Otherwise, leave this field blank.

### Payment methods

**In Payrails**

* Under **Payment methods**, enable **Pix Parcelado**.

Payrails sends the notification (webhook) URL to PagaLeve automatically with every checkout, so there's no separate webhook to configure in the PagaLeve portal.

## Request fields for PagaLeve

Send these fields in the [authorize request](https://docs.payrails.com/reference/authorizeaction.md), in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to PagaLeve when you include them. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to PagaLeve in cents. Use BRL or USD. |
| `meta.customer.name`, `lastName`, `email` | Required | Sent as the shopper's name and email. |
| `meta.customer.phone.number` | Required | Sent as the shopper phone. |
| `meta.customer.identityCardNumber` | Required | The shopper's CPF. |
| `merchantReference` | Required | Sent as the order reference. You can send `meta.order.reference` instead. |
| `meta.customer.birthDate`, `reference` | Optional | Sent as the shopper's date of birth and customer ID. |
| `meta.order.description` | Optional | Sent as the order description. |
| `meta.order.lines` | Optional | Sent as the order items. Each line needs `id`, `name`, `unitPrice` and `quantity`. |
| `meta.order.deliveryAddress`, `meta.order.billingAddress` | Optional | Sent as the shipping and billing address when `street`, `doorNumber`, `area`, `city`, `state` and `postalCode` are all present. |
| `meta.vendor.subMerchants` | Optional | `id`, `name` and `amount` of each sub-merchant. Sent as a marketplace order with split recipients. |

***

## Enable the integration

**In Payrails**

* Select **Save account** to save the configuration and enable the integration.
* The **Enabled** status confirms that the PagaLeve integration is active.

Your PagaLeve integration is now ready to process payments.

## Next steps

1. Run a test payment in **test mode** using PagaLeve's sandbox checkout simulator. Use a supported currency such as **BRL** or **USD**.
2. Verify that:
   * The payment appears in your **PagaLeve** account.
   * The payment status updates correctly in **Payrails**.
3. Once verified in test mode, repeat the setup in **live mode**.

Continue to: [Test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md)


## Related topics

- [Payment providers](https://docs.payrails.com/docs/integrations/payment-providers.md)
- [Paga Wallet](https://docs.payrails.com/docs/integrations/payment-methods/paga-wallet.md)
- [Paga Wallet via Boku](https://docs.payrails.com/docs/integrations/payment-methods/paga-wallet/boku.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.