# PagoEfectivo

> Learn how to use PagoEfectivo as one of your payment methods in Peru with EBANX Direct API.

# PagoEfectivo

PagoEfectivo is a widely-used payment method in Peru, supported by EBANX, that allows customers to complete online purchases without needing a credit or debit card. This voucher-based solution generates a unique Payment Code (CIP) that customers can use to pay in cash at various affiliated locations (such as banks, supermarkets, and convenience stores) or through bank transfer via online banking. Ideal for customers who prefer cash payments or lack traditional banking access, PagoEfectivo offers a secure and accessible payment method that meets local preferences and expands e-commerce options in Peru.

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

- **Generate a CIP code** - When your customer selects PagoEfectivo at checkout, EBANX generates a unique Payment Code (CIP). This code, valid for a specific period, is sent to your customer via email or SMS and includes all necessary payment details.
- **Complete payment** - Your customer completes the payment by visiting a partner location (such as local banks, supermarkets, or convenience stores) or through their online banking. They provide the CIP code to finalize the transaction, paying in cash or via bank transfer.
- **Payment confirmation** - After the payment is made, confirmation may take a short time depending on the venue. EBANX then updates the transaction status, allowing you to proceed with order fulfillment once the payment is confirmed.

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

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

### Define your parameters

Since PagoEfectivo operates as a voucher-based payment method, you’ll need to redirect your customer to a page displaying the voucher. To obtain this link, call the **ws/direct** endpoint with the following required fields:

#### Basic parameters

| Parameter           | Description                |
| :------------------ | :------------------------- |
| `integration_key`   | Your EBANX integration key |
| `payment_type_code` | Set to `pagoefectivo`      |
| `country`           | Set to `pe` for Peru.      |

  

#### Customer data

| Parameter | Description    |
| :-------- | :------------- |
| `name`    | Customer name  |
| `email`   | Customer email |

  

#### Charge parameters

| Parameter               | Description                       |
| :---------------------- | :-------------------------------- |
| `merchant_payment_code` | Unique merchant payment code      |
| `currency_code`         | Supported values: `PEN` and `USD` |
| `amount_total`          | Total amount to be charged        |

### Sample request

Use the following example to initiate a request.

```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",
        "document": "{{tax_id}}",
        "phone_number": "5555555555",
        "country": "pe",
        "payment_type_code": "pagoefectivo",
        "merchant_payment_code": "{{unique_merchant_code}}",
        "currency_code": "PEN",
        "amount_total": 99.85
    }
}'
```

### Sample response

A successful request returns a response similar to the example below, with the voucher link available in the **payment.cip_url** parameter.

```json
{
  "redirect_url": "{{redirect_url}}",
  "payment": {
    "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
    "country": "pe",
    "merchant_payment_code": "{{unique_merchant_code}}",
    "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",
    "currency_rate": "1",
    "currency_ext": "PEN",
    "due_date": "{{YYYY-MM-DD}}",
    "instalments": "1",
    "payment_type_code": "pagoefectivo",
    "pre_approved": false,
    "redirect_url": "{{redirect_url}}",
    "cip_url": "{{cip_url}}",
    "cip_code": "{{cip_code}}"
  },
  "status": "SUCCESS"
}
```

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

### Redirect customer to the returned URL

Redirect your customer to the URL provided in the `cip_url` parameter. They will see an interface similar to the one below:

![PagoEfectivo payment voucher showing CIP code and payment details for cash payment](/img/docs/pay-in/processing/payment-methods/country-specific/peru/pagoefectivo-voucher.png)

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

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.
- [Sample Cards](/docs/pay-in/dev-tools/sandbox-simulation/test-credit-cards)
- [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.