Process payments

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 /v1/ordersPOST, including your test Access TokenPrivate 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"
  },
  "additional_info": {
    "sub_merchant": {
      "id": "123123",
      "legal_name": "LOJINHA DO ZE",
      "mcc": "5462",
      "document_type": "CNPJ",
      "document_number": "222222222222222",
      "phone": "5551999999999",
      "url": "www.nomedofacilitador.com.br",
      "address_street": "RUA A",
      "address_door_number": 123,
      "zip": "01310100",
      "city": "Sao Paulo",
      "region_code_iso": "BR-SP",
      "region_code": "BR",
      "country": "BRA"
    }
  },
  "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.

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.

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 /v1/orders/{order_id}/capturePOST. After the capture, the order will return status=processed with status_detail=accredited.

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 when you need to confirm the result of a transaction.

To perform the query, send a request to the endpoint /v1/orders/{order_id}GET, including your test Access TokenPrivate 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}}'

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

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 /v1/orders/{order_id}/cancelPOST without sending the body in the request. Make sure to include your test Access TokenPrivate 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}}'

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.

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.

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

json
{
  "id": "ORDBTA01KJZ0AYZPD3SXDYCQ109Q69EA",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01KJZ0BPKX0BQ0KG1VPBMJDX9G",
        "transaction_id": "PAY01KJZ0AYZPD3SXDYCQ10RYPF8E",
        "amount": "24.90",
        "status": "processed"
      }
    ]
  }
}