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 (source: "web"): 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 (source: "mobile"): The customer is seamlessly redirected from your mobile site straight into their Yape app via a deeplink.
  • 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​

The payment flow is determined by the source field inside the customer_device_info object. This field is required and must be set to either web or mobile.

  1. Desktop flow (source: "web"): The partner must include the customer's phone number in the API request. Yape sends a push notification to the customer's device. The customer taps the notification to open their Yape app and approve the payment. The response contains only the consent identifier.
  2. Mobile flow (source: "mobile"): The partner must send the customer's phone number in the API request. The flow is still determined by customer_device_info.source, and the response includes a deeplink that redirects the customer to the Yape app to complete the payment.

  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. The payment flow is determined by customer_device_info.source.

    Device info parameters​

    ParameterRequirementDescription
    customer_device_info.sourceRequiredDetermines the payment flow. Must be web (desktop) or mobile (app).

    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
      },
      "customer_device_info": {
          "source": "web"
      }
    }

  3. Payment response
    ​

    The response of this call will have either a Pending (PE) or Canceled (CA) status. For source: "web", a push notification is sent to the customer's Yape app and the response contains no redirect URL. For source: "mobile", the response includes a redirect_url that you should use to redirect the customer to the Yape app.

    {
    "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: