Market specifications

Take a look of all the payment methods available.

Country reference Cards supported APM supported

Cards

Find all the information about the card supported capabilities.

Capabilities Process Card Payments

Alternative Payments

Learn how to integrate cash, bank transfer or wallet payment.

Pago Efectivo BCP Payvalida Yape Yape Recurring

Market specifications

Do you want to know more information about the Peru market? Go to the Peru economy and eCommerce market 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

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

Cards supported

`payment_method_id`	Brand ID	Name	`payment_method_type`	Details	Allowed Flows
`CARD`	`VI`	Visa	`CARD`	Credit Card	`DIRECT` `REDIRECT`
`CARD`	`VD`	Visa Debit	`CARD`	Debit Card	`DIRECT` `REDIRECT`
`CARD`	`MC`	Mastercard	`CARD`	Credit Card	`DIRECT` `REDIRECT`
`CARD`	`MD`	Mastercard Debit	`CARD`	Debit Card	`DIRECT` `REDIRECT`
`CARD`	`AE`	American Express	`CARD`	Credit Card	`DIRECT` `REDIRECT`
`CARD`	`DC`	Diners Club	`CARD`	Credit Card	`DIRECT` `REDIRECT`

ℹ️
To offer all the card options that may be available in your integration, send the payment_method_id as CARD.

Alternative Payment Method supported

`payment_method_id`	Name	`payment_method_type`	Details	Allowed Flows
`EF`	Pago Efectivo	`TICKET`	Cash Payments	`DIRECT` `REDIRECT`
`BC`	BCP	`BANK_TRANSFER`	Bank Transfer	`DIRECT` `REDIRECT`
`IO`	Payvalida	`BANK_TRANSFER`	Bank Transfer	`REDIRECT`
`YP`	Yape one-shot	`WALLET`	eWallet	`REDIRECT`
`YE`	Yape Wallet recurring	`WALLET`	eWallet	`REDIRECT`

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

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.	Yes
`country`	String	`PE`. Transaction country in ISO 3166.	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

{
  "amount": 1000,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "EF",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "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"
}

{
    "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": "165816703",
        "expiration_date": "2023-06-17T11:59:00.000+0000",
        "id": "EF-144059474",
        "barcode": "",
        "company_name": "DEMERGE PERU SAC",
        "image_url": "https://pay.dlocal.com/gmf-apm/payments/M-76d9d7bb-d3f8-40fb-befc-1cf5609de3fd",
        "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

User Interface Tips

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

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)".
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.	Yes
`country`	String	`PE`. Transaction country in ISO 3166.	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

{
  "amount": 1000,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "BC",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "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"
}

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

{
  "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": "[email protected]",
    "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

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.	Yes
`country`	String	`PE`. Transaction country in ISO 3166.	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

{
  "amount": 1000,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "IO",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "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"
}

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

{
  "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": "[email protected]",
    "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

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

You create a payment with payment_method_id: "YP" and payment_method_flow: "REDIRECT".
dLocal returns a redirect_url.
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.
After approval, dLocal sends a PAID webhook to your notification_url.

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

UX Flow Example

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

{
  "amount": 100,
  "currency": "PEN",
  "country": "PE",
  "payment_method_id": "YP",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Castillo Gomes Vanessa Silvia",
    "email": "[email protected]",
    "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"
}

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

{
  "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": "[email protected]",
    "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 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:

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

⚠️
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.

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.

⚠️
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.

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.

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

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

UX Flow

First time user

Pattern 1: Enrollment only

Use POST /enrollments to establish the user's authorization without an initial charge. See the full Create enrollment API reference for all available fields.

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

Step 1: Create the enrollment

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": "[email protected]",
    "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"
}

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

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

📘
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 endpoint.
To cancel an enrollment, use the Cancel an enrollment endpoint.

Enrollment status codes:

For the full list of enrollment status_code values, see the Get enrollment and 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 in the Yape one-shot section. The same restriction applies to enrollment.

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

Redirection using redirect_url

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.

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.

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 API reference for the full list of payment fields and the Create enrollment reference for enrollment object fields.

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": "[email protected]",
    "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"
}

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

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

{
  "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": "[email protected]",
    "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"
}

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

⚠️
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 note in Pattern 1. The same rules apply here.

Enrollment status codes:

For the full list of enrollment status_code values, see the Get enrollment and 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 API reference for the full list of fields.

UX Flow

Enrolled user

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

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

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

⚠️
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.

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

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

For a full overview of wallet payment flows, see the Wallet payments page.