Recursos para IA
Pagos con recurrencia programada
Los pagos con recurrencia programada permiten realizar cobros automáticos en intervalos definidos, utilizando los datos previamente guardados del medio de pago sin necesidad de una nueva interacción del usuario. La lógica de recurrencia es definida y gestionada por el vendedor a través de la creación de los pagos, adaptándose a las necesidades de negocio.
Este modelo está indicado para cobros recurrentes, como suscripciones, planes y servicios continuos.
Para procesar pagos con recurrencia programada, envía un POST al endpoint /v1/ordersAPI. Deberás enviar tu Access TokenClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación. y la información detallada a continuación para este tipo de pagos.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "type": "online", "external_reference": "ext_ref_1234", "total_amount": "1000.00", "processing_mode": "automatic_async", "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "amount": "1000.00", "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943", "retries": 3, "subscription": { "id": "subscription-id", "sequence": { "number": 1, "total": 12 }, "invoice": { "id": "00000000000", "billing_date": "2024-09-02", "period": { "interval": 1, "type": "monthly" } } } }, "stored_credential": { "payment_initiator": "customer", "reason": "recurring", "previous_transaction_reference": "REF-987-654-321", "first_payment": false } } ] } }'
| Atributo | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Hace referencia a tu clave privada, el Access TokenClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación.. | Requerido |
X-Idempotency-Key | Header | Llave de idempotencia. Esta llave garantiza que cada solicitud sea procesada una única vez, evitando duplicidades. Utiliza un valor exclusivo en el encabezado de tu solicitud, como un UUID V4 o strings aleatorias. | Requerido |
type | Body. String | Tipo de order, asociada a la solución de Mercado Pago para la que se crea. Para pagos online con tarjetas, el único valor posible es online. | Requerido |
external_reference | Body. String | Es una referencia externa de la order. Puede ser, por ejemplo, un hashcode del Banco Central, funcionando como identificador de origen de la transacción. Este campo debe tener como máximo 64 caracteres y estos solo pueden ser números, letras, guiones medios (-) y guiones bajos (_). Caracteres especiales como ([ ], (), '', @) no son permitidos. | Requerido |
total_amount | Body. String | Monto total de la transacción. | Requerido |
processing_mode | Body. String | Modo de procesamiento de la order. Los valores posibles son: - automatic, para crear y procesar la order en modo automático. - automatic_async, para crear la order con lógica de reintentos. Para más información, accede a Modos de procesamiento de Orders. | Opcional |
payer.customer_id | Body. String | Identificador del cliente que realizará el pago. Es obtenido en la etapa Registrar medio de pago, al momento de crear el cliente, ya sea en registros con un primer pago o registros para pagos posteriores. | Requerido |
transactions.payments.amount | Body. String | Monto de la transacción. | Requerido |
transaction.payments.automatic_payments.payment_profile_id | Body. String | Identificador del perfil de pago del cliente. Obtenido en la etapa Registrar medio de pago, al crear el perfil de pago, ya sea en registros con un primer pago o registros para pagos posteriores. | Requerido |
transaction.payments.automatic_payments.retries | Body. Integer | Número de veces en las que se reintentará el pago en caso de falla inicial. Debe ser un número entre 1 y 5. Es un campo que solo será permitido en caso de que se haya definido processing_mode=automatic_async. Adicionalmente, si el perfil de pago del cliente tiene configurado el campo max_day_overdue, la configuración de reintentos establecida para retries no tendrá prioridad. | Opcional |
transaction.payments.automatic_payments.subscription.id | Body. String | Identificador de la suscripción. Sugerimos que este valor esté compuesto por el collector + un ID de suscripción único por usuario. | Requerido si sequence_control es manual |
transaction.payments.automatic_payments.subscription.sequence.number | Body. Integer | Indica el número del pago subsecuente. | Requerido si sequence_control es manual |
transaction.payments.automatic_payments.subscription.sequence.total | Body. Integer | Indica el número total de pagos de la suscripción. Para suscripciones permanentes, debe ser null. | Requerido si sequence_control es manual |
transaction.payments.automatic_payments.subscription.invoice.id | Body. String | Identificador de la invoice asociada al ciclo de cobro. | Requerido si sequence_control es manual |
transaction.payments.automatic_payments.subscription.invoice.billing_date | Body. String | Fecha de facturación correspondiente al ciclo de la suscripción. | Requerido si sequence_control es manual |
transaction.payments.automatic_payments.subscription.invoice.period.interval | Body. Number | Intervalo de tiempo entre cada cobro. | Requerido si sequence_control es manual |
transaction.payments.automatic_payments.subscription.invoice.period.type | Body. String | Tipo de período de la recurrencia. Los valores posibles son daily, weekly o monthly. | Requerido si sequence_control es manual |
transaction.payments.stored_credentials.payment_initiator | Body. String | Identifica a quien inicia la transacción. Los valores posibles son: - customer, cuando la transacción es iniciada por el cliente. - merchant, cuando la transacción es iniciada por el vendedor. | Requerido |
transaction.payments.stored_credentials.reason | Body. String | Identificador del tipo de pago, que es la razón por la que se lo está almacenando. El único valor posible para pagos con recurrencia programada es recurring. Si envías este campo y el perfil de pago tiene definido el campo sequence_control como auto, no es necesario enviar el nodo automatic_payments.subscription, pues la información de la recurrencia será gestionada automáticamente por el sistema. Dirígete a Gestionar pagos con recurrencia programada para más información | Opcional |
transaction.payments.stored_credentials.previous_transaction_reference | Body. String | Código de referencia de la transacción previa a la que está siendo procesada, si la hubiera. Debe ser enviado a partir del segundo pago procesado para el mismo cliente. | Requerido cuando first_payment: false |
transaction.payments.stored_credentials.first_payment | Body. Boolean | Indica si se trata del procesamiento de un primer pago (true) o si es un pago posterior (false). | Opcional |
Si la solicitud es enviada correctamente, el pago se habrá creado y la respuesta se verá como el ejemplo a continuación.
json
{ "id": "ORD01J6TC8BYRR0T4ZKY0QR39WGYE", "processing_mode": "automatic_async", "external_reference": "ext_ref_1234", "total_amount": "200.00", "country_code": "MEX", "user_id": "1245621468", "created_date": "2024-09-02T22:04:01.880469Z", "last_updated_date": "2024-09-02T22:04:04.429289Z", "type": "online", "status": "processing", "status_detail": "processing", "capture_mode": "automatic_async", "integration_data": { "application_id": "4599991948843755" }, "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "id": "PAY01J6TC8BYRR0T4ZKY0QRTZ0E24", "reference_id": "74e9f7137a3246d3a3ad607c82da9880", "amount": "200.00", "status": "processing", "status_detail": "processing", "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943", "subscription": { "id": "subscription-id", "sequence": { "number": 1, "total": 12 }, "invoice": { "id": "invoice-id", "billing_date": "2024-09-02", "period": { "interval": 1, "type": "month" } } } }, "stored_credential": { "payment_initiator": "customer", "reason": "recurring", "previous_transaction_reference": "REF-987-654-321", "first_payment": false } } ] } }
Puedes consultar el detalle de los estados posibles a ser devueltos en la respuesta dirigiéndote a las secciones Estado de la order y Estado de la transacción, respectivamente. Adicionalmente, puedes consultar los Errores posibles al enviar esta solicitud.
Gestionar pagos con recurrencia programada
Cuando creas un pago con recurrencia programada, ciertos campos vinculados a la frecuencia del pago son requeridos para mejorar la tasa de aprobación. En la API de Orders, estos campos son los contenidos en el nodo subscription.
Con el apoyo de la API de Perfiles, la gestión de esta información puede realizarse de dos formas: automática o manual.
Para automatizar la gestión de la información relativa a la recurrencia del pago, y evitar enviar esta información manualmente, debes:
- Definir el campo
sequence_controldel perfil de pago del cliente comoauto. Si necesitas más información sobre cómo hacerlo, accede a nuestra Referencia de API. - Crear el pago enviando el valor
recurringpara el campotransaction.payments.stored_credentials.reason.
De esta manera, no será necesario enviar la información contenida en el nodo transaction.payments.automatic_payments.subscription ya que será gestionada automáticamente por el sistema.