AI resources

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 in credit card transactions, 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 modePATCH.

For this, send a request to the endpoint Get list of terminalsGET, using your test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Integration data > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations. The test Access Token starts with the prefix `APP_USR`.Access test credentials.

If necessary, you can filter the search using the optional query params store_id and pos_id, which correspond to the 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=0&store_id=12354567&pos_id=23545678' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

The response to this request will show the terminals associated with your account, allowing you to select the one you want to use to create your order.

The terminal can be identified by the last characters of the id field, which correspond to the serial number printed on the back label of the physical terminal.

json
{
  "data": {
    "terminals": [
      {
        "id": "NEWLAND_N950__N950NCB801293324",
        "pos_id": "23545678",
        "store_id": "12354567",
        "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 request to the endpoint /v1/ordersPOST, making sure to include your test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Integration data > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations. The test Access Token starts with the prefix `APP_USR`.Access test credentials, and the ID of the terminal to which you want to assign the order, obtained in the previous step.

If you wish, by setting credit card as the default payment method (default_type=credit_card), you can use the installment preset to define the financing type (with or without interest), the number of installments, and who will bear the financial cost. To activate the preset, include the fields default_installments and installments_cost inside the config.payment_method object when creating the order.

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": "point",
        "external_reference": "ext_ref_1234",
        "expiration_time": "PT16M",
        "transactions": {
            "payments": [
                {
                    "amount": "24.00"
                }
            ]
        },
        "config": {
            "point": {
                "terminal_id": "NEWLAND_N950__N950NCB801293324",
                "print_on_terminal": "no_ticket"
            },
            "payment_method": {
                "default_type": "credit_card",
                "default_installments": 3,
                "installments_cost": "seller"
            }
        },
        "description": "Point Smart 2",
        "integration_data": {
            "platform_id": "dev_1234567890",
            "integrator_id": "dev_1234567890",
            "sponsor": {
                "id": "446566691"
            }
        }
    }'

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 test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Integration data > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations. The test Access Token starts with the prefix `APP_USR`.Access test credentials.	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
`expiration_time`	Body. String	Indicates the validity period of the payment order from its creation. During this time, the order will be available for processing by the customer; if it is not processed within the specified period, it will automatically expire and cannot be used, requiring the generation of a new payment order to continue. The minimum allowed value is 30 seconds (PT30S) and the maximum is 3 hours (PT3H). Usage examples: for a 30-second expiration: "PT30S", for 10 minutes: "PT10M", and for 1 hour and 15 minutes: "PT1H15M".	Optional
`transactions.payments.amount`	Body.String	Total amount of the payment order. The field must contain exactly 2 decimal places, even when it is a whole number (for example, "10.00").	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 by the Get terminalsGET request, as in the following example: `NEWLAND_N950__N950NCB801293324`.	Required
`config.payment_method.default_type`	Body.String	Indicates the payment method that the terminal will accept. By default, it will accept all payment methods and will allow the customer to select the payment method they want. Sending this parameter as `credit_card` and its attributes is required when using the installment pre-configuration feature. Otherwise, the possible values are the following:	Optional
`config.payment_method.default_installments`	Body.Integer	When the default payment method is a credit card (`default_type = credit_card`), send this parameter to inform the terminal that the number of installments has been preselected, skipping the selection screen. If the card used for the payment does not support the specified number of installments, the terminal will display the selection screen. This feature is only available for Point Pro 2 and Point Pro 3 devices.	Conditional
`config.payment_method.installments_cost`	Body.String	When the default payment method is a credit card (`default_type=credit_card`) and `default_installments` is greater than `1`, send this parameter to define who will bear the financing cost of the installments. If the predefined value is 1 installment (`default_installments=1`), this field must be sent as `seller` or omitted, since a single installment has no financing cost for the `buyer`.	Conditional

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

If the request was successful, the response will return an order with status created.

json
{
  "id": "ORD00001111222233334444555566",
  "type": "point",
  "user_id": "5238400195",
  "external_reference": "ext_ref_1234",
  "description": "Point Smart 2",
  "expiration_time": "PT16M",
  "processing_mode": "automatic",
  "country_code": "BRA",
  "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": "NEWLAND_N950__N950NCB801293324",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "status": "created"
      }
    ]
  }
}

Since the order is the basis for payment processing, it's important that you save both its ID (order_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 received by the terminal to which it was assigned. If the order is not automatically loaded on the terminal, you must press the Update button or, if the terminal has one, the green button to receive the order. In this way, the buyer can make the payment on the terminal and then it will be processed. Keep in mind that if you do not fill in the expiration_time parameter, the payment must be made within 15 minutes of the order's creation; after that time, the order will expire.

Cancel an order

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

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.

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.

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

To cancel an order via API, send a request to the /v1/orders/{order_id}/cancelPOST endpoint, making sure to include your test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Integration data > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations. The test Access Token starts with the prefix `APP_USR`.Access test credentials, 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: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_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",
  "expiration_time": "PT16M",
  "country_code": "BRA",
  "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": "NEWLAND_N950__N950NCB801293324",
      "print_on_terminal": "no_ticket"
    },
    "payment_method": {
      "default_type": "credit_card"
    }
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "amount": "24.00",
        "status": "canceled",
        "status_detail": "canceled_by_api"
      }
    ]
  }
}

Refund an order

It is possible to refund an order created through our API. In this case, the refund will always be a full refund of the order amount.

An order can be refunded via API up to 90 days after its payment was made. After that time, it will no longer be possible to make the refund.

To refund an order, send a request to the endpoint /v1/orders/{order_id}/refundPOST without sending a body in the request. Make sure to include your test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Integration data > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations. The test Access Token starts with the prefix `APP_USR`.Access test credentials. You must also include 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: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

If the request is successful, the response will return status=refunded and a new node transactions.refunds, which will contain the details of the refund, along with the original payment ID (transactions.payments.id) and the refund transaction ID (transaction_id).

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 request to the endpoint /v1/orders/{order_id}GET, making sure to include your test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Integration data > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations. The test Access Token starts with the prefix `APP_USR`.Access test credentials, and the ID of the order (order_id) 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 {{YOUR_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",
  "expiration_time": "PT16M",
  "country_code": "BRA",
  "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": "NEWLAND_N950__N950NCB801293324",
      "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": 6,
          "id": "master"
        }
      }
    ],
    "refunds": [
      {
        "id": "REF01J67CQQH5904WDBVZEM1234D",
        "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
        "reference_id": "12345678",
        "amount": "38.00",
        "status": "processed"
      }
    ]
  }
}

PreviousConfigure terminalLearn how to set up your Point terminal to operate seamlessly with your POS.

NextConfigure orders notificationsConfigure orders notifications to receive alerts about your transactions with Mercado Pago Point