Modelo de integración
Checkout API ahora procesa pagos con Orders. Se trata de una API diseñada para simplificar tu desarrollo con Mercado Pago: con una única integración, podrás acceder a diversas soluciones de pago.
Además, la API hace que el código de integración sea más intuitivo y proporciona mensajes de error más detallados, facilitando el proceso de desarrollo.
Diferencias en el procesamiento
Anteriormente, los pagos a través de Checkout API eran procesados exclusivamente por la API de Pagos. Ahora, también es posible procesarlos mediante Orders, que ofrece una alternativa eficiente y sencilla para la integración.
Ve a continuación las principales diferencias entre las dos opciones.
| Funcionalidad | API de Pagos | API de Orders |
| Procesamiento del pago | Automático (crea y procesa tu transacción). | Automático y manual (eligiendo cuándo procesar la transacción). |
| Transacciones | Una transacción por solicitud. | Múltiples transacciones por solicitud. |
| Operaciones | Pagos online. | Pagos online y Pagos presenciales (Point de Mercado Pago y Código QR). |
| Notificaciones | Configuración avanzada por notification_url. | Configuración más simple a partir de la sección de Notificaciones en Tus integraciones. |
| Validación de errores | Retorna un error a la vez. | Retorna una lista con todos los errores en la solicitud. |
Modos de procesamiento de Orders
Una order de pagos online puede ser creada para ser procesada de dos modos: Modo automático y Modo manual.
La definición del modo de procesamiento se realizará al momento de crear la order mediante el parámetro processing_mode. Su valor debe ser automatic para procesamientos automáticos, o manual para procesar la order de forma manual. Consulta a continuación las características de cada modo.
capture_mode indica cómo se procesará la order y define si la respuesta a la creación tendrá un estado final o intermedio. Solo es aplicable cuando processing_mode es automatic. En modo manual, define si será necesario capturar posteriormente el valor autorizado. Para más detalles, consulta la Referencia de APIAPI.El modo automático es el modo predeterminado de la aplicación. A través suyo, la transacción se completa en una sola etapa y las modificaciones son limitadas. Está indicado para escenarios en los que toda la información necesaria para completar la transacción ya está disponible en el momento de crear la order, incluidos datos del comprador, ítems e información del medio de pago debidamente tokenizada.
En este flujo, toda la información se envía en una única solicitud y la API es responsable de orquestar la comunicación con las capas procesadoras. El estado devuelto en la respuesta de creación de la order dependerá de la configuración del parámetro capture_mode.
Para crear la order en modo automático, envía el campo processing_mode, responsable de definir el formato de creación y procesamiento de la transacción, como automatic. En el objeto transactions, el nodo payments debe contener el objeto payment_method completo, incluido el token de la tarjeta generado vía SDK o API, según el ejemplo a continuación:
body
{ "type": "online", "processing_mode": "automatic", "external_reference": "order_oneshot_123", "total_amount": 1000, "payer": { "email": "comprador@teste.com" }, "transactions": { "payments": [ { "amount": 1000, "payment_method": { "id": "master", "type": "credit_card", "token": "677859ef5f18ea7e3a87c41d02c3fbe3", "installments": 12 } } ] } }
La API devuelve el objeto de la order con el estado de la transacción ya actualizado (por ejemplo, processed o accredited):
json
{ "id": "01JC1KVZ0WJY8Y4WA7MZAD5S2T", "status": "processed", "status_detail": "accredited", "transactions": { "payments": [ { "id": "pay_01JC1KVZ0WJY8Y4WA7MZG3A8F2", "status": "processed", "status_detail": "accredited", "payment_method": { "id": "master", "type": "credit_card", "installments": 12 } } ] } }
Las operaciones permitidas son:
- Crear y procesar orderAPI: responsable por la creación de la order y el procesamiento de la transacción en simultáneo.
- Obtener orderAPI: permite obtener información sobre una order, incluido su status en tiempo real.
- Buscar orderAPI: permite buscar orders de forma masiva, utilizando diversos filtros e información de paginación.
- Capturar orderAPI: permite capturar el monto autorizado de una order. Esta opción solo es válida para tarjetas de crédito.
- Cancelar orderAPI: responsable de la cancelación de una order ya existente, pero que aún no ha sido procesada.
- Reembolsar orderAPI: permite el reembolso total o parcial de un pago. La order será reembolsada totalmente si todas las transacciones son reembolsadas por completo.
- Reembolso total: no se debe indicar un monto a reembolsar en el
bodyde la solicitud, que debe ir vacío. - Reembolso parcial: se debe especificar la cantidad a reembolsar en el
bodyde la solicitud, junto con el ID de la transacción. Todas las otras transacciones permanecerán como están y solo la transacción modificada será reembolsada.
- Reembolso total: no se debe indicar un monto a reembolsar en el