# Create order

This endpoint allows creating orders for payment transactions with Wallet Connect. In case of success, the request will return a response with status 201.

**POST** `/v1/orders`

## Request parameters

### Header

- `X-Idempotency-Key` (string, required)
  This feature allows you to safely retry requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical payments. To ensure that each request is unique, it's important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. The header accepts values between 1 and 64 characters.

- `type` (string, optional)
  Order type, associated with the Mercado Pago solution for which it is created. For Wallet Connect payments, the only possible value is `online`.

- `external_reference` (string, optional)
  It is the external reference of the order, assigned when creating it. This field must have a maximum of 64 characters and can only be numbers, letters, hyphens (-) and underscores (_). Special characters such as ([ ], (), '', @) are not allowed. It must be a unique value for each order and cannot contain PII data.

- `total_amount` (string, optional)
  Total amount to be paid. The field can contain two decimal places or none.

- `description` (string, optional)
  Description of the purchased product or service, the reason for the payment order.

- `capture_mode` (string, optional)
  Optional. Defines when the payment is captured. Its default value is `automatic`. Send `manual` when you want to only authorize the payment at order creation and capture it later through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).
Possible enum values:

  - `automatic`
  The payment is authorized and captured in a single step at order creation.

  - `manual`
  The payment is only authorized at order creation and must be captured later through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

- `integration_data` (object, optional)
  Additional information that can be used to integrate with other systems.

  - `integration_data.platform_id` (string, optional)
  Identifier of the platform, assigned by Mercado Pago.

- `transactions` (object, optional)
  Contains information about the transactions associated with the order. It is only possible to include 1 transaction per order for Wallet Connect.

  - `transactions.payments` (array, optional)
  Contains information about the payment order.

  - `transactions.payments.amount` (string, optional)
  Total amount of the payment order. The field can contain two decimal places or none. Must match the `total_amount` field.

  - `transactions.payments.payment_method` (object, optional)
  Information about the payment method.

  - `transactions.payments.payment_method.type` (string, optional)
  Type of payment method selected to make the payment. For Wallet Connect transactions, the only possible value is `wallet`.

  - `transactions.payments.payment_method.id` (string, optional)
  Identifier of the payment method selected to make the payment. For Wallet Connect transactions, the only possible value is `wallet`.

  - `transactions.payments.payment_method.token` (string, optional)
  Payment token obtained after completing the [wallet agreement flow](/developers/en/docs/wallet-connect/configure-agreements). Must be exactly 32 alphanumeric characters (no special characters).

  - `transactions.payments.payment_method.statement_descriptor` (string, optional)
  Description shown on the payment statement. Accepts up to 50 characters.

  - `transactions.payments.stored_credential` (object, optional)
  Payment credential previously stored and authorized by the payer, used to process recurring Merchant-Initiated Transactions (MIT - Merchant Initiated Transaction). Include this node only for recurring payments with its fixed values and omit it for one-shot payments.

  - `transactions.payments.stored_credential.reason` (string, optional)
  Reason for the credential storage. The only possible value is `recurring`, which indicates that the credential was stored because the payment is part of a recurring series initiated by the merchant.

  - `transactions.payments.stored_credential.payment_initiator` (string, optional)
  Indicates who was responsible for initiating the payment transaction. The only possible value is `merchant`, which indicates that the merchant initiated the payment (MIT - Merchant Initiated Transaction).

## Response parameters

- `id` (string, optional)
  Identifier of the order, automatically generated by Mercado Pago when the order is created through the endpoint [POST /v1/orders](/developers/en/reference/online-payments/wallet-connect/orders/create-order/post).

- `type` (string, optional)
  Order type.
Possible enum values:

  - `online`
  Value associated with the creation of orders for Wallet Connect payments.

- `processing_mode` (string, optional)
  Indicates how the order will be processed. For Wallet Connect orders, the only allowed value is `automatic`.
Possible enum values:

  - `automatic`
  The order is processed automatically in a single step.

- `external_reference` (string, optional)
  It is the external reference of the order, assigned when creating it. This field must have a maximum of 64 characters and can only be numbers, letters, hyphens (-) and underscores (_). Special characters such as ([ ], (), '', @) are not allowed. It must be a unique value for each order and cannot contain PII data.

- `description` (string, optional)
  Description of the purchased product or service, the reason for the payment order.

- `total_amount` (string, optional)
  Total amount to be paid.

- `total_paid_amount` (string, optional)
  Total amount paid, represents the sum of all the transaction's `paid_amount` values.

- `country_code` (string, optional)
  Identifier of the site (country) to which the Mercado Pago application that created the order belongs.

- `user_id` (string, optional)
  Identifier of the user to which the Mercado Pago application that created the order belongs. It is the person that will receive the payment.

- `status` (string, optional)
  Current status of the order.
Possible enum values:

  - `processed`
  The order was successfully processed.

  - `action_required`
  The order requires an additional action to continue. For orders created with `capture_mode=manual`, the payment was authorized and is waiting to be captured through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

  - `failed`
  An error occurred in the processing of the order.

  - `canceled`
  The order was canceled. The authorization was released and no funds were transferred.

  - `refunded`
  The order has been successfully refunded.

- `status_detail` (string, optional)
  Details about the status of the order.
Possible enum values:

  - `accredited`
  Payment accredited.

  - `waiting_capture`
  The payment was authorized and is waiting to be captured. Applies to orders created with `capture_mode=manual`; capture it through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

  - `failed`
  Payment failed.

  - `canceled`
  The order was canceled before being captured.

  - `insufficient_amount`
  Insufficient balance to process the payment.

  - `refunded`
  The order has been fully refunded.

  - `partially_refunded`
  The order has been partially refunded.

- `capture_mode` (string, optional)
  Indicates the capture mode of the order. The default value is `automatic`. With `manual`, the payment is only authorized at creation and must be captured later through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).
Possible enum values:

  - `automatic`
  The payment is authorized and captured in a single step at order creation. Funds settle immediately.

  - `manual`
  The payment is only authorized at order creation. Funds are held but not transferred. A subsequent capture request must be sent to the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

- `currency` (string, optional)
  Identifier of the currency used in the order.

- `created_date` (string, optional)
  Order's creation date, in `yyyy-MM-ddTHH:mm:ss.sssZ` format.

- `last_updated_date` (string, optional)
  Order's last update date, in `yyyy-MM-ddTHH:mm:ss.sssZ` format.

- `integration_data` (object, optional)
  Additional information that can be used to integrate with other systems.

  - `integration_data.application_id` (string, optional)
  Identifier of the Mercado Pago application that created the order.

  - `integration_data.platform_id` (string, optional)
  Identifier of the platform, assigned by Mercado Pago.

- `transactions` (object, optional)
  Contains information about the transactions associated with the order.

  - `transactions.payments` (array, optional)
  Contains information about the payment associated with the order.

  - `transactions.payments[].id` (string, optional)
  Identifier of the payment transaction, automatically generated by Mercado Pago when the order is created through the endpoint [POST /v1/orders](/developers/en/reference/online-payments/wallet-connect/orders/create-order/post).

  - `transactions.payments[].amount` (string, optional)
  Payment amount.

  - `transactions.payments[].paid_amount` (string, optional)
  Transaction paid amount. Represents the real amount paid including discounts.

  - `transactions.payments[].reference_id` (string, optional)
  Reference identifier for the payment.

  - `transactions.payments[].status` (string, optional)
  Payment status.
Possible enum values:

  - `processed`
  The payment has been successfully processed.

  - `action_required`
  The order requires an additional action. For orders with `capture_mode=manual`, the payment was authorized and is waiting to be captured through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

  - `failed`
  An error occurred in the processing of the payment.

  - `canceled`
  The order was canceled. The authorization was released and no funds were transferred.

  - `transactions.payments[].status_detail` (string, optional)
  Details about the payment status.
Possible enum values:

  - `accredited`
  Payment accredited.

  - `waiting_capture`
  The payment was authorized and is waiting to be captured. Applies to orders with `capture_mode=manual`; capture it through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

  - `insufficient_amount`
  Insufficient balance to process the payment.

  - `failed`
  Payment processing failed.

  - `canceled_transaction`
  The payment transaction was canceled before being captured.

  - `transactions.payments[].attempts` (array, optional)
  Ordered list of processing attempts for this payment.

  - `transactions.payments[].attempts[].id` (string, optional)
  Attempt identifier.

  - `transactions.payments[].attempts[].status` (string, optional)
  Status of the attempt.
Possible enum values:

  - `processed`
  The payment has been successfully processed.

  - `action_required`
  The order requires an additional action. For orders with `capture_mode=manual`, the payment was authorized and is waiting to be captured through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

  - `failed`
  An error occurred in the processing of the payment.

  - `canceled`
  The order was canceled. The authorization was released and no funds were transferred.

  - `transactions.payments[].attempts[].status_detail` (string, optional)
  Details about the attempt status.
Possible enum values:

  - `accredited`
  Payment accredited.

  - `waiting_capture`
  The payment was authorized and is waiting to be captured. Applies to orders with `capture_mode=manual`; capture it through the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/wallet-connect/orders/capture-order/post).

  - `insufficient_amount`
  Insufficient balance to process the payment.

  - `failed`
  Payment processing failed.

  - `canceled_transaction`
  The payment transaction was canceled before being captured.

  - `transactions.payments[].attempts[].payment_method` (object, optional)
  Information about the payment method used for this payment attempt.

  - `transactions.payments[].attempts[].payment_method.id` (string, optional)
  Payment method identifier.

  - `transactions.payments[].attempts[].payment_method.type` (string, optional)
  Payment method type.

  - `transactions.payments[].attempts[].payment_method.installments` (integer, optional)
  Number of installments selected.

  - `transactions.payments[].payment_method` (object, optional)
  Information about the payment method.

  - `transactions.payments[].payment_method.id` (string, optional)
  Identifier of the payment method used to process the transaction.

  - `transactions.payments[].payment_method.type` (string, optional)
  Type of payment method used to process the transaction.

  - `transactions.payments[].payment_method.statement_descriptor` (string, optional)
  Description shown on the payment statement. Accepts up to 50 characters.

  - `transactions.payments[].payment_method.installments` (integer, optional)
  Number of installments selected.

  - `transactions.payments[].stored_credential` (object, optional)
  Stored credential information associated with the payment.

  - `transactions.payments[].stored_credential.payment_initiator` (string, optional)
  Initiator of the payment.
Possible enum values:

  - `merchant`
  The payment was initiated by the merchant (MIT - Merchant Initiated Transaction).

  - `customer`
  The payment was initiated by the customer.

  - `transactions.payments[].stored_credential.reason` (string, optional)
  Reason for the stored credential.
Possible enum values:

  - `recurring`
  Indicates that the payment is recurrent and merchant-initiated.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | empty_required_header | The `X-Idempotency-Key` header is required and was not sent. Make the request again including it. |
| 400 | invalid_idempotency_key_length | The `X-Idempotency-Key` must be between 1 and 64 characters. |
| 400 | required_properties | There are some required properties missing. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | unsupported_properties | An unsupported property was sent. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | minimum_properties | The minimum number of properties required was not sent. |
| 400 | property_type | Wrong property type was submitted. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | minimum_items | Array length is below the minimum allowed. |
| 400 | maximum_items | Array length exceeds the maximum allowed. |
| 400 | property_value | An incorrect value for some property was sent. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | json_syntax_error | An incorrect JSON was sent. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | invalid_properties | Incorrect information provided. |
| 400 | invalid_total_amount | The value entered in `total_amount` is not equivalent to the sum of the `transactions.payments.amount` field of the total transactions. Please verify if the values are correct. |
| 400 | invalid_order_type | Order `type` is invalid or unsupported. |
| 401 | unauthorized_payer_token | The `payer_token` provided is not authorized for this transaction. Verify that the token is valid and belongs to the authenticated payer. |
| 401 | invalid_credentials | There is no support for test credentials. Use test users with production credentials for the sandbox environment and your production credentials for the production environment. |
| 402 | 402 | Order was created, but some transaction failed. Check the `errors` field for more information. |
| 409 | idempotency_key_already_used | The value sent as the idempotency header (`X-Idempotency-Key`) has already been used. Please try the request again sending a new value. |
| 409 | operation_not_supported | The operation is not supported for this order. Please check the order `status` and `status_detail` and try again. |
| 422 | unprocessable_entity | The payment profile associated with the `payer_token` is corrupted or incomplete. |
| 423 | resource_locked | The idempotency key (`X-Idempotency-Key`) is currently locked by an in-flight request. Please retry after a short delay. |
| 500 | idempotency_validation_failed | Idempotency validation failed. Please try submitting the request again. |
| 500 | internal_error | Generic error. Please try submitting the request again. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "description": "Smartphone",
  "capture_mode": "automatic",
  "integration_data": {
  "platform_id": "123abc"
  },
  "transactions": {
  "payments": {
  "amount": "50.00",
  "payment_method": {
  "type": "wallet",
  "id": "wallet",
  "token": "123abc123abc123abc123abc123abc12",
  "statement_descriptor": "My Store"
  },
  "stored_credential": {
  "reason": "recurring",
  "payment_initiator": "merchant"
  }
  }
  }
  }'
```

## Response example

```json
{
  "id": "ORDBTA01KHY4WFPYXJ9Z7S5CGED7WCTP",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "description": "Smartphone",
  "total_amount": "50.00",
  "total_paid_amount": "50.00",
  "country_code": "PE",
  "user_id": "1090806071",
  "status": "processed",
  "status_detail": "accredited",
  "capture_mode": "automatic",
  "currency": "PEN",
  "created_date": "2026-02-20T18:27:08.639Z",
  "last_updated_date": "2026-02-20T18:27:09.797Z",
  "integration_data": {
  "application_id": "8251964915044164",
  "platform_id": "123abc"
  },
  "transactions": {
  "payments": [
  {
  "id": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
  "amount": "50.00",
  "paid_amount": "47.28",
  "reference_id": "30f45a189ec043c28e6c4b73e0dd65a3",
  "status": "processed",
  "status_detail": "accredited",
  "attempts": [
  null
  ],
  "payment_method": {
  "id": null,
  "type": null,
  "statement_descriptor": null,
  "installments": null
  },
  "stored_credential": {
  "payment_initiator": null,
  "reason": null
  }
  }
  ]
  }
}
```

## Use cases

### Create payment with Wallet Connect

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "description": "Smartphone",
  "integration_data": {
  "platform_id": "123abc"
  },
  "transactions": {
  "payments": {
  "amount": "50.00",
  "payment_method": {
  "type": "wallet",
  "id": "wallet",
  "token": "123abc123abc123abc123abc123abc12",
  "statement_descriptor": "My Store"
  },
  "stored_credential": {
  "reason": "recurring",
  "payment_initiator": "merchant"
  }
  }
  }
  }'
```

```json
{
  "id": "ORDBTA01KHY4WFPYXJ9Z7S5CGED7WCTP",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "description": "Smartphone",
  "total_amount": "50.00",
  "total_paid_amount": "50.00",
  "country_code": "PE",
  "user_id": "0110100101",
  "status": "processed",
  "status_detail": "accredited",
  "capture_mode": "automatic",
  "currency": "PEN",
  "created_date": "2026-02-20T18:27:08.639Z",
  "last_updated_date": "2026-02-20T18:27:09.797Z",
  "integration_data": {
  "application_id": "8251964915044164",
  "platform_id": "123abc"
  },
  "transactions": {
  "payments": [
  {
  "id": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
  "amount": "50.00",
  "paid_amount": "47.28",
  "reference_id": "30f45a189ec043c28e6c4b73e0dd65a3",
  "status": "processed",
  "status_detail": "accredited",
  "attempts": [
  null
  ],
  "payment_method": {
  "id": null,
  "type": null,
  "statement_descriptor": null,
  "installments": null
  },
  "stored_credential": {
  "payment_initiator": null,
  "reason": null
  }
  }
  ]
  }
}
```

### Authorize payment with Wallet Connect (without capture)

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "description": "Smartphone",
  "capture_mode": "manual",
  "integration_data": {
  "platform_id": "123abc"
  },
  "transactions": {
  "payments": {
  "amount": "50.00",
  "payment_method": {
  "type": "wallet",
  "id": "wallet",
  "token": "123abc123abc123abc123abc123abc12",
  "statement_descriptor": "Descriptor"
  },
  "stored_credential": {
  "reason": "recurring",
  "payment_initiator": "merchant"
  }
  }
  }
  }'
```

```json
{
  "id": "ORDBTA01KSND6GM8762RHH5D38R6YASN",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "description": "Smartphone",
  "total_amount": "50.00",
  "total_paid_amount": "0.00",
  "country_code": "PE",
  "user_id": "0110100101",
  "status": "action_required",
  "status_detail": "waiting_capture",
  "capture_mode": "manual",
  "currency": "PEN",
  "created_date": "2026-05-27T19:04:50.587Z",
  "last_updated_date": "2026-05-27T19:04:51.674Z",
  "integration_data": {
  "application_id": "8251964915044164",
  "platform_id": "123abc"
  },
  "transactions": {
  "payments": [
  {
  "id": "PAY01KSND6GMT3KAG0Z2TB9M8B0WW",
  "amount": "50.00",
  "paid_amount": "0.00",
  "reference_id": "9c95dd52e6d34f109a3f6147a5aa0062",
  "status": "action_required",
  "status_detail": "waiting_capture",
  "attempts": [
  null
  ],
  "payment_method": {
  "id": null,
  "type": null,
  "statement_descriptor": null,
  "installments": null
  },
  "stored_credential": {
  "payment_initiator": null,
  "reason": null
  }
  }
  ]
  }
}
```