Skip to main content

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

  1. 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/yape
  2. 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

    ParameterRequirementDescription
    integration_keyRequiredYour integration key
    payment_type_codeRequiredMust be yape-recurrent
    operationRequiredMust be enrollment

    Enrollment Data

    ParameterRequirementDescription
    merchant_enrollment_codeRequiredUnique identifier associated with the recurrence
    phoneRequiredCustomer phone number
    emailRequiredCustomer email address
    countryRequiredMust be pe
    typeRequiredString on_demand for one click payment OR recurrent for recurring payments
    sourceRequiredString web for push notification flow OR mobile for hyperlink flow
    back_urls.successRequiredURL to redirect the user upon a successful enrollment within Yape's app, determined by the merchant
    back_urls.failureRequiredURL 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.
  3. 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"
    }
    }
    }'
  4. Enrollment response

    The response to this call will indicate the status of the operation, returning either SUCCESS or CANCELED.

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

    nupay-sandbox-redirect_url

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

    ParameterRequirementDescription
    integration_keyRequiredYour EBANX integration key from EBANX dashboard
    operationRequiredSet to enrollment
    payment_type_codeRequiredSet to yape-recurrent
    merchant_enrollment_codeRequiredUnique identifier defined by the merchant to be associated with that specific enrollment.
    countryRequiredMust 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"
    }
    }
  6. 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"
    }
    }
  7. 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/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 chevron_right

    At 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}}"
    }
    }
    }
  8. 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"
    }
  9. 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).

  10. Congratulations!

    You have succesfully integrated Yape Recurrent.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.


Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: