Yape Recurrent
Yape Recurrent or Yape-On-File it is a groundbreaking, seamless, secure, and built for the mobile-first Peruvian market. A credential-on-file solution that lets users store and link their Yape account directly at checkout. No more QR scans or OTPs needed after the first authorization.
Yape allows merchants to set up and manage recurring payments through the EBANX API. The customer authorizes the merchant to make charges using Yape without the need to approve future payments. This solution can be used for recurring payments (subscription/enrollment) or one-click payments (leveraging the previously performed enrollment to process transactions without extra user interaction), reducing barriers for customers and making the subscription process more accessible and streamlined. It also creates an opportunity for global companies to establish themselves in Peru.
Requirements
- API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
How it works
- 1. Enrollment - Customers authorize recurring payments through an app-to-app or web-to-app flow. The enrollment process has two different user experiences depending on where the customer is coming from:
- App-to-App (mobile): Considering a mobile app experience, the merchant can request the enrollment and receive a deeplink URL to redirect the customer to Yape's app, where he/she can confirm the enrollment. On successful enrollments, the customer will be redirected to the
call_back_url. success
otherwise will be taken tocall_back_url.failure
- Web-to-App Flow (web): On a web browser user experience, the merchant requests the enrollment and the customer will receive a push notification on their mobile phone prompting them to open their Yape app and approve the enrollment. Once approved, the merchant will receive a notification informing a change in status of the enrollment. The merchant can query the merchant enrollment code to get the latest status anytime.
- App-to-App (mobile): Considering a mobile app experience, the merchant can request the enrollment and receive a deeplink URL to redirect the customer to Yape's app, where he/she can confirm the enrollment. On successful enrollments, the customer will be redirected to the
- 2. Enrollment Status update - EBANX notifies merchants of enrollment status updates via webhooks to the registered URL.
- 3. Subsequent payments - Once enrolled, future payments occur automatically using the
merchant_enrollment_code
, without requiring additional customer action. - 4. Enrollment payment update - EBANX notifies merchants of payment status updates via webhooks to the registered URL.
Instructions
Follow the steps below.
Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
https://sandbox.ebanx.com/ws/userenrollment/yapeDefine your enrollment parameters
The enrollment is a necessary step where the customer reviews and approves their wallet to be accessed by the merchant, allowing the merchant to make charges to their account when necessary. The same customer can have multiple enrollments for the same merchant.
The
phone
is the key on the Yape side to identify the customer account.Basic parameters
Parameter Requirement Description integration_key
Required Your integration key payment_type_code
Required Must be yape-recurrent
operation
Required Must be enrollment
Enrollment Data
Parameter Requirement Description merchant_enrollment_code
Required Unique identifier associated with the recurrence phone
Required Customer phone number email
Required Customer email address country
Required Must be pe
type
Required String on_demand
for one click payment ORrecurrent
for recurring paymentssource
Required String web
for push notification flow ORmobile
for hyperlink flowback_urls.success
Required URL to redirect the user upon a successful enrollment within Yape's app, determined by the merchant back_urls.failure
Required URL to redirect the user upon a failed enrollment, determined by the merchant Back_urls instructions
- enrollment.back_urls.success When the customer accepts the enrollment, he/she will be redirected to this URL. The merchant will know the result of the enrollment process by identifying the arrival of the customer at this url or by querying the enrollment.
- enrollment.back_urls.failure When the customer denies the enrollment, he/she will be redirected to this URL. The merchant will know the result of the enrollment process by identifying the arrival of the customer at this url or by querying the enrollment.
Enrollment request
The enrollment step is essential for registering customers for automatic payments. This process is handled through the /ws/userenrollment/yape endpoint.
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/userenrollment/yape' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "{{your_integration_key}}",
"operation": "enrollment",
"payment_type_code": "yape-recurrent",
"enrollment": {
"merchant_enrollment_code": "{{unique_enrollment_code}}",
"phone_number": "{{customer_yape_phone}}",
"email": "{{customer_email}}",
"country": "pe",
"yape":{
"type": "on_demand", // or recurrent
"source": "mobile", //or web
},
"back_urls": {
"success": "https://developer.ebanx.com/",
"failure": "https://google.com.br"
}
}
}'Enrollment response
The response to this call will indicate the status of the operation, returning either
SUCCESS
orCANCELED
.- Response example: App Flow (customer redirect - source = mobile)
{
"redirect_url": "https://yape.com.pe/app/checkout/ocp/subscription?id=3b97de9f-454d-4793-9f06-c121a1a9ff63&service_company=The%20Demonstration%20Merchant&partner_code=PEX004&origin_detail=MOBILE",
"status": "SUCCESS",
"enrollment": {
"merchant_enrollment_code": "d057c598",
"phone_number": "85228470358",
"email": "customer@example.com",
"country": "pe",
“yape”: {
“type”: “on_demand”,
“source”: “mobile”,
},
"back_urls": {
"success": "https://developer.ebanx.com/",
"failure": "https://google.com.br"
}
}
}- Response example: Web Flow (push notification - source = web)
{
"redirect_url": "no-redirect",
"status": "SUCCESS",
"enrollment": {
"merchant_enrollment_code": "d057c599",
"phone_number": "85228470358",
"email": "customer@example.com",
"country": "pe",
“yape”: {
“type”: “on_demand”,
“source”: “web”,
},
"back_urls": {
"success": "https://developer.ebanx.com/",
"failure": "https://google.com.br"
}
}
}Sandbox Behavior - When working in a sandbox environment, the
redirect_url
will lead to a sandbox interface where you can simulate customer acceptance or cancellation of the enrollment agreement.See example below.
Enrollment status check
Users purchasing for the first time need to be enrolled and authorized the payment. To check if the customer has accepted the recurrency and the latest status of the enrollment, the merchant can query the merchant_enrollment_code, sending a request to the
/ws/userenrollments/query
endpoint.Use the following parameters when preparing your request.
Parameter Requirement Description integration_key
Required Your EBANX integration key from EBANX dashboard operation
Required Set to enrollment
payment_type_code
Required Set to yape-recurrent
merchant_enrollment_code
Required Unique identifier defined by the merchant to be associated with that specific enrollment. country
Required Must be pe
Sample request:
curl -X POST \
--location 'https://sandbox.ebanxpay.com/ws/userenrollments/query' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "{{your_integration_key}}",
"operation": "enrollment",
"payment_type_code": "yape-recurrent",
"enrollment": {
"merchant_enrollment_code": "{{unique_enrollment_code}}",
"country": "pe"
}
}
Sample response (success):{
"status": "SUCCESS",
"enrollment": {
"status": "accepted"
}
}Cancel an existing enrollment
Customers can request the enrollment cancellation at any time. To abide by the customer's request, the merchant must call a cancel endpoint to revoke the enrollment. Once an enrollment is revoked, it can no longer be used for future transactions. If the customer wishes to process new payments, a new enrollment must be requested.
Enrollments can be cancelled by sending a POST request to the
/ws/userenrollment/yape/cancel
endpoint.Sample request:
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/userenrollment/yape/cancel' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "{{your_integration_key}}",
"operation": "cancel",
"payment_type_code": "yape-recurrent",
"enrollment": {
"merchant_enrollment_code": "{{unique_enrollment_code}}",
"country": "pe",
}
}'Sample response (success):
{
"status": "SUCCESS",
"enrollment": {
"status": "revoked"
}
}Payment request
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
https://sandbox.ebanx.com/ws/userenrollment/yapeMerchants can request payments whenever necessary, as long as there is an active enrollment for that customer, calling the ws/direct endpoint with the required parameters.
You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.Defining API parameters
Essential parameters
payment.payment_type_code
- Specifies the payment method to be used for the transaction.payment.currency_code
- Three-letter code of the payment currencypayment.amount_total
- Total amount to be charged.
Additional parameters
- EBANX Integration Key - Used to authenticate and authorize API requests.
- Customer Information
- Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
- While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
- Additional Context - Extra data for specific methods or countries.
To learn more about API parameters, please refer to theAPI Reference Guide chevron_rightAt the API Reference Guide, select Peru and Yape Recurrent from the dropdown menus.
Sample request:
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "{{your_integration_key}}",
"operation": "request",
"payment": {
"name": "{{customer_full_name}}",
"email": "{{customer_email}}",
"phone_number": "{{customer_yape_phone}}",
"document": "{{customer_document}}",
"country": "pe",
"payment_type_code": "yape-recurrent",
"merchant_payment_code": "{{unique_merchant_payment_code}}",
"currency_code": "PEN",
"amount_total": 11.00,
"metadata": {
"merchant_enrollment_code": "{{unique_merchant_enrollment_code}}"
}
}
}Payment response
The response of this call will have either a Completed (CO) or Canceled, (CA) status, and there will be no redirection. There is not action from the customer during the payment flow, everything will run without customer interaction.
Response:
{
"payment": {
"hash": "682ddaf2c5f5788b544e9d1c9bd1b2b8ae96bd275e5faf82",
"country": "pe",
"merchant_payment_code": "1747835634",
"order_number": null,
"status": "PE",
"status_date": null,
"open_date": "2024-12-19 20:04:59",
"confirm_date": null,
"transfer_date": null,
"amount_br": "11.00",
"amount_ext": "11.00",
"amount_iof": "0.00",
"amount_ext_requested": "11.00",
"currency_rate": "1.0000",
"currency_ext": "PEN",
"due_date": "2025-05-23",
"instalments": "1",
"payment_type_code": "yape-recurrent",
"pre_approved": false,
"capture_available": null,
"customer": {
"document": "12345678",
"email": "customer@test.com",
"name": "Customer Name",
"birth_date": "1940-02-23"
},
"requested_currency": "PEN",
"currency_ext_base": "PEN"
},
"status": "SUCCESS"
}Monitor payment for status changes
Notifications
Payments do not require customer interaction or manual authorization. Payment confirmation is asynchronous and may take a few seconds. Once the payment is confirmed, EBANX sends a webhook notification to to the
notification_url
stored in your EBANX Dashboard to inform that the status has changed for a specific transaction.Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
Status
After receiving a notification that status has changed, retrieve the payment status.
When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).
Congratulations!
You have succesfully integrated Yape Recurrent.
For more information, refer to theDirect API reference guidechevron_right
Resources
Use the following resources when testing in your sandbox environment.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.