# Yape Integration Guide

> Yape One-shot is a payment solution for Peru that allows merchants to accept single, one-time digital payments from customers using their Yape wallet.

# Yape

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, using 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 authentication** - All API requests must be authenticated using [JWS (JSON Web Signature)](/docs/get-started/api-authentication/jws-authentication). The legacy `integration_key` is being deprecated — if you still use it, follow the [Migration Guide](/docs/get-started/api-authentication/jws-migration) to transition to JWS. If you don't have credentials yet, complete the [Merchant Signup Form](https://www.ebanx.com/en/contact/).
- **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 notification on their phone from the Yape app.
  - **For Mobile Purchases (`source: "mobile"`):** The customer is 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 notification to the customer's Yape App on their device. The customer opens their Yape app and approve the payment. The response contains only the consent identifier.
2. **Mobile flow (`source: "mobile"`):** The customer is redirected to the Yape app via a deeplink to complete the payment. The `phone_number` field is optional in this flow.

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

- **Cross-border sandbox:** `https://sandbox.ebanxpay.com/ws/direct`
- **Cross-border production:** `https://api.ebanxpay.com/ws/direct`
- **Local sandbox:** `https://sandbox-local-latam.ebanxpay.com/ws/direct`
- **Local production:** `https://api-local-latam.ebanxpay.com/ws/direct`

Check the method's availability for your country and tenant in [Payment Methods by Country](/docs/pay-in/processing/payment-methods/payment-methods-overview#payment-methods-by-country). Questions about tenant and environment? Check our [API Operability](/docs/get-started/api-operability) and [API Endpoints](/docs/get-started/api-endpoints).

### Payment request

To create a Yape payment, call the **ws/direct** endpoint with the following parameters:

#### Basic parameters

| Parameter               | Requirement | Description                |
| ----------------------- | ----------- | -------------------------- |
| **`integration_key`**   | Required    | Your EBANX integration key |
| **`payment_type_code`** | Required    | Set to `yape`              |
| **`country`**           | Required    | Set to `pe` for Peru       |

  

#### Customer data

| Parameter          | Requirement | Description                                                                                                                                                      |
| ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`name`**         | Optional    | Customer name                                                                                                                                                    |
| **`email`**        | Required    | Customer email                                                                                                                                                   |
| **`document`**     | Optional    | Customer document number                                                                                                                                         |
| **`phone_number`** | Required when `source = web` | Customer phone number registered with Yape. The payment flow is determined by `customer_device_info.source`. |

  

#### Device info parameters

| Parameter                          | Requirement | Description                                                                 |
| ---------------------------------- | ----------- | --------------------------------------------------------------------------- |
| **`customer_device_info.source`**  | Required    | Determines the payment flow. Must be `web` (desktop) or `mobile` (app).    |

  

#### Charge parameters

| Parameter                   | Requirement | Description                  |
| --------------------------- | ----------- | ---------------------------- |
| **`merchant_payment_code`** | Required    | Unique merchant payment code |
| **`currency_code`**         | Required    | Set to `PEN`                 |
| **`amount_total`**          | Required    | Total amount to be charged   |

  

For more API information, refer to the [Direct API reference guide](/api-reference?api=pay-in&page=direct)

    #### Desktop flow (source: web)
      ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.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": "{{tax_id}}",
        "country": "pe",
        "payment_type_code": "yape",
        "merchant_payment_code": "{{unique_merchant_code}}",
        "currency_code": "PEN",
        "amount_total": 99.85
    },
    "customer_device_info": {
        "source": "web"
    }
}'
```
    </TabItem>
    #### Mobile flow (source: mobile)
      ```bash
curl -X POST \
  --location 'https://sandbox.ebanxpay.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": "{{tax_id}}",
        "country": "pe",
        "payment_type_code": "yape",
        "merchant_payment_code": "{{unique_merchant_code}}",
        "currency_code": "PEN",
        "amount_total": 99.85
    },
    "customer_device_info": {
        "source": "mobile"
    }
}'
```

### Payment response

The response of this call will have either a **Pending** (**PE**) or **Canceled** (**CA**) status.
For `source: "web"`, EBANX provides an optional redirect_url pointing to an EBANX instructions page. If the merchant prefers to render their own Yape instructions, this field can be safely ignored.
For `source: "mobile"`, the response includes a `redirect_url` that you should use to redirect the customer to the Yape app.

    #### Response for desktop flow (source: web)
      ```json
{
  "payment": {
    "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
    "country": "pe",
    "merchant_payment_code": "{{unique_merchant_code}}",
    "order_number": null,
    "status": "PE",
    "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "99.85",
    "amount_ext": "99.85",
    "amount_iof": "1",
    "amount_ext_requested": "99.85",
    "currency_rate": "1",
    "currency_ext": "PEN",
    "due_date": "{{YYYY-MM-DD}}",
    "instalments": "1",
    "payment_type_code": "yape",
    "pre_approved": false,
    "capture_available": null,
    "redirect_url": "{{redirect_url}}"
  },
  "status": "SUCCESS",
  "redirect_url": "{{redirect_url}}"
}
```
    </TabItem>
    #### Response for mobile flow (source: mobile)
      ```json
{
  "payment": {
    "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
    "country": "pe",
    "merchant_payment_code": "{{unique_merchant_code}}",
    "order_number": null,
    "status": "PE",
    "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "99.85",
    "amount_ext": "99.85",
    "amount_iof": "1",
    "amount_ext_requested": "99.85",
    "currency_rate": "1",
    "currency_ext": "PEN",
    "due_date": "{{YYYY-MM-DD}}",
    "instalments": "1",
    "payment_type_code": "yape",
    "redirect_url": "{{redirect_url}}",
    "pre_approved": false,
    "capture_available": null
  },
  "status": "SUCCESS",
  "redirect_url": "{{redirect_url}}"
}
```

[Merchant Area](https://dashboard.ebanx.com)

### Monitor payment for status changes

**Notifications**

- EBANX will send a notification whenever a payment status changes.

- Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

- [Learn more about Payment Notifications](/docs/pay-in/management/status-and-retrieval/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](/docs/pay-in/management/status-and-retrieval/retrieve-payment)

### Congratulations!

You have successfully integrated **Yape**.

For more information, refer to the [Direct API reference guide](/api-reference?api=pay-in&page=direct)

## Resources

Use the following resources when testing in your sandbox environment.
- [API Reference](/api-reference)
- [Mock Customer Data](/docs/pay-in/dev-tools/sandbox-simulation/test-customer-data)
- [Error Codes](/docs/pay-in/dev-tools/response-codes/api-error-codes)
## Still need help?

If you still have questions, you can explore the following options:

- **Merchant support:** Contact our support team at [sales.engineering@ebanx.com](mailto:sales.engineering@ebanx.com) for assistance.
- **Not a partner yet?** Complete the [Merchant Signup Form](https://business.ebanx.com/en/request-contact), and our commercial team will reach out to you.