---
updatedAt: 2026-09-30T20:32:13.000Z
agentTools:
  projectIndex: https://docs.dlocal.com/llms.txt
---

# Peru

Learn about the dLocal supported payment methods in Peru.

<HTMLBlock>{`
<style>
  
  .main {
    margin-left: auto;
    margin-right: auto;
    margin-bottom: 5px;
    display: grid;
    grid-template-columns: repeat(3, 1fr); /* Tres columnas */
    width: 740px; /* Ancho máximo de la caja */
}

.overview-card1 {
    position: relative; /* Asegúrate de que el contenedor sea relativo para posicionar el pseudoelemento */
    width: 100%;
    max-width: 233px;
    box-sizing: border-box;
    margin: 0;
}

.overview-card1::after {
    content: '';
    position: absolute;
    right: 0; /* Pega la línea al borde derecho */
    top: 30%; /* Ajusta la posición superior de la línea */
    height: 60%; /* Establece el alto de la línea al 60% */
    width: 1px; /* Grosor de la línea */
    background-color: #D2D8EC; /* Color de la línea */
}

  .overview-card2 {
    position: relative; /* Asegúrate de que el contenedor sea relativo para posicionar el pseudoelemento */
    width: 100%;
    max-width: 233px;
    box-sizing: border-box;
    margin: 0;
}
  
  .overview-card2::after {
    content: '';
    position: absolute;
    right: 0; /* Pega la línea al borde derecho */
    top: 30%; /* Ajusta la posición superior de la línea */
    height: 70%; /* Establece el alto de la línea al 60% */
    width: 1px; /* Grosor de la línea */
    background-color: #D2D8EC; /* Color de la línea */
}
  
.overview-card3 {
    position: relative; /* Asegúrate de que el contenedor sea relativo para posicionar el pseudoelemento */
    width: 100%;
    max-width: 233px;
    box-sizing: border-box;
    margin: 0;
}

.overview-card-upper-side1 {
    height: 105px;
    padding: 20px;
    background-color: transparent;
    text-align: left;
}

.overview-card-bottom-side {
    position: relative;
    width: 100%;
    height: 100%;
    padding: 30px;
    padding-right: 20px;
    background-color: transparent;
    border-radius: 16px;
}

.overview-card-title1 {
    font-family: 'Plus Jakarta Sans', sans-serif;
    font-size: 24px;
    font-weight: 700;
    line-height: 26.4px;
}

.overview-card-content1 {
    font-size: 14px;
    font-weight: 300;
    margin-top: 20px;
    line-height: 20px;
    margin-bottom: 40px!important;
}

.overview-icon1 {
    margin-bottom: -5px;
    margin-top: 20px;
}
  
.doc-link {
        position: relative;
        font-weight: 500;
        color: #21A35B !important;
        text-decoration: none;
        display: block;
    }
  

div:not(.markdown-body) .doc-link:hover {
            text-decoration: none;
            color: #1043FA !important;
            transform: translateX(0.2em);
        }

.overview-card-title1:hover {
    color: #2D59F5 !important;
    cursor:pointer;
    transform: none!important;
}

    div:not(.markdown-body) .doc-link_arrow {
        display: inline-block;
        height: 1em;
        width: auto;
        vertical-align: middle;
        margin-left: 0.2em;
        margin-top: -0.1em;
    }
  
     div:not(.markdown-body) .doc-link:hover .doc-link_arrow-color {
            fill: #1043FA !important;
        }
  
      [data-color-mode="dark"] .overview-icon1 img {
  filter: brightness(0) invert(1);
  transition: filter 0.3s ease;
}
  
  
/* Media Queries para dispositivos móviles */
@media (max-width: 768px) {
  .main {
    grid-template-columns: repeat(2, 1fr); /* Dos columnas en pantallas medianas */
  }
}

@media (max-width: 480px) {
  .main {
    grid-template-columns: 1fr; /* Una columna en pantallas pequeñas */
}
</style>
  
    <div class="main">

     
      <div class="overview-card1" onclick="parent.location='/docs/peru#market-specifications'">
     <div class="overview-card-bottom-side">
     <div class="overview-icon1"><img width="48" src="https://files.readme.io/922681fecfb238c94f7213fa9e0aa1675f1e190ec55beff2b6994169c77fdefc-adjust-circle.svg"  alt="" loading="lazy"><div class="img_overlay img_color_rgba(0,0,0,.2)"></div></div>
           <h3 class="overview-card-title1">Market specifications</h3>
          <p class="overview-card-content1">

            Take a look of all the payment methods available.   
        </p>
          <a href="#country-reference" class="doc-link">Country reference</a>
          <a href="#cards-supported" class="doc-link">Cards supported</a>
          <a href="#alternative-payment-method-supported" class="doc-link">APM supported</a>
        </div>
      </div>
      
      
      <div
        class="overview-card2" onclick="parent.location='/docs/peru#cards'">
        <div class="overview-card-bottom-side">
                 <div class="overview-icon1"><img width="48" src="https://files.readme.io/8d450ada4af3880f85f70c5daedebb0bec1b2b6d64479be929af48fdc8d66f40-credit-card.svg"  alt="" loading="lazy"><div class="img_overlay img_color_rgba(0,0,0,.2)"></div></div>
           <h3 class="overview-card-title1">Cards</h3><br>
          <p class="overview-card-content1">

           Find all the information about the card supported capabilities.   
          </p>
          <a href="#capabilities" class="doc-link">Capabilities</a>
          <a href="#how-to-process-card-payments" class="doc-link">Process Card Payments</a>
        </div>
      </div>  
      
      
      <div class="overview-card3" onclick="parent.location='/docs/peru#alternative-payment-method'">
    <div class="overview-card-bottom-side">
                <div class="overview-icon1"><img width="48" src="https://files.readme.io/5a59519487455e7af361db8b67a2dee8d71627d4d6e1ed0a0bd805f5da861fcc-money-stack.svg"  alt="" loading="lazy"><div class="img_overlay img_color_rgba(0,0,0,.2)"></div></div>
           <h3 class="overview-card-title1">Alternative Payments</h3>
          <p class="overview-card-content1">

             Learn how to integrate cash, bank transfer or wallet payment.  
        </p>
          <a href="#pago-efectivo" class="doc-link">Pago Efectivo</a>
          <a href="#bcp" class="doc-link">BCP</a>
          <a href="#payvalida" class="doc-link">Payvalida</a>
      		<a href="#yape" class="doc-link">Yape</a>
          <a href="#yape-recurring" class="doc-link">Yape Recurring</a>
          <a href="#ligopay" class="doc-link">LigoPay</a>
        </div>
      </div> 
      
</div>
`}</HTMLBlock>

<br />

***

# Market specifications

Do you want to know more information about the Peru market? Go to the [Peru economy and eCommerce market](https://dlocal.com/payment-processors-in-latin-america/peru-payment-methods-processors-ecommerce-market-dlocal/) article.

## Country reference

| `country` code | `currency` code | `amount` decimals | `document` name |            `document` format            | `document` required? |
| :------------: | :-------------: | :---------------: | :-------------: | :-------------------------------------: | :------------------: |
|      `PE`      |      `PEN`      |         2         |    DNI or RUC   | 8 digits for DNI and 11 digits for RUC. |          Yes         |

<br />

<Callout icon="👍" theme="okay">
  ### Multi-currency support available

  Supports charging in either USD or local currency. To charge in USD, use the `currency_to_charge` parameter with the value `USD`; otherwise, the transaction will be processed in local currency by default. Check availability by payment method below.
</Callout>

<br />

## Cards supported

| `payment_method_id` | Brand ID | Name               | `payment_method_type` | Details       | Allowed Flows       | Logo                                                                                                            |
| :------------------ | :------- | :----------------- | :-------------------- | :------------ | :------------------ | :-------------------------------------------------------------------------------------------------------------- |
| `CARD`              | `VI`     | Visa               | `CARD`                | Credit Card ​ | `DIRECT` `REDIRECT` | <img src="https://static.dlocal.com/images/providers/checkout/VI.svg" width="40px" alt="Visa logo">             |
| `CARD`              | `VD`     | Visa Debit ​       | `CARD`                | Debit Card ​  | `DIRECT` `REDIRECT` | <img src="https://static.dlocal.com/images/providers/checkout/VD.svg" width="40px" alt="Visa Debit logo">       |
| `CARD`              | `MC`     | Mastercard         | `CARD`                | Credit Card ​ | `DIRECT` `REDIRECT` | <img src="https://static.dlocal.com/images/providers/checkout/MC.svg" width="40px" alt="Mastercard logo">       |
| `CARD`              | `MD`     | Mastercard Debit ​ | `CARD`                | Debit Card ​  | `DIRECT` `REDIRECT` | <img src="https://static.dlocal.com/images/providers/checkout/MD.svg" width="40px" alt="Mastercard Debit logo"> |
| `CARD`              | `AE`     | American Express   | `CARD`                | Credit Card ​ | `DIRECT` `REDIRECT` | <img src="https://static.dlocal.com/images/providers/checkout/AE.svg" width="40px" alt="American Express logo"> |
| `CARD`              | `DC`     | Diners Club        | `CARD`                | Credit Card ​ | `DIRECT` `REDIRECT` | <img src="https://static.dlocal.com/images/providers/checkout/DC.svg" width="40px" alt="Diners Club logo">      |

<Callout icon="ℹ️" theme="info">
  To offer all the card options that may be available in your integration, send the `payment_method_id` as `CARD`.
</Callout>

## Alternative Payment Method supported

| `payment_method_id` | Name                   | `payment_method_type` | Details            | Allowed Flows       | Logo                                                                                                      |
| :------------------ | :--------------------- | :-------------------- | :----------------- | :------------------ | :-------------------------------------------------------------------------------------------------------- |
| `EF`                | Pago Efectivo          | `TICKET`              | Cash Payments      | `DIRECT` `REDIRECT` | <img src="https://pay.dlocal.com/views/2.0/images/payments/EF.png" width="40px" alt="Pago Efectivo logo"> |
| `BC`                | BCP                    | `BANK_TRANSFER`       | Bank Transfer      | `DIRECT` `REDIRECT` | <img src="https://pay.dlocal.com/views/2.0/images/payments/BC.png" width="40px" alt="BCP logo">           |
| `IO`                | Payvalida              | `BANK_TRANSFER`       | Bank Transfer      | `REDIRECT`          | <img src="https://static.dlocal.com/images/providers/IO.png" width="40px" alt="Payvalida logo">           |
| `YP`                | Yape one-shot          | `WALLET`              | eWallet            | `REDIRECT`          | <img src="https://static.dlocal.com/images/providers/YP.png" width="40px" alt="Yape logo">                |
| `YE`                | Yape  Wallet recurring | `WALLET`              | eWallet            | `REDIRECT`          | <img src="https://static.dlocal.com/images/providers/YP.png" width="40px" alt="Yape logo">                |
| `LY`                | LigoPay                | `TICKET`              | QR + Bank Transfer | `DIRECT` `REDIRECT` | <img src="https://static.dlocal.com/images/providers/ligopay.svg" width="40px" alt="LigoPay logo">        |

<br />

***

# Cards

## Capabilities

|                               | Visa Credit                                     | Visa Debit                                      | Mastercard Credit                               | Mastercard Debit                                | American Express                                | Diners Club                                     |
| :---------------------------- | :---------------------------------------------- | :---------------------------------------------- | :---------------------------------------------- | :---------------------------------------------- | :---------------------------------------------- | :---------------------------------------------- |
| **Minimum amount**            | 5 PEN                                           | 5 PEN                                           | 5 PEN                                           | 5 PEN                                           | 5 PEN                                           | 1 PEN                                           |
| **Refunds**                   | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             |
| **Recurring**                 | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             |
| **Chargeback option**         | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             |
| **Chargeback Dispute option** | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             | Yes                                             |
| **Descriptor**                | Can be personalized, depending on the provider. | Can be personalized, depending on the provider. | Can be personalized, depending on the provider. | Can be personalized, depending on the provider. | Can be personalized, depending on the provider. | Can be personalized, depending on the provider. |

## How to process Card Payments?

Learn how to process payments with credit and debit cards with dLocal in our [Card Payments](https://docs.dlocal.com/docs/card-payments) section.

<br />

***

# Alternative Payment Method

## Pago Efectivo

Pago Efectivo was created with the aim to be the payment method to buy online and pay without a card. They created the CIP payment code to have the freedom to choose where and how to pay using the code.

Pago Efectivo is now widely used in Peru to pay their utility bills and purchases online, giving the user the ability to pay in cash, through bank transfers or with eWallets.

### Capabilities

|                                    | Pago Efectivo        |
| :--------------------------------- | :------------------- |
| **Min. amount**                    | 5 PEN                |
| **Max. expiration time supported** | 5 days               |
| **Notification delay**             | Immediate            |
| **Refunds**                        | Yes                  |
| **Flow**                           | `DIRECT`, `REDIRECT` |

### Request parameters

| Property              | Type   | Description                                                                                                | Mandatory? |
| :-------------------- | :----- | :--------------------------------------------------------------------------------------------------------- | :--------- |
| `amount`              | Number | Amount to be charged.                                                                                      | Yes        |
| `currency`            | String | `PEN`. Transaction currency in [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217).                          | Yes        |
| `country`             | String | `PE`. Transaction country in [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).     | Yes        |
| `payment_method_id`   | String | `EF`. ID of the selected payment method.                                                                   | Yes        |
| `payment_method_flow` | String | `DIRECT` or `REDIRECT`                                                                                     | Yes        |
| `payer.name`          | String | Name of the payer.                                                                                         | Yes        |
| `payer.email`         | String | Email of the payer.                                                                                        | Yes        |
| `payer.document`      | String | Document of the payer.                                                                                     | Yes        |
| `order_id`            | String | ID of the capture given by the merchant in their system. Think of it as an external ID of the capture.     | No         |
| `notification_url`    | String | dLocal sends notifications for every payment status change to the merchant's specified `notification_url`. | No         |

### Examples

```json Request
{
  "amount": 1000,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "EF",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "janedoe@mymail.com",
    "document": "434518267",
    "address": {
      "country": "PE",
      "state": "Lima",
      "city": "Lima",
      "zip_code": "88058",
      "street": "Av. Principal",
      "number": "5940"
    }
  },
  "order_id": "34545sk3483kqw0",
  "description": "Tshirt",
  "notification_url": "http://merchantsite.com/notification/new",
  "callback_url": "http://merchantsite.com/success_page"
}
```
```json Response
{
    "id": "D-4-8f95110c-4fac-43q1-b0b1-8078165a385f",
    "amount": 1000,
    "currency": "PEN",
    "payment_method_id": "EF",
    "payment_method_type": "TICKET",
    "payment_method_flow": "DIRECT",
    "country": "PE",
    "bank_transfer": {},
    "ticket": {
        "type": "CUSTOM",
        "number": "420483192",
        "expiration_date": "2026-10-02T08:47:09.935+0000",
        "id": "EF-420483192",
        "barcode": "https://codigoqr.pagoefectivolatam.com/395A6AB4-9A2D-4663-849A-B5B75E80D3EE.png",
        "company_name": "DEMERGE PERU SAC",
        "image_url": "https://pay.dlocal.com/gmf-apm/payments/N-dad97fb3-0b9d-4c64-b5e0-01c8679147d5",
        "amount": 1000,
        "currency": "PEN"
    },
    "created_date": "2023-06-14T15:38:09.000+0000",
    "status": "PENDING",
    "status_detail": "The payment is pending.",
    "status_code": "100",
    "order_id": "34545sk3483kqw0",
    "notification_url": "http://merchantsite.com/notification/new"
}
```

### Example ticket

![Pago Efectivo UI built with the information in the example above.](https://files.readme.io/2bee98ae1be90fd756ee0e8acf5e92e2d6d9f1c7d7f72f82d921571913f42a9e-APM_-_Pago_Efectivo.png)

### User Interface Tips

<Callout icon="✅" theme="okay">
  ### Provider's voucher

  We strongly recommend using the ticket on `ticket.image_url`. Peruvian users are very familiar with this ticket (example above) made by the provider itself, for every kind of purchase paid through Pago Efectivo. It includes:

  - Many payment options instructions.
  - Capability of sending the payment code through SMS.
  - Provider's store locator.
</Callout>

If you still need to design your own ticket and you are using this payment method through a DIRECT integration, follow the tips below to make it easier for your users to complete payments and boost your conversion rates.

| Element                  | Tip                                                                                                                                                                                                                                                      |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ticket Number**        | Name it as **"Código de Pago (CIP)"**.                                                                                                                                                                                                                   |
| **Ticket Barcode**       | The `ticket.barcode`carries the QR Code image.                                                                                                                                                                                                           |
| **Provider's Name**      | Show `ticket.provider_name`, as it is useful at the moment of paying through home banking.                                                                                                                                                               |
| **Currency and Amount**  | Should be relevant elements in the ticket. Users need to have that information very clearly.                                                                                                                                                             |
| **Currency Symbol**      | S/                                                                                                                                                                                                                                                       |
| **Expiration date**      | Display this element clearly and visible enough. In Peru, the date format is  **DD/MM/YYYY**.                                                                                                                                                            |
| **Payment instructions** | Although most users are familiarized with Pago Efectivo, it is a good practice to help those who are not. In the image above there is an example of instructions, but if needed, our team will be happy to help you with more personalized instructions. |
| **Save button**          | It helps users to have their tickets always on their phones, making it needless to take notes or keep the browser open.                                                                                                                                  |
| **Print button**         | It is useful for some users who need to have their tickets printed.                                                                                                                                                                                      |

## BCP

BCP is the main bank in Peru with almost half of the market share. With this integration we allow users to make transfers with instant release.

### Capabilities

|                                    | BCP                  |
| :--------------------------------- | :------------------- |
| **Min. amount**                    | 5 PEN                |
| **Max. expiration time supported** | 5 days               |
| **Notification delay**             | Immediate            |
| **Refunds**                        | Yes                  |
| **Flow**                           | `DIRECT`, `REDIRECT` |
| **Charge in USD**                  | ✅                    |

### Request parameters

| Property              | Type   | Description                                                                                                | Mandatory? |
| :-------------------- | :----- | :--------------------------------------------------------------------------------------------------------- | :--------- |
| `amount`              | Number | Amount to be charged.                                                                                      | Yes        |
| `currency`            | String | `PEN`. Transaction currency in [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217).                          | Yes        |
| `country`             | String | `PE`. Transaction country in [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).     | Yes        |
| `payment_method_id`   | String | `BC`. ID of the selected payment method.                                                                   | Yes        |
| `payment_method_flow` | String | `DIRECT` or `REDIRECT`                                                                                     | Yes        |
| `payer.name`          | String | Name of the payer.                                                                                         | Yes        |
| `payer.email`         | String | Email of the payer.                                                                                        | Yes        |
| `payer.document`      | String | Document of the payer.                                                                                     | Yes        |
| `order_id`            | String | ID of the capture given by the merchant in their system. Think of it as an external ID of the capture.     | No         |
| `notification_url`    | String | dLocal sends notifications for every payment status change to the merchant's specified `notification_url`. | No         |

### Examples

```json Request
{
  "amount": 1000,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "BC",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "janedoe@mymail.com",
    "document": "434518267",
    "address": {
      "country": "PE",
      "state": "Lima",
      "city": "Lima",
      "zip_code": "88058",
      "street": "Av. Principal",
      "number": "5940"
    }
  },
  "order_id": "34545sk3483kqw0",
  "description": "Tshirt",
  "notification_url": "http://merchantsite.com/notification/new",
  "callback_url": "http://merchantsite.com/success_page"
}
```
```json Response
{
    "id": "D-4-192c9fe0-df89-4652-9074-26c4ce246c9f",
    "amount": 1000,
    "currency": "PEN",
    "payment_method_id": "BC",
    "payment_method_type": "BANK_TRANSFER",
    "payment_method_flow": "DIRECT",
    "country": "PE",
    "bank_transfer": {},
    "ticket": {
        "type": "CUSTOM",
        "number": "234592",
        "expiration_date": "2023-06-17T04:59:00.000+0000",
        "provider_logo": "https://static.dlocal.com/images/providers/bcp.png",
        "image_url": "https://pay.dlocal.com/gmf-apm/payments/M-3d6a968f-4432-4a64-8c44-c1947de21ec6",
        "amount": 1000,
        "currency": "PEN"
    },
    "created_date": "2023-06-12T15:39:23.000+0000",
    "status": "PENDING",
    "status_detail": "The payment is pending.",
    "status_code": "100",
    "order_id": "34545sk3483kqw0",
    "notification_url": "http://merchantsite.com/notification/new"
}
```
```json Notification
{
  "id": "D-4-192c9fe0-df89-4652-9074-26c4ce246c9f",
  "amount": 1000,
  "status": "PAID",
  "status_detail": "The payment was paid.",
  "status_code": "200",
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "BC",
  "payment_method_type": "BANK_TRANSFER",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Jane Doe",
    "user_reference": "",
    "email": "janedoe@mymail.com",
    "document": "434518267"
  },
  "order_id": "34545sk3483kqw0",
  "description": "Tshirt",
  "notification_url": "http://merchantsite.com/notification/new",
  "callback_url": "http://merchantsite.com/success_page",
  "created_date": "2023-06-12T15:39:23.000+0000"
}

```

### Example ticket

![BCP UI built with the information in the example above.](https://files.readme.io/e8b41ae63c1737ba50e43e8656c66b1076ffee1e67c0d0596862f5bc47349630-APM_-_BCP.png)

<br />

## Payvalida

Payvalida is a platform specializing in collections and online payments. It has a wide collection agent network throughout the country.

### Capabilities

|                                    | Payvalida  |
| :--------------------------------- | :--------- |
| **Min. amount**                    | 5 PEN      |
| **Max. expiration time supported** | 5 days     |
| **Notification delay**             | Immediate  |
| **Refunds**                        | Yes        |
| **Flow**                           | `REDIRECT` |

### Request parameters

| Property              | Type   | Description                                                                                                | Mandatory? |
| :-------------------- | :----- | :--------------------------------------------------------------------------------------------------------- | :--------- |
| `amount`              | Number | Amount to be charged.                                                                                      | Yes        |
| `currency`            | String | `PEN`. Transaction currency in [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217).                          | Yes        |
| `country`             | String | `PE`. Transaction country in [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).     | Yes        |
| `payment_method_id`   | String | `IO`. ID of the selected payment method.                                                                   | Yes        |
| `payment_method_flow` | String | `REDIRECT`                                                                                                 | Yes        |
| `payer.name`          | String | Name of the payer.                                                                                         | Yes        |
| `payer.email`         | String | Email of the payer.                                                                                        | Yes        |
| `payer.document`      | String | Document of the payer.                                                                                     | Yes        |
| `order_id`            | String | ID of the capture given by the merchant in their system. Think of it as an external ID of the capture.     | No         |
| `notification_url`    | String | dLocal sends notifications for every payment status change to the merchant's specified `notification_url`. | No         |

### Examples

```json Request
{
  "amount": 1000,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "IO",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "janedoe@mymail.com",
    "document": "434518267",
    "address": {
      "country": "PE",
      "state": "Lima",
      "city": "Lima",
      "zip_code": "88058",
      "street": "Av. Principal",
      "number": "5940"
    }
  },
  "order_id": "34545sk3483kqw0",
  "description": "Tshirt",
  "notification_url": "http://merchantsite.com/notification/new",
  "callback_url": "http://merchantsite.com/success_page"
}
```
```json Response
{
    "id": "R-4-50733a71-49fe-494a-556t-60f702e1369b",
    "amount": 1000,
    "currency": "PEN",
    "payment_method_id": "IO",
    "payment_method_type": "BANK_TRANSFER",
    "payment_method_flow": "REDIRECT",
    "country": "PE",
    "created_date": "2023-07-10T19:33:11.000+0000",
    "status": "PENDING",
    "status_detail": "The payment is pending.",
    "status_code": "100",
    "order_id": "34545sk3483kqw0",
    "description": "Tshirt",
    "notification_url": "http://merchantsite.com/notification/new",
    "redirect_url": "https://pay.dlocal.com/gmf-apm/payments-redirect/M-8a290793-0afb-4946-er32-74f65baab83d"
}
```
```json Notification
{
  "id": "R-4-50733a71-49fe-494a-556t-60f702e1369b",
  "amount": 1000,
  "status": "PAID",
  "status_detail": "The payment was paid.",
  "status_code": "200",
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "IO",
  "payment_method_type": "BANK_TRANSFER",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Jane Doe",
    "user_reference": "",
    "email": "janedoe@mymail.com",
    "document": "434518267"
  },
  "order_id": "34545sk3483kqw0",
  "description": "Tshirt",
  "notification_url": "http://merchantsite.com/notification/new",
  "created_date": "2023-07-10T19:33:11.000+0000"
}

```

### Example ticket

<br />

## Yape

Yape is a leading wallet in Peru, operated by Banco de Crédito del Perú (BCP). With this payment method, users can pay with their Yape's balance and dLocal offers two integration modes:

**YP (Yape one-shot):** A single redirect payment. No token is issued. Best for one-time purchases.
**YE (Yape Recurring):** A tokenized flow. The user enrolls once via redirect and all subsequent charges are processed directly with a token. Best for subscriptions.

## Yape one-shot

#### Capabilities

|                                    | Yape one-shot                                 |
| :--------------------------------- | :-------------------------------------------- |
| **Min. amount**                    | 1 PEN                                         |
| **Max. amount**                    | 2,000 PEN per transaction / 2,000 PEN per day |
| **Max. expiration time supported** | 20 minutes                                    |
| **Notification delay**             | Immediate                                     |
| **Refunds**                        | Yes - full and partial, up to 365 days        |
| **Flow**                           | `REDIRECT`                                    |
| **Payment method ID**              | `YP`                                          |

#### How it works

1. You create a payment with `payment_method_id: "YP"` and `payment_method_flow`: `"REDIRECT"`.
2. dLocal returns a `redirect_url`.
3. You redirect the user to that URL.
   1. `device.type`: `"MOBILE_APP"`: The URL resolves to a deep link that opens the Yape app directly. The user approves with their PIN or biometric.
   2. `device.type`: `"WEB"`: The user lands on a dLocal-hosted page. dLocal sends a push notification to the user's Yape app using `payer.phone`. The user approves in the app.
4. After approval, dLocal sends a `PAID` webhook to your `notification_url`.

<Callout icon="📘" theme="info">
  ### Mandatory fields for User Experience

  `device.type` is **mandatory** and controls the entire UX. Sending the wrong value for the user's context will degrade conversion.

  `payer.phone` is mandatory when `device.type` is `"WEB"`. It is used to send the push notification. Without it, the payment cannot be completed.
</Callout>

<br />

#### UX Flow Example

![Yape one-shot UX flow](https://files.readme.io/a1d809f04c200aa60350ccba7d8c78589cb87ac18e413b727de50eec4aad4c60-Yape.png)

<br />

#### Request parameters

| Property              | Type   | Description                                                                                                                                              | Mandatory?                     |
| :-------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |
| `amount`              | Number | Amount to be charged.                                                                                                                                    | Yes                            |
| `currency`            | String | `PEN`. Transaction currency in ISO 4217.                                                                                                                 | Yes                            |
| `country`             | String | `PE`. Transaction country in ISO 3166.                                                                                                                   | Yes                            |
| `payment_method_id`   | String | `YP`. ID of the selected payment method.                                                                                                                 | Yes                            |
| `payment_method_flow` | String | `REDIRECT`                                                                                                                                               | Yes                            |
| `payer.name`          | String | Name of the payer.                                                                                                                                       | No                             |
| `payer.email`         | String | Email of the payer.                                                                                                                                      | No                             |
| `payer.document`      | String | Document of the payer.                                                                                                                                   | No                             |
| `payer.phone`         | String | Phone number of the payer. This field is required for the desktop payment flow to send push notifications to the user's Yape app.                        | Yes, when `device.type: "WEB"` |
| `device.type`         | String | Device from which the user creates the transaction. Controls the UX. Possible values: `WEB` and `MOBILE_APP`.                                            | Yes                            |
| `order_id`            | String | ID of the capture given by the merchant in their system.                                                                                                 | No                             |
| `notification_url`    | String | dLocal sends notifications for every status change to this URL.                                                                                          | Yes                            |
| `callback_url`        | String | Optional browser return URL after the hosted redirect flow. It does not create an automatic callback or deep link back from the Yape app after approval. | No                             |

#### Examples

```json Request
{
  "amount": 100,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "YP",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "email": "cgvs@example.com",
    "document": "434518267"
  },
  "device": {
    "type": "MOBILE_APP"
  },
  "order_id": "f3e0621c-be65-4ed5-8f24-137fdcdbefde",
  "notification_url": "http://www.merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/callback"
}
```
```json Response
{
  "id": "F-4-03c82e23-e068-41ec-865c-263de845c1ff",
  "amount": 100,
  "currency": "PEN",
  "payment_method_id": "YP",
  "payment_method_type": "TICKET",
  "payment_method_flow": "REDIRECT",
  "country": "PE",
  "created_date": "2025-04-03T20:16:52.000+0000",
  "status": "PENDING",
  "status_detail": "The payment is pending.",
  "status_code": "100",
  "order_id": "f3e0621c-be65-4ed5-8f24-137fdcdbefde",
  "notification_url": "http://merchantsite.com/notification",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments-redirect/M-fd77f5b7-ca28-7u54-9ed8-ef89d374a80c"
}

```
```json Notification
{
  "id": "F-4-03c82e23-e068-41ec-865c-263de845c1ff",
  "amount": 100,
  "status": "PAID",
  "status_detail": "The payment was paid",
  "status_code": "200",
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "YP",
  "payment_method_type": "TICKET",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "email": "cgvs@example.com",
    "document": "434518267"
  },
  "order_id": "f3e0621c-be65-4ed5-8f24-137fdcdbefde",
  "notification_url": "http://www.merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/return",
  "created_date": "2025-04-03T20:16:52.000+0000"
}
```

**Redirection using&#x20;**`redirect_url`

#### **Mobile App: Deeplink behavior**

The recommendation is to always redirect using a native/OS redirection which will always work, but if you are using a webView or open in a external browser you may face the following scenarios:

*Android - WebView*

If your app uses a WebView, it will not open the Yape app automatically. WebViews do not delegate deep links to the OS by default. Implement one of the following:

**Option 1 (recommended):** Override shouldOverrideUrlLoading to detect yape.com.pe links and open them via an Intent:

```java
@Override
public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
    Uri url = request.getUrl();
    if (url.getHost().contains("yape.com.pe")) {
        Intent intent = new Intent(Intent.ACTION_VIEW, url);
        startActivity(intent);
        return true;
    }
    return false;
}

```

**Option 2**: Open the `redirect_url` in the device's default browser instead of a WebView.

*iOS - non-Safari browsers*

On iOS, Yape Universal Links only resolve correctly when opened from Safari or via a user-initiated tap (not through a redirect chain from another domain). If a user has a non-Safari browser set as default, the deep link will open the Yape website instead of the app.

Recommended mitigations:

| Approach                                      | **UX**             | **Reliability** | **Notes**                                                                                                                             |
| :-------------------------------------------- | ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Enable `ENABLE_MANUAL_REDIRECT` on your `MID` | Good (1 extra tap) | High            | Contact your dLocal TAM to enable. Shows an "Open Yape" button. A user-initiated tap resolves the Universal Link across all browsers. |
| Send `device.type: "WEB"` for iOS users       | Moderate           | High            | Requires `payer.phone`. User receives a push notification instead of a deep link.                                                     |
| Use SFSafariViewController                    | Best               | Medium          | Only works if your app opens the URL via the Safari rendering engine.                                                                 |

<Callout icon="⚠️" theme="warn">
  ### Yape does not support automatic app callbacks

  `callback_url` is only a browser return URL for the hosted redirect flow. There is no automatic callback deep link back to your app after the user approves in Yape, this is a BCP (Yape owner) policy restriction. The user must manually return to your app after approval.
</Callout>

## Yape Recurring

dLocal supports recurring payments with Yape. The user completes a one-time enrollment redirect, and all future charges are made directly using an enrollment ID. No redirect or re-authentication required.

<Callout icon="⚠️" theme="warn">
  ### Legacy integration notice

  The previous tokenized Yape flow using `wallet.save: true` and `wallet.token` on `POST /payments` is still supported for existing merchants but is considered **legacy**. New integrations must use the Enrollment API flows described below. Maintaining an existing legacy integration? See [Tokenized wallets: Legacy](https://docs.dlocal.com/docs/wallet-payments#tokenized-wallets-legacy).
</Callout>

#### Capabilities

|                                    | Yape Recurring                                                                                 |
| ---------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Min. amount**                    | 1 PEN                                                                                          |
| **Max. amount**                    | 2,000 PEN per transaction / 2,000 PEN per day                                                  |
| **Max. expiration time supported** | 15 minutes (for enrollment only, tokenized/recurrent charge is a user-not-present transaction) |
| **Token expiry**                   | None; valid until cancelled or revoked                                                         |
| **Notification delay**             | Immediate                                                                                      |
| **Refunds**                        | Yes, full and partial, up to 365 days                                                          |
| **Enrollment flow**                | `REDIRECT`                                                                                     |
| **Recurring charge flow**          | `DIRECT`                                                                                       |
| `payment_method_id`                | `YE`                                                                                           |

#### How it works

The Enrollment API for Yape Recurring supports two integration patterns:

| Pattern                                                                                  | When to use                                                                                                                                          |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enrollment only** (`POST /enrollments`)                                                | Establish the user's authorization without an initial charge. Best for subscription products where the first billing cycle is separate from sign-up. |
| **Payment + Enrollment in the same request** (`POST /payments` with `enrollment` object) | Create the first payment and establish the authorization simultaneously. Best when the first charge and enrollment happen at the same step.          |

<Callout icon="📘" theme="info">
  ### Enrollment type for Yape

  Always send `"type": "ON_DEMAND"` for Yape Recurring. Yape does not expose a structured subscription protocol, so `ON_DEMAND` is the only valid value.
</Callout>

Once the enrollment is `ACTIVE`, all subsequent charges are made via `POST /payments` using a nested `enrollment.id` inside an `enrollment` object, with `payment_method_flow: "DIRECT"`.

<Callout icon="⚠️" theme="warn">
  ### Cancellation must be implemented

  Because Yape does not expose any user-facing cancellation control, **implementing the&#x20;**[**Cancel an enrollment**](https://docs.dlocal.com/reference/cancel-an-enrollment)**&#x20;endpoint is mandatory** for any Yape Recurring integration, it is the only way a user's consent can be revoked.
</Callout>

#### UX Flow

##### First time user

![Yape recurring first-time user UX flow](https://files.readme.io/edc48ee7012914b047d225f54f18d1877c0433861b2678b4d3b7d25a361860c1-Yape_-_wallet_-_first_time_use.png)

***

### Pattern 1: Enrollment only

Use `POST /enrollments` to establish the user's authorization without an initial charge. See the full [Create enrollment](https://docs.dlocal.com/reference/create-enrollment) API reference for all available fields.

<Callout icon="📘" theme="info">
  ### external_id

  `external_id` is your internal identifier for this enrollment. It appears in all enrollment webhooks, letting you correlate dLocal enrollment events back to your own records.
</Callout>

#### Step 1: Create the enrollment

```json Enrollment request
curl -X POST \
   -H 'X-Date: {X-Date}' \
   -H 'X-Login: {X-Login}' \
   -H 'X-Trans-Key: {X-Trans-Key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: {Signature}' \
   -d '{body}'
   https://api.dlocal.com/enrollments

{
  "currency": "PEN",
  "country": "PE",
  "type": "ON_DEMAND",
  "payment_method_id": "YE",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "document": "43451826",
    "email": "vanessa@example.com",
    "phone": "912345678"
  },
  "device": {
    "type": "MOBILE_APP"
  },
  "external_id": "enroll-pe-vanessa-001",
  "description": "Yape recurring enrollment",
  "notification_url": "http://merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/callback"
}
```
```json Synchronous response
{
  "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "external_id": "enroll-pe-vanessa-001",
  "currency": "PEN",
  "country": "PE",
  "type": "ON_DEMAND",
  "payment_method_id": "YE",
  "payment_method_flow": "REDIRECT",
  "created_date": "2025-12-26T20:37:20.000+0000",
  "status": "PENDING",
  "status_detail": "The enrollment is pending.",
  "status_code": "100",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments/E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "notification_url": "http://merchantsite.com/notifications"
}
```
```json Asynchronous notification
{
  "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "external_id": "enroll-pe-vanessa-001",
  "currency": "PEN",
  "country": "PE",
  "type": "ON_DEMAND",
  "payment_method_id": "YE",
  "payment_method_flow": "REDIRECT",
  "created_date": "2025-12-26T20:37:20.000+0000",
  "status": "ACTIVE",
  "status_detail": "The enrollment is active.",
  "status_code": "200",
  "notification_url": "http://merchantsite.com/notifications"
}
```

<Callout icon="📘" theme="info">
  ### Enrollment ID

  Persist the `id` value (for example, `E-4-32e1218f-...`) when the enrollment webhook reaches `ACTIVE` status. Pass it as `enrollment.id` inside an `enrollment` object on all future recurring charge requests.

  To check the current enrollment status at any time (for example, if your server was temporarily unavailable), use the [Get enrollment](https://docs.dlocal.com/reference/get-enrollment) endpoint.

  To cancel an enrollment, use the [Cancel an enrollment](https://docs.dlocal.com/reference/cancel-an-enrollment) endpoint.
</Callout>

**Enrollment status codes:**

For the full list of enrollment `status_code` values, see the [Get enrollment](https://docs.dlocal.com/reference/get-enrollment) and [Create enrollment](https://docs.dlocal.com/reference/create-enrollment) API references.

| `status`    | `status_code` | Description                                                                                |
| :---------- | :------------ | :----------------------------------------------------------------------------------------- |
| `PENDING`   | `100`         | The enrollment has been created and is awaiting user authorization.                        |
| `ACTIVE`    | `200`         | The user completed authorization. The enrollment ID is ready to use for recurring charges. |
| `CANCELLED` | `400`         | The enrollment was cancelled.                                                              |
| `REJECTED`  | `300`         | The user did not complete or declined the authorization.                                   |

#### Step 2: Redirect the user

After receiving the synchronous response, redirect the user to `redirect_url`. The UX behavior depends on `device.type`:

| `device.type` | Behavior                                                                                                             |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `MOBILE_APP`  | The URL resolves to a deeplink that opens the Yape app directly. The user approves with their PIN or biometric.      |
| `WEB`         | The user lands on a dLocal-hosted page and receives a push notification in the Yape app. `payer.phone` is mandatory. |

Once the user completes the authorization in Yape, dLocal sends the enrollment webhook to your `notification_url` with the final `ACTIVE` or `REJECTED` status.

* **Browser / hosted flow:** `callback_url` may be used as a browser return URL after the hosted redirect completes.
* **Mobile app / Yape app handoff:** There is no automatic deep link back to your app after the user approves in Yape. The user must return to your app manually. See [Yape does not support automatic app callbacks](#yape-does-not-support-automatic-app-callbacks) in the Yape one-shot section. The same restriction applies to enrollment.

<Callout icon="📘" theme="info">
  ### Mandatory fields for User Experience

  `device.type` is **mandatory** for Yape and controls the entire UX. Sending the wrong value for the user's context will degrade conversion.

  `payer.phone` is mandatory when `device.type` is `WEB`. It is used to send the push notification. Without it, the enrollment cannot be completed.
</Callout>

**Redirection using** `redirect_url`

1. **Mobile app flow with standard automatic redirect**

If you send `device.type = "MOBILE_APP"`, dLocal returns a hosted `redirect_url` that normally resolves to the Yape deeplink. In the simplest case, the user opens the dLocal URL, dLocal redirects to Yape, and the user approves in the Yape app.

This is the simplest integration shape, but it is not the most reliable one across all mobile surfaces. The known issues are iOS non-Safari contexts and Android WebViews, where automatic 302 deeplink handoff may fail or behave inconsistently.

2. **Mobile app flow with manual redirect (optional fallback)**

If your app cannot reliably handle automatic deeplinks (for example, if you use a WebView or have iOS-heavy traffic where non-Safari browsers break Universal Links), contact your dLocal account team to enable `ENABLE_MANUAL_REDIRECT` on your MID. When enabled, dLocal shows an intermediate page with an "Abrir Yape" button. The user taps the button and the OS opens Yape through a user-initiated action, which is more reliable than an automatic redirect in those contexts.

This is an optional merchant feature, not the default Yape recurring experience.

3. **Desktop or web flow**

If you send `device.type = "WEB"`, dLocal does not try to deep link directly into Yape. Instead, the `redirect_url` points to a dLocal instruction page, and dLocal sends a push notification to the user's Yape app using `payer.phone`, which is mandatory for this scenario.

This flow is designed for desktop checkout. It should not be used as a workaround for mobile deeplink limitations, because the mobile experience is worse than the dedicated mobile flow.

**Recommended implementation**

The best implementation for YE enrollment is native URL interception in the merchant's mobile app. Open the dLocal `redirect_url`, detect when navigation reaches a yape.com.pe URL, and then open that URL natively through the operating system instead of leaving the handoff to the WebView or browser wrapper.

This is the strongest recommendation because it avoids the extra hosted step, minimizes friction, and bypasses the known iOS/WebView deeplink limitations.

If native interception is not possible, the next best option is to keep using the standard dLocal `redirect_url` and enable `ENABLE_MANUAL_REDIRECT` so the user opens Yape from a button click instead of relying on automatic redirection. Contact your dLocal account team to enable it.

For desktop, the recommended path is always `device.type = "WEB"` plus `payer.phone`, with the understanding that the user will approve from their Yape app after receiving the push or opening the app manually.

***

### Pattern 2: Payment + Enrollment in the same request

Use this when the first charge and enrollment happen simultaneously. Include an `enrollment` object in the `POST /payments` body. See the [Create payment](https://docs.dlocal.com/reference/create-payment) API reference for the full list of payment fields and the [Create enrollment](https://docs.dlocal.com/reference/create-enrollment) reference for enrollment object fields.

```json Enrollment + Sale request
curl -X POST \
   -H 'X-Date: {X-Date}' \
   -H 'X-Login: {X-Login}' \
   -H 'X-Trans-Key: {X-Trans-Key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: {Signature}' \
   -d '{body}'
   https://api.dlocal.com/payments

{
  "amount": 100,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "YE",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "email": "vanessa@example.com",
    "document": "43451826"
  },
  "device": {
    "type": "MOBILE_APP"
  },
  "enrollment": {
    "external_id": "enroll-pe-vanessa-001",
    "type": "ON_DEMAND",
    "description": "Yape recurring enrollment",
    "notification_url": "http://merchantsite.com/enrollment_notifications",
    "callback_url": "http://merchantsite.com/enrollment_callback"
  },
  "order_id": "payment-pe-vanessa-001",
  "notification_url": "http://merchantsite.com/payments",
  "callback_url": "http://merchantsite.com/payment_callback"
}
```
```json Synchronous response
{
  "id": "F-4-03c82e23-e068-41ec-865c-263de845c1ff",
  "amount": 100,
  "currency": "PEN",
  "payment_method_id": "YE",
  "payment_method_type": "WALLET",
  "payment_method_flow": "REDIRECT",
  "country": "PE",
  "created_date": "2025-04-03T20:16:52.000+0000",
  "status": "PENDING",
  "status_detail": "The payment is pending.",
  "status_code": "100",
  "order_id": "payment-pe-vanessa-001",
  "notification_url": "http://merchantsite.com/payments",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments-redirect/M-fd77f5b7-...",
  "enrollment": {
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
    "external_id": "enroll-pe-vanessa-001",
    "created_date": "2025-04-03T20:16:52.000+0000",
    "status": "PENDING",
    "status_detail": "The enrollment is pending.",
    "status_code": "100"
  }
}
```
```json Asynchronous notification (enrollment)
{
  "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "external_id": "enroll-pe-vanessa-001",
  "currency": "PEN",
  "country": "PE",
  "type": "ON_DEMAND",
  "payment_method_id": "YE",
  "payment_method_flow": "REDIRECT",
  "created_date": "2025-04-03T20:16:52.000+0000",
  "status": "ACTIVE",
  "status_detail": "The enrollment is active.",
  "status_code": "200",
  "notification_url": "http://merchantsite.com/enrollment_notifications"
}
```
```json Asynchronous notification (payment)
{
  "id": "F-4-03c82e23-e068-41ec-865c-263de845c1ff",
  "amount": 100,
  "status": "PAID",
  "status_detail": "The payment was paid.",
  "status_code": "200",
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "YE",
  "payment_method_type": "WALLET",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "email": "vanessa@example.com",
    "document": "43451826"
  },
  "enrollment": {
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
    "external_id": "enroll-pe-vanessa-001"
  },
  "order_id": "payment-pe-vanessa-001",
  "notification_url": "http://merchantsite.com/payments",
  "callback_url": "http://merchantsite.com/payment_callback",
  "created_date": "2025-04-03T20:16:52.000+0000"
}
```

<Callout icon="📘" theme="info">
  ### Single request, dual outcome

  This request produces two independent asynchronous notifications: one for the enrollment (sent to `enrollment.notification_url`) and one for the payment (sent to `notification_url`). They may arrive in any order. Persist the `enrollment.id` only after the enrollment notification reaches `ACTIVE` status. Grant entitlement only after the payment notification reaches `PAID` status.
</Callout>

<Callout icon="⚠️" theme="warn">
  ### device.type is mandatory

  `device.type` is **mandatory** for Yape and controls the entire UX. `payer.phone` is mandatory when `device.type` is `WEB`. See the [Mandatory fields for User Experience](#mandatory-fields-enrollment) note in Pattern 1. The same rules apply here.
</Callout>

**Enrollment status codes:**

For the full list of enrollment `status_code` values, see the [Get enrollment](https://docs.dlocal.com/reference/get-enrollment) and [Create enrollment](https://docs.dlocal.com/reference/create-enrollment) API references.

| `status`    | `status_code` | Description                                                                                |
| :---------- | :------------ | :----------------------------------------------------------------------------------------- |
| `PENDING`   | `100`         | The enrollment has been created and is awaiting user authorization.                        |
| `ACTIVE`    | `200`         | The user completed authorization. The enrollment ID is ready to use for recurring charges. |
| `CANCELLED` | `400`         | The enrollment was cancelled.                                                              |
| `REJECTED`  | `300`         | The user did not complete or declined the authorization.                                   |

***

### Recurring charges

Once enrollment is `ACTIVE`, charge the user directly by passing the enrollment reference as `enrollment.id` inside an `enrollment` object. No redirect is required. See the [Create payment](https://docs.dlocal.com/reference/create-payment) API reference for the full list of fields.

#### UX Flow

##### Enrolled user

![Yape recurring tokenized user UX flow](https://files.readme.io/c88fb62b8ad35c2cbd46c8e91f6fb6b44559ec4b63af6754d8704ecd4b7c4f87-Tokenized_user.png)

```json Recurring payment request
curl -X POST \
   -H 'X-Date: {X-Date}' \
   -H 'X-Login: {X-Login}' \
   -H 'X-Trans-Key: {X-Trans-Key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: {Signature}' \
   -d '{body}'
   https://api.dlocal.com/payments

{
  "amount": 26.90,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "YE",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "document": "43451826",
    "phone": "912345678"
  },
  "enrollment": {
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4"
  },
  "order_id": "sub-pe-001-2026-07",
  "notification_url": "http://merchantsite.com/notifications"
}
```
```json Synchronous response
{
  "id": "F-4-9a8b7c6d-5e4f-3a2b-1c0d-ef1234567890",
  "amount": 26.90,
  "currency": "PEN",
  "payment_method_id": "YE",
  "payment_method_type": "WALLET",
  "payment_method_flow": "DIRECT",
  "country": "PE",
  "created_date": "2026-07-01T10:00:00.000+0000",
  "status": "PENDING",
  "status_detail": "The payment is pending.",
  "status_code": "100",
  "order_id": "sub-pe-001-2026-07",
  "notification_url": "http://merchantsite.com/notifications"
}
```
```json Asynchronous notification
{
  "id": "F-4-9a8b7c6d-5e4f-3a2b-1c0d-ef1234567890",
  "amount": 26.90,
  "status": "PAID",
  "status_detail": "The payment was paid.",
  "status_code": "200",
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "YE",
  "payment_method_type": "WALLET",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "document": "43451826",
    "phone": "912345678"
  },
  "enrollment": {
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4"
  },
  "order_id": "sub-pe-001-2026-07",
  "notification_url": "http://merchantsite.com/notifications",
  "created_date": "2026-07-01T10:00:00.000+0000"
}
```

<Callout icon="⚠️" theme="warn">
  ### Final status is asynchronous

  The synchronous response is always `PENDING`. Do not grant entitlement on this response. Wait for the asynchronous webhook with `status: "PAID"` (200) before fulfilling the order.
</Callout>

<Callout icon="📘" theme="info">
  ### Enrollment ID lifecycle

  Each user has one active enrollment at a time. If a user re-enrolls, the new enrollment replaces the previous one. Any charge against the old enrollment returns `status_code` `328`. Stop using that enrollment immediately upon receiving `328` and trigger a new enrollment flow.
</Callout>

#### Request parameters

| Property                      | Type   | Description                                                                                                                                                                                                                | Mandatory?                     |
| ----------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `amount`                      | Number | Amount to be charged.                                                                                                                                                                                                      | Yes                            |
| `currency`                    | String | `PEN`. Transaction currency in ISO 4217.                                                                                                                                                                                   | Yes                            |
| `country`                     | String | `PE`. Transaction country in ISO 3166.                                                                                                                                                                                     | Yes                            |
| `payment_method_id`           | String | `YE`. ID of the selected payment method.                                                                                                                                                                                   | Yes                            |
| `payment_method_flow`         | String | `REDIRECT` (enrollment) or `DIRECT` (recurring charge)                                                                                                                                                                     | Yes                            |
| `payer.name`                  | String | Name of the payer.                                                                                                                                                                                                         | No                             |
| `payer.email`                 | String | Email of the payer.                                                                                                                                                                                                        | No                             |
| `payer.document`              | String | Document of the payer. DNI (8 digits) or RUC (11 digits).                                                                                                                                                                  | No                             |
| `payer.phone`                 | String | Phone number of the payer. Required for desktop enrollment flows to send push notifications to the user's Yape app.                                                                                                        | Yes, when `device.type: "WEB"` |
| `enrollment.id`               | String | The enrollment ID from a previous active enrollment, passed as `enrollment.id` inside an `enrollment` object. Use this for recurring charges.                                                                              | Yes, for recurring charges     |
| `enrollment`                  | Object | Enrollment object. Include this in `POST /payments` to create a payment and enrollment simultaneously.                                                                                                                     | Yes, for Pattern 2             |
| `enrollment.external_id`      | String | An identifier used by the merchant to identify the enrollment in their system.                                                                                                                                             | Yes                            |
| `enrollment.type`             | String | Type of enrollment. Must be `ON_DEMAND` for Yape Recurring. This is the only valid value. See the [Wallet payments](https://docs.dlocal.com/docs/wallet-payments#enrollment-only) page for valid types per payment method. | Yes                            |
| `enrollment.description`      | String | Enrollment description.                                                                                                                                                                                                    | No                             |
| `enrollment.notification_url` | String | URL where dLocal sends enrollment status notifications.                                                                                                                                                                    | Yes, for enrollment            |
| `enrollment.callback_url`     | String | URL where the user lands after enrollment completion.                                                                                                                                                                      | No                             |
| `device.type`                 | String | Device from which the user creates the transaction. Controls the UX flow. Possible values: `WEB` and `MOBILE_APP`.                                                                                                         | Yes, for enrollment            |
| `order_id`                    | String | ID of the capture given by the merchant in their system.                                                                                                                                                                   | No                             |
| `notification_url`            | String | dLocal sends notifications for every status change to this URL.                                                                                                                                                            | Yes                            |
| `callback_url`                | String | Optional browser return URL after enrollment. It does not create an automatic callback or deep link back from the Yape app after approval.                                                                                 | No                             |

#### Rejection codes

| `status_code` | **Description**                                                                      | **Retriable?**                                                                         |
| ------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| 302           | Insufficient funds in Yape wallet                                                    | No. User must top up.                                                                  |
| 305           | Max PIN/OTP attempts reached                                                         | No. User must wait.                                                                    |
| 319           | Amount exceeds per-transaction or daily limit                                        | Try next day.                                                                          |
| 321           | Acquirer technical error                                                             | Yes                                                                                    |
| 322           | Wallet blocked or frozen                                                             | No                                                                                     |
| 323           | Yape user not found                                                                  | No                                                                                     |
| 325           | Frequency limit exceeded                                                             | No. Wait before retrying.                                                              |
| 327           | External network error                                                               | Yes                                                                                    |
| **328**       | **Invalid enrollment**: the enrollment has been cancelled or superseded by a new one | **No. Stop using this enrollment ID and trigger a new enrollment flow for this user.** |
| 340           | Payment expired: user did not approve in time                                        | No. Create a new payment.                                                              |

#### Descriptor

The merchant name shown in the Yape app is configured at onboarding (tied to your MID) and cannot be changed per transaction. To update it, contact your dLocal account team.

## LigoPay

LigoPay is a payment solution available in Peru that allows payers to complete purchases using either an **interoperable QR code** or a **bank transfer via CCI** (Código de Cuenta Interbancario). Both payment options are presented simultaneously on the checkout voucher, giving payers the flexibility to choose whichever method suits them best.

QR payments are compatible with all major Peruvian digital wallets and banking apps, including Yape, Plin, BCP, and others. Bank transfers use an ephemeral CCI account number — unique per transaction — that the payer enters directly in their bank app.

### Capabilities

|                                    | LigoPay             |
| :--------------------------------- | :------------------ |
| **Min. amount**                    | 1 PEN               |
| **Max. expiration time supported** | Dynamic             |
| **Notification delay**             | Immediate           |
| **Refunds**                        | Yes (not native)    |
| **Flow**                           | `DIRECT` `REDIRECT` |

### Request parameters

| Property              | Type   | Description                                                                                                | Mandatory? |
| :-------------------- | :----- | :--------------------------------------------------------------------------------------------------------- | :--------- |
| `amount`              | Number | Amount to be charged.                                                                                      | Yes        |
| `currency`            | String | `PEN`. Transaction currency in [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217).                          | Yes        |
| `country`             | String | `PE`. Transaction country in [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).     | Yes        |
| `payment_method_id`   | String | `LY`. ID of the selected payment method.                                                                   | Yes        |
| `payment_method_flow` | String | `DIRECT` or `REDIRECT`.                                                                                    | Yes        |
| `payer.name`          | String | Full name of the payer.                                                                                    | No         |
| `payer.email`         | String | Email address of the payer.                                                                                | No         |
| `payer.document`      | String | Document number of the payer (DNI or equivalent).                                                          | No         |
| `payer.phone`         | String | Phone number of the payer (9 digits). Used by LigoPay for CCI generation.                                  | No         |
| `order_id`            | String | Merchant's internal order identifier. Must be unique per transaction to ensure idempotency.                | No         |
| `notification_url`    | String | dLocal sends notifications for every payment status change to the merchant's specified `notification_url`. | No         |

### Examples

```json Request
{
  "amount": 4000,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "LY",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "janedoe@mymail.com",
    "document": "12345678",
    "phone": "912345678"
  },
  "order_id": "order-abc-001",
  "notification_url": "https://merchantsite.com/notifications"
}
```
```json Response
{
  "id": "D-4-5d83cc9e-d6f0-48d7-9791-5ca2286b6a2f",
  "amount": 4000,
  "currency": "PEN",
  "payment_method_id": "LY",
  "payment_method_type": "TICKET",
  "payment_method_flow": "DIRECT",
  "country": "PE",
  "bank_transfer": {},
  "ticket": {
    "type": "CUSTOM",
    "number": "92100134247434422043",
    "expiration_date": "2025-12-31T23:59:59.000+0000",
    "image_url": "https://pay.dlocal.com/gmf-apm/payments/N-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "amount": 4000,
    "qr_code": "00020101021226370002800103903022025100709211964393181520448295303604540410005802PE5915Dlocal PEN..."
  },
  "created_date": "2025-06-06T11:52:57.000+0000",
  "status": "PENDING",
  "status_detail": "The payment is pending.",
  "status_code": "100",
  "order_id": "order-abc-001",
  "notification_url": "https://merchantsite.com/notifications"
}
```

### Response params

| Field                    | Description                                                                                                                                     |
| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticket.number`          | Ephemeral CCI account number. Unique per transaction. Display this to the payer for manual bank transfer.                                       |
| `ticket.qr_code`         | EMV QR string. Use this to render your own QR image at checkout. Compatible with Yape, Plin, and all BCRP-connected apps.                       |
| `ticket.image_url`       | URL to dLocal's hosted payment voucher, which renders both the QR code and the CCI bank transfer option. Use this for the simplest integration. |
| `ticket.expiration_date` | Expiration date and time for this transaction.                                                                                                  |

### Asynchronous response (IPN)

When the payer completes payment, dLocal sends an IPN notification to your `notification_url`. Your server must return HTTP `200` to acknowledge receipt. If a non-2xx response is returned, dLocal will retry delivery.

<Callout icon="📘" theme="info">
  ### **Best practice**

  Implement idempotent webhook handling. Use `id` or `order_id` as your idempotency key to prevent duplicate order fulfillment in case of retried notifications.
</Callout>

```json Notification
{
  "id": "D-4-5d83cc9e-d6f0-48d7-9791-5ca2286b6a2f",
  "amount": 4000,
  "status": "PAID",
  "status_detail": "The payment was paid.",
  "status_code": "200",
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "LY",
  "payment_method_type": "TICKET",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "janedoe@mymail.com",
    "document": "12345678"
  },
  "order_id": "order-abc-001",
  "notification_url": "https://merchantsite.com/notifications",
  "created_date": "2025-06-06T11:52:57.000+0000"
}
```

### Payment statuses

| Status      | Status code | Description                                 |
| :---------- | :---------- | :------------------------------------------ |
| `PENDING`   | `100`       | Payment created. Awaiting payer action.     |
| `PAID`      | `200`       | Payment confirmed. Funds received.          |
| `EXPIRED`   | `400`       | The payment window expired without payment. |
| `CANCELLED` | `400`       | The payment was cancelled.                  |
| `REJECTED`  | `300`       | The payment was rejected.                   |

### Example ticket

![LigoPay checkout voucher showing the QR code and CCI bank transfer options.](https://files.readme.io/6cf3b7098d512c64e95d0d9856fbb60ab3d4152f3a4a7c417f512738c860db27-image.png)

### Checkout voucher — UI guidelines

Both the QR code and the CCI bank transfer option must be displayed simultaneously on the payment voucher.

<Callout icon="✅" theme="okay">
  ### Dual-rail voucher

  Use `ticket.image_url` to embed dLocal's hosted voucher — it renders both the QR and the CCI in one view. If you build a custom voucher, render the QR from `ticket.qr_code` and display the CCI from `ticket.number` with a copy-to-clipboard button.
</Callout>

| Element                  | Tip                                                                                                                                     |
| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **QR Code**              | Render prominently at the top. Most Peruvian users will scan it.                                                                        |
| **CCI / Account number** | Label as **"CCI de pago"**. Display `ticket.number` with a copy-to-clipboard button so users can paste it directly into their bank app. |
| **Currency and Amount**  | Display as **S/** (not PEN). Users need the exact amount to complete a bank transfer correctly.                                         |
| **Expiration date**      | Show visibly. Use format **DD/MM/YYYY HH:MM** for the Peruvian market.                                                                  |
| **Download QR button**   | Include a download option for the QR image. Users often save it to their gallery to scan later from a different device.                 |
| **Language**             | All instructions and labels must be in **Spanish (es-PE)**.                                                                             |