Suggest edit
Help us improve the documentation
Did you see wrong information and would you like us to explain something else or improve our manuals? Please leave your suggestions on GitHub.

Integrate the payment API for cards

Integrating Mercado Pago's payment API for cards allows you to offer a complete payment option within the site. The entire experience takes place in your store, so customers avoid exiting your site while making a purchase.

How does it work?

API-integration-flowchart


With our Mercado Pago payment API, you should take into account two aspects: data capture and payment confirmation submission.

  1. First, you need a frontend to collect card data and generate a security token with the information required to create a payment.
  2. Then, you need a backend that takes the generated token and payment data, such as amount and item, to confirm and make a payment.

Both for frontend and backend, we recommend our libraries to collect user sensitive data securely.

For more information, check API References.


Card data capture

Client-Side

To create a payment, you should capture card data through the buyer's browser. For security reasons, never store data in your servers.

      1. Include MercadoPago.js library

Use our official library to access Mercado Pago API from your application and collect data securely.

Html 

<script src="https://secure.mlstatic.com/sdk/javascript/v1/mercadopago.js"></script>

Card information will be turned into a token so that you can send data to your servers securely.

      2. Add payment form

To capture sensitive data from your customer's cards, please use our form with the corresponding attributes, which ensures information security and correct token generation. For example, you should observe data-checkout attributes and avoid putting the name attribute in fields containing sensitive data. This way your servers will never store data.

You can easily include anything you need, change the suggested label attribute, and add your own style.

The following example assumes that transaction_amount and description data were obtained in a previous step in which customers selected the product or service to be paid.

Html 

<form action="/procesar_pago.php" method="post" id="pay" name="pay" >
    <fieldset>
        <p>
            <label for="description">Description</label>
            <input type="text" name="description" id="description" value="Selected item"/>
        </p>
        <p>
            <label for="transaction_amount">Amount to pay</label>
            <input name="transaction_amount" id="transaction_amount" value="100"/>
        </p>
        <p>
            <label for="cardNumber">Card number</label>
            <input type="text" id="cardNumber" data-checkout="cardNumber" onselectstart="return false" onpaste="return false" onCopy="return false" onCut="return false" onDrag="return false" onDrop="return false" autocomplete=off />
        </p>
        <p>
            <label for="cardholderName">Name and surname</label>
            <input type="text" id="cardholderName" data-checkout="cardholderName" />
        </p>
        <p>
            <label for="cardExpirationMonth">Expiration month</label>
            <input type="text" id="cardExpirationMonth" data-checkout="cardExpirationMonth" onselectstart="return false" onpaste="return false" onCopy="return false" onCut="return false" onDrag="return false" onDrop="return false" autocomplete=off />
        </p>
        <p>
            <label for="cardExpirationYear">Expiration year</label>
            <input type="text" id="cardExpirationYear" data-checkout="cardExpirationYear" onselectstart="return false" onpaste="return false" onCopy="return false" onCut="return false" onDrag="return false" onDrop="return false" autocomplete=off />
        </p>
        <p>
            <label for="securityCode">Security code</label>
            <input type="text" id="securityCode" data-checkout="securityCode" onselectstart="return false" onpaste="return false" onCopy="return false" onCut="return false" onDrag="return false" onDrop="return false" autocomplete=off />
        </p>
        <p>
            <label for="installments">Installments</label>
            <select id="installments" class="form-control" name="installments"></select>
        </p>
        <p>
            <label for="docType">ID type</label>
            <select id="docType" data-checkout="docType"></select>
        </p>
        <p>
            <label for="docNumber">ID number</label>
            <input type="text" id="docNumber" data-checkout="docNumber"/>
        </p>
        <p>
            <label for="email">E-mail</label>
            <input type="email" id="email" name="email" value="test@test.com"/>
        </p>
        <input type="hidden" name="payment_method_id" id="payment_method_id"/>
        <input type="submit" value="Pay"/>
    </fieldset>
</form>

      3. Configure your public key

Add your public key like this:

Javascript 

window.Mercadopago.setPublishableKey("ENV_PUBLIC_KEY");

If you still don't have an account to check your credentials, sign in.

      4. Get data for your form

        Get document types

Document type is one of the mandatory fields. Use the document list to fill out your data.

When you call the next function, MercadoPago.js will automatically fill out the available options, including the select type element with id = docType in the form:

Javascript 

window.Mercadopago.getIdentificationTypes();

Find more information in the document type section.

        Get card payment method

Avoid mistakes and offer the correct available installments by validating your customers' data as they fill it out. Use the code in the following example to identify payment method and issuing bank with the first 6 digits of the card.

Javascript 

document.getElementById('cardNumber').addEventListener('keyup', guessPaymentMethod);
document.getElementById('cardNumber').addEventListener('change', guessPaymentMethod);

function guessPaymentMethod(event) {
    let cardnumber = document.getElementById("cardNumber").value;

    if (cardnumber.length >= 6) {
        let bin = cardnumber.substring(0,6);
        window.Mercadopago.getPaymentMethod({
            "bin": bin
        }, setPaymentMethod);
    }
};

function setPaymentMethod(status, response) {
    if (status == 200) {
        let paymentMethodId = response[0].id;
        let element = document.getElementById('payment_method_id');
        element.value = paymentMethodId;
        getInstallments();
    } else {
        alert(`payment method info error: ${response}`);
    }
}

        Get number of installments

The number of installments is also a mandatory field for credit card payments. You can use the function in the following example to fill out the select type suggested field called installments and get the available installments.

Javascript 

function getInstallments(){
    window.Mercadopago.getInstallments({
        "payment_method_id": document.getElementById('payment_method_id').value,
        "amount": parseFloat(document.getElementById('transaction_amount').value)

    }, function (status, response) {
        if (status == 200) {
            document.getElementById('installments').options.length = 0;
            response[0].payer_costs.forEach( installment => {
                let opt = document.createElement('option');
                opt.text = installment.recommended_message;
                opt.value = installment.installments;
                document.getElementById('installments').appendChild(opt);
            });
        } else {
            alert(`installments method info error: ${response}`);
        }
    });
}

      5. Create card token

Before payment submission, you should create a token containing all card information securely. You should generate it as follows:

Javascript 

doSubmit = false;
document.querySelector('#pay').addEventListener('submit', doPay);

function doPay(event){
    event.preventDefault();
    if(!doSubmit){
        var $form = document.querySelector('#pay');

        window.Mercadopago.createToken($form, sdkResponseHandler);

        return false;
    }
};

function sdkResponseHandler(status, response) {
    if (status != 200 && status != 201) {
        alert("verify filled data");
    }else{
        var form = document.querySelector('#pay');
        var card = document.createElement('input');
        card.setAttribute('name', 'token');
        card.setAttribute('type', 'hidden');
        card.setAttribute('value', response.id);
        form.appendChild(card);
        doSubmit=true;
        form.submit();
    }
};

The createToken method will return a card_token with the secure card display. The second field of the createToken method is the callback function, which will process the response (in this case, we use the sdkResponseHandler function). We will take and save the response ID in a hidden attribute called token and then send the form to your servers.

Important

Remember that the token is valid for 7 days and can be used only once.


Download Sample Form


Payment submission to Mercado Pago

Server-Side

To continue with the Mercado Pago payment process, your backend should know how to receive form information with the generated token and the filled out data.

In the above example, after the submit action, your backend should display a /process_payment endpoint, which is defined in the form action attribute, to receive all data.

Once the request –with all the collected information– is in your backend, it should be submitted to Mercado Pago through our APIs. The minimum mandatory fields to submit are: token, transaction_amount, installments, payment_method_id and payer.email.

For this to work, you should configure your private key. Also, to interact with our APIs, you should use Mercado Pago official SDK.

You can find payment status in status value.

<?php
    require_once 'vendor/autoload.php';

    MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");

    $payment = new MercadoPago\Payment();
    $payment->transaction_amount = 182;
    $payment->token = "ff8080814c11e237014c1ff593b57b4d";
    $payment->description = "Small Plastic Bottle";
    $payment->installments = 1;
    $payment->payment_method_id = "visa";
    $payment->payer = array(
    "email" => "horace.funk@hotmail.com"
    );

    $payment->save();


    echo $payment->status;

?>

You can find payment status in status value.

var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken("ENV_ACCESS_TOKEN");

var payment_data = {
  transaction_amount: 182,
  token: 'ff8080814c11e237014c1ff593b57b4d'
  description: 'Small Plastic Bottle',
  installments: 1,
  payment_method_id: 'visa',
  payer: {
    email: 'test@test.com'
  }
};

mercadopago.payment.save(payment_data).then(function (data) {
      console.log(data);
      res.send(data);
    }).catch(function (error) {
      console.log(error);
    });

You can find payment status in status value.

MercadoPago.SDK.setAccessToken("ENV_ACCESS_TOKEN");

Payment payment = new Payment();
payment.setTransactionAmount(182f)
       .setToken("ff8080814c11e237014c1ff593b57b4d")
       .setDescription("Small Plastic Bottle")
       .setInstallments(1)
       .setPaymentMethodId("visa")
       .setPayer(new Payer()
         .setEmail("test@test.com"));

payment.save();


System.out.println(payment.getStatus());

You can find payment status in status value.

require 'mercadopago'
MercadoPago::SDK.access_token = "ENV_ACCESS_TOKEN";

payment = MercadoPago::Payment.new()
payment.transaction_amount = 182
payment.token = 'ff8080814c11e237014c1ff593b57b4d'
payment.description = 'Small Plastic Bottle'
payment.installments = 1
payment.payment_method_id = "visa"
payment.payer = {
  email: "test@test.com"
}

payment.save()

You can find payment status in status value.

using MercadoPago;
using MercadoPago.DataStructures.Payment;
using MercadoPago.Resources;

MercadoPago.SDK.SetAccessToken("ENV_ACCESS_TOKEN");

Payment payment = new Payment()
{
    TransactionAmount = float.Parse("182"),
    Token = "ff8080814c11e237014c1ff593b57b4d",
    Description = "Small Plastic Bottle",
    Installments = 1,
    PaymentMethodId = "visa",
    Payer = new Payer(){
        Email = "test@test.com"
    }
};

payment.Save();


console.log(payment.Status);

You can find payment status in status value.

curl -X POST \
    -H 'accept: application/json' \
    -H 'content-type: application/json' \
    'https://api.mercadopago.com/v1/payments?access_token=ENV_ACCESS_TOKEN' \
    -d '{
          "transaction_amount": 182,
          "token": "ff8080814c11e237014c1ff593b57b4d",
          "description": "Small Plastic Bottle",
          "installments": 1,
          "payment_method_id": "visa",
          "issuer_id": 310,
          "payer": {
            "email": "test@test.com"
          }
    }'

        Response

Json 

{
    "status": "approved",
    "status_detail": "accredited",
    "id": 3055677,
    "date_approved": "2019-02-23T00:01:10.000-04:00",
    "payer": {
        ...
    },
    "payment_method_id": "visa",
    "payment_type_id": "credit_card",
    "refunds": [],
    ...
}

Check API References to learn about all the available fields for full payments.


Error Response Handling

Possible payment statuses are:

payment-status

For improved payment approval, you need to correctly inform results to your customers when making or creating a payment.

This will prevent rejections and chargebacks in the case of already approved transactions. For example, this allows you to correct data upload mistakes or change payment methods.

We recommend using error response handling and the suggested communication in each case.

Note

Avoid rejected payments with our recommendations to improve the approval process.

Receive payment notifications

Finally, you always need to be notified of new payments and status updates. For example, if they were approved, rejected, or are pending.

Configure webhook notifications or IPN notifications.

Next steps

REQUIRED

Test your integration

Check that everything works in your integration with test users.

RECOMMENDED

Integrate other payment methods

Learn about all the available payment options and how to offer them.

Your search returns no results.

Verifique a ortografia de termos de pesquisa ou teste com outras palavras-chave.