Yape-Recurring Integration Guide | EBANX Developers Academy

Yape Recurring or Yape-On-File it is a 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 to call_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.
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.
SandboxProduction
https://sandbox.ebanx.com/ws/userenrollment/yape

Define 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
`enrollment.merchant_enrollment_code`	Required	Unique identifier associated with the recurrence
`enrollment.phone`	Required	Customer phone number connected to the Yape Account
`enrollment.email`	Required	Customer email address
`enrollment.country`	Required	Must be `PE`
`enrollment.subscription.frequency`	Required	The billing cycle of the enrollment. Available frequencies are: `monthly`,`bimonthly`, `quarterly`, `halfyearly`, `yearly` or `ondemand`
`enrollment.subscription.fixed_amount`	Optional	Local amount definition provided when recurring payments will have a fixed value.
`enrollment.subscription.source`	Required	String `web` for push notification flow OR `mobile` for hyperlink flow
`enrollment.back_urls.success`	Required	URL to redirect the user upon a successful enrollment within Yape's app, determined by the merchant
`enrollment.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 endpoint and and the enrollment.subscription.source field determines the user experience, dictating whether they access the Yape App via push notification (web) or are redirected via the redirect_url provided in the response (mobile).

App-to-App Request
Web-to-App Request

{
  "integration_key": "{{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",
      "subscription": {
          "frequency": "monthly", 
          "fixed_amount": 20.00, 
          "source": "mobile" 
      },
      "back_urls": {
         "success": "https://your-success-url.com",
          "failure": "https://your-failure-url.com"
      }
    }
  }

{
  "integration_key": "{{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",
      "subscription": {
          "frequency": "monthly", 
          "fixed_amount": 20.00, 
          "source": "web" 
      }
 }
}

Enrollment response

The response to this call will indicate the status of the operation, returning SUCCESS and your enrollment definitions. Mobile flow will contain the redirect_url in the response for you to send your customer to Yape App.

App-to-App Response
Web-to-App Response

{
  "status": "SUCCESS",
  "redirect_url": "https://yape.com.pe/app/checkout/ocp/subscription?id=565e35a5-09d0-4947-123a-53693dae6&origin_detail=MOBILE",
  "enrollment": {
      "merchant_enrollment_code": "4993b489-da7f-40ae-b1a8-1702e94369ce",
      "country": "pe",
      "email": "john.doe@ebanx.com",
      "phone_number": "91234567",
      "back_urls": {
          "success": "https://your-success-url.com",
          "failure": "https://your-failure-url.com"
      },
      "subscription": {
          "frequency": "monthly",
          "fixed_amount": "20",
          "source": "mobile"
      }
  }
}

{
  "status": "SUCCESS",
  "enrollment": {
      "merchant_enrollment_code": "4993b489-da7f-40ae-b1a8-1702e94369ce",
      "country": "pe",
      "email": "john.doe@ebanx.com",
      "phone_number": "91234567",
      "subscription": {
          "frequency": "monthly",
          "fixed_amount": "20",
          "source": "web"
      }
  }
}

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 'https://sandbox.ebanx.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.
SandboxProduction
https://sandbox.ebanx.com/ws/userenrollment/yape
Merchants 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.
Defining API parameters
You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.

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 currency
- payment.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 the
API Reference Guide
At the API Reference Guide, select Peru and Yape Recurring 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}}", 
    "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.
- Learn more about Payment Notifications
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).
- Learn more about Retrieving Payment Status
Congratulations!
You have succesfully integrated Yape Recurring.
For more information, refer to the
Direct API reference guide

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explore

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explore

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explore

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.

Yape Recurring

Requirements​

How it works​

Instructions​

Select your environment

Define your enrollment parameters

Basic parameters​

Enrollment Data​

Back_urls instructions​

Enrollment request

Enrollment response

Enrollment status check

Cancel an existing enrollment

Payment request

Payment response

Monitor payment for status changes

Congratulations!

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Instructions

Basic parameters

Enrollment Data

Back_urls instructions

Resources