AI resources

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 with the aim of increasing the approval rate for these types of payments.

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.

Configuration

The information that needs to be sent in the create payment request 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 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.

<?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);
?>
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));
    });
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);
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]
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);
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")
         }
    }
}
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}}
        }
    }
}'
ParameterRequiredType and descriptionExample
typeRequired for all payments without CVVString. Indicates the type of Point of Interaction (POI). Must be SUBSCRIPTIONS.SUBSCRIPTIONS
first_time_useRequired for all payments without CVVBoolean. 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_idRequiredString. Subscription identifier. We suggest this value be composed of the collector + a unique subscription ID per user.COLLECTORPADRE-SUBSCRIPCION_ID
subscription_sequence.numberRequiredInteger. Indicates the number of the subsequent payment.3
subscription_sequence.totalRequired for payments with pre-established recurrenceInteger. Indicates the total number of subscription payments. For permanent subscriptions, it must be null12
invoice_period.periodRequired for payments involving pre-established recurrence and when invoice_period.type is sent.Integer. Indicates the frequency of the recurring payment.1
invoice_period.typeRequired 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_presentOptionalBoolean. Indicates if there was user intervention at the time the payment was created.true or false
billing_dateRequiredString. Billing date.2024-03-16
payment_reference.idRequired when first_time_use = falseString. ID of the validation payment with CVV, performed to save the card data. Should not be sent for first payments.20792195335
transaction_amountRequiredNumber. Payment amount.100
tokenRequiredString. Card token12346622341
descriptionOptionalString. Payment descriptionTest payment
payment_method_idRequiredString. Indicates the identifier of the selected payment method to make the paymentmaster
payer.emailRequiredString. Payer's emailbuyer@examplemail.com
payer.typeOptionalString. Type of payer identification associatedguest 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 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.

ParameterRequiredType and descriptionExample
typeRequired for all payments without CVVString. Indicates the type of Point of Interaction (POI). Must be SUBSCRIPTIONS.SUBSCRIPTIONS
first_time_useRequired for all payments without CVVBoolean. 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_idRequiredString. Subscription identifier. We suggest this value be composed of the collector + a unique subscription ID per user.COLLECTORPADRE-SUBSCRIPCION_ID
subscription_sequence.numberRequiredInteger. Indicates the number of the current payment.3
subscription_sequence.totalRequired for payments with pre-established recurrenceInteger. Indicates the total number of subscription payments. For permanent subscriptions, it must be null12
invoice_period.periodRequired for payments involving pre-established recurrence and when invoice_period.type is sent.Integer. Indicates the frequency of the recurring payment.1
invoice_period.typeRequired 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_presentOptionalBoolean. Indicates if there was user intervention at the time the payment was created.true or false
billing_dateRequiredString. Billing date.2024-03-16
payment_reference.idRequired when first_time_use = falseString. 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_amountRequiredNumber. Payment amount.100
tokenRequiredString. Card token12346622341
descriptionOptionalString. Payment descriptionTest payment
payment_method_idRequiredString. Indicates the identifier of the selected payment method to make the paymentmaster
payer.emailRequiredString. Payer's emailbuyer@examplemail.com
payer.typeOptionalString. Type of payer identification associatedguest 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.