Recursos para IA
Pagos únicos con tarjeta guardada
Los pagos únicos con tarjetas guardadas (Card on File) son pagos en los que se utilizan los datos registrados del medio de pago para realizar cargos ocasionales sin necesidad de que el usuario deba reingresar la información de la tarjeta.
Se trata de pagos que no tienen una recurrencia, sino que dependen de una acción del comercio o del cliente para ejecutarse, como pueden ser cobros automáticos en peajes o pagos en apps de delivery con tarjetas guardadas, respectivamente.
Para procesar pagos únicos con tarjetas guardadas, 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 }, "stored_credential": { "payment_initiator": "merchant", "reason": "card_on_file", "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 Modo 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.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 únicos con tarjetas guardadas es card_on_file. | 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" }, "stored_credential": { "payment_initiator": "merchant", "reason": "card_on_file", "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.