Recursos para IA

Mensageria de pagamentos automáticos

A mensageria de pagamentos automáticos, ou mensageria de subscrição, envolve informações dos pagamentos recorrentes (ID de pagamentos anteriores, ID da subscrição, número de vezes que o pagamento será gerado e POI com type = SUBSCRIPTIONS) que são enviadas para a API de Pagamentos com o intuito de aumentar a taxa de aprovação para pagamentos deste tipo.

Importante
No caso de operações com pagamentos recorrentes das bandeiras, será necessário enviar o identificador de transação da bandeira (TID) às transações de mensageria. Para mais informações sobe como enviar o TID, acesse a documentação Network Transaction ID - TID.

Configuração

As informações que precisam ser enviadas na requisição de criar pagamento para a mensageria de Pagamentos automáticos variam dependendo se é um primeiro pagamento ou pagamentos subsequentes. Veja a seguir os requisitos para cada opção.

Processar primeiro pagamento

Para o primeiro pagamento na mensageria de pagamentos automáticos, envie um POST ao endpoint v1/payments, ou utilize um dos nossos SDKs.

Os campos descritos na tabela abaixo pertencem ao objeto point_of_interaction, que contém a informação específica para este tipo de pagamentos. Você deverá enviá-los seguindo as especificações indicadas para cada um. Caso deseje saber como enviar o resto da requisição, consulte nossa Referência de API.

<?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}}
        }
    }
}'
ParâmetroObrigatoriedadeTipo e descriçãoExemplo
typeObrigatório em todos os pagamentos sem CVVString. Indica o tipo de Point of Interaction (POI). Deve ser SUBSCRIPTIONS.SUBSCRIPTIONS
first_time_useObrigatório em todos os pagamentos sem CVVBoolean. Indica se é o primeiro pagamento da assinatura. Para o pagamento de validação, deve ser true. Para o restante dos pagamentos, false.false
subscription_idObrigatórioString. Identificador da assinatura. Sugerimos que este valor esteja composto pelo collector + um ID de assinatura único por usuário.COLLECTORPADRE-SUBSCRIPCION_ID
subscription_sequence.numberObrigatórioInteger. Indica o número do pagamento subsequente.3
subscription_sequence.totalObrigatório em pagamentos com recorrência pré-estabelecidaInteger. Indica o número total de pagamentos da assinatura. Para assinaturas permanentes, deve ser null12
invoice_period.periodObrigatório para pagamentos que envolvam recorrência pré-estabelecida e quando se envia invoice_period.type.Integer. Indica a frequência do pagamento recorrente.1
invoice_period.typeObrigatório para pagamentos que envolvam recorrência pré-estabelecida e quando se envia invoice_period.period.String. Indica o tipo de período do pagamento recorrente. É possível enviar qualquer valor que represente um período de tempo.daily, monthly, yearly, quarterly
user_presentOpcionalBoolean. Indica se houve intervenção do usuário no momento em que o pagamento foi criado.true ou false
billing_dateObrigatórioString. Data de cobrança.2024-03-16
payment_reference.idObrigatório quando first_time_use = falseString. ID do pagamento de validação com CVV, realizado para salvar o cartão. Não deve ser enviado para primeiros pagamentos.20792195335
transaction_amountObrigatórioNumber. Valor do pagamento.100
tokenObrigatórioString. Token do cartão12346622341
descriptionOpcionalString. Descrição do pagamentoPagamento de teste
payment_method_idObrigatórioString. Indica o identificador do meio de pagamento selecionado para realizar o pagamentomaster
payer.emailObrigatórioString. Email do pagadorbuyer@examplemail.com
payer.typeOpcionalString. Tipo de identificação do pagador associadoguest ou customer

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

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

Processar pagamentos subsequentes

Para os pagamentos subsequentes na mensageria de pagamentos automáticos, reenvie as informações através do objeto point_of_interaction ao endpoint v1/payments, levando em conta os novos requisitos listados a seguir, ou utilize um dos nossos SDKs. Lembre-se de que você pode acessar as informações para enviar o resto dos parâmetros da requisição através de nossa Referência de API.

ParâmetroObrigatoriedadeTipo e descriçãoExemplo
typeObrigatório em todos os pagamentos sem CVVString. Indica o tipo de Point of Interaction (POI). Deve ser SUBSCRIPTIONS.SUBSCRIPTIONS
first_time_useObrigatório em todos os pagamentos sem CVVBoolean. Indica se é o primeiro pagamento da assinatura. Para os pagamentos subsequentes deve ser false, porque não é a primeira transação.false
subscription_idObrigatórioString. Identificador da assinatura. Sugerimos que este valor esteja composto pelo collector + um ID de assinatura único por usuário.COLLECTORPADRE-SUBSCRIPCION_ID
subscription_sequence.numberObrigatórioInteger. Indica o número do pagamento atual.3
subscription_sequence.totalObrigatório em pagamentos com recorrência pré-estabelecidaInteger. Indica o número total de pagamentos da assinatura. Para assinaturas permanentes, deve ser null12
invoice_period.periodObrigatório para pagamentos que envolvam recorrência pré-estabelecida e quando se envia invoice_period.type.Integer. Indica a frequência do pagamento recorrente.1
invoice_period.typeObrigatório para pagamentos que envolvam recorrência pré-estabelecida e quando se envia invoice_period.period.String. Indica o tipo de período do pagamento recorrente. É possível enviar qualquer valor que represente um período de tempo.daily, monthly, yearly, quarterly
user_presentOpcionalBoolean. Indica se houve intervenção do usuário no momento em que o pagamento foi criado.true ou false
billing_dateObrigatórioString. Data de cobrança.2024-03-16
payment_reference.idObrigatório quando first_time_use = falseString. ID do primeiro pagamento de validação com CVV, realizado para salvar o cartão. Deve ser enviado para os pagamentos subsequentes e deve ser sempre o ID desse primeiro pagamento.20792195335
transaction_amountObrigatórioNumber. Valor do pagamento.100
tokenObrigatórioString. Token do cartão12346622341
descriptionOpcionalString. Descrição do pagamentoPagamento de teste
payment_method_idObrigatórioString. Indica o identificador do meio de pagamento selecionado para realizar o pagamentomaster
payer.emailObrigatórioString. Email do pagadorbuyer@examplemail.com
payer.typeOpcionalString. Tipo de identificação do pagador associadoguest ou customer

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

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

Erros frequentes

Alguns campos a serem enviados na configuração da mensageria de Pagamentos automáticos apresentam certas particularidades que devem ser levadas em consideração para evitar erros nas requisições à API.

Veja a seguir quais são os campos e como evitar esses erros.