Recursos para IA
Realizar cobranças recorrentes
Com Pagamentos Automáticos, é possível processar pagamentos com cartões armazenados (Card on File) sem solicitar o CVV em cada transação.
Para isso, é necessário obter os dados do cliente e do cartão, incluindo o código de segurança (CVV), seja processando um pagamento ou apenas armazenando-os de forma segura. Em seguida, você deverá associar o cliente e o cartão no seu sistema.
Obter dados do cartão
Siga o passo a passo abaixo para saber como realizar este processo em ambos os fluxos: processando um primeiro pagamento, ou apenas realizando um pagamento de validação para armazenar os dados e utilizá-los para uma primeira cobrança posterior.
Caso o registro inclua o pagamento da primeira parcela, este primeiro pagamento é processado com Checkout API ou Checkout Bricks seguindo os processos de pagamento ao Mercado Pago. Para isso, seu backend deve poder receber as informações do formulário com o token gerado e os dados fornecidos.
Nota
Para mais informações, siga os passos da nossa integração de pagamentos com cartão através de Checkout API ou utilizando Checkout Bricks.
Os campos mínimos requeridos para enviar são: token, transaction_amount, installments, payment_method_id e o payer.email. Lembre-se de que quanto mais informações adicionais você enviar, maior será a probabilidade de o pagamento ser aprovado, já que a avaliação de risco terá mais dados para analisar.
curl
curl -X POST \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'X-Idempotency-Key: SOME_UNIQUE_VALUE' \ 'https://api.mercadopago.com/v1/payments' \ -d '{ "transaction_amount": 100, "token": "4cbbee6da93f85e98f51647241b0e51e", "description": "Firstpayment", "installments": 1, "payment_method_id": "master", "payer": { "email": "test_user_447545153071711713382622257553@testuser.com" }, "statement_descriptor": "Primeiro pagamento", "external_reference": "9ce0e6cb-205b-4a7b-b156-847eab8cc137", "point_of_interaction": { "type": "SUBSCRIPTIONS", "transaction_data": { "first_time_use": true, "subscription_id": "subscription-gym-1", "subscription_sequence": { "number": 1, "total": 12 }, "invoice_period": { "period": 1, "type": "monthly" }, "billing_date": "2025-11-26", "user_present": true } }, "additional_info": { "items": [ { "description": "Primeiro pagamento", "quantity": 1, "title": "título", "unit_price": 100 } ] } }
Importante
Para mais informações sobre como enviar as informações dos pagamentos recorrentes ao endpoint v1/payments com o objetivo de aumentar a taxa de aprovação para este tipo de pagamentos, acesse a documentação Mensageria de pagamentos automáticos.
- No caso de a afiliação incluir o pagamento da primeira parcela, o primeiro pagamento é processado com Checkout API ou Checkout Bricks seguindo os processos de pagamento ao Mercado Pago. Para isso, é necessário que seu backend possa receber a informação do formulário com o token gerado e os dados informados.
Nota
Para mais informações, siga os passos da nossa integração de pagamentos com cartão através do Checkout API ou utilizando o Checkout Bricks.
Para mais informações, siga os passos de nossa integração de pagamentos com cartão do Checkout API ou utilizando o Brick de Card Payment.
Associar cartão ao cliente
Após processar o primeiro pagamento e garantir que o cartão é válido, crie um cliente e associe-o ao cartão utilizado no primeiro pagamento.
Para criar um cliente e associá-lo ao seu cartão, é preciso enviar o customer_id e o card_token. Cada cliente será guardado com o valor customer e cada cartão com o valor card.
Além disso, recomendamos armazenar os dados do cartão sempre que um pagamento for concluído com sucesso. Isso permite que os dados corretos sejam armazenados para compras futuras e otimiza o processo de pagamento para o comprador.
Para criar um cliente e cartão, utilize um dos SDKs abaixo.
<?php
MercadoPagoConfig::setAccessToken("YOUR_ACCESS_TOKEN");
$client_customer = new CustomerClient();
$customer = $client_customer->create(["email" => "my.user@example.com"]);
$client = new CustomerCardClient();
$customer_card = $client->create($customer->id, ["token" => "your_card_token"]);
?>const client = new MercadoPagoConfig({ accessToken: 'YOUR_ACCESS_TOKEN' });
const customer = new Customer(client);
const body = {
email: "my.user@example.com"
};
customer.create({ body: body }).then((result) => {
const customerCard = new CustomerCard(client);
const body = {
token : result.token,
};
customerCard.create({ customerId: 'customer_id', body })
.then((result) => console.log(result));
})MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");
CustomerClient customerClient = new CustomerClient();
CustomerCardClient customerCardClient = new CustomerCardClient();
CustomerRequest customerRequest = CustomerRequest.builder()
.email("john@test.com")
.build();
Customer customer = customerClient.create(customerRequest);
CustomerCardIssuer issuer = CustomerCardIssuer.builder()
.id("3245612")
.build();
CustomerCardCreateRequest cardCreateRequest = CustomerCardCreateRequest.builder()
.token("9b2d63e00d66a8c721607214cedaecda")
.issuer(issuer)
.paymentMethodId("debit_card")
.build();
customerCardClient.create(customer.getId(), cardCreateRequest);require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')
customer_request = {
email: 'john@yourdomain.com'
}
customer_response = sdk.customer.create(customer_request)
customer = customer_response[:response]
card_request = {
token: '9b2d63e00d66a8c721607214cedaecda',
issuer_id: '3245612',
payment_method_id: 'visa'
}
card_response = sdk.card.create(customer['id'], card_request)
card = card_response[:response]MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";
var customerRequest = new CustomerRequest
{
Email = "test_payer_12345@testuser.com",
};
var customerClient = new CustomerClient();
Customer customer = await customerClient.CreateAsync(customerRequest);
var cardRequest = new CustomerCardCreateRequest
{
Token = "9b2d63e00d66a8c721607214cedaecda"
};
CustomerCard card = await customerClient.CreateCardAsync(customer.Id, cardRequest);import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")
customer_data = {
"email": "test_payer_12345@testuser.com"
}
customer_response = sdk.customer().create(customer_data)
customer = customer_response["response"]
card_data = {
"token": "9b2d63e00d66a8c721607214cedaecda",
"issuer_id": "3245612",
"payment_method_id": "visa"
}
card_response = sdk.card().create(customer["id"], card_data)
card = card_response["response"]curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
-d '{"token": "9b2d63e00d66a8c721607214cedaecda", "issuer_id": "3245612", "payment_method_id": "visa"}'Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout API.
Obter os dados do cliente
Para obter os dados do cliente como, por exemplo, ID, endereço ou data de registro, é possível obtê-los através da nossa API de clientes. Para isso, envie um GET com e-mail do cliente ao endpoint /v1/customers/search e execute a requisição ou, se preferir, utilize um dos SDKs abaixo.
<?php
MercadoPagoConfig::setAccessToken("YOUR_ACCESS_TOKEN");
$client = new CustomerClient();
$customer = $client->search(1, 0, ["email" => "my.user@example.com"]);
?>import { Customer, MercadoPagoConfig } from '@src/index';
const client = new MercadoPagoConfig({ accessToken: '<ACCESS_TOKEN>' });
const customer = new Customer(client);
customer.search({ options: { email: '<EMAIL>' } }).then(console.log).catch(console.log);CustomerClient client = new CustomerClient();
Map<String, Object> filters = new HashMap<>();
filters.put("email", "test_payer_12345@testuser.com");
MPSearchRequest searchRequest =
MPSearchRequest.builder().offset(0).limit(0).filters(filters).build();
client.search(searchRequest);customers_response = sdk.customer.search(filters: { email: 'test_payer_12345@testuser.com' })
customers = customers_response[:response]var searchRequest = new SearchRequest
{
Filters = new Dictionary<string, object>
{
["email"] = "test_payer_12345@testuser.com",
},
};
ResultsResourcesPage<Customer> results = await customerClient.SearchAsync(searchRequest);
IList<Customer> customers = results.Results;filters = {
"email": "test_payer_12345@testuser.com"
}
customers_response = sdk.customer().search(filters=filters)
customers = customers_response["response"]curl -X GET \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/search' \
-d '{
"email": "test_user_19653727@testuser.com"
}'Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout API ou a seção de renderização padrão do Brick de Card Payment.
Obter o cartão associado ao cliente
Tendo obtido o ID do cliente, utilize-o para localizar o cartão associado.
<?php
$customer_client = new CustomerClient();
$cards = $client->list("customer_id");
echo implode ($cards);
?>const client = new MercadoPagoConfig({ accessToken: 'access_token' });
const customerCard = new CustomerCard(client);
customerCard.list({ customerId: '<CUSTOMER_UD>' }).then(console.log).catch(console.log);MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");
CustomerCardClient customerCardClient = new CustomerCardClient();
MPResourceList<CustomerCard> list = customerCardClient.listAll("000000000-abcdEfghiJklM");
List<CustomerCard> customerCards = list.getResults();cards_response = sdk.card.list(customer_id)
cards = cards_response[:response]var customerClient = new CustomerClient();
ResourcesList<CustomerCard> customerCards = await customerClient.ListCardsAsync("CUSTOMER_ID");cards_response = sdk.card().list_all(customer_id)
cards = cards_response["response"]curl -X GET \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout API.
Gerar um token do cartão
Após localizar os dados do cartão associado ao cliente, utilize um dos snippets abaixo para tokenizar o cartão utilizando seu ID (card_id). A tokenização fornece uma experiência de pagamento digital mais segura substituindo o número do cartão por um número alternativo, o token.
<?php
use MercadoPago\Client\CardToken\CardTokenClient;
use MercadoPago\Exceptions\MPApiException;
use MercadoPago\MercadoPagoConfig;
require_once 'vendor/autoload.php';
MercadoPagoConfig::setAccessToken("<ACCESS_TOKEN>");
$client = new CardTokenClient();
try {
$request = [
"card_id" => "cardId"
];
$card_token = $client->create($request);
var_dump($card_token);
} catch (MPApiException $e) {
echo "Status code: " . $e->getApiResponse()->getStatusCode() . "\n";
echo "Content: ";
var_dump($e->getApiResponse()->getContent());
echo "\n";
} catch (\Exception $e) {
echo $e->getMessage();
}import { MercadoPagoConfig, CardToken } from 'mercadopago';
const client = new MercadoPagoConfig({ accessToken: '<ACCESS_TOKEN>' });
const cardToken = new CardToken(client);
const body = {
card_id : '<CARD_ID>'
};
cardToken.create({ body }).then(console.log).catch(console.log);import com.mercadopago.client.cardtoken.CardTokenClient;
import com.mercadopago.client.cardtoken.CardTokenRequest;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.resources.CardToken;
public class App {
public static void main(String[] args){
MercadoPagoConfig.setAccessToken("<ACCESS_TOKEN>");
CardTokenRequest request = CardTokenRequest.builder().cardId("<CARD_ID>").build();
CardTokenClient client = new CardTokenClient();
try {
CardToken cardToken = client.create(request);
System.out.println(cardToken);
} catch (MPApiException ex) {
System.out.printf(
"MercadoPago Error. Status: %s, Content: %s%n",
ex.getApiResponse().getStatusCode(), ex.getApiResponse().getContent());
} catch (MPException ex) {
ex.printStackTrace();
}
}
}using System;
using MercadoPago.Config;
using MercadoPago.Client.CardToken;
using MercadoPago.Resource.CardToken;
MercadoPagoConfig.AccessToken = "<ACCESS_TOKEN>";
var request = new CardTokenRequest
{
CardId = "<CARD_ID>"
};
var client = new CardTokenClient();
CardToken cardToken = await client.CreateAsync(request);
Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cardToken));require_relative '../lib/mercadopago.rb'
sdk = Mercadopago::SDK.new('<ACCESS_TOKEN>')
card_token_request = {
card_id: '<CARD_ID>'
}
card_token_response = sdk.card_token.create(card_token_request)
card_token = card_token_response[:response]
puts card_tokenimport mercadopago
sdk = mercadopago.SDK("<ACCESS_TOKEN>")
card_token_data = {
"card_id": "<CARD_ID>"
}
result = sdk.card_token().create(card_token_data)
card_token = result["response"]
print(card_token)curl --location --request POST 'https://api.mercadopago.com/v1/card_tokens' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"card_id": {{card_id}}
}'Importante
Siga o passo a passo e evite pagamentos fraudulentos com nossas recomendações para melhorar a aprovação de seus pagamentos.
Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout API.
Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout API.
Realizar a cobrança
Utilize o token gerado anteriormente para registrar o pagamento, indicando o ID do cliente associado ao cartão.
<?php
use MercadoPago\Client\Payment\PaymentClient;
MercadoPagoConfig::setAccessToken("YOUR_ACCESS_TOKEN");
$customer_client = new CustomerClient();
$cards = $client->list("customer_id");
$client = new PaymentClient();
$request_options = new RequestOptions();
$request_options->setCustomHeaders(["X-Idempotency-Key: <SOME_UNIQUE_VALUE>"]);
$payment = $client->create([
"transaction_amount" => 100.0,
"token" => $cards[0]-> token,
"description" => "My product",
"installments" => 1,
"payment_method_id" => "visa",
"issuer_id" => "123",
"payer" => [
"type" => "customer",
"id" => "1234"
]
], $request_options);
echo implode($payment);
?>const client = new MercadoPagoConfig({ accessToken: 'access_token' });
const customerClient = new Customer(client);
customerClient.listCards({ customerId: '<CUSTOMER_ID>' })
.then((result) => {
const payment = new Payment(client);
const body = {
transaction_amount: 100,
token: result[0].token,
description: 'My product',
installments: 1,
payment_method_id: 'visa',
issuer_id: 123,
payer: {
type: 'customer',
id: '123'
}
};
payment.create({ body: body }).then((result) => console.log(result));
});MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");
PaymentClient client = new PaymentClient();
PaymentCreateRequest request = PaymentCreateRequest.builder()
.transactionAmount(new BigDecimal("100"))
.installments(1)
.token("ff8080814c11e237014c1ff593b57b4d")
.payer(PaymentPayerRequest.builder()
.type("customer")
.id("247711297-jxOV430go9fx2e")
.build())
.build();
client.create(request);require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')
payment_request = {
token: 'ff8080814c11e237014c1ff593b57b4d',
installments: 1,
transaction_amount: 100,
payer: {
type: 'customer',
id: '123456789-jxOV430go9fx2e'
}
}
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,
Token = "ff8080814c11e237014c1ff593b57b4d",
Installments = 1,
Payer = new PaymentPayerRequest
{
Type = "customer",
Email = "test_payer_12345@testuser.com",
},
};
var client = new PaymentClient();
Payment payment = await client.CreateAsync(request);import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")
payment_data = {
"transaction_amount": 100,
"token": 'ff8080814c11e237014c1ff593b57b4d',
"installments": 1,
"payer": {
"type": "customer",
"id": "123456789-jxOV430go9fx2e"
}
}
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' \
--data '
{
"transaction_amount": 100,
"token": "ff8080814c11e237014c1ff593b57b4d",
"installments": 1,
"payer": {
"type": "customer",
"id": "123456789-jxOV430go9fx2e"
},
"description": "pagamento de assinatura",
"notification_url": "https://tu-webhoock.com",
"statement_descriptor": "Sua loja",
"external_reference": "49646973",
"additional_info": {
"items": [
{
"id": "FT9200101024",
"title": "seu produto",
"quantity": 1,
"unit_price": 100
}
],
"payer": {
"phone": {
"area_code": "54",
"number": "1234567"
},
"first_name": "MARTINEZ",
"last_name": "GODOY",
"address": {
"zip_code": "2804",
"street_name": "Mendoza",
"street_number": "125"
},
"registration_date": null
}
},
"point_of_interaction": {
"type": "SUBSCRIPTIONS",
"transaction_data": {
"subscription_id": "Tu Comercio_4b4ef2f2-c5d6-4c1d-a492-070630bed20a",
"subscription_sequence": {
"number": 2,
"total":10
},
"invoice_period": {
"period": 1,
"type": "monthly"
},
"billing_date": "2025-09-16"
}
}
}'Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout API ou a seção de renderização padrão do Brick de Card Payment.
Atualizar cartões
Caso necessário, é possível adicionar novos cartões a um determinado cliente. Para isso, busque o cliente e defina os novos dados de cartão utilizando um dos códigos disponíveis abaixo.
Importante
Caso seja necessário excluir um cartão antes de adicionar novos cartões a um cliente, envie um DELETE ao endpoint /v1/customers/{customer_id}/cards/{id} fornecendo o
customer_id e o id do cartão que deseja excluir. Após a execução bem-sucedida da requisição, você poderá adicionar o novo cartão.<?php
MercadoPagoConfig::setAccessToken("YOUR_ACCESS_TOKEN");
$customer_client = new CustomerClient();
$customer = $customer_client->get("1234");
$card_client = new CustomerCardClient();
$customer_card = $client->create($customer->id, [
"token" => "your_card_token",
"issuer_id" => "2345",
"payment_method_id" => "debit_card"
]);
echo implode($customer_card);
?>const client = new MercadoPagoConfig({ accessToken: 'access_token' });
const customerClient = new Customer(client);
const customer = customerClient.get({ customerId: '<CUSTOMER_ID>' })
.then((result) => {
const cardClient = new CustomerCard(client);
const body = {
token : result.token,
issuer_id: '2345',
payment_method: 'debit_card'
};
cardClient.create({ customerId: customer, body: body })
.then(console.log).catch(console.log);
});MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");
CustomerClient customerClient = new CustomerClient();
CustomerCardClient customerCardClient = new CustomerCardClient();
Customer customer = customerClient.get("247711297-jxOV430go9fx2e");
CustomerCardIssuer issuer = CustomerCardIssuer.builder()
.id("3245612")
.build();
CustomerCardCreateRequest cardCreateRequest = CustomerCardCreateRequest.builder()
.token("9b2d63e00d66a8c721607214cedaecda")
.issuer(issuer)
.paymentMethodId("debit_card")
.build();
customerCardClient.create(customer.getId(), cardCreateRequest);require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')
customer_response = sdk.customer.get('247711297-jxOV430go9fx2e')
customer = customer_response[:response]
card_request = {
token: '9b2d63e00d66a8c721607214cedaecda',
issuer_id: '3245612',
payment_method_id: 'debit_card'
}
card_response = sdk.card.create(customer['id'], card_request)
card = card_response[:response]
puts cardMercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";
var customerClient = new CustomerClient();
Customer customer = await customerClient.GetAsync("247711297-jxOV430go9fx2e");
var cardRequest = new CustomerCardCreateRequest
{
Token = "9b2d63e00d66a8c721607214cedaecda",
};
CustomerCard card = await customerClient.CreateCardAsync(customer.Id, cardRequest);
Console.WriteLine(card.Id);import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")
customer_response = sdk.customer().get("247711297-jxOV430go9fx2e")
customer = customer_response["response"]
card_data = {
"token": "9b2d63e00d66a8c721607214cedaecda",
"issuer_id": "3245612",
"payment_method_id": "debit_card"
}
card_response = sdk.card().create(customer["id"], card_data)
card = card_response["response"]
print(card)curl -X GET \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
-d '{"token": "9b2d63e00d66a8c721607214cedaecda", "issuer": {"id": "3245612"}, "payment_method_id":"debit_card"}'Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout API.