Recursos para IA
Realizar cobranças recorrentes
Com Pagamentos Automáticos, você pode receber pagamentos sem fricção, iniciados pelo cliente (CIT — Customer-Initiated Transaction) ou pelo comerciante (MIT — Merchant-Initiated Transaction), sem que o comprador precise reinserir os dados do cartão. Com base na recorrência da cobrança, o produto oferece dois tipos de pagamento:
- Pagamentos com recorrência programada: pagamentos com periodicidade pré-estabelecida, como assinaturas e renovações automáticas.
- Pagamentos únicos com cartão salvo (Card on File): cobranças pontuais que reutilizam um cartão já registrado, sem necessidade de reinserção dos dados. Podem ser CIT, como em compras de um toque ou recompras, ou MIT, como em débitos por consumo.
Veja abaixo como realizar o processo de integração.
Para realizar a integração com Pagamentos Automáticos, você precisará obter e armazenar os dados do cartão do cliente. Ambos os fluxos a seguir servem como validação do cartão e a diferença está no método de validação utilizado:
- Validação de cartão com Zero Dollar Auth (ZDA) — valida e armazena as credenciais sem gerar cobrança real, por meio de Recorrência (CIT) ou Cobranças avulsas (CIT) utilizando o recurso de Zero Dollar Auth (ZDA).
- Validação de cartão com Primeiro pagamento — valida o cartão por meio da primeira cobrança real de uma cadeia de pagamentos, seja iniciado pelo cliente (CIT) ou iniciado pelo estabelecimento com dados migrados (MIT / CoF).
A validação com ZDA confirma e armazena as credenciais do cartão sem gerar nenhuma cobrança real. Para isso, escolha o cenário de acordo com o uso futuro do cartão:
- Recorrência (CIT): para cartões que serão usados em assinaturas com periodicidade definida.
- Cobranças avulsas (CIT): para cartões que serão usados em cobranças por evento ou demanda, sem calendário fixo.
Valida o cartão antes do início de uma assinatura, sem gerar cobrança real. Indica às bandeiras que o cartão está sendo armazenado com intenção de cobranças periódicas futuras, vinculando a validação à assinatura desde o primeiro contato.
Exemplo: uma plataforma de streaming solicita os dados do cartão para iniciar um período de avaliação gratuita de 30 dias antes da primeira cobrança mensal.
Para validar o cartão, envie um POST ao endpoint v1/paymentsAPI incluindo o header X-Card-Validation: card_validation e enviando com valor 0 o parâmetro transaction_amount.
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>' \ -H 'X-Card-Validation: card_validation' \ 'https://api.mercadopago.com/v1/payments' \ -d '{ "transaction_amount": 0, "token": "{{card_token}}", "payment_method_id": "master", "payer": { "id": "{{customer_id}}", "type": "customer" }, "point_of_interaction": { "type": "CREDENTIAL_ON_FILE", "sub_type": "recurring", "transaction_data": { "first_transaction": true, "storage": "store", "transaction_initiator": "customer", "subscription_id": "87654321" } } }'
| Parâmetro | Obrigatoriedade | Tipo e descrição | Exemplo |
X-Card-Validation | Obrigatório | Header. Identifica a requisição como uma validação Zero Dollar Auth (ZDA). | card_validation |
transaction_amount | Obrigatório | Number. Valor da transação. Deve ser 0 para não gerar cobrança efetiva no cartão. | 0 |
token | Obrigatório | String. Identificador do token do cartão. | {{card_token}} |
payment_method_id | Obrigatório | String. Identificador do meio de pagamento. | master |
payer.id | Obrigatório | String. ID do cliente no Mercado Pago. | {{customer_id}} |
payer.type | Obrigatório | String. Tipo de identificação do pagador. Deve ser customer. | customer |
point_of_interaction.type | Obrigatório | String. Classifica o tipo de Point of Interaction (POI) que será aplicado à transação. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obrigatório | String. Define a natureza da cobrança, sendo recurring para cobranças com periodicidade definida e unscheduled para cobranças por evento, sem calendário fixo. | recurring |
point_of_interaction.transaction_data.first_transaction | Obrigatório | Boolean. Indica se é o início de uma nova cadeia de cobranças do titular, sendo true para a transação inicial e false para as subsequentes. | true |
point_of_interaction.transaction_data.storage | Obrigatório | String. Estado de armazenamento das credenciais, sendo store quando o cartão está sendo capturado pela primeira vez e stored quando as credenciais já existem no sistema. | store |
point_of_interaction.transaction_data.transaction_initiator | Obrigatório | String. Identifica quem inicia a transação, sendo customer quando o titular está presente na sessão e merchant quando o estabelecimento dispara a cobrança automaticamente. | customer |
point_of_interaction.transaction_data.subscription_id | Obrigatório | String. Identificador único da assinatura. Sugerimos que seja composto pelo collector + identificador único por usuário. | 87654321 |
Valida o cartão para armazenamento sem periodicidade definida, sem gerar cobrança real. Indica às bandeiras que o cartão será usado para cobranças por evento — como pedidos sob demanda ou pedágios — sem calendário de recorrência. Não requer subscription_id.
Exemplo: um aplicativo de mobilidade solicita e valida o cartão no momento do cadastro, antes de qualquer corrida ser realizada.
Para validar o cartão, envie um POST ao endpoint v1/paymentsAPI incluindo o header X-Card-Validation: card_validation e enviando com valor 0 o parâmetro transaction_amount.
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>' \ -H 'X-Card-Validation: card_validation' \ 'https://api.mercadopago.com/v1/payments' \ -d '{ "transaction_amount": 0, "token": "{{card_token}}", "payment_method_id": "master", "payer": { "id": "{{customer_id}}", "type": "customer" }, "point_of_interaction": { "type": "CREDENTIAL_ON_FILE", "sub_type": "unscheduled", "transaction_data": { "first_transaction": true, "storage": "store", "transaction_initiator": "customer" } } }'
| Parâmetro | Obrigatoriedade | Tipo e descrição | Exemplo |
X-Card-Validation | Obrigatório | Header. Identifica a requisição como uma validação Zero Dollar Auth (ZDA). | card_validation |
transaction_amount | Obrigatório | Number. Valor da transação. Deve ser 0 para não gerar cobrança efetiva no cartão. | 0 |
token | Obrigatório | String. Identificador do token do cartão. | {{card_token}} |
payment_method_id | Obrigatório | String. Identificador do meio de pagamento. | master |
payer.id | Obrigatório | String. ID do cliente no Mercado Pago. | {{customer_id}} |
payer.type | Obrigatório | String. Tipo de identificação do pagador. Deve ser customer. | customer |
point_of_interaction.type | Obrigatório | String. Classifica o tipo de Point of Interaction (POI) que será aplicado à transação. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obrigatório | String. Define a natureza da cobrança, sendo recurring para cobranças com periodicidade definida e unscheduled para cobranças por evento, sem calendário fixo. | unscheduled |
point_of_interaction.transaction_data.first_transaction | Obrigatório | Boolean. Indica se é o início de uma nova cadeia de cobranças do titular, sendo true para a transação inicial e false para as subsequentes. | true |
point_of_interaction.transaction_data.storage | Obrigatório | String. Estado de armazenamento das credenciais, sendo store quando o cartão está sendo capturado pela primeira vez e stored quando as credenciais já existem no sistema. | store |
point_of_interaction.transaction_data.transaction_initiator | Obrigatório | String. Identifica quem inicia a transação, sendo customer quando o titular está presente na sessão e merchant quando o estabelecimento dispara a cobrança automaticamente. | customer |
Utilize um dos SDK 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("<YOUR_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: '<YOUR_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("<YOUR_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 = "<YOUR_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('<YOUR_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("<YOUR_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 <YOUR_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 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 o e-mail do cliente ao endpoint /v1/customers/searchAPI e execute a requisição ou, se preferir, utilize um dos SDK 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: '<YOUR_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 <YOUR_ACCESS_TOKEN>' \
'https://api.mercadopago.com/v1/customers/search' \
-d '{
"email": "test_user_19653727@testuser.com"
}'Tendo obtido o ID do cliente, utilize-o para localizar o cartão associado enviando um GET ao endpoint /v1/customers/{customer_id}/cardsAPI. Para mais informações, veja a seção de Salvar cartões ou a seção de renderização padrão do Brick de Card Payment..
Após garantir que o cartão é válido, crie um cliente e associe-o ao cartão validado. 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 SDK 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("<YOUR_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('<YOUR_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 = "<YOUR_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("<YOUR_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 <YOUR_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 Salvar cartões
Tendo validado o cartão e obtido os dados necessários do cliente, utilize o token do cartão gerado anteriormente e o ID do cliente associado para registrar o pagamento.
Além dos campos mínimos requeridos para a requisição (token, transaction_amount, installments, payment_method_id epayer.email), o envio do point_of_interaction.type = "CREDENTIAL_ON_FILE" (Mensageria de Pagamentos Automáticos) também é necessário para classificar corretamente cada transação recorrente junto às bandeiras e emissores, garantindo maior precisão na aprovação,
Além disso, é altamente recomendado enviar o Network Transaction ID (TID) da bandeira. Para obtê-lo, inclua o header X-Expand-Responde-Nodes: gateway.reference na requisição e o valor retornado em expanded.gateway.reference.network_transaction_id deverá ser enviado como transaction_data.network_transaction_id nas cobranças MIT subsequentes.
O
network_transaction_id é vinculado diretamente ao cartão utilizado na transação. Caso o titular troque de cartão dentro da mesma assinatura, nunca reutilize o TID gerado a partir de um pagamento realizado com o cartão anterior. Gere novamente o TID na requisição subsequente, já que cada TID corresponde exclusivamente ao cartão com o qual foi gerado.<?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: '<YOUR_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("<YOUR_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('<YOUR_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 = "<YOUR_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("<YOUR_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 -X POST \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
-H 'X-Expand-Responde-Nodes: gateway.reference' \
'https://api.mercadopago.com/v1/payments' \
-d '{
"transaction_amount": 100,
"token": "ff8080814c11e237014c1ff593b57b4d",
"installments": 1,
"payment_method_id": "master",
"payer": {
"type": "customer",
"id": "123456789-jxOV430go9fx2e"
},
"description": "pagamento de assinatura",
"notification_url": "https://seu-webhook.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": "CREDENTIAL_ON_FILE",
"sub_type": "recurring",
"transaction_data": {
"first_transaction": false,
"storage": "stored",
"transaction_initiator": "merchant",
"network_transaction_id": "n7w-c0d3-t7d",
"subscription_id": "Tu Comercio_4b4ef2f2-c5d6-4c1d-a492-070630bed20a",
"subscription_sequence": {
"number": 2,
"total": 10
},
"invoice_period": {
"period": 1,
"type": "monthly"
},
"billing_date": "2026-01-25",
"reference": {
"id": "FIRST_CIT_PAYMENT_ID"
}
}
}
}'| Parâmetro | Obrigatoriedade | Tipo e descrição | Exemplo |
transaction_amount | Obrigatório | Number. Custo do produto. | 100 |
token | Obrigatório | String. Identificador do token do cartão. O token é gerado a partir dos dados do próprio cartão, proporcionando maior segurança no processo de pagamento. | ff8080814c11e237014c1ff593b57b4d |
installments | Obrigatório | Integer. Número de parcelas selecionado. | 1 |
payment_method_id | Obrigatório | String. Indica o identificador do meio de pagamento selecionado para efetuar o pagamento. | master |
payer.type | Obrigatório | String. Tipo de identificação do pagador. Deve ser customer. | customer |
payer.id | Obrigatório | String. ID do cliente associado ao cartão. | 123456789-jxOV430go9fx2e |
point_of_interaction.type | Obrigatório | String. Classifica o tipo de Point of Interaction (POI) que será aplicado à transação. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obrigatório | String. Define a natureza da cobrança, sendo recurring para cobranças com periodicidade definida e unscheduled para cobranças por evento, sem calendário fixo. | recurring |
point_of_interaction.transaction_data.first_transaction | Obrigatório | Boolean. Indica se é o início de uma nova cadeia de cobranças. Deve ser false para cobranças subsequentes. | false |
point_of_interaction.transaction_data.storage | Obrigatório | String. Estado de armazenamento das credenciais, sendo store quando o cartão está sendo capturado pela primeira vez e stored quando as credenciais já existem no sistema. | stored |
point_of_interaction.transaction_data.transaction_initiator | Obrigatório | String. Identifica quem inicia a transação, sendo customer quando o titular está presente na sessão e merchant quando o estabelecimento dispara a cobrança automaticamente. | merchant |
point_of_interaction.transaction_data.network_transaction_id | Opcional — fortemente recomendado | String. TID da bandeira gerado na primeira transação CIT deste cartão. Nunca envie o TID de um cartão diferente. | n7w-c0d3-t7d |
point_of_interaction.transaction_data.subscription_id | Obrigatório | String. Mesmo identificador único da assinatura utilizado na transação inicial (CIT). | 87654321 |
point_of_interaction.transaction_data.subscription_sequence.number | Obrigatório | Integer. Número sequencial da cobrança atual dentro da assinatura. | 2 |
point_of_interaction.transaction_data.subscription_sequence.total | Obrigatório condicional | Integer. Indica o número total de cobranças da assinatura. Para assinaturas permanentes deve ser null. | 10 |
point_of_interaction.transaction_data.invoice_period.period | Obrigatório condicional | Integer. Indica a frequência do ciclo de cobrança. Obrigatório quando se envia invoice_period.type. | 1 |
point_of_interaction.transaction_data.invoice_period.type | Obrigatório condicional | String. Indica o tipo do período de cobrança (monthly, daily, yearly, quarterly). Obrigatório quando se envia invoice_period.period. | monthly |
point_of_interaction.transaction_data.billing_date | Obrigatório | String. Data prevista de cobrança no formato ISO 8601 (YYYY-MM-DD). | 2026-01-25 |
point_of_interaction.transaction_data.reference.id | Obrigatório | String. ID da primeira transação CIT desta assinatura. Deve ser sempre o ID daquela transação e nunca o de cobranças intermediárias. | FIRST_CIT_PAYMENT_ID |
Após o cartão estar armazenado e a primeira transação concluída, as cobranças subsequentes podem ocorrer em três situações:
- Automático pelo comerciante por calendário fixo (MIT): o estabelecimento cobra automaticamente na data acordada, sem qualquer ação do cliente — como a renovação mensal de uma assinatura.
- Automático pelo comerciante por evento (MIT): o estabelecimento cobra quando um evento de uso ocorre, sem periodicidade definida — como um débito ao passar por um pedágio.
- Compra avulsa pelo cliente (CIT): o cliente, com cartão já salvo, inicia uma compra avulsa — como um pedido de delivery ou uma corrida com um toque no app.
Envie o
Para obtê-lo a cada cobrança, inclua o header
Além disso, o
network_transaction_id sempre que disponível, visto que esse identificador corresponde ao TID gerado pela bandeira em uma transação CIT anterior do titular com o mesmo cartão e aumenta a taxa de aprovação junto às adquirentes. Para obtê-lo a cada cobrança, inclua o header
X-Expand-Responde-Nodes: gateway.reference na requisição. O valor retornado em expanded.gateway.reference.network_transaction_id deve ser enviado na próxima cobrança. Se o TID não retornar em uma cobrança intermediária, utilize o valor obtido na primeira transação CIT deste cartão. Além disso, o
network_transaction_id é vinculado diretamente ao cartão utilizado na transação. Caso o titular troque de cartão, nunca reutilize o TID gerado com o cartão anterior porque cada TID corresponde exclusivamente ao cartão com o qual foi gerado.Cobranças automáticas disparadas pelo estabelecimento conforme o calendário acordado, sem intervenção do cliente.
O campo
reference.id é obrigatório e deve conter sempre o ID retornado na primeira transação CIT desta assinatura, nunca o ID de cobranças intermediárias.Para processar cobranças automáticas subsequentes, envie um POST ao endpoint v1/payments.
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>' \ -H 'X-Expand-Responde-Nodes: gateway.reference' \ 'https://api.mercadopago.com/v1/payments' \ -d '{ "transaction_amount": 100, "token": "12346622341", "payment_method_id": "master", "payer": { "id": "123456789-jxOV430go9fx2e", "type": "customer" }, "point_of_interaction": { "type": "CREDENTIAL_ON_FILE", "sub_type": "recurring", "transaction_data": { "first_transaction": false, "storage": "stored", "transaction_initiator": "merchant", "network_transaction_id": "n7w-c0d3-t7d", "subscription_id": "87654321", "subscription_sequence": { "number": 2, "total": 12 }, "invoice_period": { "period": 1, "type": "monthly" }, "billing_date": "2026-02-25", "reference": { "id": "20792195335" } } } }'
| Parâmetro | Obrigatoriedade | Tipo e descrição | Exemplo |
transaction_amount | Obrigatório | Number. Valor da transação. | 100 |
token | Obrigatório | String. Identificador do token do cartão. | 12346622341 |
payment_method_id | Obrigatório | String. Identificador do meio de pagamento. | master |
payer.id | Obrigatório | String. ID do cliente no Mercado Pago. | 123456789-jxOV430go9fx2e |
payer.type | Obrigatório | String. Tipo de identificação do pagador. Deve ser customer. | customer |
point_of_interaction.type | Obrigatório | String. Classifica o tipo de Point of Interaction (POI) que será aplicado à transação. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obrigatório | String. Define a natureza da cobrança, sendo recurring para cobranças com periodicidade definida e unscheduled para cobranças por evento, sem calendário fixo. | recurring |
point_of_interaction.transaction_data.first_transaction | Obrigatório | Boolean. Indica se é o início de uma nova cadeia de cobranças do titular, sendo true para a transação inicial e false para as subsequentes. | false |
point_of_interaction.transaction_data.storage | Obrigatório | String. Estado de armazenamento das credenciais, sendo store quando o cartão está sendo capturado pela primeira vez e stored quando as credenciais já existem no sistema. | stored |
point_of_interaction.transaction_data.transaction_initiator | Obrigatório | String. Identifica quem inicia a transação, sendo customer quando o titular está presente na sessão e merchant quando o estabelecimento dispara a cobrança automaticamente. | merchant |
point_of_interaction.transaction_data.network_transaction_id | Opcional — fortemente recomendado | String. TID da bandeira gerado na primeira transação CIT do cartão atual. Nunca envie o TID de um cartão diferente. | n7w-c0d3-t7d |
point_of_interaction.transaction_data.subscription_id | Obrigatório | String. Mesmo identificador único da assinatura utilizado na transação inicial (CIT). | 87654321 |
point_of_interaction.transaction_data.subscription_sequence.number | Obrigatório | Integer. Número sequencial da cobrança atual dentro da assinatura. Começa em 1 e é incrementado a cada cobrança. | 2 |
point_of_interaction.transaction_data.subscription_sequence.total | Obrigatório condicional | Integer. Indica o número total de cobranças da assinatura. Para assinaturas permanentes deve ser null. Obrigatório em assinaturas com prazo definido. | 12 |
point_of_interaction.transaction_data.invoice_period.period | Obrigatório condicional | Integer. Indica a frequência do ciclo de cobrança. Obrigatório para recorrência pré-estabelecida e quando se envia invoice_period.type. | 1 |
point_of_interaction.transaction_data.invoice_period.type | Obrigatório condicional | String. Indica o tipo do período de cobrança, podendo ser monthly, daily, yearly, quarterly. Obrigatório para recorrência pré-estabelecida e quando se envia invoice_period.period. | monthly |
point_of_interaction.transaction_data.billing_date | Obrigatório | String. Data prevista de cobrança no formato ISO 8601 (YYYY-MM-DD). | 2026-02-25 |
point_of_interaction.transaction_data.reference.id | Obrigatório condicional | String. ID da primeira transação CIT desta assinatura, retornado na resposta do primeiro pagamento. Deve ser sempre o ID daquela transação e nunca o de cobranças intermediárias. Obrigatório quando first_transaction = false. | 20792195335 |
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 SDK 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. Para mais informações, veja a seção de Salvar cartões.<?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: '<YOUR_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("<YOUR_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('<YOUR_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 = "<YOUR_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("<YOUR_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 <YOUR_ACCESS_TOKEN>' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
-d '{"token": "9b2d63e00d66a8c721607214cedaecda", "issuer": {"id": "3245612"}, "payment_method_id":"debit_card"}'Ao substituir ou adicionar um novo cartão a um cliente, o
network_transaction_id gerado com o cartão anterior não deve ser reutilizado nas cobranças subsequentes. Cada TID é vinculado exclusivamente ao cartão com o qual foi gerado. Realize uma nova transação com o titular presente (CIT) para capturar um TID correspondente ao novo cartão e utilize esse valor nas próximas cobranças.