Yape-Recurring Integration Guide

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.
- Web-to-App Flow (web): On a web browser user experience, the merchant requests the enrollment and the customer will have 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` OR `mobile` depending on customer device

Enrollment request

The enrollment step is essential for registering customers for automatic payments. This process is handled through the /ws/userenrollment endpoint and the enrollment.subscription.source field determines the user experience, dictating whether they have to manually open their Yape App on the phone (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": "5555555555",
      "email": "john.doe@example.com",
      "country": "pe",
      "subscription": {
          "frequency": "{{frequency}}",
          "fixed_amount": "99.85",
          "source": "mobile"
      }
  }
}

{
  "integration_key": "{{integration_key}}",
  "operation": "enrollment",
  "payment_type_code": "yape-recurrent",
  "enrollment": {
      "merchant_enrollment_code": "{{unique_enrollment_code}}",
      "phone_number": "5555555555",
      "email": "john.doe@example.com",
      "country": "pe",
      "subscription": {
          "frequency": "{{frequency}}",
          "fixed_amount": "99.85",
          "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://acquirer.redirect.example.com",
  "enrollment": {
      "merchant_enrollment_code": "{{unique_enrollment_code}}",
      "country": "pe",
      "email": "john.doe@example.com",
      "phone_number": "5555555555",
      "subscription": {
          "frequency": "{{frequency}}",
          "fixed_amount": "99.85",
          "source": "mobile"
      }
  }
}

{
  "status": "SUCCESS",
  "enrollment": {
      "merchant_enrollment_code": "{{unique_enrollment_code}}",
      "country": "pe",
      "email": "john.doe@example.com",
      "phone_number": "5555555555",
      "subscription": {
          "frequency": "{{frequency}}",
          "fixed_amount": "99.85",
          "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_ebanx_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"
    }
}

A successful request will return a JSON response like the one above, with a status of accepted for the enrollment approved by the customer. Other possible enrollment statuses include not_accepted, pending, expired, and cancelled, depending on the actions taken by the merchant or customer.

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

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.

Parameter	Requirement	Description
`integration_key`	Required	Your EBANX integration key
`name`	Required	Customer full name
`merchant_payment_code`	Required	Unique merchant payment code
`amount_total`	Required	Total amount to be charged. Note that the amount must match the one set in the enrollment
`currency_code`	Required	Must be `PEN`
`country`	Required	Must be `pe`
`payment_type_code`	Required	Must be `yape-recurrent`
`email`	Required	Customer e-mail
`phone_number`	Required	Customer phone number that is the Yape account key
`enrollment.merchant_enrollment_code`	Required	The enrollment code generated in the previous steps. The enrollment must have a `accepted` status to be used in recurring payments

Check the example:

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "payment": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone_number": "5555555555",
        "document": "{{document_id}}",
        "country": "pe",
        "payment_type_code": "yape-recurrent",
        "merchant_payment_code": "{{merchant_payment_code}}",
        "currency_code": "PEN",
        "amount_total": 99.85,
        "enrollment": {
            "merchant_enrollment_code": "{{unique_enrollment_code}}"
        }
    }
}'

Payment response

The response of this call will have a Pending (PE) 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": "59acc5f00945fa382ab051651440826da7701533249b3a475",
        "country": "pe",
        "merchant_payment_code": "{{merchant_payment_code}}",
        "order_number": null,
        "status": "PE",
        "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "confirm_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "transfer_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "amount_br": "99.85",
        "amount_ext": "99.85",
        "amount_iof": "0.00",
        "amount_ext_requested": "99.85",
        "currency_rate": "1.0000",
        "currency_ext": "PEN",
        "due_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "instalments": "1",
        "payment_type_code": "yape-recurrent",
        "pre_approved": false,
        "capture_available": null,
        "customer": {
            "document": "{{document_id}}",
            "email": "john.doe@example.com",
            "name": "John Doe",
            "birth_date": "{{YYYY-MM-DD}}"
        },
        "requested_currency": "PEN",
        "currency_ext_base": "PEN",
        "transaction_status": {
            "acquirer": "EBANX",
            "code": "OK",
            "description": "Payment successfully paid",
            "description_code": "ACCEPTED"
        }
    },
    "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

Alternative: Enroll and charge in a single request

As an alternative to the two-step process described above (steps 2-8), you can create an enrollment and a payment in a single API request to the /ws/direct endpoint. This simplifies the integration by combining the enrollment creation and the first payment into one operation. The customer will still need to authorize the enrollment through the Yape app. Once authorized, the payment will be processed automatically.

Parameters

Parameter	Description
`integration_key`	Your EBANX integration key.	Required
`operation`	Set to `request`.	Required
`payment.payment_type_code`	Set to `yape-recurrent`.	Required
`payment.merchant_payment_code`	Unique ID for the payment.	Required
`payment.email`	Customer email.	Required
`payment.country`	Set to `pe`.	Required
`payment.currency_code`	Set to `PEN`.	Required
`payment.phone_number`	Customer phone number connected to the Yape account.	Required
`payment.amount_total`	Total amount to charge.	Required
`payment.enrollment.merchant_enrollment_code`	Unique ID for the recurring enrollment.	Required
`payment.enrollment.subscription.frequency`	Billing cycle: `monthly`, `bimonthly`, `quarterly`, `halfyearly`, `yearly`, or `ondemand`.	Required
`payment.enrollment.subscription.source`	`mobile` (app-to-app) or `web` (web-to-app).	Required

Enroll and charge request

Send the combined enrollment and charge request to the /ws/direct endpoint. The subscription.source field determines the customer experience, just like in the standard enrollment flow.

App-to-App (source: mobile)
Web-to-App (source: web)

curl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
  "integration_key": "{{integration_key}}",
  "operation": "request",
  "payment": {
      "merchant_payment_code": "{{merchant_payment_code}}",
      "payment_type_code": "yape-recurrent",
      "amount_total": 99.85,
      "country": "pe",
      "currency_code": "PEN",
      "email": "john.doe@example.com",
      "phone_number": "5555555555",
      "enrollment": {
          "merchant_enrollment_code": "{{unique_enrollment_code}}",
          "subscription": {
              "frequency": "{{frequency}}",
              "source": "mobile"
          }
      }
  }
}'

curl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
  "integration_key": "{{integration_key}}",
  "operation": "request",
  "payment": {
      "merchant_payment_code": "{{merchant_payment_code}}",
      "payment_type_code": "yape-recurrent",
      "amount_total": 99.85,
      "country": "pe",
      "currency_code": "PEN",
      "email": "john.doe@example.com",
      "phone_number": "5555555555",
      "enrollment": {
          "merchant_enrollment_code": "{{unique_enrollment_code}}",
          "subscription": {
              "frequency": "{{frequency}}",
              "source": "web"
          }
      }
  }
}'

Enroll and charge response

The response confirms that both the enrollment and the payment have been created. The enrollment remains in a pending state until the customer authorizes it through the Yape app.

App-to-App Response (mobile)
Web-to-App Response (web)

{
  "payment": {
      "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
      "country": "pe",
      "merchant_payment_code": "{{merchant_payment_code}}",
      "order_number": null,
      "status": "PE",
      "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "confirm_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "transfer_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "amount_br": "99.85",
      "amount_ext": "99.85",
      "amount_iof": "0.00",
      "amount_ext_requested": "99.85",
      "currency_rate": "1.0000",
      "currency_ext": "PEN",
      "due_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "instalments": "1",
      "payment_type_code": "yape-recurrent",
      "pre_approved": false,
      "capture_available": null,
              "redirect_url": "https://acquirer.redirect.example.com",
              "enrollment": {
          "status": "pending",
          "merchant_enrollment_code": "{{unique_enrollment_code}}"
      }
  },
  "status": "SUCCESS",
  "redirect_url": "https://acquirer.redirect.example.com"
}

{
  "payment": {
      "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
      "country": "pe",
      "merchant_payment_code": "{{merchant_payment_code}}",
      "order_number": null,
      "status": "PE",
      "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "confirm_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "transfer_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "amount_br": "99.85",
      "amount_ext": "99.85",
      "amount_iof": "0.00",
      "amount_ext_requested": "99.85",
      "currency_rate": "1.0000",
      "currency_ext": "PEN",
      "due_date": "{{YYYY-MM-DD HH:mm:ss}}",
      "instalments": "1",
      "payment_type_code": "yape-recurrent",
      "pre_approved": false,
      "capture_available": null,
      "enrollment": {
          "status": "pending",
          "merchant_enrollment_code": "{{unique_enrollment_code}}"
      }
  },
  "status": "SUCCESS"
}

The enrollment remains in a pending state until the customer authorizes it through the Yape app. After the status changes, a notification will be sent. You can also verify the enrollment status using the Query enrollment status method described above.

The payment will initially be in Pending (PE) status while waiting for the enrollment authorization. Once the customer authorizes the enrollment, the payment begins processing. After processing completes, the payment status will change to Confirmed (CO) or Canceled (CA), and a notification will be sent.

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​

Enrollment request​

Enrollment response​

Enrollment status check​

Cancel an existing enrollment​

Payment request​

Payment response​

Monitor payment for status changes​

Alternative: Enroll and charge in a single request​

Parameters​

Enroll and charge request​

Enroll and charge response​

Congratulations!​

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Instructions

Select your environment

Define your enrollment parameters

Basic parameters

Enrollment Data

Enrollment request

Enrollment response

Enrollment status check

Cancel an existing enrollment

Payment request

Payment response

Monitor payment for status changes

Alternative: Enroll and charge in a single request

Parameters

Enroll and charge request

Enroll and charge response

Congratulations!

Resources