# MD for: https://www.mercadopago.com.uy/developers/en/docs/mp-point/payment-processing.md \# Integrate payment processing Payment processing with Mercado Pago Point is based on creating orders associated with a payment transaction. These orders allow your system to initiate and track each payment processed on the terminal, link it to the corresponding operation through \`external\_reference\`, and keep its reconciliation up to date based on status changes. In \*\*PDV mode\*\*, the seller creates an order, which is automatically sent to the indicated Point terminal so the buyer can complete the payment. 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. > NOTE > > To offer installments \[with\](https://www.mercadopago.com.uy/ayuda/24694) or \[without interest\](https://www.mercadopago.com.uy/developers/en/support/cuotas-sin-interes\_3299) for credit card transactions, configure them in your Mercado Pago account in advance. During payment, installments are configured on the terminal. Do not include installment fields in the order creation request. :::::AccordionComponent{title="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. For this, send a request to the endpoint :TagComponent{tag="GET" text="Get terminals" href="/developers/en/reference/in-person-payments/point/terminals/get-terminals/get" color="accent"}, using your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private key linked to an application, used in the \_backend\_ to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the \_frontend\_, and starts with the \`APP\_USR\` prefix."}. 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 :TagComponent{tag="POST" text="/v1/orders" href="/developers/en/reference/in-person-payments/point/orders/create-order/post" color="green"}, making sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private key linked to an application, used in the \_backend\_ to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the \_frontend\_, and starts with the \`APP\_USR\` prefix."}, and the ID of the terminal to which you want to assign the order, obtained in the previous step. If the seller is an \*\*individual\*\* (natural person), do not send \`config.point.ticket\_number\` or \`payer\` in the request: \`\`\`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": "99.12" } \] }, "config": { "point": { "terminal\_id": "NEWLAND\_N950\_\_N950NCB801293324", "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" } } }' \`\`\` If the seller is a \*\*business\*\* (legal entity), you must send \`config.point.ticket\_number\` and \`payer.entity\_type\`, regardless of the payment method (card, debit, QR, or without \`payment\_method\`): \`\`\`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\_pj", "expiration\_time": "PT16M", "transactions": { "payments": \[ { "amount": "100.00" } \] }, "config": { "point": { "terminal\_id": "NEWLAND\_N950\_\_N950NCB801293324", "print\_on\_terminal": "seller\_ticket", "ticket\_number": "3902848" }, "payment\_method": { "default\_type": "credit\_card" } }, "integration\_data": { "platform\_id": "dev\_1234567890", "integrator\_id": "dev\_1234567890" }, "payer": { "entity\_type": "business" } }' \`\`\` 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 your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private key linked to an application, used in the \_backend\_ to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the \_frontend\_, and starts with the \`APP\_USR\` prefix."}. | 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. It must be sent as a string with exactly two decimal places, for example \`"99.12"\` or \`"100.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 :TagComponent{tag="GET" text="Get terminals" href="/developers/en/reference/in-person-payments/point/terminals/get-terminals/get" color="accent"} request. In Uruguay, only NEWLAND N950 terminals are supported, so the value must start with \`NEWLAND\_N950\_\_\`. | Required | | \`config.point.print\_on\_terminal\` | Body.String | Defines whether the terminal prints the transaction receipt. It accepts \`seller\_ticket\` —the default value— or \`no\_ticket\`. \`buyer\_ticket\` is not available in Uruguay. | Optional | | \`config.point.ticket\_number\` | Body.String | Sales ticket number, from 1 to 9 digits, without leading zeros and without letters. It is required for businesses and not allowed for individuals. | Conditional | | \`payer.entity\_type\` | Body.String | Buyer type associated with the payment: \`individual\` (natural person) or \`business\` (legal entity). It is required when the seller is a business and not allowed when the seller is an individual. | Conditional | | \`config.payment\_method.default\_type\` | Body.String | Indicates the payment method the terminal will accept: \`credit\_card\`, \`debit\_card\`, or \`qr\`. If not sent, the terminal accepts all payment methods. | Optional | In Uruguay, the seller's tax profile is determined from the data registered in your Mercado Pago account. Depending on that profile, the following rules apply regardless of the payment method: | Error code | HTTP | When it occurs | What to do | |---|---|---|---| | \`field\_not\_allowed\` | 400 | An individual sends \`config.point.ticket\_number\` or \`payer\`. | Remove those fields from the request. | | \`missing\_required\_field\` | 400 | A business does not send \`config.point.ticket\_number\` or \`payer\`. The API validates \`ticket\_number\` first. | Send the missing field. | | \`9200\` | 424 | It was not possible to validate the seller information. | Retry later without changing the request. | | \`9201\` | 429 | The seller information validation limit was reached. | Retry with exponential backoff. | Do not send the \`taxes\` field. In Uruguay, Mercado Pago manages it automatically. > NOTE > > To find out more details about all the parameters to be sent in this request, please check our :TagComponent{tag="API" text="API Reference" href="/developers/en/reference/in-person-payments/point/orders/create-order/post"}. If the request was successful, the response will return an order with status \`created\`. In this example for a business seller, the response includes the ticket number sent in the request. \`\`\`json { "id": "ORD00001111222233334444555566", "type": "point", "external\_reference": "ext\_ref\_1234\_pj", "status": "created", "status\_detail": "created", "config": { "point": { "terminal\_id": "NEWLAND\_N950\_\_N950NCB801293324", "print\_on\_terminal": "seller\_ticket", "ticket\_number": "3902848" }, "payment\_method": { "default\_type": "credit\_card" } }, "transactions": { "payments": \[ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "100.00", "status": "created" } \] } } \`\`\` > NOTE > > Since the order is the basis for payment processing, save its ID (\`order\_id\`) and the payment ID (\`transactions.payments.id\`) obtained when creating it, and associate them with \`external\_reference\`. This data will allow you to perform other operations, query your notifications, and keep your system reconciled. You can also consult our documentation in the \*\*Resources section\*\* to learn about the \[possible statuses of an order and a transaction\](https://www.mercadopago.com.uy/developers/en/docs/mp-point/resources/status-order-transaction). Once created, the order will be sent to the assigned terminal. In \*\*PDV mode\*\*, if the order does not load automatically, press the \*\*Update\*\* button or, if the terminal has one, the \*\*green button\*\* to receive it. If you do not complete the \`expiration\_time\` parameter, the order will expire 15 minutes after it is created. ::::: :::::AccordionComponent{title="Cancel an order"} An order can be canceled via API or, when it has \`at\_terminal\` status, directly from the terminal. > NOTE > > To track the cancellation of an order in \`at\_terminal\`, whether requested via API or performed from the terminal, configure your \[Webhook notifications\](https://www.mercadopago.com.uy/developers/en/docs/mp-point/notifications) beforehand. The notification confirms that the cancellation took effect and allows you to maintain your reconciliation. - If the order's \`status\` is \`created\`, it must be canceled via API and is processed synchronously. - If its \`status\` is \`at\_terminal\`, it has already been retrieved by the terminal. In this case, cancellation can be requested asynchronously via API or performed directly from the terminal. Choose the option that best suits your needs to learn how to cancel your order. ::::TabsComponent :::TabComponent{title="Via API"} To cancel an order with \`created\` or \`at\_terminal\` status via API, send a request to the :TagComponent{tag="POST" text="/v1/orders/{order\_id}/cancel" href="/developers/en/reference/in-person-payments/point/orders/cancel-order/post" color="green"} endpoint, including your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private key linked to an application, used in the \_backend\_ to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the \_frontend\_, and starts with the \`APP\_USR\` prefix."} and the order ID obtained in the response to its creation. > WARNING > > If the \`x-allow-cancelable-status\` header is omitted or has a value other than \`at\_terminal\`, the API cancellation request for an order with \`status=at\_terminal\` returns the \`409 cannot\_cancel\_order\` error. > \> In addition, the feature is available on Point Smart 2 terminals that have their software updated to the latest available version. Otherwise, the request is handled as if the header had not been sent and returns the same error. \`\`\`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 'x-allow-cancelable-status: at\_terminal' \\ -H 'Authorization: Bearer {{YOUR\_ACCESS\_TOKEN}}' \`\`\` The result depends on the order status at the time of the request: - For \`created\`, cancellation is synchronous and the API returns \`HTTP 200\`, with the order in \`status=canceled\` and the payment in \`status\_detail=canceled\_by\_api\`. The \`x-allow-cancelable-status\` header is optional and, when sent, is ignored. - For \`at\_terminal\`, the API accepts the request asynchronously and returns \`HTTP 202\`. The order remains in \`status=at\_terminal\`, while the payment changes to \`status\_detail=cancellation\_requested\`, until a Webhook notification confirms the cancellation. If the payment is already being processed, the terminal may prioritize it and not complete the cancellation; therefore, the \`HTTP 202\` response must not be interpreted as final confirmation. ### Response for an order in \`created\` \`\`\`json { "id": "ORD00009999222233334444555566", "user\_id": "5238400195", "type": "point", "external\_reference": "ext\_ref\_1234", "description": "Point Smart 2", "expiration\_time": "PT16M", "country\_code": "UY", "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", "ticket\_number": "3902848" }, "payment\_method": { "default\_type": "credit\_card" } }, "transactions": { "payments": \[ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP4", "amount": "24.00", "status": "canceled", "status\_detail": "canceled\_by\_api" } \] } } \`\`\` ### Response for an order in \`at\_terminal\` \`\`\`json { "id": "ORD00009999222233334444555566", "status": "at\_terminal", "status\_detail": "at\_terminal", "transactions": { "payments": \[ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP4", "status": "at\_terminal", "status\_detail": "cancellation\_requested" } \] } } \`\`\` The \`HTTP 202\` response only confirms that the request was accepted. Consider the order canceled only after receiving confirmation through \[Webhook notifications\](https://www.mercadopago.com.uy/developers/en/docs/mp-point/notifications). ::: :::TabComponent{title="From the terminal"} Since the order is automatically retrieved by the terminal, to cancel it you'll need to exit the screen without completing the charge. To do this, press the \*\*bottom right button\*\* on the terminal. Then, when asked if you want to exit without finishing, choose the \*\*Yes\*\* option. Once you finish the cancellation via terminal, and once your \[Webhook notifications\](https://www.mercadopago.com.uy/developers/en/docs/mp-point/notifications) are configured, you will receive the notification in your system, which will allow you to maintain your reconciliation. ::: :::: ::::: :::::AccordionComponent{title="Refund an order"} If needed, it is possible to refund an order created through our API. This endpoint allows you to make a \*\*total or partial\*\* refund of a payment transaction associated with the order. To request a total refund, you do not need to send a \`body\` in the request. For a partial refund, you must inform in the \`body\` the amount to be refunded and the transaction identifier. > WARNING > > An order can be refunded via API \*\*up to 90 days after its payment was made\*\*. After that period, it will no longer be possible to make the refund. For some orders, depending on the acquirer and card brand, the refund must be processed directly on the physical terminal, as it is necessary to insert the card into the device. Choose the option that best suits your needs and follow the corresponding instructions. ::::TabsComponent :::TabComponent{title="Total refund"} To make a \*\*total\*\* refund of an order, send a request to the endpoint :TagComponent{tag="POST" text="/v1/orders/{order\_id}/refund" href="/developers/en/reference/in-person-payments/point/orders/refund-order/post" color="green"} \*\*without sending a body\*\* in the request. Make sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private key linked to an application, used in the \_backend\_ to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the \_frontend\_, and starts with the \`APP\_USR\` prefix."}. You must also include the ID of the order (\`order\_id\`) 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": "ORD00001111222233334444555566", "status": "refunded", "status\_detail": "refunded", "transactions": { "refunds": \[ { "id": "REF01J67CQQH5904WDBVZEM1234D", "transaction\_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference\_id": "12345678", "amount": "24.00", "status": "processed" } \] } } \`\`\` ::: :::TabComponent{title="Partial refund"} To make a \*\*partial\*\* refund of an order, send a request to the endpoint :TagComponent{tag="POST" text="/v1/orders/{order\_id}/refund" href="/developers/en/reference/in-person-payments/point/orders/refund-order/post" color="green"}, including in the request \*\*body\*\* the array \`transactions\` with the payment transaction identifier (\`id\`) and the amount to be refunded (\`amount\`). Make sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private key linked to an application, used in the \_backend\_ to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the \_frontend\_, and starts with the \`APP\_USR\` prefix."}. You should send the fields as indicated in the table below. > WARNING > > Partial refunds are available for payments made with card, QR codes paid with the Mercado Pago wallet and other wallets. \`\`\`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}}' \\ -d '{ "transactions": \[ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "12.45" } \] }' \`\`\` | Attribute | Type | Description | Requirement | |-|-|-|-| | \`order\_id\` | String | ID of the order containing the associated payment transaction to be refunded. This value is returned in the response to the \[Create an order\](https://www.mercadopago.com.uy/developers/en/docs/mp-point/payment-processing#:\~:text=Create%20an%20order-,To,-start%20processing%20payments) request. | Required. | | \`transactions\` | Array | Contains information about the transaction associated with the order to be refunded. | Required for partial refunds. | | \`transactions.id\` | String | Identifier of the payment transaction created in the request, obtained in the response to the creation of the order (\`transactions.payments.id\`). | Required for partial refunds. | | \`transactions.amount\` | String | Amount to be refunded. You can perform multiple partial refunds, as long as the sum does not exceed the total transaction amount. | Required for partial refunds. | If the request was successful, the response will show \`status=processed\` (if there is still balance in the order) and \`status\_detail=partially\_refunded\`, along with the \`transactions.refunds\` node containing the partial refund details. \`\`\`json { "id": "ORD00001111222233334444555566", "status": "processed", "status\_detail": "partially\_refunded", "transactions": { "refunds": \[ { "id": "REF01J75Z9M6KQ8R3C4V2N7P1TXAB", "transaction\_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference\_id": "12345678", "amount": "12.45", "status": "processed" } \] } } \`\`\` ::: :::: ::::: :::::AccordionComponent{title="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 :TagComponent{tag="GET" text="/v1/orders/{order\_id}" href="/developers/en/reference/in-person-payments/point/orders/get-order/get" color="accent"}, making sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private key linked to an application, used in the \_backend\_ to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the \_frontend\_, and starts with the \`APP\_USR\` prefix."}, and the ID of the order (\`order\_id\`) whose information you want to query, obtained in the response to its creation. > WARNING > > 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: :::::