AI resources
Create recurring charges
With Automatic Payments, you can receive frictionless payments initiated by the customer (CIT — Customer-Initiated Transaction) or by the merchant (MIT — Merchant-Initiated Transaction), without the payer needing to re-enter card data. Based on the charge recurrence model, the product offers two types of payment:
- Scheduled recurring payments: payments with a pre-established frequency, such as subscriptions and automatic renewals.
- One-time charges with a saved card (Card on File): point-in-time charges that reuse an already registered card, without requiring the customer to re-enter their data. They can be CIT, as in one-tap purchases or reorders, or MIT, as in consumption-based debits.
To integrate with Automatic Payments, you will need to obtain and store the customer's card data. To do this, you must use the First payment flow, which validates the card through the first real charge in a payment chain, whether customer-initiated (CIT) or merchant-initiated with migrated data (MIT / CoF).
Validation with First payment
This validation flow occurs after the first charge with the card in question, after which its data is stored for future transactions. The first payment of a subscription can occur in two distinct contexts:
- Customer-initiated (CIT): the customer is at checkout, enters the card data, and makes the payment at the time of enrollment. The ID returned in this transaction will be stored and used as
reference.idin all subsequent MIT charges. - Merchant-initiated with migrated data (MIT / CoF): the card was already stored on another platform and was migrated to Mercado Pago. The first charge is initiated by the merchant, without the customer needing to be present or re-enter their data.
First payment of a subscription with the cardholder present in the interface, entering card data at that moment. Credentials are captured in this transaction and the ID returned in the response must be stored and used as reference.id in all subsequent MIT charges for this subscription.
The ID returned in this response must be stored and used as
reference.id in all subsequent MIT charges. This value must not be changed throughout the charge chain.To make this first payment, send a POST to the endpoint v1/paymentsAPI.
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", "description": "Pagamento de teste", "installments": 1, "payment_method_id": "master", "payer": { "id": "123456789-jxOV430go9fx2e", "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", "subscription_sequence": { "number": 1, "total": 12 }, "invoice_period": { "period": 1, "type": "monthly" }, "billing_date": "2026-01-25" } } }'
| Parameter | Required | Type and description | Example |
transaction_amount | Required | Number. Transaction amount. | 100 |
token | Required | String. Card token identifier. | 12346622341 |
installments | Required | Integer. Number of installments. | 1 |
payment_method_id | Required | String. Payment method identifier. | master |
payer.id | Required | String. Customer ID in Mercado Pago. | 123456789-jxOV430go9fx2e |
payer.type | Required | String. Payer identification type. Must be customer. | customer |
point_of_interaction.type | Required | String. Classifies the type of Point of Interaction (POI) that will be applied to the transaction. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Required | String. Defines the nature of the charge, being recurring for charges with a defined frequency and unscheduled for event-based charges without a fixed schedule. | recurring |
point_of_interaction.transaction_data.first_transaction | Required | Boolean. Indicates whether this is the start of a new charge chain by the cardholder, being true for the initial transaction and false for subsequent ones. | true |
point_of_interaction.transaction_data.storage | Required | String. Credential storage state, being store when the card is being captured for the first time and stored when credentials already exist in the system. | store |
point_of_interaction.transaction_data.transaction_initiator | Required | String. Identifies who initiates the transaction, being customer when the cardholder is present in the session and merchant when the merchant triggers the charge automatically. | customer |
point_of_interaction.transaction_data.subscription_id | Required | String. Unique subscription identifier. We suggest it be composed of the collector + a unique identifier per user. | 87654321 |
point_of_interaction.transaction_data.subscription_sequence.number | Required | Integer. Sequential number of the charge within the subscription. Starts at 1 and is incremented with each charge. | 1 |
point_of_interaction.transaction_data.subscription_sequence.total | Required for subscriptions with a defined term | Integer. Indicates the total number of charges in the subscription. For open-ended subscriptions, must be null. | 12 |
point_of_interaction.transaction_data.invoice_period.period | Conditionally required | Integer. Indicates the frequency of the billing cycle. Required for pre-established recurrence and when invoice_period.type is sent. | 1 |
point_of_interaction.transaction_data.invoice_period.type | Conditionally required | String. Indicates the billing period type: monthly, daily, yearly, or quarterly. Required for pre-established recurrence and when invoice_period.period is sent. | monthly |
point_of_interaction.transaction_data.billing_date | Required | String. Expected billing date in ISO 8601 format (YYYY-MM-DD). | 2026-01-25 |
If the request was successful, the response will look like the following example:
json
{ "id": 20792195335, "status": "approved", "status_detail": "accredited", "transaction_amount": 100, "point_of_interaction": { "type": "CREDENTIAL_ON_FILE", "sub_type": "recurring", "transaction_data": { "first_transaction": true, "storage": "store", "transaction_initiator": "customer", "subscription_id": "87654321", "subscription_sequence": { "number": 1, "total": 12 }, "invoice_period": { "period": 1, "type": "monthly" }, "billing_date": "2026-01-25" } }, "expanded": { "gateway": { "reference": { "network_transaction_id": "n7w-c0d3-t7d" } } } }
Use the SDK below to tokenize the card using its ID (card_id). Tokenization provides a more secure digital payment experience by replacing the credit card number with an alternative number, the 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}}
}'Follow the step-by-step guide and prevent fraudulent payments with our recommendations to improve the approval of your payments.
To obtain customer data such as ID, address or registration date, you can retrieve them through our customer API. To do this, send a GET with the customer's email to the endpoint /v1/customers/searchAPI and execute the request, or if you prefer, use one of the SDKs below.
<?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"
}'Once you have the customer ID, use it to locate the associated card by sending a GET request to the /v1/customers/{customer_id}/cardsAPI endpoint. For more information, check the section Save cards or the section Default rendering in Card Payment Brick..
After ensuring that the card is valid, create a customer and associate them with the validated card. To create a customer and associate them with their card, you need to send the customer_id and the card_token. Each customer will be stored with the value customer and each card with the value card.
Additionally, we recommend storing card data whenever a payment is successfully completed. This ensures the correct data is stored for future purchases and optimizes the payment process for the buyer.
To create a customer and card, use one of the SDKs below.
<?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"}'For more information, check the section Save cards
Once you have validated the card and obtained the necessary customer data, use the previously generated card token and the associated customer ID to register the payment.
In addition to the minimum required fields for the request (token, transaction_amount, installments, payment_method_id, and payer.email), sending point_of_interaction.type = "CREDENTIAL_ON_FILE" (Automatic Payments Messaging) is also required to correctly classify each recurring transaction with card networks and card issuers, ensuring greater approval precision.
Additionally, for recurring payment operations with card networks (Visa, Mastercard, and others), it is necessary to send the network transaction identifier (Network Transaction ID - TID). To obtain it, include the header X-Expand-Responde-Nodes: gateway.reference in the request. The TID will be returned in the expanded.gateway.reference.network_transaction_id field and must be sent as transaction_data.network_transaction_id in subsequent MIT charges for that card.
The
network_transaction_id is directly linked to the card used in the transaction. If the cardholder switches cards within the same subscription, never reuse the TID generated from a payment made with the previous card. Re-generate the TID in the subsequent request, as each TID corresponds exclusively to the card with which it was generated.<?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"
}
}
}
}'| Parameter | Required | Type and description | Example |
transaction_amount | Required | Number. Product cost. | 100 |
token | Required | String. Card token identifier. The token is generated from the card data itself, providing greater security in the payment process. | ff8080814c11e237014c1ff593b57b4d |
installments | Required | Integer. Number of installments selected. | 1 |
payment_method_id | Required | String. Indicates the identifier of the payment method selected to make the payment. | master |
payer.type | Required | String. Payer identification type. Must be customer. | customer |
payer.id | Required | String. ID of the customer associated with the card. | 123456789-jxOV430go9fx2e |
point_of_interaction.type | Required | String. Classifies the type of Point of Interaction (POI). Must be CREDENTIAL_ON_FILE. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Required | String. Defines the nature of the charge. Must be recurring. | recurring |
point_of_interaction.transaction_data.first_transaction | Required | Boolean. Indicates whether this is the start of a new charge chain. Must be false for subsequent charges. | false |
point_of_interaction.transaction_data.storage | Required | String. Credential storage state. Must be stored. | stored |
point_of_interaction.transaction_data.transaction_initiator | Required | String. Identifies who initiates the transaction. Must be merchant. | merchant |
point_of_interaction.transaction_data.network_transaction_id | Optional — strongly recommended | String. Card network TID generated in the first CIT transaction for this card. Never send the TID from a different card. | n7w-c0d3-t7d |
point_of_interaction.transaction_data.subscription_id | Required | String. Same unique subscription identifier used in the initial (CIT) transaction. | 87654321 |
point_of_interaction.transaction_data.subscription_sequence.number | Required | Integer. Sequential number of the current charge within the subscription. | 2 |
point_of_interaction.transaction_data.subscription_sequence.total | Conditionally required | Integer. Indicates the total number of charges in the subscription. For open-ended subscriptions, must be null. | 10 |
point_of_interaction.transaction_data.invoice_period.period | Conditionally required | Integer. Indicates the frequency of the billing cycle. Required when invoice_period.type is sent. | 1 |
point_of_interaction.transaction_data.invoice_period.type | Conditionally required | String. Indicates the billing period type (monthly, daily, yearly, quarterly). Required when invoice_period.period is sent. | monthly |
point_of_interaction.transaction_data.billing_date | Required | String. Expected billing date in ISO 8601 format (YYYY-MM-DD). | 2026-01-25 |
point_of_interaction.transaction_data.reference.id | Required | String. ID of the first CIT transaction for this subscription. Must always be the ID from that transaction and never from intermediate charges. | FIRST_CIT_PAYMENT_ID |
After the card is stored and the first transaction is complete, subsequent charges can occur in three situations:
- Automatic merchant-initiated by fixed schedule (MIT): the merchant charges automatically on the agreed date, without any action from the customer — such as the monthly renewal of a subscription.
- Automatic merchant-initiated by event (MIT): the merchant charges when a usage event occurs, without a defined frequency — such as a debit when passing through a toll.
- One-time purchase by cardholder (CIT): the customer, with a card already saved, initiates a one-time purchase — such as a delivery order or a one-tap ride in an app.
Send the
To obtain it with each charge, include the header
Additionally, the
network_transaction_id whenever available, as this identifier corresponds to the TID generated by the card network in a previous CIT transaction by the cardholder with the same card and increases the approval rate with acquirers. To obtain it with each charge, include the header
X-Expand-Responde-Nodes: gateway.reference in the request. The value returned in expanded.gateway.reference.network_transaction_id must be sent in the next charge. If the TID is not returned in an intermediate charge, use the value obtained in the first CIT transaction for this card. Additionally, the
network_transaction_id is directly linked to the card used in the transaction. If the cardholder switches cards, never reuse the TID generated with the previous card because each TID corresponds exclusively to the card with which it was generated.Automatic charges triggered by the merchant according to the agreed schedule, without customer intervention.
The
reference.id field is required and must always contain the ID returned in the first CIT transaction for this subscription, never the ID of intermediate charges.To process subsequent automatic charges, send a POST to the 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" } } } }'
| Parameter | Required | Type and description | Example |
transaction_amount | Required | Number. Transaction amount. | 100 |
token | Required | String. Card token identifier. | 12346622341 |
payment_method_id | Required | String. Payment method identifier. | master |
payer.id | Required | String. Customer ID in Mercado Pago. | 123456789-jxOV430go9fx2e |
payer.type | Required | String. Payer identification type. Must be customer. | customer |
point_of_interaction.type | Required | String. Classifies the type of Point of Interaction (POI). Must be CREDENTIAL_ON_FILE. | CREDENTIAL_ON_FILE |
point_of_interaction.sub_type | Required | String. Defines the nature of the charge. Must be recurring. | recurring |
point_of_interaction.transaction_data.first_transaction | Required | Boolean. Indicates whether this is the start of a new charge chain. Must be false. | false |
point_of_interaction.transaction_data.storage | Required | String. Credential storage state. Must be stored. | stored |
point_of_interaction.transaction_data.transaction_initiator | Required | String. Identifies who initiates the transaction. Must be merchant. | merchant |
point_of_interaction.transaction_data.network_transaction_id | Optional — strongly recommended | String. Card network TID generated in the first CIT transaction for the current card. Never send the TID from a different card. | n7w-c0d3-t7d |
point_of_interaction.transaction_data.subscription_id | Required | String. Same unique subscription identifier used in the initial (CIT) transaction. | 87654321 |
point_of_interaction.transaction_data.subscription_sequence.number | Required | Integer. Sequential number of the current charge within the subscription. Starts at 1 and is incremented with each charge. | 2 |
point_of_interaction.transaction_data.subscription_sequence.total | Conditionally required | Integer. Indicates the total number of charges in the subscription. For open-ended subscriptions, must be null. Required for subscriptions with a defined term. | 12 |
point_of_interaction.transaction_data.invoice_period.period | Conditionally required | Integer. Indicates the frequency of the billing cycle. Required for pre-established recurrence and when invoice_period.type is sent. | 1 |
point_of_interaction.transaction_data.invoice_period.type | Conditionally required | String. Indicates the billing period type: monthly, daily, yearly, or quarterly. Required for pre-established recurrence and when invoice_period.period is sent. | monthly |
point_of_interaction.transaction_data.billing_date | Required | String. Expected billing date in ISO 8601 format (YYYY-MM-DD). | 2026-02-25 |
point_of_interaction.transaction_data.reference.id | Conditionally required | String. ID of the first CIT transaction for this subscription, returned in the response of the first payment. Must always be the ID from that transaction and never from intermediate charges. Required when first_transaction = false. | 20792195335 |
If necessary, it is possible to add new cards to a specific customer. To do this, locate the customer and define the new card details using one of the available SDK below.
If it is necessary to delete a card before adding new cards to a customer, send a DELETE to the endpoint /v1/customers/{customer_id}/cards/{id} providing the
customer_id and the id of the card you want to delete. After the successful execution of the request, you can add the new card. For more information, check the section Save cards.<?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"}'When replacing or adding a new card to a customer, the
network_transaction_id generated with the previous card must not be reused in subsequent charges. Each TID is exclusively linked to the card with which it was generated. Perform a new transaction with the cardholder present (CIT) to capture a TID corresponding to the new card and use that value in the next charges.