Skip to main content

Yape

Trusted Redirects Bundle

Yape One-shot is a payment solution that allows merchants to accept single, one-time digital payments from customers using their Yape wallet. The system is designed to provide a secure and streamlined checkout experience, leveraging the Yape mobile application for payment authorization.

The "one-shot" name signifies that it is intended for a single transaction, where the customer approves a specific payment without storing their financial details on the merchant's site for future use.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

How it works​

Here is the simple, step-by-step payment process your customers will experience when they choose to pay with Yape One-shot.

  • 1. The Customer Selects "Pay with Yape": On your checkout page, your customer will choose "Pay with Yape" from the available payment options to start the process.
  • 2. The Customer is Prompted on Their Phone:
    • For Desktop Purchases: Your system will securely send the customer's phone number (which you have already collected) in the background. This automatically triggers a push notification on their phone from the Yape app.
    • For Mobile Purchases: The customer is seamlessly redirected from your mobile site straight into their Yape app.
  • 3. The Customer Approves the Transaction: Inside their Yape app, the customer will see the transaction details, including your store name and the purchase amount. They will then tap a button to securely approve the payment.
  • 4. The Customer Receives Confirmation and Returns to Your Site: After a successful payment, the customer sees a confirmation screen in their Yape app. They are then automatically redirected back to your website's order confirmation page, completing the purchase.

Instructions​

Basically, there are two flows to request a payment.

  1. Mobile flow: For the mobile flow, in case of success, the endpoint should respond with the consent identifier and a deeplink with which the partner may redirect to the Yape application so the Yape User may continue with the payment process.
  2. Desktop (web) flow: For the desktop flow, the partner must send the Yape User's cell phone number in the API request. Yape will then send a push notification to the user's device. The Yape User should be advised to tap this notification to open their Yape app, where they may approve and complete the payment. The endpoint will respond with the consent identifier only.

An important observation is that the cell phone number is a mandatory field for this flow. Sending this field automatically defines the transaction as a desktop-type flow.

  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/direct

  2. Payment request
    ​

    To create a Yape payment, call the ws/direct endpoint with the following required fields:

    Basic parameters​

    ParameterRequirementDescription
    integration_keyRequiredYour EBANX integration key
    payment_type_codeRequiredSet to yape
    countryRequiredSet to pe for Peru

    Customer data​

    ParameterRequirementDescription
    nameRequiredCustomer name
    emailRequiredCustomer email
    documentRequiredCustomer document number
    phone_numberRequiredCustomer phone number registered with Yape. A push notification is sent to the customer's Yape app (desktop flow). For mobile purchases, the customer is redirected to the Yape app via deeplink.

    Charge parameters​

    ParameterRequirementDescription
    merchant_payment_codeRequiredUnique merchant payment code
    currency_codeRequiredSet to PEN
    amount_totalRequiredTotal amount to be charged
    For more API information, refer to the
    Direct API reference guidechevron_right

    curl -X POST --location 'https://sandbox.ebanx.com/ws/direct' --header 'Content-Type: application/json' --data '{
      "integration_key": "your_ebanx_integration_key",
      "payment": {
          "name": "{{customer_full_name}}",
          "email": "{{customer_email}}",
          "phone_number": "{{customer_yape_phone}}",
          "document": "{{customer_document}}",
          "country": "pe",
          "payment_type_code": "yape",
          "merchant_payment_code": "{{unique_merchant_payment_code}}",
          "currency_code": "PEN",
          "amount_total": 11.00
      }
    }

  3. Payment response
    ​

    The response of this call will have either a Pending (PE) or Canceled, (CA) status. If the request was sent via phone number, the notification will arrive directly on the device associated with the phone number in the Yape app, and there will be no redirection. If the request was not sent with the phone number, a link will be generated and sent in the response to redirect the customer to complete the payment.

    {
    "payment": {
      "hash": "682ddaf2c5f5788b544e9d1c9bd1b2b8ae96bd275e5faf82",
      "country": "pe",
      "merchant_payment_code": "1747835634",
      "order_number": null,
      "status": "PE",
      "status_date": null,
      "open_date": "2026-02-04 12:36:58",
      "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": "2026-02-07",
      "instalments": "1",
      "payment_type_code": "yape",
      "pre_approved": false,
      "capture_available": null
    },
    "status": "SUCCESS"
    }
    At this stage, the payment will appear as Pending (PE) in your
    EBANX Dashboardchevron_right

  4. Monitor payment for status changes
    ​

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

  5. Congratulations!
    ​

    You have successfully integrated Yape.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources​

Use the following resources when testing in your sandbox environment.

Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

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

Click to explorechevron_right
Warning Icon

Error Codes

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

Click to explorechevron_right

Still need help?

Help Image

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