# Create order

This endpoint allows to create an order for QR Code for payment and cashout transactions. It is possible to create a payment transaction, a withdrawal transaction, or both at the same time. 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, you must use an exclusive value in the header of each unique value for each call. If you use a value already assigned to another request, you will receive information corresponding to that created resource in response, not this new request. We suggest using a UUID V4 or random strings.

- `type` (string, optional)
  Order type, associated with the Mercado Pago solution for which it is created. For Mercado Pago's QR Code payments, the only possible value is "qr".
Possible enum values:

  - `qr`
  Value associated with the creation of orders for Mercado Pago QR Code payments.

- `total_amount` (string, optional)
  Total order amount. Represents the sum of the transactions, so if it includes payment transactions ("payments") and cash_outs ("cash_outs"), it must be the sum of both values. The field can contain two decimal places or none.

- `description` (string, optional)
  Description of the purchased product or service, the reason for the order. The maximum limit is 150 characters and it must not contain PII data.

- `external_reference` (string, optional)
  It is the external reference of the order, assigned when creating it. The maximum allowed limit is 64 characters, and the allowed characters are: uppercase and lowercase letters, numbers, and the symbols hyphen (-) and underscore (_). This field must not contain PII data.

- `expiration_time` (string, optional)
  Specifies the order's validity period in ISO 8601 duration format (e.g., P3Y6M4DT12H30M5S). Minimum of 30 seconds and maximum of 3600 hours. Behavior varies by QR model. Dynamic QR defaults to 15 minutes and honors the value sent. Static QR defaults to 10 minutes and is capped at 10 minutes regardless of the value sent. Hybrid QR follows the same rules per type: the Dynamic QR honors the value sent, while the linked Static QR is always capped at 10 minutes.

- `marketplace_fee` (string, optional)
  This field is exclusive to OAuth integrations. It represents the marketplace fee, which will be given to the marketplace owner account. The field can contain two decimal places or none.

- `integration_data` (object, optional)
  Contains information about the Mercado Pago application that created the order.

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

  - `integration_data.integrator_id` (string, optional)
  Identifier of the user who develops the integration that creates the order, assigned by Mercado Pago. It must contain the prefix "dev_"

  - `integration_data.sponsor` (object, optional)

  - `integration_data.sponsor.id` (string, optional)
  Mercado Pago's "USER_ID" of the integrator system.

- `config` (object, optional)
  Order type configuration.

  - `config.qr` (object, optional)
  QR Code order configuration.

  - `config.qr.external_pos_id` (string, optional)
  External identifier of the POS, defined by the integrator during its creation. With its inclusion, the order information is associated with the pos and store previously created within the Mercado Pago system.

  - `config.qr.mode` (string, optional)
  QR code mode associated with the order. The possible values are listed below, and if you don't submit one, the default value will be "static".
Possible enum values:

  - `static`
  Static model, in which the static QR code, associated to the POS defined by the "external_pos_id" field, receives the order information.

  - `dynamic`
  Dynamic mode, in which a unique QR code for each transaction contains the specific data of the created order.

  - `hybrid`
  Allows payment to be made using either of the two modes, static or dynamic, since the order will be linked to the static QR code associated with the POS.

- `transactions` (object, optional)
  Contains information about the transaction associated with the order. When the type is qr, both payment transactions (payments) and cashout transactions (cash_outs) can be included. At a minimum, at least one payments or one cash_outs must be included.

  - `transactions.payments` (array, optional)
  Contains information about the payment order. Only one payment transaction can be sent per order.

  - `transactions.payments.amount` (string, optional)
  Payment amount. The field can contain two decimal places or none.

  - `transactions.cash_outs` (array, optional)
  Contains information about the cashout order. Only one cashout transaction can be sent per order.

  - `transactions.cash_outs.amount` (string, optional)
  Cashout amount. The field can contain two decimal places or none.

  - `transactions.cash_outs.additional_info` (object, optional)
  Specifies additional cashout information.

  - `transactions.cash_outs.additional_info.fixed_amount` (boolean, optional)
  Determines whether the payer can define the cashout amount from their Mercado Pago wallet. If set to true, the payer will be able to define the amount, and if set to false, it will be defined by the seller and cannot be modified.

  - `transactions.cash_outs.additional_info.agency_type` (string, optional)
  Type of agency or financial institution processing the transaction. Possible values are as follows.
Possible enum values:

  - `AGTEC`
  Commercial establishments.

  - `AGTOT`
  Agents whose activity is the provision of auxiliary services, such as ATMs or country correspondents.

  - `AGPSS`
  Participant who facilitates the withdrawal of money.

  - `transactions.cash_outs.additional_info.bank_service_code` (string, optional)
  Identifies the type of banking service being requested through the transaction. This field can take any value.

- `items` (array, optional)
  Information about the list of items to be paid. It is possible to send a maximum of 10 items.

  - `items.title` (string, optional)
  Item name. The character limit is 150.

  - `items.unit_price` (string, optional)
  Unit price of the purchased item. The field can contain two decimal places or none.

  - `items.quantity` (number, optional)
  Purchased items quantity.

  - `items.unit_measure` (string, optional)
  A value that represents a unit of measurement associated with the item. It can contain a maximum of 10 characters, and we suggest sending the value in lowercase.

  - `items.external_code` (string, optional)
  Code that identifies the item within the external system, for example, an EAN code. It is allowed a maximum of 30 characters.

  - `items.external_categories` (array, optional)
  List of categories associated with the item within the external system. A maximum of 10 categories ("id").

  - `items.external_categories.id` (string, optional)
  Identifier of the category associated with the item.

- `discounts` (object, optional)
  Contains information about the discounts the seller wants to offer on the payment transaction ("payment") of the order. Discounts can be configured for any payment method, but they will only apply if the payment is made through Mercado Pago wallet. If this node is sent, it is necessary to define the new payment value, which will replace the "total_amount" of the order. In case the payer does not use any of the payment methods assigned with a discount, the amount to be paid will continue to be the one defined in the "total_amount" field of the order.

  - `discounts.payment_methods` (array, optional)
  Information about the payment method with which the discount is applied.

  - `discounts.payment_methods.new_total_amount` (string, optional)
  Defines the new total value of the order when the discount is applied. If the created order contains both cashouts and payments, the value of this field must be the sum of the cashout amount plus the payment amount with the discount applied, and it cannot be less or equal to the cashout amount. The field can contain two decimal places or none.

  - `discounts.payment_methods.type` (string, optional)
  Identifier of the payment method with which the discount will be applied if used by the payer to make the payment through Mercado Pago wallet. Discounts can be defined for the 4 payment methods listed below, and a maximum of 4 available payment methods can be entered.
Possible enum values:

  - `debit_card`
  Debit card that is registered in Mercado Pago wallet.

  - `credit_card`
  Credit card that is registered in Mercado Pago wallet.

  - `account_money`
  Available money in the Mercado Pago wallet.

  - `prepaid_card`
  Prepaid card that is registered in Mercado Pago wallet.

## Response parameters

- `id` (string, optional)
  Identifier of the order created in the request, automatically generated by Mercado Pago.

- `user_id` (string, optional)
  ID of the Mercado Pago account that created the order.

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

  - `qr`
  Order created for Mercado Pago QR Code payments.

- `external_reference` (string, optional)
  External reference of the order, assigned when creating it.

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

- `expiration_time` (string, optional)
  Specifies the order's validity period in ISO 8601 duration format (e.g., P3Y6M4DT12H30M5S). Minimum of 30 seconds and maximum of 3600 hours. Behavior varies by QR model. Dynamic QR defaults to 15 minutes and honors the value sent. Static QR defaults to 10 minutes and is capped at 10 minutes regardless of the value sent. Hybrid QR follows the same rules per type: the Dynamic QR honors the value sent, while the linked Static QR is always capped at 10 minutes.

- `processing_mode` (string, optional)
  Indicates how the order will be processed. For QR orders, the only allowed value is "automatic", that sets the order to be ready to process.

- `total_amount` (string, optional)
  Total order amount. Represents the sum of the transactions, so if it includes payment transactions ("payments") and cash_outs ("cash_outs"), it must be the sum of both values. The field can contain two decimal places or none.

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

- `marketplace_fee` (string, optional)
  This field is exclusive to OAuth integrations. It represents the marketplace fee, which will be given to the seller's account.

- `integration_data` (object, optional)
  Contains information about the Mercado Pago application that created the order.

  - `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.

  - `integration_data.integrator_id` (string, optional)
  Identifier of the user who develops the integration that creates the order, assigned by Mercado Pago. It must contain the prefix "dev_"

  - `integration_data.sponsor` (object, optional)

  - `integration_data.sponsor.id` (string, optional)
  Mercado Pago's USER_ID of the integrator system.

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

  - `created`
  The order has been succesfully created.

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

  - `created`
  The order has been succesfully created.

- `currency` (string, optional)
  Identifier of the currency used in the order. We currently have the following options.
Possible enum values:

  - `BRL`
  Brazilian real.

  - `ARS`
  Argentine peso.

  - `CLP`
  Chilean peso.

  - `MXN`
  Mexican peso.

  - `UYU`
  Urugayan peso.

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

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

- `config` (object, optional)
  Order type configuration.

  - `config.qr` (object, optional)
  QR Code order configuration.

  - `config.qr.external_pos_id` (string, optional)
  External identifier of the POS, defined by the integrator during its creation.

  - `config.qr.mode` (string, optional)
  QR code mode associated with the order.

- `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 created in the request, automatically generated by Mercado Pago.

  - `transactions.payments[].amount` (string, optional)
  Payment amount, assigned when creating the order.

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

  - `created`
  The payment has been succesfully created.

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

  - `ready_to_process`
  The payment has been succesfully created and is ready to process.

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

  - `transactions.cash_outs[].id` (string, optional)
  Identifier of the cashout transaction created in the request, automatically generated by Mercado Pago.

  - `transactions.cash_outs[].amount` (string, optional)
  Cashout amount, assigned when creating the order.

  - `transactions.cash_outs[].status` (string, optional)
  Current cashout status.
Possible enum values:

  - `created`
  The cashout has been successfully created.

  - `transactions.cash_outs[].status_detail` (string, optional)
  Current details about the cashout.
Possible enum values:

  - `ready_to_process`
  The cashout has been succesfully created and is ready to process.

  - `transactions.cash_outs[].additional_info` (object, optional)
  Specifies additional cashout information.

  - `transactions.cash_outs[].additional_info.fixed_amount` (boolean, optional)
  Determines whether the payer can define the cashout amount from their Mercado Pago wallet. If set to true, the payer will be able to define the amount, and if set to false, it will be defined by the seller and cannot be modified.

  - `transactions.cash_outs[].additional_info.agency_type` (string, optional)
  Type of agency or financial institution processing the transaction. Possible values are as follows.
Possible enum values:

  - `AGTEC`
  Commercial establishments.

  - `AGTOT`
  Agents whose activity is the provision of auxiliary services, such as ATMs or country correspondents.

  - `AGPSS`
  Participant who facilitates the withdrawal of money.

  - `transactions.cash_outs[].additional_info.bank_service_code` (string, optional)
  Identifies the type of banking service being requested through the transaction. This field can take any value.

- `items` (array, optional)
  Information about the list of items to be paid.

  - `items[].title` (string, optional)
  Item name.

  - `items[].unit_price` (string, optional)
  Unit price of the item.

  - `items[].quantity` (number, optional)
  Purchased items quantity.

  - `items[].unit_measure` (string, optional)
  A value that represents a unit of measurement associated with the item, assigned when creating the order.

  - `items[].external_code` (string, optional)
  Code that identifies the item within the external system, assigned when creating the order. For example, an EAN code.

  - `items[].external_categories` (array, optional)
  List of categories associated with the item within the external system. A maximum of 10 categories ("id").

  - `items[].external_categories[].id` (string, optional)
  Identifier of the category associated with the item.

- `discounts` (object, optional)
  Contains information about the discounts the seller set for the payment transaction ("payment") of the order, associated with a payment method.

  - `discounts.payment_methods` (array, optional)
  Information about the payment method selected to apply the discount, assigned when creating the order.

  - `discounts.payment_methods[].new_total_amount` (string, optional)
  New total value of the order when the discount is applied. If the created order contains both cashouts and payments, the value of this field will be the sum of the cashout amount plus the payment amount with the discount applied.

  - `discounts.payment_methods[].type` (string, optional)
  Identifier of the payment method with which the discount will be applied if used by the payer to make the payment.
Possible enum values:

  - `debit_card`
  Debit card that is registered in Mercado Pago wallet.

  - `credit_card`
  Credit card that is registered in Mercado Pago wallet.

  - `account_money`
  Available money in the Mercado Pago wallet.

  - `prepaid_card`
  Prepaid card that is registered in Mercado Pago wallet.

- `type_response` (object, optional)
  Object returned if the "config.qr.mode" field has been set to "dynamic" or "hybrid".

  - `type_response.qr_data` (string, optional)
  QR frame, which must be transformed into a QR code so that payment can be made.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | bad_request | An attempt was made to create the order with unsupported or invalid fields. Please retry sending the request, validating all fields and. |
| 400 | empty_required_header | The "X-Idempotency-Key" header is required and was not sent. Make the request again including it. |
| 400 | marketplace_not_valid | The Access Token sent as a header in the request is not one obtained through the OAuth protocol and, therefore, it is not possible to identify a valid marketplace. Please verify that you have completed the process correctly. |
| 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 | property_type | An incorrect property type was sent. Check the message returned in the error details to find out what the problem was and try again. |
| 400 | sponsor_id_not_valid | An invalid value was sent as the Mercado Pago account identifier (USER_ID). Check the returned message in the error details to find out what the problem was and try again. |
| 400 | seller_configuration | The seller is not authorized to make requisitions with cashout ("cash_out") transactions. Please contact your Mercado Pago advisor to register the user and try again. |
| 400 | unsupported_site | An attempt was made to create the order from an unsupported country. Make sure you have the necessary authorization. |
| 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. |
| 401 | unauthorized | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 404 | marketplace_fee_not_allowed | The "marketplace_fee" field cannot be submitted because the marketplace could not be found. Please verify if the correct Access Token was sent and try again. |
| 404 | pos_not_found | The value for the "external_pos_id" field does not belong to any POS. Please confirm that you entered the correct value and try again. |
| 409 | idempotency_key_already_used | The value sent as the idempotency header has already been used with a different request within the last 24 hours. Please try the request again sending a new value. |
| 422 | — | Error. |
| 500 | 500 | Generic error. Please check the returned message and 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": "qr",
  "total_amount": "50.00",
  "description": "Smartphone",
  "external_reference": "ext_ref_1234",
  "expiration_time": "PT16M",
  "marketplace_fee": "11.20",
  "integration_data": {
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_1234",
  "sponsor": {
  "id": "446566691"
  }
  },
  "config": {
  "qr": {
  "external_pos_id": "EXTERNALPOS019285",
  "mode": "static"
  }
  },
  "transactions": {
  "payments": {
  "amount": "24.50"
  },
  "cash_outs": {
  "amount": "24.50",
  "additional_info": {
  "fixed_amount": "true",
  "agency_type": "AGTEC",
  "bank_service_code": "abc123"
  }
  }
  },
  "items": {
  "title": "Smartphone",
  "unit_price": "24.50",
  "quantity": 1,
  "unit_measure": "kg",
  "external_code": "777489134",
  "external_categories": {
  "id": "device"
  }
  },
  "discounts": {
  "payment_methods": {
  "new_total_amount": "47.28",
  "type": "account_money"
  }
  }
  }'
```

## Response example

```json
{
  "id": "ORD00001111222233334444555566",
  "user_id": "5238400195",
  "type": "qr",
  "external_reference": "ext_ref_1234",
  "description": "Smartphone",
  "expiration_time": "PT16M",
  "processing_mode": "automatic",
  "total_amount": "50.00",
  "country_code": "BR",
  "marketplace_fee": "11.20",
  "integration_data": {
  "application_id": "dev_1234567890",
  "platform_id": "dev_1234567890",
  "integrator_id": "dev_1234",
  "sponsor": {
  "id": "446566691"
  }
  },
  "status": "created",
  "status_detail": "created",
  "currency": "BRL",
  "created_date": "2024-09-10T14:26:42.109Z",
  "last_updated_date": "2024-09-10T14:27:42.109Z",
  "config": {
  "qr": {
  "external_pos_id": "EXTERNALPOS019285",
  "mode": "hybrid"
  }
  },
  "transactions": {
  "payments": [
  {
  "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "status": "created",
  "status_detail": "ready_to_process"
  }
  ],
  "cash_outs": [
  {
  "id": "CAS01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "status": "created",
  "status_detail": "ready_to_process",
  "additional_info": {
  "fixed_amount": null,
  "agency_type": null,
  "bank_service_code": null
  }
  }
  ]
  },
  "items": [
  {
  "title": "Smartphone",
  "unit_price": "24.50",
  "quantity": 1,
  "unit_measure": "kg",
  "external_code": "777489134",
  "external_categories": [
  {
  "id": null
  }
  ]
  }
  ],
  "discounts": {
  "payment_methods": [
  {
  "new_total_amount": "47.28",
  "type": "account_money"
  }
  ]
  },
  "type_response": {
  "qr_data": "00020101021243650016com.mercadolibre020130636261ba79b-e543-41c7-b71a-cec05c18e72b50120008326594305204970053030325802AR5904Test6004CABA63041094"
  }
}
```