# MD for: https://www.mercadopago.com.br/developers/es/docs/automatic-payments/recurring-charges/subscription-messaging.md

\# Automatic payments messaging Automatic payments messaging, or \*\*Subscription Messaging\*\*, involves information about recurring payments (previous payment ID, subscription ID, number of times the payment will be generated, and POI with \`type = SUBSCRIPTIONS\`) that is sent to the \[Payments API\](https://www.mercadopago.com.br/developers/en/reference/online-payments/checkout-api-payments/create-payment/post) with the aim of increasing the approval rate for these types of payments. > WARNING > > Important > > In the case of operations with recurring payments from the card brands, it will be necessary to send the transaction identifier (TID) in messaging transactions. For more information on how to send the TID, check the documentation \[Network Transaction ID - TID\](https://www.mercadopago.com.br/developers/en/docs/automatic-payments/recurring-charges/network-transaction-id). ## Configuration The information that needs to be sent in the \[create payment request\](https://www.mercadopago.com.br/developers/en/reference/online-payments/checkout-api-payments/create-payment/post) for Automatic payment messaging varies depending on whether it is a first payment or subsequent payments. See below the requirements for each option. ### Process the first payment For the \*\*first payment\*\* in the Automatic payment messaging, send a \*\*POST\*\* to the \[v1/payments\](https://www.mercadopago.com.br/developers/en/reference/online-payments/checkout-api-payments/create-payment/post) endpoint, or use one of our SDKs. The fields described in the table below belong to the \`point\_of\_interaction\` object, which contains the specific information for this type of payment. You must send them following the specifications indicated for each one. If you want to know how to send the rest of the request, check our \[API Reference\](https://www.mercadopago.com.br/developers/en/reference/online-payments/checkout-api-payments/create-payment/post). 

* [csharp ](#editor%5F5)
* [curl ](#editor%5F7)
* [java ](#editor%5F3)
* [node ](#editor%5F2)
* [php ](#editor%5F1)
* [python ](#editor%5F6)
* [ruby ](#editor%5F4)
php node java ruby csharp python curl 

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

MercadoPagoConfig::setAccessToken("ENV_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" => (float) $_POST['transactionAmount'],
  "token" => $_POST['token'],
  "description" => $_POST['description'],
  "installments" => (int) $_POST['installments'],
  "payment_method_id" => $_POST['paymentMethodId'],
  "payer" => [
  "id" => $_POST['id'],
  "type" => $_POST['type']
  ],
  "point_of_interaction" => [
  "type" => $_POST['type'],
  "transaction_data" => [
  "first_time_use" => $_POST['first_time_use'],
  "subscription_id" => "COLLECTORPADRE-SUBSCRIPCION_ID",
  "subscription_sequence" => [
  "number" => (int) $_POST['number'],
  "total" => (int) $_POST['total']
  ],
  "invoice_period" => [
  "period" => (int) $_POST['period'],
  "type" => $_POST['type']
  ],
  "billing_date" => $_POST['billing_date'],
  ]
]

], $request_options);
echo implode($payment);
?>
```

Copiar 

```
import { Payment, MercadoPagoConfig } from 'mercadopago';

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

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

  const payment = new Payment(client);

  const body = {
  transaction_amount: req.transaction_amount,
  token: req.token,
  description: req.description,
  installments: req.installments,
  payment_method_id: req.payment_method_id,
  payer: {
  id: req.id,
  type: req.type
  },
  point_of_interaction: {
  type: req.type,
  transaction_data: {
  first_time_use: req.first_time_use,
  subscription_id: req.subscription_id,
  subscription_sequence: {
  number: req.number,
  total: req.total
  },
  invoice_period: {
  period: req.period,
  type: req.type
  },
  billing_date: req.billing_date
  }
  }

  };

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

Copiar 

```
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("x-idempotency-key", <SOME_UNIQUE_VALUE>);
 
MPRequestOptions requestOptions = MPRequestOptions.builder()
  .customHeaders(customHeaders)
  .build();

MercadoPagoConfig.setAccessToken("ENV_ACCESS_TOKEN");

PaymentClient client = new PaymentClient();

PaymentCreateRequest request = PaymentCreateRequest.builder()
  .transactionAmount(request.getTransactionAmount())
  .installments(request.getInstallments())
  .token(request.getToken())
  .payer(PaymentPayerRequest.builder()
  .id(request.getPayer().getId())
  .type(request.getPayer().getType())
  .build())
  .pointOfInteraction(PointOfInteraction.builder()
  .type(request.getPointOfInteraction().getType())
  .transactionData(TransactionData.builder()
  .firstTimeUse(request.getTransactionData().getFirstTimeUse())
  .subscriptionId(request.getTransactionData().getSubscriptionId())
  .subscriptionSequence(SubscriptionSequence.builder()
  .number(request.getTransactionData().getSubscriptionSequence().getNumber())
  .total(request.getTransactionData().getSubscriptionSequence().getTotal())
  .build())
  .invoicePeriod(InvoicePeriod.builder()
  .period(request.getTransactionData().getInvoicePeriod().getPeriod())
  .type(request.getTransactionData().getInvoicePeriod().getType())
  .build())
  .billingDate(request.getTransactionData().getBillingDate())
  .build())
  .build())
  .build();

client.create(request);
```

Copiar 

```
require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')

custom_headers = {
 'x-idempotency-key': '<SOME_UNIQUE_VALUE>'
}

custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)

payment_request = {
 transaction_amount: params[:transactionAmount].to_f,
 token: params[:token],
 description: params[:description],
 payment_method_id: params[:paymentMethodId],
 payer: {
  id: params[:id],
  type: params[:type]
 },
 point_of_interaction: {
  type: params[:type],
  transaction_data: {
  first_time_use: params[:first_time_use],
  subscription_id: params[:subscription_id],
  subscription_sequence: {
  number: params[:number],
  total: params[:total]
  },
  invoice_period: {
  period: params[:period],
  type: params[:type]
  },
  billing_date: params[:billing_date],
  }
}
 
payment_response = sdk.payment.create(payment_request, custom_request_options)
payment = payment_response[:response]
```

Copiar 

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

MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";

var requestOptions = new RequestOptions();
requestOptions.CustomHeaders.Add("x-idempotency-key", "<SOME_UNIQUE_VALUE>");

var request = new PaymentCreateRequest
{
  TransactionAmount = decimal.Parse(Request["transactionAmount"]),
  Token = Request["token"],
  Description = Request["description"],
  PaymentMethodId = Request["paymentMethodId"],
  Installments = Request["installments"],
  Payer = new PaymentPayerRequest
  {
  Id = Request["id"],
  Type = Request["type"]
  },
  PointOfInteraction = new PointOfInteractionRequest
  {
  Type = Request["type"],
  TransactionData = new TransactionDataRequest
  {
  FirstTimeUse = Request["firstTimeUse"],
  SubscriptionId = Request["subscriptionId"],
  SubscriptionSequence = new SubscriptionSequenceRequest
  {
  Number = Request["number"],
  Total = Request["total"]
  },
  InvoicePeriod = new InvoicePeriodRequest
  {
  Period = Request["period"],
  Type = Request["type"]
  },
  BillingDate = Request["billingDate"]
  }
  }
};

var client = new PaymentClient();
Payment payment = await client.CreateAsync(paymentRequest, requestOptions);
```

Copiar 

```
import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")

request_options = mercadopago.config.RequestOptions()
request_options.custom_headers = {
  'x-idempotency-key': '<SOME_UNIQUE_VALUE>'
}

payment_data = {
  "transaction_amount": float(request.POST.get("transaction_amount")),
  "token": request.POST.get("token"),
  "description": request.POST.get("description"),
  "payment_method_id": request.POST.get("payment_method_id"),
  "payer": {
  "id": request.POST.get("id"),
  "type": request.POST.get("type")
  },
  "point_of_interaction": {
  "type": request.POST.get("type"),
  "transaction_data": {
  "first_time_use": bool(request.POST.get("first_time_use")),
  "subscription_id": request.POST.get("subscription_id"),
  "subscription_sequence": {
  "number": int(request.POST.get("number")),
  "total": int(request.POST.get("total"))
  },
  "invoice_period": {
  "period": int(request.POST.get("period")),
  "type": request.POST.get("type")
  },
  "billing_date": request.POST.get("billing_date")
  }
  }
}
```

Copiar 

```
curl --location 'https://api.mercadopago.com/v1/payments' \
--header 'Authorization: Bearer ENV_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "description": "{{description}}",
  "token": "{{card_token}}",
  "payer": {
  "id": "{{customer_id}}",
  "type": "{{type}}"
  },
  "payment_method_id": "{{payment_method_id}}",
  "transaction_amount": {{transaction_amount}},
  "point_of_interaction": {
  "type": "{{type}}",
  "transaction_data": {
  "first_time_use": {{first_time_use}},
  "subscription_id": "{{subscription_id}}",
  "subscription_sequence": {
  "number": {{subscription_number}},
  "total": {{subscription_total}}
  },
  "invoice_period": {
  "period": {{invoice_period}},
  "type": "{{invoice_type}}"
  },
  "billing_date": "{{billing_date}}",
  "user_present": {{user_present}}
  }
  }
}'
```

Copiar 

| Parameter | Required | Type and description | Example | | ---- | ---- | ---- | ---- | | \`type\` | Required for all payments without CVV | String. Indicates the type of \*Point of Interaction\* (POI). Must be \`SUBSCRIPTIONS\`. | \`SUBSCRIPTIONS\` | | \`first\_time\_use\` | Required for all payments without CVV | Boolean. Indicates if it is the first payment of the subscription. For the validation payment, it must be \`true\`. For the rest of the payments, \`false\`. | \`false\` | | \`subscription\_id\` | Required | String. Subscription identifier. We suggest this value be composed of the \`collector\` + a unique subscription \`ID\` per user. | \`COLLECTORPADRE-SUBSCRIPCION\_ID\` | | \`subscription\_sequence.number\` | Required | Integer. Indicates the number of the subsequent payment. | \`3\` | | \`subscription\_sequence.total\` | Required for payments with pre-established recurrence | Integer. Indicates the total number of subscription payments. For permanent subscriptions, it must be \`null\` | \`12\` | | \`invoice\_period.period\` | Required for payments involving pre-established recurrence and when \`invoice\_period.type\` is sent. | Integer. Indicates the frequency of the recurring payment. | \`1\` | | \`invoice\_period.type\` | Required for payments involving pre-established recurrence and when \`invoice\_period.period\` is sent. | String. Indicates the type of recurring payment period. You can send any value that represents a time period. | \`daily\`, \`monthly\`, \`yearly\`, \`quarterly\` | | \`user\_present\` | Optional | Boolean. Indicates if there was user intervention at the time the payment was created. | \`true\` or \`false\` | | \`billing\_date\` | Required | String. Billing date. | \`2024-03-16\` | | \`payment\_reference.id\` | Required when \`first\_time\_use = false\` | String. ID of the validation payment with CVV, performed to save the card data. Should not be sent for first payments. | \`20792195335\` | | \`transaction\_amount\` | Required | Number. Payment amount. | \`100\` | | \`token\` | Required | String. Card token | \`12346622341\` | | \`description\` | Optional | String. Payment description | \`Test payment\` | | \`payment\_method\_id\` | Required | String. Indicates the identifier of the selected payment method to make the payment | \`master\` | | \`payer.email\` | Required | String. Payer's email | \`buyer@examplemail.com\` | | \`payer.type\` | Optional | String. Type of payer identification associated | \`guest\` or \`customer\` | If the request was successful, the response will look like the following example: \`\`\`json { "payer": {...}, "transaction\_amount": 20, "description": "...", "token": "....", "statement\_descriptor": "PRUEBA", "issuer\_id": ..., "payment\_method\_id": "...", "amounts": {...}, "installments": 1, "pos\_id": "....", "external\_reference": "...", "point\_of\_interaction": { "type": "SUBSCRIPTIONS", "transaction\_data": { "first\_time\_use": true, "subscription\_id": "COLLECTORPADRE-SUBSCRIPCION\_ID", "subscription\_sequence": { "number": 1, "total": 12 }, "invoice\_period": { "period": 1, "type": "monthly" }, "payment\_reference": { "id": "20792195335" }, "user\_present": true/false, "billing\_date": "2024-03-16" } } } \`\`\` ### Process subsequent payments For \*\*subsequent payments\*\* in the recurrence messaging, resend the information through the \`point\_of\_interaction\` object to the \[v1/payments\](https://www.mercadopago.com.br/developers/en/reference/online-payments/checkout-api-payments/create-payment/post) endpoint, taking into account the \*\*new requirements\*\* listed below, or use one of our SDKs. Remember that you can access the information to send the rest of the request parameters through our \[API Reference\](https://www.mercadopago.com.br/developers/en/reference/online-payments/checkout-api-payments/create-payment/post). | Parameter | Required | Type and description | Example | | ---- | ---- | ---- | ---- | | \`type\` | Required for all payments without CVV | String. Indicates the type of \*Point of Interaction\* (POI). Must be \`SUBSCRIPTIONS\`. | \`SUBSCRIPTIONS\` | | \`first\_time\_use\` | Required for all payments without CVV | Boolean. Indicates if it is the first payment of the subscription. For subsequent payments it must be \`false\`, because it is not the first transaction. | \`false\` | | \`subscription\_id\` | Required | String. Subscription identifier. We suggest this value be composed of the \`collector\` + a unique subscription \`ID\` per user. | \`COLLECTORPADRE-SUBSCRIPCION\_ID\` | | \`subscription\_sequence.number\` | Required | Integer. Indicates the number of the current payment. | \`3\` | | \`subscription\_sequence.total\` | Required for payments with pre-established recurrence | Integer. Indicates the total number of subscription payments. For permanent subscriptions, it must be \`null\` | \`12\` | | \`invoice\_period.period\` | Required for payments involving pre-established recurrence and when \`invoice\_period.type\` is sent. | Integer. Indicates the frequency of the recurring payment. | \`1\` | | \`invoice\_period.type\` | Required for payments involving pre-established recurrence and when \`invoice\_period.period\` is sent. | String. Indicates the type of recurring payment period. You can send any value that represents a time period. | \`daily\`, \`monthly\`, \`yearly\`, \`quarterly\` | | \`user\_present\` | Optional | Boolean. Indicates if there was user intervention at the time the payment was created. | \`true\` or \`false\` | | \`billing\_date\` | Required | String. Billing date. | \`2024-03-16\` | | \`payment\_reference.id\` | Required when \`first\_time\_use = false\` | String. ID of the first validation payment with CVV, performed to save the card data. Must be sent for subsequent payments and must always be the ID of that first payment. | \`20792195335\` | | \`transaction\_amount\` | Required | Number. Payment amount. | \`100\` | | \`token\` | Required | String. Card token | \`12346622341\` | | \`description\` | Optional | String. Payment description | \`Test payment\` | | \`payment\_method\_id\` | Required | String. Indicates the identifier of the selected payment method to make the payment | \`master\` | | \`payer.email\` | Required | String. Payer's email | \`buyer@examplemail.com\` | | \`payer.type\` | Optional | String. Type of payer identification associated | \`guest\` or \`customer\` | If the request was successful, the response will look like the following example: \`\`\`json { "payer": {...}, "transaction\_amount": 20, "description": "...", "token": "....", "statement\_descriptor": "PRUEBA", "issuer\_id": ..., "payment\_method\_id": "...", "amounts": {...}, "installments": 1, "pos\_id": "....", "external\_reference": "...", "point\_of\_interaction": { "type": "SUBSCRIPTIONS", "transaction\_data": { "first\_time\_use": false, "subscription\_sequence": { "number": 3, "total": 12 }, "invoice\_period": { "period": 1, "type": "monthly" }, "payment\_reference": { "id": "20792195335" }, "user\_present": true/false, "billing\_date": "2024-03-16" } } } \`\`\` ## Common errors Some fields to be sent in the automatic payment messaging configuration have certain particularities that should be considered to avoid errors in API requests. See below how to avoid these errors. :::AccordionComponent{title="payment\_reference"} The requirement for this field depends on the value sent for \`first\_time\_use\`: - If \`first\_time\_use = true\`, the field is \*\*not\*\* required. - If \`first\_time\_use = false\`, the field \*\*is required\*\*. If not sent, the API will return a 400 - Bad request error, as illustrated below: \`\`\`json { "message": "The following parameters can't be null: payment\_reference", "error": "bad\_request", "status": 400, "cause": \[ { "code": 15, "description": "The following parameters can't be null: ", "data": "19-08-2025T18:36:51UTC;2d57e208-8d5b-4ad3-97fe-060fa4e1b821" } \] } \`\`\` ::: :::AccordionComponent{title="invoice\_period"} The attributes of this object are interdependent: if one of them is sent, the other must be sent as well. That is, if \`invoice\_period.period\` is sent, \`invoice\_period.type\` must also be sent, and vice versa. If this behavior is not respected, the API will return a 400 - Bad request error, as illustrated below: \`\`\`json { "error": "bad\_request", "message": "The following parameters can't be null: point\_of\_interaction.transaction\_data.invoice\_period.type", "status": 400 } \`\`\` :::