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.
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.
plain
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:
html
<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.
Generate token via MercadoPago.js
Use the mp.yape.create
method to generate a Yape token, as shown in the code below:
javascript
(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
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:
json
{
"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.
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.
json
{
"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.
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.
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.