> ## 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

> A step-by-step guide for setting up your PagaLeve payments integration in the Payrails portal.

<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.
</Note>

## 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.
</Note>

## Step 2: Choose the provider

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

<img src="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" alt="Payrails provider selection set to PagaLeve" className="mx-auto block rounded-lg object-cover border border-gray-200" width="100%" data-path="images/docs/integrations/orchestration/pagaleve-image-01.png" />

## 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.
</Tip>

### 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.

<img src="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" alt="Payrails integration instance name field for PagaLeve" className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/integrations/orchestration/pagaleve-image-02.png" />

### 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.

<img src="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" alt="Payrails Public Key and Secret Key fields for PagaLeve" className="mx-auto block rounded-lg object-cover border border-gray-200" width="100%" data-path="images/docs/integrations/orchestration/pagaleve-image-03.png" />

### 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.

## 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](/docs/orchestration/payment-acceptance/test-payments)


## Related topics

- [Integrations](/docs/orchestration/integrations/index.md)
- [Paga Wallet](/docs/orchestration/payment-methods/paga-wallet.md)
- [Self-served migration of card data from PSPs](/docs/token-vault/token-migration/self-serve-migration.md)