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.

Get card data and validate

To integrate with Automatic Payments, you will need to obtain and store the customer's card data. Both flows below serve as card validation and the difference lies in the validation method used:

Card validation with Zero Dollar Auth (ZDA) — validates and stores credentials without generating a real charge, through Recurring (CIT) or One-time charges (CIT) using the Zero Dollar Auth (ZDA) feature.
Card validation with First payment — 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 ZDA confirms and stores the card credentials without generating any real charge. To do this, choose the scenario according to the future use of the card:

Recurring (CIT): for cards that will be used in subscriptions with a defined frequency.
One-time charges (CIT): for cards that will be used in event-based or on-demand charges, without a fixed schedule.

Recurring (CIT)

Validates the card before the start of a subscription, without generating a real charge. It signals to card networks that the card is being stored with the intent of future periodic charges, binding the validation to the subscription from the first interaction.

Example: a streaming platform requests card data to start a 30-day free trial period before the first monthly charge.

To validate the card, send a POST to the endpoint v1/paymentsAPI including the header X-Card-Validation: card_validation and sending 0 as the transaction_amount parameter.

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"
        }
      }
    }'

Parameter	Required	Type and description	Example
`X-Card-Validation`	Required	Header. Identifies the request as a Zero Dollar Auth (ZDA) validation.	`card_validation`
`transaction_amount`	Required	Number. Transaction amount. Must be `0` to avoid generating an actual charge on the card.	`0`
`token`	Required	String. Card token identifier.	`{{card_token}}`
`payment_method_id`	Required	String. Payment method identifier.	`master`
`payer.id`	Required	String. Customer ID in Mercado Pago.	`{{customer_id}}`
`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 `true`.	`true`
`point_of_interaction.transaction_data.storage`	Required	String. Credential storage state. Must be `store` (capturing for the first time).	`store`
`point_of_interaction.transaction_data.transaction_initiator`	Required	String. Identifies who initiates the transaction. Must be `customer`.	`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`

One-time charges (CIT)

Validates the card for storage without a defined frequency, without generating a real charge. It signals to card networks that the card will be used for event-based charges — such as on-demand orders or tolls — without a recurrence schedule. Does not require subscription_id.

Example: a mobility app requests and validates the card at registration, before any ride is taken.

To validate the card, send a POST to the endpoint v1/paymentsAPI including the header X-Card-Validation: card_validation and sending 0 as the transaction_amount parameter.

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"
        }
      }
    }'

Parameter	Required	Type and description	Example
`X-Card-Validation`	Required	Header. Identifies the request as a Zero Dollar Auth (ZDA) validation.	`card_validation`
`transaction_amount`	Required	Number. Transaction amount. Must be `0` to avoid generating an actual charge on the card.	`0`
`token`	Required	String. Card token identifier.	`{{card_token}}`
`payment_method_id`	Required	String. Payment method identifier.	`master`
`payer.id`	Required	String. Customer ID in Mercado Pago.	`{{customer_id}}`
`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 `unscheduled`.	`unscheduled`
`point_of_interaction.transaction_data.first_transaction`	Required	Boolean. Indicates whether this is the start of a new charge chain. Must be `true`.	`true`
`point_of_interaction.transaction_data.storage`	Required	String. Credential storage state. Must be `store` (capturing for the first time).	`store`
`point_of_interaction.transaction_data.transaction_initiator`	Required	String. Identifies who initiates the transaction. Must be `customer`.	`customer`

Generate a card token

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_token

import 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.

Get customer data

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..

Associate card to customer

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

Process first charge with a stored card

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`

Process subsequent charges

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 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`

Update cards

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 card

MercadoPagoConfig.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.

Pré-requisitos

Veja os pré-requisitos para integrar a solução de pagamentos recorrentes sem a necessidade de utilizar o CVV.

Configurar notificações de Card Updater

Configure os alertas para manter sincronizados os dados de cartões salvos, garantindo a continuidade das cobranças.

Documentation

Starting now?

Resources

Support

Partners

Community

Create recurring charges

Navigation

Resources and Community

Mercado Pago

Country and language