Yape

To receive payments, add a form to the frontend that captures the phone number and the OTP that the buyer generates in the Yape application.

If you already have a development that includes your own payment form, make sure to include Yape among the payment options you want to offer, as shown below, and continue to the Create Yape token step.

If you do not have a payment form yet, add the template below to your project and include the Yape identifier as an option to be offered.

html
<form id="form-checkout" action="/process_payment" method="post">
  <div>
    <label for="payerPhone">Phone number</label>
    <input id="form-checkout__payerPhone" name="payerPhone" type="text" />
  </div>
  <div>
    <label for="payerOTP">OTP</label>
    <input id="form-checkout__payerOTP" name="payerOTP" type="text" />
  </div>
  <div>
    <button type="submit">Pay with Yape</button>
  </div>
</form>

The Yape token is created from the phone number and the OTP (One-Time Password) sent in the request, increasing security during the payment flow. Once the token is used in a given purchase, it is discarded, requiring the creation of a new one for future purchases.

You can create it with MercadoPago.js or through a direct API call.

javascript
const form = document.getElementById("form-checkout");

form.addEventListener("submit", async (event) => {
  event.preventDefault();

  const otp = document.getElementById("form-checkout__payerOTP").value;
  const phoneNumber = document.getElementById("form-checkout__payerPhone").value;
  const yape = mp.yape({ otp, phoneNumber });
  const yapeToken = await yape.create();

  // Send yapeToken.id to your server to create the order.
});

The payment must be submitted by creating an order that contains the associated payment transaction.

To do this, send a request with your test Access TokenPrivate key of the application created in Mercado Pago, used in the backend. Access it at Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the `APP_USR` prefix. and the parameters listed below to the /v1/ordersPOST endpoint.

curl
curl --location --request POST 'https://api.mercadopago.com/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--data-raw '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "total_amount": "100.00",
  "payer": {
    "email": "test_user_pe@testuser.com",
    "entity_type": "individual",
    "identification": {
      "type": "DNI",
      "number": "12345678"
    },
    "phone": {
      "area_code": "51",
      "number": "987654321"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "100.00",
        "payment_method": {
          "id": "yape",
          "type": "debit_card",
          "token": "{{YOUR_YAPE_TOKEN}}"
        }
      }
    ]
  }
}'

See in the table below the descriptions of the parameters that are required in the request and of those that, although optional, have some particularity worth highlighting.

After successfully creating the order, you will receive a response with status: processed and status_detail: accredited, indicating that the payment was approved.

json
{
  "id": "ORDPE01EXAMPLEPE1234NCAKKBF68N64S",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "100.00",
  "total_paid_amount": "100.00",
  "country_code": "PER",
  "user_id": "1234567890",
  "status": "processed",
  "status_detail": "accredited",
  "capture_mode": "automatic_async",
  "currency": "PEN",
  "created_date": "2026-07-29T21:03:42.252Z",
  "last_updated_date": "2026-07-29T21:03:43.985Z",
  "integration_data": {
    "application_id": "1234567890123456"
  },
  "transactions": {
    "payments": [
      {
        "id": "PAYPE01EXAMPLEPE1234BSAR5ZWXX5YZG",
        "reference_id": "1234567890",
        "amount": "100.00",
        "paid_amount": "100.00",
        "status": "processed",
        "status_detail": "accredited",
        "payment_method": {
          "id": "yape",
          "type": "debit_card"
        }
      }
    ]
  }
}

Since Yape is processed synchronously when the order is created in automatic mode, there is no buyer redirect. Among the returned parameters, the following are highlighted in the table below.

Depending on the mode in which the order is created (automatic or manual), a Yape payment can be processed in two different ways and, consequently, so can its cancellation. See below how to proceed in each situation:

• Automatic mode: the order is created in automatic mode and the Yape payment is processed synchronously (status=processed). As a result, the order creation response already returns the final payment result, and it is not possible to cancel it once approved (status_detail=accredited). In this case, you will need to carry out a refund process through a request to the /v1/orders/{order_id}/refundPOST endpoint.
  
  
• Manual mode: the order is created in manual mode and payment processing requires an additional step (status=action_required) at the Process orderPOST endpoint. In this case, before processing the payment you will be able to cancel it through a request to the /v1/orders/{order_id}/cancelPOST endpoint.

For more information, see the Refunds and cancellations section.