Integrar el procesamiento de pagos

El procesamiento de pagos con Mercado Pago Point integrado a tu punto de venta se basa en la creación de orders que contienen asociada una transacción de pago. Al crear una order, esta será cargada automáticamente a la terminal indicada, y el comprador podrá realizar su pago de manera presencial.

El procesamiento de pagos integrado con Mercado Pago Point te permitirá crear orders, procesarlas, cancelarlas o bien realizar reembolsos y consultar su información o actualizaciones de estado.

Si deseas configurar que las cuotas sean con o sin interés, previo a crear una order, deberás configurarlas en tu cuenta de Mercado Pago.

Crear una order

Para comenzar a procesar pagos con Point desde los puntos de venta, primero necesitas identificar a qué terminal deseas asignar la order. Recuerda que esta terminal debe haber sido configurada en modo PDV.

Para eso, envía un GET el endpoint Obtener lista de terminalsAPI. Utiliza tu Access Token de producciónClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend en ambientes de desarrollo y al momento de recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Producción > Credenciales de producción., en caso de estar realizando una integración propia, o el Access Token obtenido por medio de OAuthClave privada generada mediante el protocolo de seguridad OAuth, que permite gestionar integraciones en nombre de terceros. Para más información, dirígete a la documentación.OAuth, en caso de estar realizando una integración para terceros.

Recomendamos filtrar la búsqueda utilizando los query params opcionales query params store_id y pos_id, identificadores de la tienda y la caja devueltos en la respuesta a la creación de cada una.

curl
curl -X GET \
    'https://api.mercadopago.com/terminals/v1/list?limit=50&offset=1&store_id=1235456678&pos_id=1235456678' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer TEST-232********97488-12********26f67454********f4c8b49c********9526408'

La respuesta a esta solicitud te permitirá ver las terminales asociadas a tu cuenta y seleccionar la que deseas usar para crear tu order. Podrás identificarla por medio de los últimos caracteres del campo id, que deberán coincidir con el serial de la etiqueta trasera de la terminal física.

json
{
  "data": {
    "terminals": [
      {
        "id": "PAX_A910__SMARTPOS1234345545",
        "pos_id": 47792476,
        "store_id": "47792478",
        "external_pos_id": "SUC0101POS",
        "operating_mode": "PDV"
      }
    ]
  },
  "paging": {
    "total": 1,
    "offset": 0,
    "limit": 50
  }
}

Luego, deberás crear la order. Para eso, envía un POST al endpoint /v1/ordersAPI, cuidando de incluir tu Access Token de producciónClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend en ambientes de desarrollo y al momento de recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Producción > Credenciales de producción., en caso de estar realizando una integración propia, o el Access Token obtenido por medio de OAuthClave privada generada mediante el protocolo de seguridad OAuth, que permite gestionar integraciones en nombre de terceros. Para más información, dirígete a la documentación.OAuth, en caso de estar realizando una integración para terceros, y el id de la terminal a la que quieres asignar la order, obtenido en el paso anterior.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
    -H 'Authorization: Bearer TEST-232********97488-12********26f67454********f4c8b49c********9526408' \
    -d '{
        "type": "point",
        "external_reference": "ext_ref_1234",
        "transactions": {
            "payments": [
                {
                    "amount": "24.00"
                }
            ]
        },
        "config": {
            "point": {
                "terminal_id": "PAX_A910__SMARTPOS1423",
                "print_on_terminal": "no_ticket"
            },
            "payment_method": {
                "default_type": "credit_card"
            }
        },
        "description": "Point Smart 2",
        "integration_data": {
            "platform_id": "dev_1234567890",
            "integrator_id": "dev_1234567890",
            "sponsor": {
                "id": "446566691"
            }
        },
        "taxes": [
            {
                "payer_condition": "payment_taxable_iva"
            }
        ]
    }'

Consulta en la tabla a continuación las descripciones de los parámetros que poseen alguna particularidad importante que debe destacarse.

Atributo	Tipo	Descripción	Obligatoriedad
`Authorization`	Header	Hace referencia o bien a tu Access Token de producciónClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend en ambientes de desarrollo y al momento de recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Producción > Credenciales de producción., en caso de estar realizando una integración propia, o al obtenido por medio de OAuthClave privada generada mediante el protocolo de seguridad OAuth, que permite gestionar integraciones en nombre de terceros. Para más información, dirígete a la documentación.OAuth.	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, asociado a la solución de Mercado Pago para la que se crea. Para pagos con Mercado Pago Point, el único valor posible es `point`.	Requerido
`external_reference`	Body.String	Es una referencia externa de la order, asignada al momento de su creación. Debe ser un valor único para cada order, y no puede contener datos PII. El límite máximo permitido es de 64 caracteres y los permitidos son: letras mayúsculas y minúsculas, números y los símbolos de guion (-) y guion bajo (_).	Requerido
`transaction.payments.amount`	Body.String	Monto total de la order de pago. Debe ser un número entero, sin decimales.	Requerido
`config.point.terminal_id`	Body.String	Identificador de la terminal Point que obtendrá la order. Debes enviarlo tal cual fue devuelto en el llamado Obtener terminalsAPI, como en el siguiente ejemplo: "PAX_A910__SMARTPOS123456789".	Requerido

Para conocer en detalle todos los parámetros a ser enviados en esta requisición, consulta nuestra Referencia de API.

Si la solicitud fue exitosa, la respuesta devolverá una order con estado created.

json
{
  "id": "ORD00001111222233334444555566",
  "type": "point",
  "user_id": "5238400195",
  "external_reference": "ext_ref_1234",
  "description": "Point Smart 2",
  "processing_mode": "automatic",
  "country_code": "CHL",
  "integration_data": {
    "application_id": "1234567890",
    "platform_id": "dev_1234567890",
    "integrator_id": "dev_1234567890",
    "sponsor": {
      "id": "446566691"
    }
  },
  "status": "created",
  "status_detail": "created",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
    "point": {
      "terminal_id": "PAX_A910__SMARTPOS1423",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": "6",
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24",
        "status": "created"
      }
    ]
  },
  "taxes": [
    {
      "payer_condition": "payment_taxable_iva"
    }
  ]
}

Como la order es la base del procesamiento del pago, es importante que guardes su id y el id del pago (transactions.payments.id) obtenidos al crearla, porque te permitirán realizar otras operaciones y consultar tus notificaciones de manera adecuada. Adicionalmente, puedes consultar nuestra documentación en la sección Recursos para conocer mejor sobre los posibles status de una order y de una transacción.

Esta order creada será obtenida de manera automática a la terminal a la que fue asignada. Así, el pago podrá ser realizado por el comprador en el punto de venta físico y posteriormente procesado. Ten en cuenta que, para esto, el tiempo transcurrido entre la creación de la order y su pago debe ser menor a 15 minutos, pues pasado este lapso, la order expirará y no será posible pagarla.

Cancelar una order

La cancelación de una order se puede realizar por dos vías, dependiendo del estado en el que se encuentre.

Si el status de la order es created, su cancelación debe realizarse vía API.
Si su status es at_terminal, significa que la order ya fue obtenida por la terminal y deberá ser cancelada desde allí.

Si una order no es procesada a los 15 minutos de haber sido creada, su status pasará a ser expired y ya no será posible cancelarla.
Además, en el caso de cancelaciones desde la terminal, es importante tener previamente configuradas tus notificaciones Webhooks para recibir el aviso de la cancelación en tu sistema, lo que te permitirá mantener tu conciliación.

Elige la opción que mejor se adecúe a tus necesidades para conocer cómo cancelar tu order.

Si deseas cancelar una order con estado created, deberás enviar un POST al endpoint Cancelar order por ID, cuidando de incluir tu Access Token de producciónClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend en ambientes de desarrollo y al momento de recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Producción > Credenciales de producción., en caso de estar realizando una integración propia, o el Access Token obtenido por medio de OAuthClave privada generada mediante el protocolo de seguridad OAuth, que permite gestionar integraciones en nombre de terceros. Para más información, dirígete a la documentación.OAuth, en caso de estar realizando una integración para terceros, y el id de la order cuya cancelación quieres realizar, obtenido en la respuesta a su creación.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders/ORDER_ID/cancel' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
    -H 'Authorization: Bearer ACCESS_TOKEN'

Si la solicitud fue exitosa, la respuesta mostrará un status=canceled.

json
{
  "id": "ORD0000ABCD222233334444555566",
  "user_id": "5238400195",
  "type": "point",
  "external_reference": "ext_ref_1234",
  "description": "Point Smart 2",
  "country_code": "CHL",
  "processing_mode": "automatic",
  "integration_data": {
    "application_id": "1234567890",
    "platform_id": "dev_1234567890",
    "integrator_id": "dev_1234567890",
    "sponsor": {
      "id": "446566691"
    }
  },
  "status": "canceled",
  "status_detail": "canceled",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
    "point": {
      "terminal_id": "PAX_A910__SMARTPOS1423",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": "6",
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "status": "canceled",
        "status_detail": "canceled_by_api"
      }
    ]
  },
  "taxes": [
    {
      "payer_condition": "payment_taxable_iva"
    }
  ]
}

Reembolsar una order

Si lo deseas, puedes reembolsar una order creada para Mercado Pago Point a través de nuestra API. Este reembolso será siempre una devolución total del valor de la order.

Una order pagada con tarjeta podrá ser reembolsada vía API hasta 90 días después de realizado su pago. Para los pagos realizados mediante Edenred, solo podrán realizarse reembolsos vía API hasta las 23:59:59 del mismo día en que fue creado el pago y para los pagos efectuados con Pluxee, los reembolsos podrán ser realizados vía API hasta 5 días hábiles desde la creación del pago. Pasado ese tiempo, ya no será posible hacer la devolución.

Para realizar un reembolso total de una order, envía un POST al endpoint Reembolsar una orderAPI, cuidando de incluir tu Access Token de producciónClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend en ambientes de desarrollo y al momento de recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Producción > Credenciales de producción., en caso de estar realizando una integración propia, o el Access Token obtenido por medio de OAuthClave privada generada mediante el protocolo de seguridad OAuth, que permite gestionar integraciones en nombre de terceros. Para más información, dirígete a la documentación.OAuth, en caso de estar realizando una integración para terceros, y el id de la order que estás queriendo reembolsar, obtenido en la respuesta a su creación.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders/ORDER_ID/refund' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
    -H 'Authorization: Bearer ACCESS_TOKEN'

Si la solicitud fue exitosa, la respuesta mostrará un status=refunded, y traerá consigo un nuevo nodo, transactions.refunds, que contendrá los detalles de la devolución, junto con el identificador del pago original y de la transacción de reembolso.

json
{
  "id": "ORD0000ABCD222233334444555566",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01J67CQQH5904WDBVZEM1234D",
        "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "reference_id": "12345678",
        "amount": "38.00",
        "status": "processed"
      }
    ]
  }
}

Consultar datos de una order

Si lo necesitas, puedes consultar los datos de una order y sus transacciones asociadas, sean pagos o reembolsos, incluídos sus estados o valores.

Si bien la utilización recurrente de esta consulta vía API no es recomendada, sí puede resultar útil en caso de que requieras información adicional sobre la order.

Para consultar los datos de una order, envía un GET al endpoint Obtener order por IDAPI, cuidando de incluir tu Access Token de producciónClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend en ambientes de desarrollo y al momento de recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación > Producción > Credenciales de producción., en caso de estar realizando una integración propia, o el Access Token obtenido por medio de OAuthClave privada generada mediante el protocolo de seguridad OAuth, que permite gestionar integraciones en nombre de terceros. Para más información, dirígete a la documentación.OAuth, en caso de estar realizando una integración para terceros, y el id de la order cuya información quieres consultar, obtenido en la respuesta a su creación.

Ten en cuenta que esta solicitud solo permitirá consultar las orders creadas con una antigüedad menor a 3 meses. Si necesitas información sobre orders anteriores, te recomendamos que contactes a nuestro servicio de atención al cliente para obtener asistencia adicional.

curl
curl -X GET \
    'https://api.mercadopago.com/v1/orders/ORDER_ID' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ACCESS_TOKEN'

Si la solicitud fue exitosa, la respuesta te devolverá toda la información de la order, incluidos su estado y el estado del pago y/o del reembolso en tiempo real:

json
{
  "id": "ORD00001111222233334444555566",
  "user_id": "5238400195",
  "type": "point",
  "external_reference": "ext_ref_1234",
  "processing_mode": "automatic",
  "description": "Point Smart 2",
  "country_code": "CHL",
  "integration_data": {
    "application_id": "1234567890",
    "platform_id": "dev_1234567890",
    "integrator_id": "dev_1234567890",
    "sponsor": {
      "id": "446566691"
    }
  },
  "status": "refunded",
  "status_detail": "refunded",
  "created_date": "2024-09-10T14:26:42.109320977Z",
  "last_updated_date": "2024-09-10T14:26:42.109320977Z",
  "config": {
    "point": {
      "terminal_id": "PAX_A910__SMARTPOS1423",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card",
      "default_installments": "6",
      "installments_cost": "seller"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "refunded_amount": "38.00",
        "tip_amount": "14.00",
        "paid_amount": "38.00",
        "status": "refunded",
        "status_detail": "created",
        "reference_id": "12345678",
        "payment_method": {
          "type": "credit_card",
          "installments": 1,
          "id": "master"
        }
      }
    ],
    "refunds": [
      {
        "id": "REF01J67CQQH5904WDBVZEM1234D",
        "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "reference_id": "12345678",
        "amount": "38.00",
        "status": "processed"
      }
    ]
  },
  "taxes": [
    {
      "payer_condition": "payment_taxable_iva"
    }
  ]
}

Configurar terminal

Descubre cómo configurar tu terminal Point para operar de manera integrada con tu PDV.

Configurar notificaciones

Las notificaciones son mensajes enviados por el servidor de Mercado Pago desde eventos que se realizan en tu aplicación.

Documentación

¿Comenzando ahora?

Recursos

Soporte

Comunidad

Integrar el procesamiento de pagos

Navegación

Recursos y Comunidad

Mercado Pago

País e idioma