# MD for: https://www.mercadopago.com.ar/developers/pt/docs/mp-point-v2/payment-processing.md

\# 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. In \*\*PDV mode\*\*, the seller creates an order and it is automatically sent to the indicated Point terminal, allowing the buyer to make the payment. In the case of \*\*SELF-SERVICE mode\*\*, the order is processed in real time between the kiosk used by the buyer and Mercado Pago, without the need for manual intervention. Additionally, in SELF\_SERVICE mode, the terminal will be dedicated exclusively to payment processing, with restricted access to settings and advanced features. 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 > > If you want the installments set to be \[with\](https://www.mercadopago.com.ar/ayuda/24694) or \[without\](https://www.mercadopago.com.ar/developers/es/support/cuotas-sin-interes\_3299) interests, before creating an order, you must \*\*set them up in your Mercado Pago account\*\*. :::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. Remember that this terminal must be \[set to PDV or SELF-SERVICE mode\](https://www.mercadopago.com.ar/developers/en/docs/mp-point-v2/configure-terminal#:\~:text=on%20the%20terminal-,As,-the%20last%20step). For this, send a \*\*GET\*\* to the endpoint :TagComponent{tag="API" text="Get list of terminals" href="/developers/en/reference/in-person-payments/point/terminals/get-terminals-v2/get"}. Use your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point-v2/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private 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."}. 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=0&store\_id=12354567&pos\_id=23545678' \\ -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": "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 \*\*POST\*\* to the endpoint :TagComponent{tag="API" text="/v1/orders" href="/developers/en/reference/in-person-payments/point/orders/create-order-v2/post"}, making sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point-v2/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private 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."}, 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", "expiration\_time": "PT16M", "transactions": { "payments": \[ { "amount": "24.00" } \] }, "config": { "point": { "screen\_time": "PT15S", "terminal\_id": "NEWLAND\_N950\_\_N950NCB801293324", "print\_on\_terminal": "no\_ticket", "ticket\_number": "S0392JED" }, "payment\_method": { "default\_type": "credit\_card" } }, "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 :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point-v2/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private 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."} or the one :toolTipComponent\[obtained via OAuth\]{link="/developers/en/docs/mp-point/resources/security/landing-hub" linkText="OAuth" content="Private key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation."}. | 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 | | \`transaction.payments.amount\`| \_Body.String\_ | Total amount of the payment order. El campo debe llevar obligatoriamente 2 números decimales, incluso cuando es un número entero (por ejemplo, "10.00"). | Required | | \`config.point.screen\_time\` | \_Body.String\_ | Allows you to specify the time that the terminal screens will be enabled to process the order, using ISO 8601 duration format (for example: "\`PT1M15S\`" represents a duration of 1 minute and 15 seconds, where the minimum possible value is 5 seconds and the maximum is 5 minutes). This time is reset every time the screen changes or the user interacts with the terminal. If not configured, the default value is 15 seconds. During the configured period, the order will be enabled to be processed; if it is not processed within this period, it will be canceled. If you wish to continue with the payment, you must create a new order.   
 \*\*Important: the card reading screen for payment will be displayed for, at most, 60 seconds (1 minute) regardless of whether the value configured for this field is greater than 60 seconds.\*\* | Optional | | \`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 :TagComponent{tag="API" text="Get terminals" href="/developers/en/reference/in-person-payments/point/terminals/get-terminals-v2/get"} request, as in the following example: "NEWLAND\_N950\_\_N950NCB801293324". | Required | > NOTE > > To find out more details about all the parameters to be sent in this request, please check our \[API Reference\](https://www.mercadopago.com.ar/developers/en/reference/in-person-payments/point/orders/create-order-v2/post). 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", "expiration\_time": "PT16M", "processing\_mode": "automatic", "country\_code": "ARG", "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", "ticket\_number": "S0392JED" }, "payment\_method": { "default\_type": "credit\_card", } }, "transactions": { "payments": \[ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "status": "created" } \] }, } \`\`\` > NOTE > > 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\](https://www.mercadopago.com.ar/developers/en/docs/mp-point-v2/resources/status-order-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.\*\*Remember that if the \`expiration\_time\` parameter is not filled in, the payment must be made within 15 minutes (for PDV mode) or within 15 seconds (for SELF\_SERVICE mode) after the order is created. After this period, the order will expire.\*\* > NOTE > > For operations carried out in SELF\_SERVICE mode, the payment receipt will be printed by the kiosk where the transaction was made, not by the Point terminal. ::: :::::AccordionComponent{title="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. > WARNING > > If the \`expiration\_time\` parameter is not filled in, and the order is not processed within \*\*15 minutes of its creation in PDV operation mode\*\*, or within \*\*15 seconds in SELF\_SERVICE operation mode\*\*, its \`status\` will become \`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\](https://www.mercadopago.com.ar/developers/en/docs/mp-point-v2/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. ::::TabsComponent :::TabComponent{title="Via API"} If you want to cancel an order with \`created\` status, you'll need to send a \*\*POST\*\* to the :TagComponent{tag="API" text="/v1/orders/{order\_id}/cancel" href="/developers/en/reference/in-person-payments/point/orders/cancel-order-v2/post"} endpoint, making sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point-v2/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private 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."}. You must also send 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", "expiration\_time": "PT16M", "country\_code": "ARG", "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": { "screen\_time": "PT15S", "terminal\_id": "NEWLAND\_N950\_\_N950NCB801293324", "print\_on\_terminal": "no\_ticket", "ticket\_number": "S0392JED" }, "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" } \] }, } \`\`\` ::: :::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.ar/developers/en/docs/mp-point-v2/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 necessary, you can 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, it is not necessary to send a \`body\` in the request. For a partial refund, you need to inform the amount to be refunded and the transaction identifier in the \`body\`. > 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 \*\*POST\*\* to the endpoint :TagComponent{tag="API" text="/v1/orders/{order\_id}/refund" href="/developers/en/reference/in-person-payments/point/orders/refund-order-v2/post"} \*\*without sending the body\*\* in the request. Make sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point-v2/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private 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."}. You also need to inform 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 \`status=refunded\` and will include a new node \`transactions.refunds\`, which will contain the refund details, 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" } \] } } \`\`\` ::: :::TabComponent{title="Partial refund"} To make a \*\*partial\*\* refund of an order, send a \*\*POST\*\* to the endpoint :TagComponent{tag="API" text="/v1/orders/{order\_id}/refund" href="/developers/en/reference/in-person-payments/point/orders/refund-order-v2/post"}, 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-v2/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private 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."}. 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: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \\ -H 'Authorization: Bearer ACCESS\_TOKEN' \\ -d '{ "transactions": \[ { "id": "TRANSACTION\_ID", "amount": "24.90" } \] }' \`\`\` | 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.ar/developers/en/docs/mp-point-v2/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": "ORD01J49MMW3SSBK5PSV3DFR32959", "status": "processed", "status\_detail": "partially\_refunded", "transactions": { "refunds": \[ { "id": "REF01J49MMW3SSBK5PSV3DFR32959", "transaction\_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC", "reference\_id": "12345678", "amount": "24.90", "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 \*\*GET\*\* to the endpoint :TagComponent{tag="API" text="/v1/orders/{order\_id}" href="/developers/en/reference/in-person-payments/point/orders/get-order-v2/get"}, making sure to include your :toolTipComponent\[test Access Token\]{link="/developers/en/docs/mp-point-v2/create-application#bookmark\_access\_test\_credentials" linkText="Access test credentials" content="Private 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."}, and the id of the order 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 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": "ARG", "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": { "screen\_time": "PT15S", "terminal\_id": "NEWLAND\_N950\_\_N950NCB801293324", "print\_on\_terminal": "no\_ticket", "ticket\_number": "S0392JED" }, "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" } \] }, } \`\`\` :::