Procesar pagos (vía Advanced Payments API)
Con Advanced Payments API, los pagos se procesan a partir del payer_token obtenido en la vinculación, debitando el monto directamente de la billetera del comprador. Antes de procesar pagos, es necesario haber concluido el flujo de vinculación y obtenido el payer_token. Si aún no lo has hecho, consulta la sección Configurar la vinculación.
Para procesar un pago, envía una solicitud al endpoint /v1/advanced_paymentsPOST, incluyendo tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En la integración con Wallet Connect, en un primer momento tu Access Token será entregado por el equipo responsable de crear tu aplicación en Mercado Pago, pero después de tener acceso a esa aplicación podrás visualizarlo en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y el token de pago del comprador.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/advanced_payments' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "wallet_payment": { "transaction_amount": 550, "description": "Smartphone", "external_reference": "Payment_seller_123" }, "payer": { "token": "PAYER_TOKEN", "type_token": "wallet-tokens" }, "capture": true }'
Consulta en la tabla a continuación las descripciones de los parámetros que son obligatorios en la solicitud y aquellos que, aunque son opcionales, tienen alguna particularidad importante que debe destacarse.
| Parámetro | Tipo | Descripción | Obligatoriedad |
X-Idempotency-Key | Header | Clave de idempotencia. Esta clave garantiza que cada solicitud sea procesada solo una vez, evitando la creación de dos pagos idénticos. Usa un valor exclusivo en el header de la solicitud, como un UUID V4 o una string aleatoria. | Obligatorio |
Authorization | Header | Se refiere a tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En la integración con Wallet Connect, en un primer momento tu Access Token será entregado por el equipo responsable de crear tu aplicación en Mercado Pago, pero después de tener acceso a esa aplicación podrás visualizarlo en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`.. | Obligatorio |
X-Meli-Session-Id | Header | Identificador del dispositivo del comprador en el momento de la compra, utilizado para mejorar la seguridad y aumentar la tasa de aprobación del pago. | Opcional |
wallet_payment.transaction_amount | Body. Number | Monto del pago. | Obligatorio |
wallet_payment.description | Body. String | Breve descripción del pago. | Opcional |
wallet_payment.external_reference | Body. String | Referencia personalizada del vendedor, utilizada para correlacionar un pago de Mercado Pago con un pedido interno. | Opcional |
wallet_payment.statement_descriptor | Body. String | Texto que aparece en el extracto del comprador junto con el monto y la fecha del cargo. Acepta como máximo 50 caracteres alfanuméricos. | Opcional |
payer.token | Body. String | Token de pago (payer_token) obtenido en el flujo de vinculación, utilizado para cobrar la billetera del comprador. | Obligatorio |
payer.type_token | Body. String | Tipo del token. Para pagos vía Wallet Connect, el valor debe ser wallet-tokens. | Obligatorio |
capture | Body. Boolean | Indica si el pago debe capturarse inmediatamente. En pagos de dos pasos, envía false para reservar el monto y captúralo posteriormente enviando true en una solicitud separada. | Opcional |
binary_mode | Body. Boolean | Cuando está activado, el pago solo puede ser aprobado o rechazado. De lo contrario, el pago puede quedar pendiente. | Opcional |
Si la solicitud es exitosa, la respuesta devolverá el estado 201 con el pago creado.
json{ "id": 10267812, "payments": [ { "id": 3870106238, "status": "approved", "status_detail": "accredited", "payment_type_id": "account_money", "transaction_amount": 550.0 } ], "wallet_payment": { "transaction_amount": 550.0, "description": "Smartphone", "external_reference": "Payment_seller_123" } }
Entre los parámetros devueltos, tenemos los indicados en la tabla a continuación.
| Parámetro | Tipo | Descripción |
id | Number | Identificador único del pago creado. Utilízalo para consultar, capturar o reembolsar el pago. |
payments.status | String | Devuelve el status del pago. Los valores posibles son approved, in_process y rejected. |
payments.status_detail | String | Detalla el motivo del status del pago. En los pagos aprobados, devuelve accredited. |
payments.transaction_amount | Number | Monto efectivamente cobrado al comprador. |
payments puede ser rejected según el estado de la cuenta del comprador, incluso cuando la solicitud devuelve 201. Verifica siempre el status de cada pago antes de confirmar la compra al comprador.La consulta permite obtener los datos actualizados de un pago realizado por Advanced Payments API, incluyendo su status.
Para realizar la consulta, envía una solicitud al endpoint /v1/advanced_payments/{advanced_payment_id}GET, incluyendo tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En la integración con Wallet Connect, en un primer momento tu Access Token será entregado por el equipo responsable de crear tu aplicación en Mercado Pago, pero después de tener acceso a esa aplicación podrás visualizarlo en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y el advanced_payment_id obtenido en la respuesta a su creación.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/advanced_payments/{{ADVANCED_PAYMENT_ID}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Parámetro | Tipo | Descripción | Obligatoriedad |
advanced_payment_id | Path. Number | Identificador único del pago que se desea consultar, obtenido en la respuesta a su creación. | Obligatorio |
Authorization | Header | Se refiere a tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En la integración con Wallet Connect, en un primer momento tu Access Token será entregado por el equipo responsable de crear tu aplicación en Mercado Pago, pero después de tener acceso a esa aplicación podrás visualizarlo en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`.. | Obligatorio |
Si la solicitud es exitosa, la respuesta devolverá el estado 200 con los datos actualizados del pago.
json{ "id": 10267812, "wallet_payment": { "transaction_amount": 550.0, "description": "Smartphone", "external_reference": "Payment_seller_123" }, "payments": [ { "id": 3870106238, "status": "approved", "status_detail": "accredited", "payment_type_id": "account_money", "transaction_amount": 550.0 } ] }