Yape

Yape é um aplicativo móvel que simplifica o processo de transferências bancárias. Os usuários podem efetuar transações de maneira fácil e rápida diretamente pelo celular, após associarem seu cartão de débito MultiRed ao aplicativo.

Para realizar uma transação com o Yape, o processo inicia com a criação de um token, necessário para a etapa de criação do pagamento. Esse token pode ser gerado de duas formas: diretamente através de uma API ou utilizando o SDK JS do Mercado Pago.

Nesta documentação você encontra todas as etapas necessárias para realizar a configuração e os testes de integração com o Yape de forma completa.

Integração via SDK javascript

Com o Checkout API, é possível oferecer pagamentos via Yape utilizando o método de SDK JS para gerar um token. Para isso, é necessário enviar os campos de celular e OTP (One-time password encontrado no aplicativo Yape). Com o token, é possível criar um pagamento.

Para oferecer pagamentos com Yape, siga os seguintes passos.

Importar o MercadoPago.js

A primeira etapa do processo de integração de pagamentos com Yape é a captura dos dados de OTP (One-time password) e celular para gerar o token de pagamento. Isso é feito incluindo a biblioteca MercadoPago.js no seu projeto, seguida pelo formulário para capturar os dados necessários.

Utilize o código a seguir para importar a biblioteca MercadoPago.js antes de adicionar o formulário. Você pode importar a biblioteca via HTML ou via Bash.

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

npm install @mercadopago/sdk-js

Configurar credencial

As credenciais são chaves únicas usadas para identificar uma integração em sua conta. Elas são utilizadas para capturar pagamentos em lojas online e outras aplicações de forma segura.

Utilize o código abaixo para configurar sua credencial, substituindo o valor YOUR_PUBLIC_KEY pela sua Public key de produção disponível na aplicação criada em Suas integrações. Para mais detalhes, veja credenciais.

plain
const mp = new MercadoPago("YOUR_PUBLIC_KEY");

Adicionar formulário para captura de OTP e celular

Para gerar um token Yape, é necessário preencher o campo OTP, que representa o código gerado no aplicativo Yape, e o número de celular. Para capturar esses dados, utilize o HTML abaixo diretamente no projeto:

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>

Gerar token

Após concluir a inclusão do formulário e obter os dados necessários, gere o token de Yape usando MercadoPago.js ou via API.

Gerar token via MercadoPago.js

Utilize o método mp.yape.create para gerar um token de Yape, conforme o código abaixo.

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;
});

Gerar token via API

Uma outra maneira de gerar o token é por meio de uma API. Para isso, utilize o seguinte cURL, preenchendo os parâmetros conforme detalhado na tabela abaixo.

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"
}'

Exemplo da resposta:

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"
}

Criar pagamento

Após adicionar o formulário para captura dos dados de celular e OTP e gerar o token, você deve criar o pagamento. Para isso, envie o token fornecido pelo Mercado Pago JS SDK e todos os dados necessários para o endpoint /v1/payments. Estes dados incluem 'transaction_amount', 'installments', 'payment_method_id' (especificamente yape), e informações do pagador. Alternativamente, você também pode fazer a solicitação usando um dos nossos SDKs backend.

O detalhamento de cada um dos parâmetros citados acima, bem como seus respectivos valores possíveis, está descrito na tabela a seguir.

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_pe@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_pe@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_pe@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_pe@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_pe@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_pe@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_pe@testuser.com"
   }
}'

Exemplo da resposta. Tenha em mente que algumas informações foram omitidas para mostrar os campos mais relevantes.

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",
    ...
}

Por ser uma transação com cartão de débito, os status de pagamento possíveis são aprovado ou rejeitado. As políticas de reembolso e cancelamento também se aplicam.

Testar a integração

É possível utilizar um OTP e números de celular de teste para simular diferentes respostas de pagamento em uma transação, sem a necessidade de usar números de celular e OTPs reais. Isso permite reproduzir os status mapeados em payments.

Para testar a integração, insira o OTP e um dos números de celular listados na tabela abaixo no formulário de Checkout para simular cenários de sucesso e falha na implementação.

Os procedimentos para gerar o token de Yape e criar o pagamento são os mesmos: é necessário fornecer o número de celular e o OTP da tabela acima. Se houver dúvidas sobre como gerar o token Yape ou criar o pagamento, consulte as seções Gerar token e Criar pagamento respectivamente.