Other payment methods - Integration configuration - Mercado Pago Developers
Which documentation are you looking for?

Do not know how to start integrating? 

Check the first steps

Other payment methods

With the Mercado Pago's Checkout API, it is also possible to offer payments with OXXO, Paycash, Citibanamex, Santander, BBVA Bancomer and Mercado Pago Card.

Important
In addition to the options available in this documentation, it is also possible to integrate other payment methods using the Payment Brick. Check Default rendering documentation of Payment for more details.

To get a detailed list of all payment methods available for integration, send a GET with your Access token to the endpoint /v1/payment_methods and run the request or, if you prefer, make the request using the SDKs below.

          
<?php
  use MercadoPago\MercadoPagoConfig;

  MercadoPagoConfig::setAccessToken("ENV_ACCESS_TOKEN");

  $client = new PaymentMethodClient();
  $payment_method = $client->get();

?>

        
          
import { MercadoPagoConfig, PaymentMethods } from 'mercadopago';

const client = new MercadoPagoConfig({ accessToken: 'access_token' });
const paymentMethods = new PaymentMethods(client);

paymentMethods.get().then((result) => console.log(result))
  .catch((error) => console.log(error));

        
          
MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");

PaymentMethodClient client = new PaymentMethodClient();
client.list();


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

payment_methods_response = sdk.payment_methods.get()
payment_methods = payment_methods_response[:response]


        
          
using MercadoPago.Client.PaymentMethod;
using MercadoPago.Config;
using MercadoPago.Resource;
using MercadoPago.Resource.PaymentMethod;

MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";

var client = new PaymentMethodClient();
ResourcesList<PaymentMethod> paymentMethods = await client.ListAsync();


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

payment_methods_response = sdk.payment_methods().list_all()
payment_methods = payment_methods_response["response"]

        
          
curl -X GET \
    -H 'accept: application/json' \
    -H 'content-type: application/json' \
    -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
    'https://api.mercadopago.com/v1/payment_methods' \

        

To offer payments with OXXO, Paycash, Citibanamex, Santander, BBVA Bancomer or Mercado Pago Card, follow the steps below.

Import MercadoPago.js

To perform the Checkout API integration, you need to capture the necessary data to process the payment.

This capture is made by including the MercadoPago.js library in your project, followed by the payment form. Use the code below to import the library before adding the payment form.

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


        
          
npm install @mercadopago/sdk-js


        

Configure credentials

Credentials are unique passwords with which we identify an integration in your account. They are made to capture payments in virtual stores and other applications securely.

This is the first step of a complete code structure that must be followed for the correct integration of the payment flow. Pay attention to the blocks below to add to the codes as indicated.

          
<script>
  const mp = new MercadoPago("YOUR_PUBLIC_KEY");
</script>

        
          
import { loadMercadoPago } from "@mercadopago/sdk-js";

await loadMercadoPago();
const mp = new window.MercadoPago("YOUR_PUBLIC_KEY");


        

Add payment form

With the MercadoPago.js library included, add the payment form below to your project to ensure the secure capture of buyer data. In this step, it is important to use the list you consulted to obtain the available payment methods to create the payment options you want to offer.

          
  <form id="form-checkout" action="/process_payment" method="post">
    <div>
      <div>
        <label for="payerFirstName">Name</label>
        <input id="form-checkout__payerFirstName" name="payerFirstName" type="text">
      </div>
      <div>
        <label for="payerLastName">Last name</label>
        <input id="form-checkout__payerLastName" name="payerLastName" type="text">
      </div>
      <div>
        <label for="email">E-mail</label>
        <input id="form-checkout__email" name="email" type="text">
      </div>
      <div>
        <label for="identificationType">Type of document</label>
        <select id="form-checkout__identificationType" name="identificationType" type="text"></select>
      </div>
      <div>
        <label for="identificationNumber">Document number</label>
        <input id="form-checkout__identificationNumber" name="identificationNumber" type="text">
      </div>
    </div>

    <div>
      <div>
        <input type="hidden" name="transactionAmount" id="transactionAmount" value="100">
        <input type="hidden" name="description" id="description" value="Nome do Produto">
        <br>
        <button type="submit">Pay</button>
      </div>
    </div>
  </form>

        

Send payment

When finalizing the inclusion of the payment form and obtaining the types of documents, it is necessary to forward the buyer's email, type and document number, the payment method used and the details of the amount to be paid using our Payments API or one of our SDKs.

Important
When executing the APIs mentioned in this documentation, you may come across the attribute X-Idempotency-Key. Filling it out is important to ensure the execution and reexecution of requests without undesirable situations, such as duplicate payments, for example.

To configure payments with OXXO, Paycash, Citibanamex, Santander, BBVA Bancomer and/or Mercado Pago Card , send a POST with the appropriate parameters to the endpoint /v1/payments and execute the request or, if you prefer, use one of our SDKs below.

Important
For this step, when making the request via API or SDKs, it is necessary to send your Private Key - Access token.
          
<?php
  use MercadoPago\Client\Payment\PaymentClient;

  $client = new PaymentClient();
  $request_options = new RequestOptions();
  $request_options->setCustomHeaders(["X-Idempotency-Key: <SOME_UNIQUE_VALUE>"]);

  $payment = $client->create([
    "transaction_amount" => (float) $_POST['<TRANSACTION_AMOUNT>'],
    "payment_method_id" => $_POST['<PAYMENT_METHOD_ID>'],
    "payer" => [
      "email" => $_POST['<EMAIL>']
    ]
  ], $request_options);
  echo implode($payment);
?>

        
          
import { MercadoPagoConfig, Payments } from 'mercadopago';

const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const payments = new Payments(client);

payments.create({
body: {
		transaction_amount: '<TRANSACTION_AMOUNT>',
		payment_method_id: '<PAYMENT_METHOD_ID>',
		payer: {
			email: '<EMAIL>'
			}
},
	requestOptions: { idempotencyKey: '<SOME_UNIQUE_VALUE>' }
})
	.then((result) => console.log(result))
	.catch((error) => console.log(error));

        
          
PaymentCreateRequest paymentCreateRequest = PaymentCreateRequest.builder()
          .transactionAmount(new BigDecimal("<TRANSACTION_AMOUNT>"))
          .paymentMethodId("<PAYMENT_METHOD_ID>")
          .payer(
              PaymentPayerRequest.builder()
                  .email("<EMAIL>").build()
          ).build();

Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("x-idempotency-key", "<SOME_UNIQUE_VALUE>");

MPRequestOptions requestOptions = MPRequestOptions.builder()
    .customHeaders(customHeaders).build();

PaymentClient client = new PaymentClient();
client.create(paymentCreateRequest, requestOptions);


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

payment_request = {
transaction_amount: 100,
description: 'Product title',
payment_method_id: 'oxxo',
payer: {
email: 'test_user_82045343@testuser.com',
}
}

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


        
          
using MercadoPago.Config;
using MercadoPago.Client.Payment;
using MercadoPago.Resource.Payment;

MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";

var request = new PaymentCreateRequest
{
TransactionAmount = 100,
Description = "Product Title",
PaymentMethodId = "oxxo",
Payer = new PaymentPayerRequest
{
Email = "test_user_82045343@testuser.com",
},
};

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


        
          
import market
sdk = Mercadopago.SDK("ENV_ACCESS_TOKEN")

payment_data = {
"transaction_amount": 100,
"description": "Product title",
"payment_method_id": "oxxo",
"payer": {
"email": "test_user_82045343@testuser.com"
}
}

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

        
          
curl --location 'https://api.mercadopago.com/v1/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ENV_ACCESS_TOKEN' \
--header 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
--data-raw '{
  "transaction_amount": 100,
  "description": "Titulo del producto",
  "payment_method_id": "oxxo",
  "payer": { "email": "test_user_12345@testuser.com" }
}'


        

The response will show the pending status until the buyer completes the payment. Also, in the response to the request, the external_resource_url parameter will return a URL that contains instructions for the buyer to make the payment. You can redirect to this same link to complete the payment flow.

json

[
{
...,
"id": 5466310457,
"status": "pending",
"status_detail": "pending_waiting_payment",
...,
"transaction_details": {
"payment_method_reference_id": "24304329",
"verification_code": "882430432923032000100001",
"net_received_amount": 0,
"total_paid_amount": 100,
"overpaid_amount": 0,
"external_resource_url": "https://www.mercadopago.com/mlm/payments/sandbox/ticket/helper?payment_id=1234&payment_method_reference_id=12345678&caller_id=1234&hash=aaaaaa-bbb-cccc-dddd-eeeeeeee",
"installment_amount": 0,
"financial_institution": "",
"payable_deferral_period": null,
}
}
]

Cancel payment

To avoid billing issues, it is important to cancel overdue payments. Also, keep in mind that it is possible to cancel only payments that are pending or in process.

If a payment expires within 30 days, the cancellation is automatic and the final status of the payment will be canceled or expired. For more information, see the Refunds and Cancellations section.

Payment locations

When completing the integration, it is important to share with buyers the information on the different places where they can make the payment. See the details of each one in the table below.

Payment methodAvailable stores
OXXOOXXO
PayCash7-Eleven
PayCashCircle K
PayCashSoriana
PayCashExtra
PayCashCalimax
PayCashSantander
BBVA BancomerPharmacies in Ahorro
BBVA BancomerLey House
BBVA BancomerBBVA Bancomer
CitibanamexChedraui
CitibanamexTelecomm
CitibanamexCitibanamex