Recursos para IA
Realizar cobros recurrentes
Con Pagos Automáticos, puedes recibir pagos sin fricción, iniciados por el cliente (CIT — Customer-Initiated Transaction) o por el comercio (MIT — Merchant-Initiated Transaction), sin que el comprador necesite reingresar los datos de la tarjeta. Según la recurrencia del cobro, el producto ofrece dos tipos de pago:
- Pagos con recurrencia programada: pagos con periodicidad preestablecida, como suscripciones y renovaciones automáticas.
- Pagos únicos con tarjeta guardada (Card on File): cobros puntuales que reutilizan una tarjeta ya registrada, sin necesidad de reingresar los datos. Pueden ser CIT, como en compras de un toque o recompras, o MIT, como en débitos por consumo.
Para realizar la integración con Pagos Automáticos, necesitarás obtener y almacenar los datos de la tarjeta del cliente. Ambos flujos a continuación sirven como validación de la tarjeta y la diferencia está en el método de validación utilizado:
- Validación de tarjeta con Zero Dollar Auth (ZDA) — valida y almacena las credenciales sin generar cobro real, a través de Recurrencia (CIT) o Cobros por evento (CIT) utilizando el recurso de Zero Dollar Auth (ZDA).
- Validación de tarjeta con Primer pago — valida la tarjeta mediante el primer cobro real de una cadena de pagos, siendo iniciado por el cliente (CIT) o iniciado por el comercio con datos migrados (MIT / CoF).
La validación con ZDA confirma y almacena las credenciales de la tarjeta sin generar ningún cobro real. Para ello, elige el escenario de acuerdo con el uso futuro de la tarjeta:
- Recurrencia (CIT): para tarjetas que se usarán en suscripciones con periodicidad definida.
- Cobros por evento (CIT): para tarjetas que se usarán en cobros por evento o demanda, sin calendario fijo.
Valida la tarjeta antes del inicio de una suscripción, sin generar cobro real. Indica a las redes de tarjetas que la tarjeta está siendo almacenada con intención de cobros periódicos futuros, vinculando la validación a la suscripción desde el primer contacto.
Ejemplo: una plataforma de streaming solicita los datos de la tarjeta para iniciar un período de evaluación gratuita de 30 días antes del primer cobro mensual.
Para validar la tarjeta, envía un POST al endpoint v1/paymentsAPI incluyendo el header X-Card-Validation: card_validation y enviando con valor 0 el 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 | Obligatoriedad | Tipo y descripción | Ejemplo |
X-Card-Validation | Obligatorio | Header. Identifica la solicitud como una validación Zero Dollar Auth (ZDA). | card_validation |
transaction_amount | Obligatorio | Number. Valor de la transacción. Debe ser 0 para no generar cobro efectivo en la tarjeta. | 0 |
token | Obligatorio | String. Identificador del token de la tarjeta. | {{card_token}} |
payment_method_id | Obligatorio | String. Identificador del medio de pago. | master |
payer.id | Obligatorio | String. ID del cliente en Mercado Pago. | {{customer_id}} |
payer.type | Obligatorio | String. Tipo de identificación del pagador. Debe ser customer. | customer |
point_of_interaction.type | Obligatorio | String. Clasifica el tipo de Point of Interaction (POI). Debe ser CREDENTIAL_ON_FILE. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obligatorio | String. Define la naturaleza del cobro. Debe ser recurring. | recurring |
point_of_interaction.transaction_data.first_transaction | Obligatorio | Boolean. Indica si es el inicio de una nueva cadena de cobros. Debe ser true. | true |
point_of_interaction.transaction_data.storage | Obligatorio | String. Estado de almacenamiento de las credenciales. Debe ser store (capturando por primera vez). | store |
point_of_interaction.transaction_data.transaction_initiator | Obligatorio | String. Identifica quién inicia la transacción. Debe ser customer. | customer |
point_of_interaction.transaction_data.subscription_id | Obligatorio | String. Identificador único de la suscripción. Sugerimos que esté compuesto por el collector + identificador único por usuario. | 87654321 |
Valida la tarjeta para almacenamiento sin periodicidad definida, sin generar cobro real. Indica a las redes de tarjetas que la tarjeta se usará para cobros por evento — como pedidos bajo demanda o peajes — sin calendario de recurrencia. No requiere subscription_id.
Ejemplo: una aplicación de movilidad solicita y valida la tarjeta en el momento del registro, antes de que se realice cualquier viaje.
Para validar la tarjeta, envía un POST al endpoint v1/paymentsAPI incluyendo el header X-Card-Validation: card_validation y enviando con valor 0 el 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 | Obligatoriedad | Tipo y descripción | Ejemplo |
X-Card-Validation | Obligatorio | Header. Identifica la solicitud como una validación Zero Dollar Auth (ZDA). | card_validation |
transaction_amount | Obligatorio | Number. Valor de la transacción. Debe ser 0 para no generar cobro efectivo en la tarjeta. | 0 |
token | Obligatorio | String. Identificador del token de la tarjeta. | {{card_token}} |
payment_method_id | Obligatorio | String. Identificador del medio de pago. | master |
payer.id | Obligatorio | String. ID del cliente en Mercado Pago. | {{customer_id}} |
payer.type | Obligatorio | String. Tipo de identificación del pagador. Debe ser customer. | customer |
point_of_interaction.type | Obligatorio | String. Clasifica el tipo de Point of Interaction (POI). Debe ser CREDENTIAL_ON_FILE. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obligatorio | String. Define la naturaleza del cobro. Debe ser unscheduled. | unscheduled |
point_of_interaction.transaction_data.first_transaction | Obligatorio | Boolean. Indica si es el inicio de una nueva cadena de cobros. Debe ser true. | true |
point_of_interaction.transaction_data.storage | Obligatorio | String. Estado de almacenamiento de las credenciales. Debe ser store (capturando por primera vez). | store |
point_of_interaction.transaction_data.transaction_initiator | Obligatorio | String. Identifica quién inicia la transacción. Debe ser customer. | customer |
Utiliza uno de los SDK a continuación para tokenizar la tarjeta utilizando su ID (card_id). La tokenización proporciona una experiencia de pago digital más segura al reemplazar el número de la tarjeta por un número alternativo, el 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}}
}'Sigue el paso a paso y evita pagos fraudulentos con nuestras recomendaciones para mejorar la aprobación de tus pagos.
Puedes obtener los datos del cliente como el ID, la dirección o la fecha de registro, a través de nuestra API de clientes. Para ello, envía un GET con el correo electrónico del cliente al endpoint /v1/customers/searchAPI y realiza la solicitud, o si lo prefieres, utiliza uno de los siguientes SDK.
<?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"
}'Una vez obtenido el ID del cliente, utilízalo para localizar la tarjeta asociada enviando un GET al endpoint /v1/customers/{customer_id}/cardsAPI. Para más información, consulta la sección de Guardar tarjetas o la sección de renderizado por defecto del Brick de Card Payment..
Después de verificar que la tarjeta es válida, crea un cliente y asígnale la tarjeta validada. Para crear un cliente y asociarlo con su tarjeta, debes enviar el customer_id y el card_token. Cada cliente se almacenará con el valor customer y cada tarjeta con el valor card.
Además, recomendamos almacenar los datos de la tarjeta siempre que se complete con éxito un pago. Esto permite que se guarden los datos correctos para compras futuras y optimiza el proceso de pago para el comprador.
Para crear un cliente y una tarjeta, utiliza uno de los siguientes SDK.
<?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 obtener más información, consulta la sección de Guardar tarjetas
Tras validar la tarjeta y obtener los datos necesarios del cliente, utiliza el token de la tarjeta generado anteriormente y el ID del cliente asociado para registrar el pago.
Además de los campos mínimos requeridos para la solicitud (token, transaction_amount, installments, payment_method_id y payer.email), el envío de point_of_interaction.type = "CREDENTIAL_ON_FILE" (Mensajería de Pagos Automáticos) también es necesario para clasificar correctamente cada transacción recurrente ante las redes de tarjetas y los emisores, garantizando mayor precisión en la aprobación.
Además, para operaciones con pagos recurrentes de las redes de tarjetas (Visa, Mastercard, entre otras), es necesario enviar el identificador de transacción de la red de tarjetas (Network Transaction ID - TID). Para obtenerlo, incluye el header X-Expand-Responde-Nodes: gateway.reference en la solicitud. El TID se retornará en el campo expanded.gateway.reference.network_transaction_id y deberá enviarse como transaction_data.network_transaction_id en los cobros MIT subsecuentes de esta tarjeta.
El
network_transaction_id está vinculado directamente a la tarjeta utilizada en la transacción. Si el titular cambia de tarjeta dentro de la misma suscripción, nunca reutilices el TID generado a partir de un pago realizado con la tarjeta anterior. Genera nuevamente el TID en la solicitud subsecuente, ya que cada TID corresponde exclusivamente a la tarjeta con la que fue generado.<?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 | Obligatoriedad | Tipo y descripción | Ejemplo |
transaction_amount | Obligatorio | Number. Costo del producto. | 100 |
token | Obligatorio | String. Identificador del token de la tarjeta. El token se genera a partir de los datos de la propia tarjeta, proporcionando mayor seguridad en el proceso de pago. | ff8080814c11e237014c1ff593b57b4d |
installments | Obligatorio | Integer. Número de cuotas seleccionado. | 1 |
payment_method_id | Obligatorio | String. Indica el identificador del medio de pago seleccionado para efectuar el pago. | master |
payer.type | Obligatorio | String. Tipo de identificación del pagador. Debe ser customer. | customer |
payer.id | Obligatorio | String. ID del cliente asociado a la tarjeta. | 123456789-jxOV430go9fx2e |
point_of_interaction.type | Obligatorio | String. Clasifica el tipo de Point of Interaction (POI). Debe ser CREDENTIAL_ON_FILE. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obligatorio | String. Define la naturaleza del cobro. Debe ser recurring. | recurring |
point_of_interaction.transaction_data.first_transaction | Obligatorio | Boolean. Indica si es el inicio de una nueva cadena de cobros. Debe ser false para cobros subsecuentes. | false |
point_of_interaction.transaction_data.storage | Obligatorio | String. Estado de almacenamiento de las credenciales. Debe ser stored. | stored |
point_of_interaction.transaction_data.transaction_initiator | Obligatorio | String. Identifica quién inicia la transacción. Debe ser merchant. | merchant |
point_of_interaction.transaction_data.network_transaction_id | Opcional — fuertemente recomendado | String. TID de la red de tarjetas generado en la primera transacción CIT de esta tarjeta. Nunca envíes el TID de una tarjeta diferente. | n7w-c0d3-t7d |
point_of_interaction.transaction_data.subscription_id | Obligatorio | String. Mismo identificador único de la suscripción utilizado en la transacción inicial (CIT). | 87654321 |
point_of_interaction.transaction_data.subscription_sequence.number | Obligatorio | Integer. Número secuencial del cobro actual dentro de la suscripción. | 2 |
point_of_interaction.transaction_data.subscription_sequence.total | Obligatorio condicional | Integer. Indica el número total de cobros de la suscripción. Para suscripciones permanentes debe ser null. | 10 |
point_of_interaction.transaction_data.invoice_period.period | Obligatorio condicional | Integer. Indica la frecuencia del ciclo de cobro. Obligatorio cuando se envía invoice_period.type. | 1 |
point_of_interaction.transaction_data.invoice_period.type | Obligatorio condicional | String. Indica el tipo del período de cobro (monthly, daily, yearly, quarterly). Obligatorio cuando se envía invoice_period.period. | monthly |
point_of_interaction.transaction_data.billing_date | Obligatorio | String. Fecha prevista de cobro en formato ISO 8601 (YYYY-MM-DD). | 2026-01-25 |
point_of_interaction.transaction_data.reference.id | Obligatorio | String. ID de la primera transacción CIT de esta suscripción. Debe ser siempre el ID de aquella transacción y nunca el de cobros intermedios. | FIRST_CIT_PAYMENT_ID |
Tras almacenar la tarjeta y completar la primera transacción, los cobros subsecuentes pueden ocurrir en tres situaciones:
- Automático por el comercio por calendario fijo (MIT): el comercio cobra automáticamente en la fecha acordada, sin ninguna acción del cliente — como la renovación mensual de una suscripción.
- Automático por el comercio por evento (MIT): el comercio cobra cuando ocurre un evento de uso, sin periodicidad definida — como un débito al pasar por un peaje.
- Compra puntual por el cliente (CIT): el cliente, con tarjeta ya guardada, inicia una compra puntual — como un pedido de delivery o un viaje con un toque en la app.
Envía el
Para obtenerlo en cada cobro, incluye el header
Además, el
network_transaction_id siempre que esté disponible, ya que este identificador corresponde al TID generado por la red de tarjetas en una transacción CIT anterior del titular con la misma tarjeta y aumenta la tasa de aprobación con los adquirentes. Para obtenerlo en cada cobro, incluye el header
X-Expand-Responde-Nodes: gateway.reference en la solicitud. El valor retornado en expanded.gateway.reference.network_transaction_id debe enviarse en el próximo cobro. Si el TID no se retorna en un cobro intermedio, utiliza el valor obtenido en la primera transacción CIT de esta tarjeta. Además, el
network_transaction_id está vinculado directamente a la tarjeta utilizada en la transacción. Si el titular cambia de tarjeta, nunca reutilices el TID generado con la tarjeta anterior porque cada TID corresponde exclusivamente a la tarjeta con la que fue generado.Cobros automáticos disparados por el comercio conforme al calendario acordado, sin intervención del cliente.
El campo
reference.id es obligatorio y debe contener siempre el ID retornado en la primera transacción CIT de esta suscripción, nunca el ID de cobros intermedios.Para procesar cobros automáticos subsecuentes, envía un POST al 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 | Obligatoriedad | Tipo y descripción | Ejemplo |
transaction_amount | Obligatorio | Number. Monto de la transacción. | 100 |
token | Obligatorio | String. Identificador del token de la tarjeta. | 12346622341 |
payment_method_id | Obligatorio | String. Identificador del medio de pago. | master |
payer.id | Obligatorio | String. ID del cliente en Mercado Pago. | 123456789-jxOV430go9fx2e |
payer.type | Obligatorio | String. Tipo de identificación del pagador. Debe ser customer. | customer |
point_of_interaction.type | Obligatorio | String. Clasifica el tipo de Point of Interaction (POI). Debe ser CREDENTIAL_ON_FILE. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Obligatorio | String. Define la naturaleza del cobro. Debe ser recurring. | recurring |
point_of_interaction.transaction_data.first_transaction | Obligatorio | Boolean. Indica si es el inicio de una nueva cadena de cobros. Debe ser false. | false |
point_of_interaction.transaction_data.storage | Obligatorio | String. Estado de almacenamiento de las credenciales. Debe ser stored. | stored |
point_of_interaction.transaction_data.transaction_initiator | Obligatorio | String. Identifica quién inicia la transacción. Debe ser merchant. | merchant |
point_of_interaction.transaction_data.network_transaction_id | Opcional — fuertemente recomendado | String. TID de la red de tarjetas generado en la primera transacción CIT de la tarjeta actual. Nunca envíes el TID de una tarjeta diferente. | n7w-c0d3-t7d |
point_of_interaction.transaction_data.subscription_id | Obligatorio | String. Mismo identificador único de la suscripción utilizado en la transacción inicial (CIT). | 87654321 |
point_of_interaction.transaction_data.subscription_sequence.number | Obligatorio | Integer. Número secuencial del cobro actual dentro de la suscripción. Comienza en 1 y se incrementa en cada cobro. | 2 |
point_of_interaction.transaction_data.subscription_sequence.total | Obligatorio condicional | Integer. Indica el número total de cobros de la suscripción. Para suscripciones permanentes debe ser null. Obligatorio en suscripciones con plazo definido. | 12 |
point_of_interaction.transaction_data.invoice_period.period | Obligatorio condicional | Integer. Indica la frecuencia del ciclo de cobro. Obligatorio para recurrencia preestablecida y cuando se envía invoice_period.type. | 1 |
point_of_interaction.transaction_data.invoice_period.type | Obligatorio condicional | String. Indica el tipo del período de cobro, pudiendo ser monthly, daily, yearly, quarterly. Obligatorio para recurrencia preestablecida y cuando se envía invoice_period.period. | monthly |
point_of_interaction.transaction_data.billing_date | Obligatorio | String. Fecha prevista de cobro en formato ISO 8601 (YYYY-MM-DD). | 2026-02-25 |
point_of_interaction.transaction_data.reference.id | Obligatorio condicional | String. ID de la primera transacción CIT de esta suscripción, retornado en la respuesta del primer pago. Debe ser siempre el ID de aquella transacción y nunca el de cobros intermedios. Obligatorio cuando first_transaction = false. | 20792195335 |
En caso de necesitarlo, es posible agregar nuevas tarjetas a un cliente específico. Para ello, busca al cliente y establece los nuevos datos de la tarjeta utilizando uno de los SDK disponibles a continuación.
Si necesitas eliminar una tarjeta antes de agregar nuevas tarjetas a un cliente, envía una solicitud DELETE al endpoint /v1/customers/{customer_id}/cards/{id} proporcionando el
customer_id y el id de la tarjeta que deseas eliminar. Después de que la solicitud se ejecute con éxito, podrás agregar la nueva tarjeta. Para obtener más información, consulta la sección de Guardar tarjetas.<?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"}'Al reemplazar o agregar una nueva tarjeta a un cliente, el
network_transaction_id generado con la tarjeta anterior no debe reutilizarse en los cobros subsecuentes. Cada TID está vinculado exclusivamente a la tarjeta con la que fue generado. Realiza una nueva transacción con el titular presente (CIT) para capturar un TID correspondiente a la nueva tarjeta y utiliza ese valor en los próximos cobros.