Recursos para IA

Realizar cobranças recorrentes

Com Pagamentos Automáticos, você pode receber pagamentos sem fricção, iniciados pelo cliente (CIT — Customer-Initiated Transaction) ou pelo comerciante (MIT — Merchant-Initiated Transaction), sem que o comprador precise reinserir os dados do cartão. Com base na recorrência da cobrança, o produto oferece dois tipos de pagamento:

Pagamentos com recorrência programada: pagamentos com periodicidade pré-estabelecida, como assinaturas e renovações automáticas.
Pagamentos únicos com cartão salvo (Card on File): cobranças pontuais que reutilizam um cartão já registrado, sem necessidade de reinserção dos dados. Podem ser CIT, como em compras de um toque ou recompras, ou MIT, como em débitos por consumo.

Veja abaixo como realizar o processo de integração.

Obter dados e validar cartão

Para realizar a integração com Pagamentos Automáticos, você precisará obter e armazenar os dados do cartão do cliente. Para isso você deverá utilizar o fluxo do Primeiro pagamento, onde se valida o cartão por meio da primeira cobrança real de uma cadeia de pagamentos, seja iniciado pelo cliente (CIT) ou iniciado pelo estabelecimento com dados migrados (MIT / CoF).

Validação com Primeiro pagamento

Esse fluxo de validação ocorre após a realização de uma primeira cobrança com o cartão em questão, onde a partir disso os seus dados serão armazenados para futuras transações. O primeiro pagamento de uma assinatura pode ocorrer em dois contextos distintos:

Iniciado pelo cliente (CIT): o cliente está no checkout, insere os dados do cartão e realiza o pagamento no ato da contratação. O ID retornado nessa transação será armazenado e ele será usado como reference.id em todas as cobranças MIT subsequentes.
Iniciado pelo estabelecimento com dados migrados (MIT / CoF): o cartão já estava armazenado em outra plataforma e foi migrado para o Mercado Pago. A primeira cobrança é iniciada pelo estabelecimento, sem que o cliente precise estar presente ou reinserir seus dados.

Primeiro pagamento de uma assinatura com o titular do cartão presente na interface, inserindo os dados do cartão naquele momento. As credenciais são capturadas nesta transação e o ID retornado na resposta deve ser armazenado e utilizado como reference.id em todas as cobranças MIT subsequentes desta assinatura.

O ID retornado nesta resposta deve ser armazenado e utilizado como reference.id em todas as cobranças MIT subsequentes. Este valor não deve ser alterado ao longo da cadeia de cobranças.

Para esse primeiro pagamento, envie um POST ao 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"
        }
      }
    }'

Parâmetro	Obrigatoriedade	Tipo e descrição	Exemplo
`transaction_amount`	Obrigatório	Number. Valor da transação.	`100`
`token`	Obrigatório	String. Identificador do token do cartão.	`12346622341`
`installments`	Obrigatório	Integer. Número de parcelas selecionado.	`1`
`payment_method_id`	Obrigatório	String. Identificador do meio de pagamento.	`master`
`payer.id`	Obrigatório	String. ID do cliente no Mercado Pago.	`123456789-jxOV430go9fx2e`
`payer.type`	Obrigatório	String. Tipo de identificação do pagador. Deve ser `customer`.	`customer`
`point_of_interaction.type`	Obrigatório	String. Classifica o tipo de Point of Interaction (POI) que será aplicado à transação.	`CREDENTIAL_ON_FILE`
`point_of_interaction.sub_type`	Obrigatório	String. Define a natureza da cobrança, sendo `recurring` para cobranças com periodicidade definida e `unscheduled` para cobranças por evento, sem calendário fixo.	`recurring`
`point_of_interaction.transaction_data.first_transaction`	Obrigatório	Boolean. Indica se é o início de uma nova cadeia de cobranças do titular, sendo `true` para a transação inicial e `false` para as subsequentes.	`true`
`point_of_interaction.transaction_data.storage`	Obrigatório	String. Estado de armazenamento das credenciais, sendo `store` quando o cartão está sendo capturado pela primeira vez e `stored` quando as credenciais já existem no sistema.	`store`
`point_of_interaction.transaction_data.transaction_initiator`	Obrigatório	String. Identifica quem inicia a transação, sendo `customer` quando o titular está presente na sessão e `merchant` quando o estabelecimento dispara a cobrança automaticamente.	`customer`
`point_of_interaction.transaction_data.subscription_id`	Obrigatório	String. Identificador único da assinatura. Sugerimos que seja composto pelo `collector` + identificador único por usuário.	`87654321`
`point_of_interaction.transaction_data.subscription_sequence.number`	Obrigatório	Integer. Número sequencial da cobrança dentro da assinatura. Começa em `1` e é incrementado a cada cobrança.	`1`
`point_of_interaction.transaction_data.subscription_sequence.total`	Obrigatório em assinaturas com prazo definido	Integer. Indica o número total de cobranças da assinatura. Para assinaturas permanentes deve ser `null`.	`12`
`point_of_interaction.transaction_data.invoice_period.period`	Obrigatório condicional	Integer. Indica a frequência do ciclo de cobrança. Obrigatório para recorrência pré-estabelecida e quando se envia `invoice_period.type`.	`1`
`point_of_interaction.transaction_data.invoice_period.type`	Obrigatório condicional	String. Indica o tipo do período de cobrança, podendo ser `monthly`, `daily`, `yearly`, `quarterly`. Obrigatório para recorrência pré-estabelecida e quando se envia `invoice_period.period`.	`monthly`
`point_of_interaction.transaction_data.billing_date`	Obrigatório	String. Data prevista de cobrança no formato ISO 8601 (`YYYY-MM-DD`).	`2026-01-25`

Se a solicitação foi bem-sucedida, a resposta será como o seguinte exemplo:

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

Gerar um token do cartão

Utilize um dos SDK abaixo para tokenizar o cartão utilizando seu ID (card_id). A tokenização fornece uma experiência de pagamento digital mais segura substituindo o número do cartão por um número alternativo, o token.

<?php

use MercadoPago\Client\CardToken\CardTokenClient;
use MercadoPago\Exceptions\MPApiException;
use MercadoPago\MercadoPagoConfig;

require_once 'vendor/autoload.php';

MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");

$client = new CardTokenClient();

try {
    $request = [
        "card_id" => "cardId"
    ];

    $card_token = $client->create($request);
    var_dump($card_token);
} catch (MPApiException $e) {
    echo "Status code: " . $e->getApiResponse()->getStatusCode() . "\n";
    echo "Content: ";
    var_dump($e->getApiResponse()->getContent());
    echo "\n";
} catch (\Exception $e) {
    echo $e->getMessage();
}

import { MercadoPagoConfig, CardToken } from 'mercadopago';

const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const cardToken = new CardToken(client);

const body = {
	card_id : '<CARD_ID>'
};

cardToken.create({ body }).then(console.log).catch(console.log);

import com.mercadopago.client.cardtoken.CardTokenClient;
import com.mercadopago.client.cardtoken.CardTokenRequest;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.resources.CardToken;

public class App {
    public static void main(String[] args){
        MercadoPagoConfig.setAccessToken("<YOUR_ACCESS_TOKEN>");
        
        CardTokenRequest request = CardTokenRequest.builder().cardId("<CARD_ID>").build();
        CardTokenClient client = new CardTokenClient();

        try {
            CardToken cardToken = client.create(request);
            System.out.println(cardToken);
        } catch (MPApiException ex) {
            System.out.printf(
                    "MercadoPago Error. Status: %s, Content: %s%n",
                    ex.getApiResponse().getStatusCode(), ex.getApiResponse().getContent());
        } catch (MPException ex) {
            ex.printStackTrace();
        }
    }
}

using System;
using MercadoPago.Config;
using MercadoPago.Client.CardToken;
using MercadoPago.Resource.CardToken;

MercadoPagoConfig.AccessToken = "<YOUR_ACCESS_TOKEN>";

var request = new CardTokenRequest
{
    CardId = "<CARD_ID>"
};

var client = new CardTokenClient();
CardToken cardToken = await client.CreateAsync(request);

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cardToken));

require_relative '../lib/mercadopago.rb'

sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')

card_token_request = {
  card_id: '<CARD_ID>'
}

card_token_response = sdk.card_token.create(card_token_request)
card_token = card_token_response[:response]
puts card_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}}
}'

Siga o passo a passo e evite pagamentos fraudulentos com nossas recomendações para melhorar a aprovação de seus pagamentos.

Obter dados do cliente

Para obter os dados do cliente como, por exemplo, ID, endereço ou data de registro, é possível obtê-los através da nossa API de clientes. Para isso, envie um GET com o e-mail do cliente ao endpoint /v1/customers/searchAPI e execute a requisição ou, se preferir, utilize um dos SDK abaixo.

<?php
  MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");
  
  $client = new CustomerClient();

  $customer = $client->search(1, 0, ["email" => "my.user@example.com"]);
?>

import { Customer, MercadoPagoConfig } from '@src/index';

const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const customer = new Customer(client);

customer.search({ options: { email: '<EMAIL>' } }).then(console.log).catch(console.log);

CustomerClient client = new CustomerClient();

Map<String, Object> filters = new HashMap<>();
filters.put("email", "test_payer_12345@testuser.com");

MPSearchRequest searchRequest =
   MPSearchRequest.builder().offset(0).limit(0).filters(filters).build();

client.search(searchRequest);

customers_response = sdk.customer.search(filters: { email: 'test_payer_12345@testuser.com' })
customers = customers_response[:response]

var searchRequest = new SearchRequest
{
    Filters = new Dictionary<string, object>
    {
        ["email"] = "test_payer_12345@testuser.com",
    },
};
ResultsResourcesPage<Customer> results = await customerClient.SearchAsync(searchRequest);
IList<Customer> customers = results.Results;

filters = {
    "email": "test_payer_12345@testuser.com"
}

customers_response = sdk.customer().search(filters=filters)
customers = customers_response["response"]

curl -X GET \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  'https://api.mercadopago.com/v1/customers/search' \
  -d '{
    "email": "test_user_19653727@testuser.com"
}'

Tendo obtido o ID do cliente, utilize-o para localizar o cartão associado enviando um GET ao endpoint /v1/customers/{customer_id}/cardsAPI. Para mais informações, veja a seção de Salvar cartões ou a seção de renderização padrão do Brick de Card Payment..

Associar cartão ao cliente

Após garantir que o cartão é válido, crie um cliente e associe-o ao cartão validado. Para criar um cliente e associá-lo ao seu cartão, é preciso enviar o customer_id e o card_token. Cada cliente será guardado com o valor customer e cada cartão com o valor card.

Além disso, recomendamos armazenar os dados do cartão sempre que um pagamento for concluído com sucesso. Isso permite que os dados corretos sejam armazenados para compras futuras e otimiza o processo de pagamento para o comprador.

Para criar um cliente e cartão, utilize um dos SDK abaixo.

<?php
  MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");
  
  $client_customer = new CustomerClient();
  $customer = $client_customer->create(["email" => "my.user@example.com"]);
  $client = new CustomerCardClient();
  $customer_card = $client->create($customer->id, ["token" => "your_card_token"]);
?>

const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const customer = new Customer(client);

const body = {
  email: "my.user@example.com"
};

customer.create({ body: body }).then((result) => {
  const customerCard = new CustomerCard(client);

  const body = {
    token : result.token,
  };

  customerCard.create({ customerId: 'customer_id', body })
     .then((result) => console.log(result));
})

MercadoPagoConfig.setAccessToken("<YOUR_ACCESS_TOKEN>");

CustomerClient customerClient = new CustomerClient();
CustomerCardClient customerCardClient = new CustomerCardClient();

CustomerRequest customerRequest = CustomerRequest.builder()
   .email("john@test.com")
   .build();
Customer customer = customerClient.create(customerRequest);

CustomerCardIssuer issuer = CustomerCardIssuer.builder()
   .id("3245612")
   .build();

CustomerCardCreateRequest cardCreateRequest = CustomerCardCreateRequest.builder()
   .token("9b2d63e00d66a8c721607214cedaecda")
   .issuer(issuer)
   .paymentMethodId("debit_card")
   .build();

customerCardClient.create(customer.getId(), cardCreateRequest);

require 'mercadopago'

sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')

customer_request = {
  email: 'john@yourdomain.com'
}
customer_response = sdk.customer.create(customer_request)
customer = customer_response[:response]

card_request = {
  token: '9b2d63e00d66a8c721607214cedaecda',
  issuer_id: '3245612',
  payment_method_id: 'visa'
}
card_response = sdk.card.create(customer['id'], card_request)
card = card_response[:response]

MercadoPagoConfig.AccessToken = "<YOUR_ACCESS_TOKEN>";

var customerRequest = new CustomerRequest
{
    Email = "test_payer_12345@testuser.com",
};
var customerClient = new CustomerClient();
Customer customer = await customerClient.CreateAsync(customerRequest);

var cardRequest = new CustomerCardCreateRequest
{
    Token = "9b2d63e00d66a8c721607214cedaecda"
};
CustomerCard card = await customerClient.CreateCardAsync(customer.Id, cardRequest);

import mercadopago
sdk = mercadopago.SDK("<YOUR_ACCESS_TOKEN>")

customer_data = {
  "email": "test_payer_12345@testuser.com"
}
customer_response = sdk.customer().create(customer_data)
customer = customer_response["response"]

card_data = {
  "token": "9b2d63e00d66a8c721607214cedaecda",
  "issuer_id": "3245612",
  "payment_method_id": "visa"
}
card_response = sdk.card().create(customer["id"], card_data)
card = card_response["response"]

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
  -d '{"token": "9b2d63e00d66a8c721607214cedaecda", "issuer_id": "3245612", "payment_method_id": "visa"}'

Para mais informações, veja a seção de Salvar cartões

Realizar primeira cobrança com cartão armazenado

Tendo validado o cartão e obtido os dados necessários do cliente, utilize o token do cartão gerado anteriormente e o ID do cliente associado para registrar o pagamento.

Além dos campos mínimos requeridos para a requisição (token, transaction_amount, installments, payment_method_id epayer.email), o envio do point_of_interaction.type = "CREDENTIAL_ON_FILE" (Mensageria de Pagamentos Automáticos) também é necessário para classificar corretamente cada transação recorrente junto às bandeiras e emissores, garantindo maior precisão na aprovação,

Além disso, é altamente recomendado enviar o Network Transaction ID (TID) da bandeira. Para obtê-lo, inclua o header X-Expand-Responde-Nodes: gateway.reference na requisição e o valor retornado em expanded.gateway.reference.network_transaction_id deverá ser enviado como transaction_data.network_transaction_id nas cobranças MIT subsequentes.

O network_transaction_id é vinculado diretamente ao cartão utilizado na transação. Caso o titular troque de cartão dentro da mesma assinatura, nunca reutilize o TID gerado a partir de um pagamento realizado com o cartão anterior. Gere novamente o TID na requisição subsequente, já que cada TID corresponde exclusivamente ao cartão com o qual foi gerado.

<?php
  use MercadoPago\Client\Payment\PaymentClient;


  MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");

  $customer_client = new CustomerClient();
  $cards = $client->list("customer_id");
  
  $client = new PaymentClient();
  $request_options = new RequestOptions();
  $request_options->setCustomHeaders(["X-Idempotency-Key: <SOME_UNIQUE_VALUE>"]);

  $payment = $client->create([
    "transaction_amount" => 100.0,
    "token" => $cards[0]-> token,
    "description" => "My product",
    "installments" => 1,
    "payment_method_id" => "visa",
    "issuer_id" => "123",
    "payer" => [
      "type" => "customer",
      "id" => "1234"
    ]
  ], $request_options);
  echo implode($payment);
?>

const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const customerClient = new Customer(client);

customerClient.listCards({ customerId: '<CUSTOMER_ID>' })
	.then((result) => {

  const payment = new Payment(client);

  const body = {
    transaction_amount: 100,
    token: result[0].token,
    description: 'My product',
    installments: 1,
    payment_method_id: 'visa',
    issuer_id: 123,
    payer: {
      type: 'customer',
      id: '123'
  }
};

  payment.create({ body: body }).then((result) => console.log(result));
});

MercadoPagoConfig.setAccessToken("<YOUR_ACCESS_TOKEN>");

PaymentClient client = new PaymentClient();

PaymentCreateRequest request = PaymentCreateRequest.builder()
   .transactionAmount(new BigDecimal("100"))
   .installments(1)
   .token("ff8080814c11e237014c1ff593b57b4d")
   .payer(PaymentPayerRequest.builder()
       .type("customer")
       .id("247711297-jxOV430go9fx2e")
       .build())
   .build();

client.create(request);

require 'mercadopago'

sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')

payment_request = {
  token: 'ff8080814c11e237014c1ff593b57b4d',
  installments: 1,
  transaction_amount: 100,
  payer: {
    type: 'customer',
    id: '123456789-jxOV430go9fx2e'
  }
}
payment_response = sdk.payment.create(payment_request)
payment = payment_response[:response]

using MercadoPago.Config;
using MercadoPago.Client.Payment;
using MercadoPago.Resource.Payment;

MercadoPagoConfig.AccessToken = "<YOUR_ACCESS_TOKEN>";

var request = new PaymentCreateRequest
{
    TransactionAmount = 100,
    Token = "ff8080814c11e237014c1ff593b57b4d",
    Installments = 1,
    Payer = new PaymentPayerRequest
    {
        Type = "customer",
        Email = "test_payer_12345@testuser.com",
    },
};

var client = new PaymentClient();
Payment payment = await client.CreateAsync(request);

import mercadopago
sdk = mercadopago.SDK("<YOUR_ACCESS_TOKEN>")

payment_data = {
    "transaction_amount": 100,
    "token": 'ff8080814c11e237014c1ff593b57b4d',
    "installments": 1,
    "payer": {
        "type": "customer",
        "id": "123456789-jxOV430go9fx2e"
    }
}

payment_response = sdk.payment().create(payment_data)
payment = payment_response["response"]

curl -X POST \
   -H 'accept: application/json' \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
   -H 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
   -H 'X-Expand-Responde-Nodes: gateway.reference' \
   'https://api.mercadopago.com/v1/payments' \
   -d '{
      "transaction_amount": 100,
      "token": "ff8080814c11e237014c1ff593b57b4d",
      "installments": 1,
      "payment_method_id": "master",
      "payer": {
          "type": "customer",
          "id": "123456789-jxOV430go9fx2e"
      },
      "description": "pagamento de assinatura",
      "notification_url": "https://seu-webhook.com",
      "statement_descriptor": "Sua loja",
      "external_reference": "49646973",
      "additional_info": {
          "items": [
              {
                  "id": "FT9200101024",
                  "title": "seu produto",
                  "quantity": 1,
                  "unit_price": 100
              }
          ],
          "payer": {
              "phone": {
                  "area_code": "54",
                  "number": "1234567"
              },
              "first_name": "MARTINEZ",
              "last_name": "GODOY",
              "address": {
                  "zip_code": "2804",
                  "street_name": "Mendoza",
                  "street_number": "125"
              },
              "registration_date": null
          }
      },
      "point_of_interaction": {
          "type": "CREDENTIAL_ON_FILE",
          "sub_type": "recurring",
          "transaction_data": {
              "first_transaction": false,
              "storage": "stored",
              "transaction_initiator": "merchant",
              "network_transaction_id": "n7w-c0d3-t7d",
              "subscription_id": "Tu Comercio_4b4ef2f2-c5d6-4c1d-a492-070630bed20a",
              "subscription_sequence": {
                  "number": 2,
                  "total": 10
              },
              "invoice_period": {
                  "period": 1,
                  "type": "monthly"
              },
              "billing_date": "2026-01-25",
              "reference": {
                  "id": "FIRST_CIT_PAYMENT_ID"
              }
          }
      }
   }'

Parâmetro	Obrigatoriedade	Tipo e descrição	Exemplo
`transaction_amount`	Obrigatório	Number. Custo do produto.	`100`
`token`	Obrigatório	String. Identificador do token do cartão. O token é gerado a partir dos dados do próprio cartão, proporcionando maior segurança no processo de pagamento.	`ff8080814c11e237014c1ff593b57b4d`
`installments`	Obrigatório	Integer. Número de parcelas selecionado.	`1`
`payment_method_id`	Obrigatório	String. Indica o identificador do meio de pagamento selecionado para efetuar o pagamento.	`master`
`payer.type`	Obrigatório	String. Tipo de identificação do pagador. Deve ser `customer`.	`customer`
`payer.id`	Obrigatório	String. ID do cliente associado ao cartão.	`123456789-jxOV430go9fx2e`
`point_of_interaction.type`	Obrigatório	String. Classifica o tipo de Point of Interaction (POI) que será aplicado à transação.	`CREDENTIAL_ON_FILE`
`point_of_interaction.sub_type`	Obrigatório	String. Define a natureza da cobrança, sendo `recurring` para cobranças com periodicidade definida e `unscheduled` para cobranças por evento, sem calendário fixo.	`recurring`
`point_of_interaction.transaction_data.first_transaction`	Obrigatório	Boolean. Indica se é o início de uma nova cadeia de cobranças. Deve ser `false` para cobranças subsequentes.	`false`
`point_of_interaction.transaction_data.storage`	Obrigatório	String. Estado de armazenamento das credenciais, sendo `store` quando o cartão está sendo capturado pela primeira vez e `stored` quando as credenciais já existem no sistema.	`stored`
`point_of_interaction.transaction_data.transaction_initiator`	Obrigatório	String. Identifica quem inicia a transação, sendo `customer` quando o titular está presente na sessão e `merchant` quando o estabelecimento dispara a cobrança automaticamente.	`merchant`
`point_of_interaction.transaction_data.network_transaction_id`	Opcional — fortemente recomendado	String. TID da bandeira gerado na primeira transação CIT deste cartão. Nunca envie o TID de um cartão diferente.	`n7w-c0d3-t7d`
`point_of_interaction.transaction_data.subscription_id`	Obrigatório	String. Mesmo identificador único da assinatura utilizado na transação inicial (CIT).	`87654321`
`point_of_interaction.transaction_data.subscription_sequence.number`	Obrigatório	Integer. Número sequencial da cobrança atual dentro da assinatura.	`2`
`point_of_interaction.transaction_data.subscription_sequence.total`	Obrigatório condicional	Integer. Indica o número total de cobranças da assinatura. Para assinaturas permanentes deve ser `null`.	`10`
`point_of_interaction.transaction_data.invoice_period.period`	Obrigatório condicional	Integer. Indica a frequência do ciclo de cobrança. Obrigatório quando se envia `invoice_period.type`.	`1`
`point_of_interaction.transaction_data.invoice_period.type`	Obrigatório condicional	String. Indica o tipo do período de cobrança (`monthly`, `daily`, `yearly`, `quarterly`). Obrigatório quando se envia `invoice_period.period`.	`monthly`
`point_of_interaction.transaction_data.billing_date`	Obrigatório	String. Data prevista de cobrança no formato ISO 8601 (`YYYY-MM-DD`).	`2026-01-25`
`point_of_interaction.transaction_data.reference.id`	Obrigatório	String. ID da primeira transação CIT desta assinatura. Deve ser sempre o ID daquela transação e nunca o de cobranças intermediárias.	`FIRST_CIT_PAYMENT_ID`

Realizar cobranças subsequentes

Após o cartão estar armazenado e a primeira transação concluída, as cobranças subsequentes podem ocorrer em três situações:

Automático pelo comerciante por calendário fixo (MIT): o estabelecimento cobra automaticamente na data acordada, sem qualquer ação do cliente — como a renovação mensal de uma assinatura.
Automático pelo comerciante por evento (MIT): o estabelecimento cobra quando um evento de uso ocorre, sem periodicidade definida — como um débito ao passar por um pedágio.
Compra avulsa pelo cliente (CIT): o cliente, com cartão já salvo, inicia uma compra avulsa — como um pedido de delivery ou uma corrida com um toque no app.

Envie o network_transaction_id sempre que disponível, visto que esse identificador corresponde ao TID gerado pela bandeira em uma transação CIT anterior do titular com o mesmo cartão e aumenta a taxa de aprovação junto às adquirentes.

Para obtê-lo a cada cobrança, inclua o header X-Expand-Responde-Nodes: gateway.reference na requisição. O valor retornado em expanded.gateway.reference.network_transaction_id deve ser enviado na próxima cobrança. Se o TID não retornar em uma cobrança intermediária, utilize o valor obtido na primeira transação CIT deste cartão.

Além disso, o network_transaction_id é vinculado diretamente ao cartão utilizado na transação. Caso o titular troque de cartão, nunca reutilize o TID gerado com o cartão anterior porque cada TID corresponde exclusivamente ao cartão com o qual foi gerado.

Cobranças automáticas disparadas pelo estabelecimento conforme o calendário acordado, sem intervenção do cliente.

O campo reference.id é obrigatório e deve conter sempre o ID retornado na primeira transação CIT desta assinatura, nunca o ID de cobranças intermediárias.

Para processar cobranças automáticas subsequentes, envie um POST ao endpoint v1/payments.

curl
curl -X POST \
   -H 'accept: application/json' \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
   -H 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
   -H 'X-Expand-Responde-Nodes: gateway.reference' \
   'https://api.mercadopago.com/v1/payments' \
   -d '{
      "transaction_amount": 100,
      "token": "12346622341",
      "payment_method_id": "master",
      "payer": {
        "id": "123456789-jxOV430go9fx2e",
        "type": "customer"
      },
      "point_of_interaction": {
        "type": "CREDENTIAL_ON_FILE",
        "sub_type": "recurring",
        "transaction_data": {
          "first_transaction": false,
          "storage": "stored",
          "transaction_initiator": "merchant",
          "network_transaction_id": "n7w-c0d3-t7d",
          "subscription_id": "87654321",
          "subscription_sequence": {
            "number": 2,
            "total": 12
          },
          "invoice_period": {
            "period": 1,
            "type": "monthly"
          },
          "billing_date": "2026-02-25",
          "reference": {
            "id": "20792195335"
          }
        }
      }
    }'

Parâmetro	Obrigatoriedade	Tipo e descrição	Exemplo
`transaction_amount`	Obrigatório	Number. Valor da transação.	`100`
`token`	Obrigatório	String. Identificador do token do cartão.	`12346622341`
`payment_method_id`	Obrigatório	String. Identificador do meio de pagamento.	`master`
`payer.id`	Obrigatório	String. ID do cliente no Mercado Pago.	`123456789-jxOV430go9fx2e`
`payer.type`	Obrigatório	String. Tipo de identificação do pagador. Deve ser `customer`.	`customer`
`point_of_interaction.type`	Obrigatório	String. Classifica o tipo de Point of Interaction (POI) que será aplicado à transação.	`CREDENTIAL_ON_FILE`
`point_of_interaction.sub_type`	Obrigatório	String. Define a natureza da cobrança, sendo `recurring` para cobranças com periodicidade definida e `unscheduled` para cobranças por evento, sem calendário fixo.	`recurring`
`point_of_interaction.transaction_data.first_transaction`	Obrigatório	Boolean. Indica se é o início de uma nova cadeia de cobranças do titular, sendo `true` para a transação inicial e `false` para as subsequentes.	`false`
`point_of_interaction.transaction_data.storage`	Obrigatório	String. Estado de armazenamento das credenciais, sendo `store` quando o cartão está sendo capturado pela primeira vez e `stored` quando as credenciais já existem no sistema.	`stored`
`point_of_interaction.transaction_data.transaction_initiator`	Obrigatório	String. Identifica quem inicia a transação, sendo `customer` quando o titular está presente na sessão e `merchant` quando o estabelecimento dispara a cobrança automaticamente.	`merchant`
`point_of_interaction.transaction_data.network_transaction_id`	Opcional — fortemente recomendado	String. TID da bandeira gerado na primeira transação CIT do cartão atual. Nunca envie o TID de um cartão diferente.	`n7w-c0d3-t7d`
`point_of_interaction.transaction_data.subscription_id`	Obrigatório	String. Mesmo identificador único da assinatura utilizado na transação inicial (CIT).	`87654321`
`point_of_interaction.transaction_data.subscription_sequence.number`	Obrigatório	Integer. Número sequencial da cobrança atual dentro da assinatura. Começa em `1` e é incrementado a cada cobrança.	`2`
`point_of_interaction.transaction_data.subscription_sequence.total`	Obrigatório condicional	Integer. Indica o número total de cobranças da assinatura. Para assinaturas permanentes deve ser `null`. Obrigatório em assinaturas com prazo definido.	`12`
`point_of_interaction.transaction_data.invoice_period.period`	Obrigatório condicional	Integer. Indica a frequência do ciclo de cobrança. Obrigatório para recorrência pré-estabelecida e quando se envia `invoice_period.type`.	`1`
`point_of_interaction.transaction_data.invoice_period.type`	Obrigatório condicional	String. Indica o tipo do período de cobrança, podendo ser `monthly`, `daily`, `yearly`, `quarterly`. Obrigatório para recorrência pré-estabelecida e quando se envia `invoice_period.period`.	`monthly`
`point_of_interaction.transaction_data.billing_date`	Obrigatório	String. Data prevista de cobrança no formato ISO 8601 (`YYYY-MM-DD`).	`2026-02-25`
`point_of_interaction.transaction_data.reference.id`	Obrigatório condicional	String. ID da primeira transação CIT desta assinatura, retornado na resposta do primeiro pagamento. Deve ser sempre o ID daquela transação e nunca o de cobranças intermediárias. Obrigatório quando `first_transaction = false`.	`20792195335`

Atualizar cartões

Caso necessário, é possível adicionar novos cartões a um determinado cliente. Para isso, busque o cliente e defina os novos dados de cartão utilizando um dos SDK disponíveis abaixo.

Caso seja necessário excluir um cartão antes de adicionar novos cartões a um cliente, envie um DELETE ao endpoint /v1/customers/{customer_id}/cards/{id} fornecendo o customer_id e o id do cartão que deseja excluir. Após a execução bem-sucedida da requisição, você poderá adicionar o novo cartão. Para mais informações, veja a seção de Salvar cartões.

<?php
  MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");
  
  $customer_client = new CustomerClient();
  $customer = $customer_client->get("1234");

  $card_client = new CustomerCardClient();
  
  $customer_card = $client->create($customer->id, [
    "token" => "your_card_token",
    "issuer_id" => "2345",
    "payment_method_id" => "debit_card"
  ]);

  echo implode($customer_card);
?>

const client = new MercadoPagoConfig({ accessToken: '<YOUR_ACCESS_TOKEN>' });
const customerClient = new Customer(client);

const customer = customerClient.get({ customerId: '<CUSTOMER_ID>' })
	.then((result) => {

  const cardClient = new CustomerCard(client);

  const body = {
       token : result.token,
       issuer_id: '2345',
       payment_method: 'debit_card' 
  };

cardClient.create({ customerId: customer, body: body })
.then(console.log).catch(console.log);
});

MercadoPagoConfig.setAccessToken("<YOUR_ACCESS_TOKEN>");

CustomerClient customerClient = new CustomerClient();
CustomerCardClient customerCardClient = new CustomerCardClient();

Customer customer = customerClient.get("247711297-jxOV430go9fx2e");

CustomerCardIssuer issuer = CustomerCardIssuer.builder()
   .id("3245612")
   .build();

CustomerCardCreateRequest cardCreateRequest = CustomerCardCreateRequest.builder()
   .token("9b2d63e00d66a8c721607214cedaecda")
   .issuer(issuer)
   .paymentMethodId("debit_card")
   .build();

customerCardClient.create(customer.getId(), cardCreateRequest);

require 'mercadopago'

sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')

customer_response = sdk.customer.get('247711297-jxOV430go9fx2e')
customer = customer_response[:response]

card_request = {
  token: '9b2d63e00d66a8c721607214cedaecda',
  issuer_id: '3245612',
  payment_method_id: 'debit_card'
}
card_response = sdk.card.create(customer['id'], card_request)
card = card_response[:response]

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

Ao substituir ou adicionar um novo cartão a um cliente, o network_transaction_id gerado com o cartão anterior não deve ser reutilizado nas cobranças subsequentes. Cada TID é vinculado exclusivamente ao cartão com o qual foi gerado. Realize uma nova transação com o titular presente (CIT) para capturar um TID correspondente ao novo cartão e utilize esse valor nas próximas cobranças.

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.

Documentação

Começando agora?

Recursos

Suporte

Parcerias

Comunidade

Realizar cobranças recorrentes

Validação com Primeiro pagamento

Navegação

Recursos e Comunidade

Mercado Pago

País e idioma