# MD for: https://www.mercadopago.com.mx/developers/en/docs/wallet-connect/process-payments.md

\# Process payments With Wallet Connect, payments are processed through the \*\*Orders API\*\*, an API designed to simplify the integration with Mercado Pago. The order represents the purchase intent and concentrates the payment transactions associated with it, allowing the amount to be debited directly from the buyer's wallet using the payment token obtained in the agreement. Before processing payments, you must have completed the agreement flow and obtained the \`payer\_token\`. If you have not done so yet, see the \[Configure agreements\](https://www.mercadopago.com.mx/developers/en/docs/wallet-connect/configure-agreements) section. > NOTE > > Before creating the order, you must define when the amount will be captured. This definition is made at creation time through the \`capture\_mode\` parameter, and determines whether the payment will be debited immediately upon the creation of the order (\`automatic\`) or only authorized for later capture (\`manual\`). If you define that the capture will be performed later, after the \[order creation\](https://www.mercadopago.com.mx/developers/en/docs/wallet-connect/process-payments#bookmark\_create\_order) you must capture it through the endpoint :TagComponent{tag="POST" text="/v1/orders/{order\_id}/capture" href="/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post" color="green"}. :::AccordionComponent{title="Create order" pill="1"} Creating the order is the operation that performs the charge on the buyer's wallet. It is only possible to associate \*\*one payment transaction per order\*\* in Wallet Connect integrations. To do this, send a request to the endpoint :TagComponent{tag="POST" text="/v1/orders" href="/developers/en/reference/online-payments/wallet-connect/orders/create-order/post" color="green"}, including your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."} and the \`payer\_token\` obtained in the agreement. \`\`\`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": "online", "external\_reference": "ext\_ref\_1234", "total\_amount": "24.90", "description": "Smartphone", "capture\_mode": "automatic", "integration\_data": { "platform\_id": "123abc" }, "transactions": { "payments": \[ { "amount": "24.90", "payment\_method": { "type": "wallet", "id": "wallet", "token": "PAYER\_TOKEN", "statement\_descriptor": "My Store" } } \] } }' \`\`\` See the table below for descriptions of the parameters that are mandatory in the request and those that, although optional, have some important particularity that should be highlighted. | Parameter | Type | Description | Requirement | |---|---|---|---| | \`X-Idempotency-Key\` | \_Header\_ | Idempotency key. This key ensures that each request is processed only once, avoiding duplicate charges if the request is resent. Use a unique value per payment attempt, such as a UUID V4 or a random string, with a length between 1 and 64 characters. | Required | | \`Authorization\` | \_Header\_ | Refers to your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."}. | Required | | \`type\` | \_Body. String\_ | Type of order, associated with the Mercado Pago solution for which it was created. For payments with Wallet Connect, the only possible value is \`online\`. | Required | | \`external\_reference\` | \_Body. String\_ | External reference of the order, assigned at creation time. It must be a unique value for each order and must not contain PII data. The maximum limit is 64 characters and the allowed ones are: \*\*uppercase and lowercase letters\*\*, \*\*numbers\*\* and \*\*hyphen (-) and underscore (\_) symbols\*\*. | Required | | \`total\_amount\` | \_Body. String\_ | Total amount to be paid. The field must contain 2 decimal places, even when it is a whole number (for example, "10.00"). | Required | | \`description\` | \_Body. String\_ | Description of the purchased product or service, that is, the reason for the payment order. | Optional | | \`capture\_mode\` | \_Body. String\_ | Defines when the payment is captured. The possible values are:   
  
 \- \`automatic\`: debits the amount from the buyer's wallet immediately upon order creation. This is the default value if the field is not sent.   
  
 \- \`manual\`: only authorizes the payment upon order creation, requiring it to be captured later through the capture endpoint. | Optional | | \`integration\_data.platform\_id\` | \_Body. String\_ | Platform identifier assigned by Mercado Pago. | Optional | | \`transactions.payments.amount\` | \_Body. String\_ | Amount of the payment transaction. It must match the value informed in \`total\_amount\` and follow the same decimal places rule. | Required | | \`transactions.payments.payment\_method.type\` | \_Body. String\_ | Type of payment method. For transactions with Wallet Connect, the only possible value is \`wallet\`. | Required | | \`transactions.payments.payment\_method.id\` | \_Body. String\_ | Identifier of the payment method. For transactions with Wallet Connect, the only possible value is \`wallet\`. | Required | | \`transactions.payments.payment\_method.token\` | \_Body. String\_ | Payment token (\`payer\_token\`) obtained upon completing the wallet agreement flow. It must contain exactly 32 alphanumeric characters, with no special characters. | Required | | \`transactions.payments.payment\_method.statement\_descriptor\` | \_Body. String\_ | Description with which the payment will appear on the buyer's statement. Accepts up to 50 characters. | Optional | | \`transactions.payments.stored\_credential\` | \_Body. Object\_ | Payment credential previously authorized by the buyer, used to process recurring payments initiated by the seller (MIT — Merchant Initiated Transaction). Send the \`reason\` field with the value \`recurring\` and \`payment\_initiator\` with the value \`merchant\` only for recurring payments, omitting the parameter for one-time payments. | Optional | If the request is successful, the response will return status 201 with the created order. For orders with \`capture\_mode=automatic\`, the payment will return \`status=processed\` and \`status\_detail=accredited\`, indicating that the amount has already been debited from the buyer's wallet. \`\`\`json { "id": "ORDBTA01KJZ06DEJX3DMY26FAB44BXNN", "type": "online", "processing\_mode": "automatic", "external\_reference": "ext\_ref\_1234", "description": "Smartphone", "total\_amount": "24.90", "total\_paid\_amount": "24.90", "status": "processed", "status\_detail": "accredited", "capture\_mode": "automatic", "transactions": { "payments": \[ { "id": "PAY01KJZ06DEJX3DMXXXXXXXXXXXX", "amount": "24.90", "paid\_amount": "24.90", "status": "processed", "status\_detail": "accredited", "payment\_method": { "id": "wallet", "type": "wallet", "statement\_descriptor": "My Store", "installments": 1 } } \] } } \`\`\` Among the returned parameters, we have those indicated in the table below. | Parameter | Type | Description | |---|---|---| | \`id\` | \_String\_ | Identifier of the created order, automatically generated by Mercado Pago. Use it to query, capture, cancel or refund the order. | | \`status\` | \_String\_ | Returns the order status. The possible values are \`processed\`, \`action\_required\`, \`failed\` and \`canceled\`. | | \`status\_detail\` | \_String\_ | Details the reason for the order status. For approved payments, it returns \`accredited\`. For orders created with \`capture\_mode\` set to \`manual\`, it returns \`waiting\_capture\` until the capture is performed. | | \`total\_paid\_amount\` | \_String\_ | Amount effectively paid for the order, including any discounts applied. | | \`transactions.payments.id\` | \_String\_ | Identifier of the payment transaction, automatically generated by Mercado Pago. It is required to perform partial refunds. | | \`transactions.payments.status\` | \_String\_ | Returns the status of the payment transaction. | | \`transactions.payments.attempts\` | \_Array\_ | Ordered list of the processing attempts made for this payment, with the status and the payment method of each one. | If you created the order in manual mode, that is, with the \`capture\_mode=manual\` field, remember that processing the payment requires an additional step. In this scenario, the amount is only authorized upon order creation and the response will return \`status=action\_required\` with \`status\_detail=waiting\_capture\`, indicating that the transaction is awaiting capture. To complete the charge and debit the amount from the buyer's wallet, you must send a request to the endpoint :TagComponent{tag="POST" text="/v1/orders/{order\_id}/capture" href="/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post" color="green"}. After the capture, the order will return \`status=processed\` with \`status\_detail=accredited\`. > SUCCESS\_MESSAGE > > To learn in detail about all the parameters sent and returned in this request, please refer to our :TagComponent{tag="API" text="API Reference" href="/developers/en/reference/online-payments/wallet-connect/overview" color="accent"}. Additionally, if you receive an error when submitting the payment, consult the \[Possible errors\](https://www.mercadopago.com.mx/developers/en/docs/wallet-connect/integration-errors) section for more information. ::: :::AccordionComponent{title="Get order data" pill="2"} The query allows you to obtain the updated data of an order, including the payment status and the processing attempts made. We recommend using it as an alternative to \[notifications\](https://www.mercadopago.com.mx/developers/en/docs/wallet-connect/notifications) when you need to confirm the result of a transaction. To perform the query, send a request to the endpoint :TagComponent{tag="GET" text="/v1/orders/{order\_id}" href="/developers/en/reference/online-payments/wallet-connect/orders/get-order/get" color="accent"}, including your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."} and the order ID (\`order\_id\`) obtained in the response to its creation. \`\`\`curl curl -X GET \\ 'https://api.mercadopago.com/v1/orders/{{ORDER\_ID}}' \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer {{YOUR\_ACCESS\_TOKEN}}' \`\`\` | Parameter | Type | Description | Requirement | |---|---|---|---| | \`order\_id\` | \_Path. String\_ | Identifier of the order you want to query, obtained in the response to its creation. | Required | | \`Authorization\` | \_Header\_ | Refers to your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."}. | Required | If the request is successful, the response will return status 200 with the updated order data. \`\`\`json { "id": "ORDBTA01KJZ06DEJX3DMY26FAB44BXNN", "type": "online", "processing\_mode": "automatic", "external\_reference": "ext\_ref\_1234", "description": "Smartphone", "total\_amount": "24.90", "total\_paid\_amount": "24.90", "status": "processed", "status\_detail": "accredited", "transactions": { "payments": \[ { "id": "PAY01KJZ06DEJX3DMXXXXXXXXXXXX", "amount": "24.90", "paid\_amount": "24.90", "status": "processed", "status\_detail": "accredited" } \] } } \`\`\` ::: :::AccordionComponent{title="Cancel order" pill="3"} Cancelling releases the authorization of a payment that has not yet been captured, without transferring any amount from the buyer's wallet. It applies only to orders with the \`action\_required\` status, that is, created with \`capture\_mode=manual\` and still pending capture. To cancel an order, send a request to the endpoint :TagComponent{tag="POST" text="/v1/orders/{order\_id}/cancel" href="/developers/en/reference/online-payments/wallet-connect/orders/cancel-order/post" color="green"} \*\*without sending the body\*\* in the request. Make sure to include your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."} and the order ID (\`order\_id\`) you want to cancel. \`\`\`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}}' \`\`\` | Parameter | Type | Description | Requirement | |---|---|---|---| | \`order\_id\` | \_Path. String\_ | Identifier of the order you want to cancel, obtained in the response to its creation. | Required | | \`X-Idempotency-Key\` | \_Header\_ | Idempotency key. Use a unique value per request to prevent the cancellation from being reprocessed. | Required | | \`Authorization\` | \_Header\_ | Refers to your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."}. | Required | If the request is successful, the response will return the order with \`status=canceled\` and \`status\_detail=canceled\_transaction\`, indicating that the authorization has been released. > NOTE > > To reverse a payment that has already been captured, use the refund described in the next stage. An order that has already been cancelled will return the \`order\_already\_canceled\` error on new attempts. ::: :::::AccordionComponent{title="Refund order" pill="4"} Refunds are transactions performed when a given charge is reversed and the paid amounts are returned to the buyer. With Wallet Connect, it is possible to perform the \*\*total or partial\*\* refund of an order that has already been processed. Choose the option that best suits your needs and follow the corresponding instructions. ::::TabsComponent :::TabComponent{title="Total refund"} To perform the \*\*total\*\* refund of an order, send a request to the endpoint :TagComponent{tag="POST" text="/v1/orders/{order\_id}/refund" href="/developers/en/reference/online-payments/wallet-connect/orders/refund-order/post" color="green"} \*\*without sending the body\*\* in the request. Make sure to include your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."} and the order ID (\`order\_id\`) you want to refund. \`\`\`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}}' \`\`\` | Parameter | Type | Description | Requirement | |---|---|---|---| | \`order\_id\` | \_Path. String\_ | Identifier of the order you want to refund, obtained in the response to its creation. | Required | | \`X-Idempotency-Key\` | \_Header\_ | Idempotency key. Use a unique value per request to prevent the refund from being reprocessed. | Required | | \`Authorization\` | \_Header\_ | Refers to your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."}. | Required | If the request is successful, the response will return \`status=refunded\` and a new \`transactions.refunds\` node, which will contain the refund details, in addition to the \`id\` of the original payment transaction and the \`id\` of the refund transaction. \`\`\`json { "id": "ORDBTA01KJZ0AYZPD3SXDYCQ109Q69EA", "status": "refunded", "status\_detail": "refunded", "transactions": { "refunds": \[ { "id": "REF01KJZ0BPKX0BQ0KG1VPBMJDX9G", "transaction\_id": "PAY01KJZ0AYZPD3SXDYCQ10RYPF8E", "amount": "24.90", "status": "processed" } \] } } \`\`\` ::: :::TabComponent{title="Partial refund"} To perform 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/online-payments/wallet-connect/orders/refund-order/post" color="green"}, including in the request \*\*body\*\* the \`transactions\` array with the identifier of the payment transaction (\`id\`) and the amount to be refunded (\`amount\`). Make sure to include your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."} and the order ID (\`order\_id\`) you want to refund. \`\`\`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": "PAY01KJZ0C7BBATS9W8XSXQVXSAV5", "amount": "12.45" } \] }' \`\`\` | Parameter | Type | Description | Requirement | |---|---|---|---| | \`order\_id\` | \_Path. String\_ | Identifier of the order you want to refund, obtained in the response to its creation. | Required | | \`X-Idempotency-Key\` | \_Header\_ | Idempotency key. Use a unique value per request to prevent the refund from being reprocessed. | Required | | \`Authorization\` | \_Header\_ | Refers to your :toolTipComponent\[test Access Token\]{content="Private key used in the backend to authenticate the requests. In the Wallet Connect integration, your Access Token will initially be provided by the team responsible for creating your application in Mercado Pago, but once you have access to that application you will be able to view it in \*Your integrations > Integration data > Tests > Test credentials\*. The test Access Token starts with the prefix \`APP\_USR\`."}. | Required | | \`transactions.id\` | \_Body. String\_ | Identifier of the payment transaction you want to refund, obtained in \`transactions.payments.id\` in the response to the order creation. | Required | | \`transactions.amount\` | \_Body. String\_ | Amount to be refunded. It must contain 2 decimal places and cannot exceed the amount available in the transaction, otherwise the \`refund\_amount\_exceeds\` error will be returned. | Required | If the request is successful, the response will return the order with \`status\_detail=partially\_refunded\` and the \`transactions.refunds\` node with the details of the refund performed. \`\`\`json { "id": "ORDBTA01KJZ0C7BBATS9W8XSXQ0CBMFJ", "status": "processed", "status\_detail": "partially\_refunded", "transactions": { "refunds": \[ { "id": "REF01KJZ0CZ4FBFQMNZADKW8T7ZEH", "transaction\_id": "PAY01KJZ0C7BBATS9W8XSXQVXSAV5", "amount": "12.45", "status": "processed" } \] } } \`\`\` ::: :::: :::::