Recursos para IA
Realizar cobranças recorrentes (legacy)
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.
Siga as etapas 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 Transparente 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.
Para mais informações, siga os passos da nossa integração de pagamentos com cartão através de Checkout Transparente 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_payer@example.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 } ] } }
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.
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" => "test_payer@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: "test_payer@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("test_payer@example.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@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@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 Transparente.
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" => "test_payer@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@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@testuser.com' })
customers = customers_response[:response]var searchRequest = new SearchRequest
{
Filters = new Dictionary<string, object>
{
["email"] = "test_payer@testuser.com",
},
};
ResultsResourcesPage<Customer> results = await customerClient.SearchAsync(searchRequest);
IList<Customer> customers = results.Results;filters = {
"email": "test_payer@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_payer@example.com"
}'Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout Transparente ou a seção de renderização padrão do Brick de Card Payment.
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 Transparente.
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}}
}'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 Transparente.
Para mais informações, veja a seção de Gestão de cartões e clientes do Checkout Transparente.
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@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 Transparente ou a seção de renderização padrão do Brick de Card Payment.
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.
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 Transparente.