Integrate payment processing

Payment processing with Mercado Pago Point integrated into your point of sale is based on creating orders that have an associated payment transaction. When an order is created, it will be automatically loaded to the specified terminal, and the buyer will be able to make the payment in person.

Integrated payment processing with Mercado Pago Point will allow you to create orders, process them, cancel them, or make refunds and query their information or status updates.

If you want the installments set to be with or without interests, before creating an order, you must set them up in your Mercado Pago account.

Create an order

To start processing payments with Point from points of sale, you first need to identify which terminal you want to assign the order to. Remember that this terminal must be set to PDV mode.

For this, send a GET to the endpoint Get list of terminalsAPI. Use your Production Access TokenPrivate key of the application created in Mercado Pago, which is used in the backend in development environments and when receiving real payments. You can access it through Your integrations > Application details > Production > Production credentials., if you are doing your own integration, or the Access Token obtained via OAuthPrivate key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation.OAuth, if you are doing an integration for third parties.

We recommend filtering the search by using the optional query params store_id and pos_id, store and box identifiers returned in the response to the creation of each one.

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'

The response to this request will allow you to see the terminals associated with your account and select the one you want to use to create your order. You can identify it by the last characters of the id field, which should match the serial number on the back label of the physical terminal.

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
  }
}

Then, you'll need to create the order. For this, send a POST to the endpoint /v1/ordersAPI, making sure to include your Production Access TokenPrivate key of the application created in Mercado Pago, which is used in the backend in development environments and when receiving real payments. You can access it through Your integrations > Application details > Production > Production credentials., if you are doing your own integration, or the Access Token obtained through OAuthPrivate key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation.OAuth, if you are doing an integration for third parties, and the id of the terminal to which you want to assign the order, obtained in the previous step.

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"
                }
            ]
        },
        "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"
            }
        ]
    }'

Check the table below for descriptions of parameters that have some important particularity that should be highlighted.

Attribute	Type	Description	Required
`Authorization`	Header	Refers to the Production Access TokenPrivate key of the application created in Mercado Pago, which is used in the backend in development environments and when receiving real payments. You can access it through Your integrations > Application details > Production > Production credentials. or the one obtained via OAuthPrivate key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation.OAuth.	Required
`X-Idempotency-Key`	Header	Idempotency key. It is used to ensure that each request is processed only once, avoiding duplications. Use a unique value in the header of your request, such as a UUID V4 or random strings.	Required
`type`	Body.String	Type of order, associated with the Mercado Pago solution for which it is being created. For payments with Mercado Pago Point, the only possible value is `point`.	Required
`external_reference`	Body.String	It is an external reference of the order, assigned at the time of its creation. It must be a unique value for each order and cannot contain PII data. The maximum allowed limit is 64 characters and the allowed ones are: uppercase and lowercase letters, numbers and hyphen (-) and underscore (_) symbols.	Required
`transaction.payments.amount`	Body.String	Total amount of the payment order. Must be an integer, with no decimal places.	Required
`config.point.terminal_id`	Body.String	Identifier of the Point terminal that will receive the order. You must send it exactly as it was returned in the Get terminalsAPI request, as in the following example: "PAX_A910SMARTPOS123456789".	Required

To find out more details about all the parameters to be sent in this request, please check our API Reference.

If the request was successful, the response will return an order with a status 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"
    }
  ]
}

Since the order is the basis for payment processing, it's important that you save both its id and the payment id (transactions.payments.id) obtained when creating it, as they will allow you to perform other operations and properly query your notifications. Additionally, you can consult our documentation in the Resources section to better understand the possible status of an order and a transaction.

This created order will be automatically send to the terminal to which it was assigned. So, the payment can be made by the buyer at the physical point of sale and subsequently processed. Please note that, for this, the time elapsed between order creation and payment must be less than 15 minutes, as after this time period, the order will expire and it will not be possible to pay it.

Cancel an order

An order can be cancelled in two ways, depending on its status.

If the order's status is created, its cancellation must be done via API.
If the status is at_terminal, it has already been retrieved by the terminal and must be cancelled from there.

If an order is not processed within 15 minutes of being created, its status will change to expired and it will no longer be possible to cancel it.
Additionally, in the case of cancellations from the terminal, it's important to have previously configured your Webhook notifications to receive the cancellation notice in your system, which will allow you to maintain your reconciliation.

Choose the option that best suits your needs to learn how to cancel your order.

If you want to cancel an order with created status, you'll need to send a POST to the Cancel order by ID endpoint, making sure to include your Production Access TokenPrivate key of the application created in Mercado Pago, which is used in the backend in development environments and when receiving real payments. You can access it through Your integrations > Application details > Production > Production credentials., if you are doing your own integration, or the Access Token obtained through OAuthPrivate key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation.OAuth, if you are doing an integration for third parties, and the id of the order you want to cancel, obtained in the response to its creation.

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'

If the request was successful, the response will show a 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"
    }
  ]
}

Refund an order

If you wish, you can refund an order created for Mercado Pago Point through our API. This refund will always be a total refund of the order value.

An order paid with a card can be refunded via API up to 90 days after the payment is made. For payments made through Edenred, refunds via API can only be made until 23:59:59 of the same day the payment was created and for payments made with Pluxee, refunds via API can be made up to 5 business days from the payment creation. After this time period, it will no longer be possible to process the refund.

To make a total refund of an order, send a POST to the endpoint Refund an orderAPI, making sure to include your Production Access TokenPrivate key of the application created in Mercado Pago, which is used in the backend in development environments and when receiving real payments. You can access it through Your integrations > Application details > Production > Production credentials., if you are doing your own integration, or the Access Token obtained through OAuthPrivate key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation.OAuth, if you are doing an integration for third parties, and the id of the order you want to refund, obtained in the response to its creation.

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'

If the request was successful, the response will show a status=refunded, and will bring with it a new node, transactions.refunds, which will contain the details of the refund, along with the identifier of the original payment and the refund transaction.

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

Query order data

If needed, you can query the data of an order and its associated transactions, whether payments or refunds, including their statuses or values.

Although the recurring use of this API query is not recommended, it can be useful if you need additional information about the order.

To query order data, send a GET to the endpoint Get order by IDAPI, making sure to include your Production Access TokenPrivate key of the application created in Mercado Pago, which is used in the backend in development environments and when receiving real payments. You can access it through Your integrations > Application details > Production > Production credentials., if you are doing your own integration, or the Access Token obtained through OAuthPrivate key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation.OAuth, if you are doing an integration for third parties, and the id of the order whose information you want to query, obtained in the response to its creation.

Keep in mind that this request will only allow you to query orders created less than 3 months ago. If you need information about older orders, we recommend that you contact our customer service for additional assistance.

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

If the request was successful, the response will return all the order information, including its status and the status of the payment and/or refund in real time:

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"
    }
  ]
}

Adobe Commerce

Instale o nosso checkout em uma plataforma com soluções customizáveis para grandes empresas.

Documentation

Starting now?

Resources

Support

Community

Integrate payment processing

Navigation

Resources and Community

Mercado Pago

Country and language