Mensajería de pagos automáticos
La mensajería de pagos automáticos, o mensajería de suscripción, involucra información de los pagos recurrentes (ID de pagos anteriores, ID de la suscripción, número de veces que se generará el pago y POI con type = SUBSCRIPTIONS) que se envía a la API de Pagos con el objetivo de aumentar la tasa de aprobación para este tipo de pagos.
Configuración
La información que necesita ser enviada en la solicitud de crear pago para la mensajería de pagos automáticos varía dependiendo de si es un primer pago, o si son pagos subsecuentes. Ve a continuación los requisitos para cada opción.
Procesar el primer pago
Para el primer pago en la mensajería de pagos automáticos, envía un POST al endpoint v1/payments, o utiliza uno de nuestros SDKs.
Los campos descriptos en la tabla debajo pertenecen al objeto point_of_interaction, que es el que contiene la información específica para este tipo de pagos. Deberás enviarlos siguiendo las especificaciones indicadas para cada uno. Si deseas saber cómo enviar el resto de la solicitud, consulta nuestra Referencia 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ámetro | Requerido | Tipo y descripción | Ejemplo |
type | Requerido en todos los pagos sin CVV | String. Indica el tipo de Point of Interaction (POI). Debe ser SUBSCRIPTIONS. | SUBSCRIPTIONS |
first_time_use | Requerido en todos los pagos sin CVV | Boolean. Indica si es el primer pago de la suscripción. Para el pago de validación, debe ser true. Para el resto de los pagos, false. | false |
subscription_id | Requerido | String. Identificador de la suscripción. Sugerimos que este valor esté compuesto por el collector + un ID de suscripción único por usuario. | COLLECTORPADRE-SUBSCRIPCION_ID |
subscription_sequence.number | Requerido | Integer. Indica el número del pago subsecuente. | 3 |
subscription_sequence.total | Requerido en pagos con recurrencia preestablecida | Integer. Indica el número total de pagos de la suscripción. Para suscripciones permanentes, debe ser null | 12 |
invoice_period.period | Requerido para pagos que impliquen una recurrencia preestablecida y cuando se envía invoice_period.type. | Integer. Indica la frecuencia del pago recurrente. | 1 |
invoice_period.type | Requerido para pagos que impliquen una recurrencia preestablecida y cuando se envía invoice_period.period. | String. Indica el tipo de periodo del pago recurrente. Puedes enviar cualquier valor que represente un período de tiempo. | daily, monthly, yearly, quarterly |
user_present | Opcional | Boolean. Indica si hubo intervención del usuario en el momento en que se creó el pago. | true o false |
billing_date | Requerido | String. Fecha de facturación. | 2024-03-16 |
payment_reference.id | Requerido cuando first_time_use = false | String. ID del pago de validación con CVV, realizado para guardar la tarjeta. No debe ser enviado para primeros pagos. | 20792195335 |
transaction_amount | Requerido | Number. Monto del pago. | 100 |
token | Requerido | String. Token de tarjeta | 12346622341 |
description | Opcional | String. Descripción de pago | Pago de prueba |
payment_method_id | Requerido | String. Indica el identificador del método de pago seleccionado para realizar el pago | master |
payer.email | Requerido | String. Email del pagador | buyer@examplemail.com |
payer.type | Opcional | String. Tipo de identificación del pagador asociado | guest o customer |
Si la solicitud fue correcta, la respuesta se verá como el siguiente ejemplo:
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" } } }
Procesar pagos subsecuentes
Para los pagos subsecuentes en la mensajería de pagos automáticos, reenvía la información a través del objeto point_of_interaction al endpoint v1/payments, teniendo en cuenta los nuevos requisitos enumerados a continuación, o utiliza uno de nuestros SDKs. Recuerda que puedes acceder a la información para enviar el resto de los parámetros de la solicitud a través de nuestra Referencia de API.
| Parámetro | Requerido | Tipo y descripción | Ejemplo |
type | Requerido en todos los pagos sin CVV | String. Indica el tipo de Point of Interaction (POI). Debe ser SUBSCRIPTIONS. | SUBSCRIPTIONS |
first_time_use | Requerido en todos los pagos sin CVV | Boolean. Indica si es el primer pago de la suscripción. Para los pagos subsecuentes debe ser false, porque no es la primera transacción. | false |
subscription_id | Requerido | String. Identificador de la suscripción. Sugerimos que este valor esté compuesto por el collector + un ID de suscripción único por usuario. | COLLECTORPADRE-SUBSCRIPCION_ID |
subscription_sequence.number | Requerido | Integer. Indica el número del pago actual. | 3 |
subscription_sequence.total | Requerido en pagos con recurrencia preestablecida | Integer. Indica el número total de pagos de la suscripción. Para suscripciones permanentes, debe ser null | 12 |
invoice_period.period | Requerido para pagos que impliquen una recurrencia preestablecida y cuando se envía invoice_period.type. | Integer. Indica la frecuencia del pago recurrente. | 1 |
invoice_period.type | Requerido para pagos que impliquen una recurrencia preestablecida y cuando se envía invoice_period.period. | String. Indica el tipo de periodo del pago recurrente. Puedes enviar cualquier valor que represente un período de tiempo. | daily, monthly, yearly, quarterly |
user_present | Opcional | Boolean. Indica si hubo intervención del usuario en el momento en que se creó el pago. | true o false |
billing_date | Requerido | String. Fecha de facturación. | 2024-03-16 |
payment_reference.id | Requerido cuando first_time_use = false | String. ID del primer pago de validación con CVV, realizado para guardar la tarjeta. Debe ser enviado para los pagos subsecuentes y debe ser siempre el ID de ese primer pago. | 20792195335 |
transaction_amount | Requerido | Number. Monto del pago. | 100 |
token | Requerido | String. Token de tarjeta | 12346622341 |
description | Opcional | String. Descripción de pago | Pago de prueba |
payment_method_id | Requerido | String. Indica el identificador del método de pago seleccionado para realizar el pago | master |
payer.email | Requerido | String. Email del pagador | buyer@examplemail.com |
payer.type | Opcional | String. Tipo de identificación del pagador asociado | guest o customer |
Si la solicitud fue correcta, la respuesta se verá como el siguiente ejemplo:
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" } } }
Errores frecuentes
Algunos campos a enviar en la configuración de la mensajería de Pagos automáticos comportan ciertas particularidades a tener en cuenta para evitar errores en las solicitudes a la API.
Ve a continuación cuáles son y cómo evitar estos errores.