Yape - Integration configuration - Mercado Pago Developers

Do not know how to start integrating?

Yape

Yape is a mobile application that simplifies the process of bank transfers. Users can make transactions easily and quickly directly from their cell phones, after linking their MultiRed debit card to the application.

To make a transaction with Yape, first you must generate a token, which is necessary for the payment creation stage. This token can be generated in two ways: directly through an API or using the Mercado Pago JS SDK.

In this documentation, you will find all the necessary steps to perform the configuration and integration tests with Yape comprehensively.

Integração via SDK javascript

With Checkout API, it is possible to offer payments via Yape using the JS SDK method to generate a token. For this, it is necessary to send the phone number and OTP (one-time password found in the Yape application) fields. With the token, a payment can be created.

To offer payments with Yape, follow these steps.

Importing MercadoPago.js

The first step in the payment integration process with Yape is capturing the OTP (One-time password) and phone number data to generate the payment token. This is done by including the MercadoPago.js library in your project, followed by the form to capture the necessary data.

Important

If you wish to perform the integration via API, proceed to the section Adding form for OTP and phone number capture and follow the instructions.

Use the following code to import the MercadoPago.js library before adding the form. You can import the library via HTML or Bash.

          
<body>
  <script src="https://sdk.mercadopago.com/js/v2"></script>
</body>

          
npm install @mercadopago/sdk-js

Configure credentials

Credentials are unique keys used to identify an integration in your account. They are used to securely capture payments in online stores and other applications.

Use the code below to configure your credential, replacing the value YOUR_PUBLIC_KEY with your production Public key available in the application created in Your integrations. For more details, see credentials.

const mp = new MercadoPago("YOUR_PUBLIC_KEY");

Adding form for OTP and phone number capture

To generate a Yape token, you need to fill out the OTP field, which represents the code generated in the Yape application, and the phone number. To capture this data, use the following HTML directly in your project:

<form id="form-checkout">
  <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 onclick="handleYape()">Create YAPE</button>
  </div>
</form>

Generate token

After completing the inclusion of the form and obtaining the necessary data, generate the Yape token using MercadoPago.js or via API.

The token is single-use per purchase and must be sent during the payment creation stage.

Generate token via MercadoPago.js

Use the mp.yape.create method to generate a Yape token, as shown in the code below:

(async function handleYape () {
  const otp = docment.getElementById("form-checkout__payerOTP").value;
  const phoneNumber = docment.getElementById("form-checkout__payerPhone").value;
  const yapeOptions = {
    otp,
    phoneNumber
  };
  const yape = mp.yape(yapeOptions);
  const yapeToken = await yape.create();
  return yapeToken;
});

Generate token via API

Another way to generate the token is through an API. To do this, use the following cURL, filling in the parameters as detailed in the table below.

Field	Type	Description	Required/Optional	Examples/Possible values
`phoneNumber`	number	Phone number of the payer obtained in the Capture cell phone and OTP data step.	Required	123214234342
`otp`	number	Unique numeric 6-digit code found in the Yape app. This field is obtained in the Capture cell phone and OTP data step.	Required	123344
`requestId`	string	Field automatically generated by the JS SDK, not necessary to send. Must be sent only in integrations done via cURL.	Required for integrations done via cURL	aaaaaaaa-bbbb-1ccc-8ddd-eeeeeeeeeeee

curl --location 'https://api.mercadopago.com/platforms/pci/yape/v1/payment?public_key=<PUBLIC_KEY>' \
--header 'Content-Type: application/json' \
--data '{
   "phoneNumber": "123214234342",
   "otp": "123344",
   "requestId": "3127367123234234"
}

Example response:

{
    "live_mode": true,
    "luhn_validation": null,
    "require_esc": null,
    "cloned": false,
    "cardholder": {
        "identification": {
            "number": null,
            "type": null,
            "subtype": null
        },
        "name": "yape"
    },
    "security_code_id": 8069792005119486812,
    "security_code_length": 6,
    "card_number_length": 9,
    "expiration_month": 5,
    "expiration_year": 2024,
    "card_present_id": null,
    "card_id": null,
    "client_id": 7775327892346559,
    "present": null,
    "id": "45d013f72bf42717a1625f4c508fc20f",
    "card_number_id": "FFTSHQTOSJTXGFVFGJKCBAIVOUISTFZBDRTQWLYJ",
    "creation_date": null,
    "due_date": null,
    "last_modified_date": null,
    "product_id": null,
    "trust_level": "unknown",
    "public_key": "APP_USR-352587ca-674b-4ae4-a348-8583ab39b4ac",
    "site_id": "MPE",
    "status": "active",
    "transaction_id": null,
    "trunc_card_number": null,
    "used_date": null,
    "bin": "111111",
    "version": 0,
    "client_header": null,
    "first_six_digits": "111111",
    "last_four_digits": "6789"
}

Create payment

After adding the form to capture the cell phone and OTP data and generating the token, you must create the payment. To do so, send the token provided by the Mercado Pago JS SDK and all the necessary data to the endpoint /v1/payments. These data include 'transaction_amount', 'installments', 'payment_method_id' (specifically 'yape'), and payer information. Alternatively, you can also make the request using one of our backend SDKs.

Details of each parameter mentioned above, as well as their respective possible values, are described in the following table.

Important

For this step, when making the request through the API or SDKs, it is necessary to send your productive private key (access_token ).

Field	Type	Description	Required/Optional	Examples/Possible values
`token`	string	Token provided by the Mercado Pago JS SDK. For more details, see the Generate Yape token section.	Required	"f8ae90c6a83e71d698d5ea927f851034"
`transaction_amount`	number	Transaction amount. There is a maximum amount limit that can be S/500, S/900, or S/2000, configured directly within the Yape application.	Required	2000
`description`	string	Product title.	Optional	"Video game"
`installments`	number	Number of installments. As it is a debit card payment, the number of installments will be 1.	Required	1
`payment_method_id`	string	`yape` for all cases.	Required	`yape`
`payer.email`	string	Payer's email.	Required	"test_user_12345@testuser.com"

          
MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");

PaymentClient client = new PaymentClient();

PaymentCreateRequest createRequest =
    PaymentCreateRequest.builder()
        .description("Titulo del producto")
        .installments(1)
        .payer(PaymentPayerRequest.builder()
            .email("test_user_123@testuser.com")
            .build())
        .paymentMethodId("yape")
        .token("ff8080814c11e237014c1ff593b57b4d")
        .transactionAmount(new BigDecimal("5000"))
        .build();

client.create(createRequest);

          
MercadoPagoConfig::setAccessToken("ENV_ACCESS_TOKEN");
    
$client = new PaymentClient();

$createRequest = [
  "description" => "Titulo del producto",
  "installments" => 1,
  "payer" => [
     "email" => "test_user_123@testuser.com",
  ],
  "payment_method_id" => "yape",
  "token" => "ff8080814c11e237014c1ff593b57b4d",
  "transaction_amount" => 5000,
];

    $client->create($createRequest, $request_options);

          
const mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken(config.access_token);

var payment = req.body;

var payment_data = {
  token: '<ff8080814c11e237014c1ff593b57b4d>',
  transaction_amount: 5000,
  installments: 1,
  description: 'Titulo del producto',
  payment_method_id: 'yape',
  payer: {
    email: payment.email,
  }
};

var payment = mercadopago.payment.save(payment_data)
  .then(function (response) {
    res.status(response.status).json({
      status: response.body.status,
      status_detail: response.body.status_detail,
      id: respose.body.id,
    });
  })
  .catch(function (error) {
    res.status(error.status).send(error);
});

var payment_link = payment.transaction_details.external_resource_url;

          
import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")

request_options = mercadopago.config.RequestOptions()
request_options.custom_headers = {
\t'x-idempotency-key': '<SOME_UNIQUE_VALUE>'
}

payment_data = {
\t"description": "Titulo del producto",
\t"installments": 1,
\t"payer": {
\t\t"email": "test_user_123@testuser.com",
\t},
\t"payment_method_id": "yape",
\t"token": "ff8080814c11e237014c1ff593b57b4d",
\t"transaction_amount": 5000
}

payment_response = sdk.payment().create(payment_data, request_options)
payment = payment_response["response"]

          
MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN

var paymentPayerRequest = new PaymentPayerRequest
{
    Email = "test_user_123@testuser.com",
};

var request = new PaymentCreateRequest
{
    Description = "Titulo del producto",
    Installments = 1,
    Payer = paymentPayerRequest,
    PaymentMethodId = "yape",
    TransactionAmount = (decimal?)5000,
    Token = "ff8080814c11e237014c1ff593b57b4d"
};

var client = new PaymentClient();
Payment payment = await client.CreateAsync(request, requestOptions);

          
require 'mercadopago'

sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')

custom_headers = {
 'x-idempotency-key': '<SOME_UNIQUE_VALUE>'
}

custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)

payment_object = {
  description: 'Titulo del producto',
  installments: 1,
  payer: {
    email: 'test_user_123@testuser.com',
  },
  payment_method_id: 'yape',
  token: 'ff8080814c11e237014c1ff593b57b4d',
  transaction_amount: 5000
}

payment_response = sdk.payment.create(payment_request, custom_request_options)
payment_response[:response]

          
package main

import (
	"context"
	"fmt"

	"github.com/mercadopago/sdk-go/pkg/config"
	"github.com/mercadopago/sdk-go/pkg/payment"
)

func main() {
	accessToken := "ENV_ACCESS_TOKEN"

	cfg, err := config.New(accessToken)
	if err != nil {
		fmt.Println(err)
		return
	}

	client := payment.NewClient(cfg)

	request := payment.Request{
		TransactionAmount: 5000,
            Description: "Titulo del producto",
		PaymentMethodID:   "yape",
		Payer: &payment.PayerRequest{
			Email: "test_user_123@testuser.com",
		},
		Token:        "ff8080814c11e237014c1ff593b57b4d",
		Installments: 1,
	}

	resource, err := client.Create(context.Background(), request)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(resource)
}

          
curl --location 'https://api.mercadopago.com/v1/payments' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-key: <IDEMPOTENCY_KEY>' \
--data-raw '{
   "token": "ff8080814c11e237014c1ff593b57b4d",
   "transaction_amount": 5000,
   "description": "Título del producto",
   "installments": 1,
   "payment_method_id": "yape",
   "payer": {
    "email": "test_user_1295925766@testuser.com"
   }
}'

Below is an example response. Please note that some information has been omitted to highlight the most relevant fields.

{
    "id": 74581527758,
    ...
    "payment_method_id": "yape",
    "payment_type_id": "debit_card",
    "payment_method": {
        "id": "yape",
        "type": "debit_card",
        "issuer_id": "12759",
        "data": {
            "routing_data": {
                "merchant_account_id": "462540702"
            }
        }
    },
    "status": "approved",
    "status_detail": "accredited",
    ...
}

Due to being a debit card transaction, possible payment statuses are approved or rejected. Additionally, the refund and cancellation policies also apply.

Note

If any error occurs while generating a payment, refer to the list of possible errors in the API Reference .

Integration test

You can use a test OTP and phone numbers to simulate different payment responses in a transaction, without needing to use real phone numbers and OTPs. This allows you to replicate the statuses mapped in payments.

To test the integration, enter the OTP and one of the phone numbers listed in the table below into the Checkout form to simulate scenarios of success and failure in implementation.

To test the integration, you must use the test credentials of your productive account. For more information, refer to the

Phone Number	OTP	Expected status in `payments`
111111111	123456	`approved`
111111112	123456	`cc_rejected_call_for_authorize`
111111113	123456	`cc_amount_rate_limit_exceeded`
111111114	123456	`cc_unsupported_unsupported`
111111115	123456	`cc_rejected_card_type_not_allowed`
111111116	123456	`cc_rejected_max_attempts`
111111117	123456	`cc_rejected_bad_filled_security_code`
111111118	123456	`cc_rejected_form_error`

The procedures to generate the Yape token and create the payment are the same: you need to provide the phone number and OTP from the table above. If you have any questions about generating the Yape token or creating the payment, refer to the Generate token and Create payment sections respectively.

Conta Mercado Pago

Permita o processamento automático de pagamentos através da carteira digital do Mercado Pago.

Outros meios de pagamento

Conheça outros meios de pagamento disponíveis para integração com Checkout Transparente.