# Create order This endpoint allows to create orders in `automatic` (processing the transaction in a single stage) or `manual` (processing the transaction in stages that can be configured and executed incrementally) mode for payment transactions with Checkout API. 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 128 characters. - `type` (string, optional) Order type, associated with the Mercado Pago solution for which it is created. For online card payments, the only possible value is `online`. Possible enum values: - `online` Value associated with the creation of Orders for online payments. - `external_reference` (string, optional) It is an external reference of the order. It can be, for example, a hashcode from the Central Bank, functioning as an identifier of the transaction origin. This field must have a maximum of 64 characters and can only be numbers, letters, hyphens (-) and underscores (_). Special characters ([ ], (), '', @) are not allowed. Required for PSE payments. Optional for card and Efecty payments. - `transactions` (object, optional) Contains information about the transactions associated with the order. It can contain only one transaction. Required when processing payment in `automatic` mode, optional in `manual` mode. If not sent in `manual` mode, it must be `null` (not an empty `array`). - `transactions.payments` (array, optional) Contains information about the payment order. Required when processing payment in `automatic` mode. Must not be present (or must be empty) when creating an order in `manual` mode, as transactions are added later via a request to the endpoint [POST /v1/orders/{order_id}/transactions](/developers/en/reference/online-payments/checkout-api/add-transaction-order/post). - `transactions.payments.amount` (string, optional) Transaction amount. If only one payment method is used, it must be equivalent to the amount entered in the `total_amount` field. If two are used, it is the sum between the two `amount` that must be equivalent to the `total_amount` value. The field can contain two decimal places or none. - `transactions.payments.payment_method` (object, optional) Information about the payment method. Access the endpoint [GET /v1/payment_methods](/developers/en/reference/online-payments/checkout-api/payment-methods/get) to check all available payment methods and get a list with the details of each one and their properties. The requirement of this parameter varies according to the need to send its attributes in the request. Depending on the payment method you are integrating, check below which of these attributes are required. - `transactions.payments.payment_method.id` (string, optional) Identifier of the payment method selected to make the payment. If it's a card payment, it will show the brand. Possible enum values: - `visa` "Visa" credit card. - `master` "Master" credit card. - `debmaster` "Master" debit card. - `debvisa` "Visa" debit card. - `pse` Payment with "PSE" (Pagos Seguros en Línea), a digital payment method that allows you to use funds online directly from your savings account, checking account, or digital wallet. - `transactions.payments.payment_method.type` (string, optional) Type of payment method selected to make the payment. Possible enum values: - `credit_card` Credit card. - `debit_card` Debit card. - `bank_transfer` Bank transfer. - `transactions.payments.payment_method.token` (string, optional) Token that identifies the card and contains its data securely. Only required for card payments. It has a minimum length of 32 characters, and a maximum length of 33. If you don't know how to generate it, go to the [card payment configuration](/developers/en/docs/checkout-api-orders/payment-integration/websites/cards). - `transactions.payments.payment_method.installments` (integer, optional) Number of installments selected. The maximum accepted value is 36. - `transactions.payments.payment_method.statement_descriptor` (string, optional) Description used to identify the charge on the buyer's payment method statement. Send this value in each [order creation](/developers/en/reference/online-payments/checkout-api/create-order/post) request where you want the description to appear, as it is not a one-time configuration. Accepts up to 50 characters. - `transactions.payments.payment_method.financial_institution` (string, optional) Code of the financial institution where the buyer will make the electronic transfer to complete the payment. Required only for PSE payments. - `transactions.payments.expiration_time` (string, optional) Transaction expiration date. Applicable to PSE and Efecty payments. Required for PSE and optional for Efecty. The valid format of the attribute is ISO 8601 duration format, for example: `P3Y6M4DT12H30M5S` represents a duration of 3 years, 6 months, 4 days, 12 hours, 30 minutes, and 5 seconds. - `transactions.payments.date_of_expiration` (string, optional) Date and time of the expiration of the payment. If an `expiration_time` is not sent, this field adopts a default value that depends on the payment method. - `payer` (object, optional) Payer information. The requirement of this parameter depends on which attributes must be sent in the request. Check below which ones are required for the payment method you are integrating. Depending on your store's business activity or industry, sending this parameter when creating the order can help increase the chances of your payments being approved. For more information, see [Industry data](/developers/en/docs/checkout-api-orders/payment-management/improve-payment-approval/industry-data). - `payer.email` (string, optional) Payer email. Required for PSE and Efecty payments. Optional for card payments. - `payer.entity_type` (string, optional) Type of payer's entity. Required for PSE payments. Optional for card and Efecty payments. Possible enum values: - `individual` Payer is individual. - `association` Payer is an association. - `payer.first_name` (string, optional) Payer first name. Depending on your store's business activity or industry, sending this parameter when creating the order can help increase the chances of your payments being approved. For more information, see [Industry data](/developers/en/docs/checkout-api-orders/payment-management/improve-payment-approval/industry-data). - `payer.last_name` (string, optional) Payer last name. Depending on your store's business activity or industry, sending this parameter when creating the order can help increase the chances of your payments being approved. For more information, see [Industry data](/developers/en/docs/checkout-api-orders/payment-management/improve-payment-approval/industry-data). - `payer.identification` (object, optional) Payer's personal identification. This parameter and its required attributes are needed for PSE and Efecty payments. For card payments, they are optional. Depending on your store's business activity or industry, sending this parameter, including its attributes, when creating the order can help increase the chances of your payments being approved. For more information, see [Industry data](/developers/en/docs/checkout-api-orders/payment-management/improve-payment-approval/industry-data). - `payer.identification.type` (string, optional) Payer's identification document type. Access the endpoint [GET /v1/identification_types](/developers/en/reference/online-payments/checkout-api/identification-types/get) to check all available identification types by country and get a list with the details of each one and their properties. - `payer.identification.number` (string, optional) Payer's identification document number. - `payer.phone` (object, optional) Payer's phone information. This parameter and its required attributes are needed for PSE payments. For card and Efecty payments, they are optional. Depending on your store's business activity or industry, sending this parameter, including its attributes, when creating the order can help increase the chances of your payments being approved. For more information, see [Industry data](/developers/en/docs/checkout-api-orders/payment-management/improve-payment-approval/industry-data). - `payer.phone.area_code` (string, optional) Phone area code. - `payer.phone.number` (string, optional) Phone number. - `payer.address` (object, optional) Payer's address information. This parameter and its required attributes are needed for PSE payments. For card and Efecty payments, they are optional. Depending on your store's business activity or industry, sending this parameter, including its attributes, when creating the order can help increase the chances of your payments being approved. For more information, see [Industry data](/developers/en/docs/checkout-api-orders/payment-management/improve-payment-approval/industry-data). - `payer.address.zip_code` (string, optional) Payer's address zip code. - `payer.address.street_name` (string, optional) Payer's address street name. - `payer.address.street_number` (string, optional) Payer address street number. - `payer.address.state` (string, optional) Payer's address state. Can contain up to 50 characters. - `payer.address.city` (string, optional) Payer's address city. - `payer.address.complement` (string, optional) Payer's address complement. - `shipment` (object, optional) Shipping information. This parameter and its required attributes are needed only for PSE payments. - `shipment.address` (object, optional) Shipping address information. - `shipment.address.zip_code` (string, optional) Shipping address zip code. - `shipment.address.street_name` (string, optional) Shipping address street name. - `shipment.address.street_number` (string, optional) Shipping address street number. - `shipment.address.city` (string, optional) Shipping address city. - `shipment.address.state` (string, optional) Shipping address state. Can contain up to 50 characters. - `shipment.address.complement` (string, optional) Shipping address complement. - `total_amount` (string, optional) Total amount to be paid. The field can contain two decimal places or none. - `capture_mode` (string, optional) Order capture mode. Possible enum values: - `manual` Order's capture will be made manually. It allows the reservation of the transaction value in the payer's card, so the capture can be made afterwards, by using the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/checkout-api/capture-order/post). - `automatic` Order's capture will be made automatically. Authorize and capture values at the same time. - `automatic_async` The order can be processed asynchronously. The order may remain in `status=processing` awaiting asynchronous update and the final status will be updated later through [webhooks](/developers/en/docs/checkout-api-orders/notifications) or queries. - `processing_mode` (string, optional) Order processing mode Possible enum values: - `manual` Order's processing will be made manually. It is the processing mode used for the `manual` option, as it sets the processing to be made afterwards, by using the endpoint [POST /v1/orders/{order_id}/process](/developers/en/reference/online-payments/checkout-api/process-order/post). - `automatic` Order's processing will be made instantly. It is the capture mode used for the `automatic` option. - `expiration_time` (string, optional) When an order is created in [manual mode](/developers/en/docs/checkout-api-orders/integration-model#bookmark_processing_modes_for_orders) (`processing_mode=manual`), this parameter lets you define its expiration time using the ISO 8601 duration format. The period starts at `created_date` and the maximum limit is 2920 hours. If not sent, the default value will be `P1D` (one day). **This parameter must not be sent when creating an order in [automatic mode](/developers/en/docs/checkout-api-orders/integration-model#bookmark_processing_modes_for_orders) (`processing_mode=automatic`).** - `description` (string, optional) Description of the purchased product or service, the reason for the payment order, or the description of a product in the marketplace. - `integration_data` (object, optional) Additional information that can be used to integrate with other systems, such as the identifier of the order in the integrator's system. - `integration_data.integrator_id` (string, optional) Identifier of the integrator in Mercado Pago. It is the unique identifier of the integrator in Mercado Pago's systems. - `integration_data.platform_id` (string, optional) Identifier of the platform in Mercado Pago. It is the unique identifier of the platform in Mercado Pago's systems. - `integration_data.corporation_id` (string, optional) Identifier of the corporation in Mercado Pago. It is the unique identifier of the corporation in Mercado Pago's systems. - `integration_data.sponsor` (object, optional) Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems. - `integration_data.sponsor.id` (string, optional) Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems. Before making the request, remember to replace `` with your real `sponsor.id`. - `items` (array, optional) Information about the list of items to be paid. - `items[].title` (string, optional) Item name. The character limit is 150. - `items[].unit_price` (string, optional) Unit price of the purchased item. This field must have a maximum of 18 characters. - `items[].quantity` (Integer, optional) Purchased items quantity. - `items[].description` (string, optional) Purchased item description. The character limit is 100. - `items[].external_code` (string, optional) Item External code. - `items[].picture_url` (string, optional) Image URL corresponding to the item. - `items[].category_id` (string, optional) Item category ID. - `items[].type` (string, optional) Item type. - `items[].warranty` (boolean, optional) If the item has a warranty. - `items[].event_date` (string, optional) Event date. - `config` (object, optional) This `object` allows you to configure specific settings for the order, such as security settings for online transactions with cards using the 3DS (3D Secure) authentication protocol. - `config.location` (object, optional) Information about the payer's location. - `config.location.state_id` (string, optional) Code of the payer's state, province, or administrative region, formed by the two-letter country code, followed by a hyphen and the location code. The accepted values are: Possible enum values: - `CO-AMA` Amazonas. - `CO-ANT` Antioquia. - `CO-ARA` Arauca. - `CO-ATL` Atlántico. - `CO-DCO` Bogotá D.C.. - `CO-BOL` Bolívar. - `CO-BOY` Boyaca. - `CO-CAL` Caldas. - `CO-CAQ` Caqueta. - `CO-CAS` Casanare. - `CO-CAU` Cauca. - `CO-CES` Cesar. - `CO-CHO` Choco. - `CO-COR` Córdoba. - `CO-CUN` Cundinamarca. - `CO-GUA` Guainía. - `CO-LAG` Guajira. - `CO-GUV` Guaviare. - `CO-HUI` Huila. - `CO-MAG` Magdalena. - `CO-MET` Meta. - `CO-NAR` Nariño. - `CO-NSA` Norte De Santander. - `CO-PUT` Putumayo. - `CO-QUI` Quindio. - `CO-RIS` Risaralda. - `CO-SAP` San Andres y Providencia. - `CO-SAN` Santander. - `CO-SUC` Sucre. - `CO-TOL` Tolima. - `CO-VAC` Valle Del Cauca. - `CO-VAU` Vaupes. - `CO-VID` Vichada. - `config.online` (object, optional) This `object` contains settings that apply only to online transactions with cards. Use this configuration to indicate when 3DS (3D Secure) authentication should be triggered in case of fraud risk and to define financial liability in case of disputes. - `config.online.transaction_security` (object, optional) Transaction security configuration for 3DS (3D Secure). After creating the order, the response will indicate if the challenge is required. If not required, the `status` field will have the value `processed`, allowing you to continue normally with the application flow. If the challenge is required, the order will be returned with `status=action_required`, `status_detail=pending_challenge` and the challenge URL will be available in the `url` field. The challenge must be displayed in an iframe using the URL returned, allowing the buyer to complete authentication without leaving the checkout flow. The buyer has 40 minutes to complete the challenge from when the URL is created. If not completed within this period, the bank will reject the transaction and Mercado Pago will consider the payment expired. For more details on the complete integration flow, see the [3DS 2.0](/developers/en/docs/checkout-api-orders/payment-management/integrate-3ds) documentation. - `config.online.transaction_security.validation` (string, optional) Defines when the 3DS (3D Secure) flow should be executed. Possible enum values: - `on_fraud_risk` 3DS (3D Secure) is required according to transaction risk. Recommended to balance security and transaction approval. - `never` The 3DS (3D Secure) flow and challenge are never executed. This is the default value if the field is not sent. - `config.online.transaction_security.liability_shift` (string, optional) Defines the financial responsibility in case of dispute. Should not be sent when `validation` is `never`. Possible enum values: - `required` The financial responsibility in case of dispute is of the card brand. This is the only value accepted for 3DS (3D Secure). - `config.online.callback_url` (string, optional) - `additional_info` (object, optional) Additional information about the order. This parameter and its required attributes are needed only for PSE payments. - `additional_info.payer` (object, optional) Additional payer information. - `additional_info.payer.ip_address` (string, optional) IP address of the payer at the time the payment is generated. Required only for PSE payments. - `splits` (array, optional) List of receivers with their amounts. Required for Split Payments 1:N orders. - `splits[].receiver_id` (string, optional) Receiver identifier. For the primary receiver (`owner`), use their numeric `user_id` as a string. For each secondary receiver (`partner`), use the consent UUID returned by [POST /v1/split-consent](/developers/en/reference/online-payments/checkout-api/split-payments-1n/consent/create-consents/post). - `splits[].receiver_type` (string, optional) Receiver role: `owner` for the primary receiver, `partner` for secondary receivers. - `splits[].amount` (string, optional) Amount assigned to this receiver. - `splits[].description` (string, optional) Description of this split portion. ## Response parameters - `id` (string, optional) Identifier of the order created in the request, automatically generated by Mercado Pago. - `type` (string, optional) Order type, associated with the Mercado Pago solution for which it is created. For online card payments, the only possible value is `online`. Possible enum values: - `online` Value associated with the creation of Orders for online payments. - `processing_mode` (string, optional) Order processing mode Possible enum values: - `manual` Order's processing will be made manually. It is the processing mode used for the `manual` option, as it sets the processing to be made afterwards, by using the endpoint [POST /v1/orders/{order_id}/process](/developers/en/reference/online-payments/checkout-api/process-order/post). - `automatic` Order's processing will be made instantly. It is the capture mode used for the `automatic` option. - `expiration_time` (string, optional) Expiration period (in ISO 8601 format) returned for an order created in [manual mode](/developers/en/docs/checkout-api-orders/integration-model#bookmark_processing_modes_for_orders) (`processing_mode=manual`), counted from `created_date`. When omitted from the request, the returned default will be `P1D` (one day). **This parameter will not be returned for an order created in [automatic mode](/developers/en/docs/checkout-api-orders/integration-model#bookmark_processing_modes_for_orders) (`processing_mode=automatic`).** - `external_reference` (string, optional) It is an external reference of the order. It can be, for example, a hashcode from the Central Bank, functioning as an identifier of the transaction origin. This field must have a maximum of 64 characters and can only be numbers, letters, hyphens (-) and underscores (_). Special characters ([ ], (), '', @) are not allowed. Required for PSE payments. Optional for card and Efecty payments. - `total_amount` (string, optional) Total amount to be paid. - `total_paid_amount` (string, optional) Total amount to be paid, represents the sum of all the transaction's `paid_amount` values. - `integration_data` (object, optional) Additional information that can be used to integrate with other systems, such as the identifier of the order in the integrator's system. - `integration_data.application_id` (string, optional) Identifier of the Mercado Pago application that created the order. - `integration_data.integrator_id` (string, optional) Identifier of the integrator in Mercado Pago. It is the unique identifier of the integrator in Mercado Pago's systems. - `integration_data.platform_id` (string, optional) Identifier of the platform in Mercado Pago. It is the unique identifier of the platform in Mercado Pago's systems. - `integration_data.corporation_id` (string, optional) Identifier of the corporation in Mercado Pago. It is the unique identifier of the corporation in Mercado Pago's systems. - `integration_data.sponsor` (object, optional) Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems. - `integration_data.sponsor.id` (string, optional) Identifier of the sponsor in Mercado Pago. It is the unique identifier of the sponsor in Mercado Pago's systems. - `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. - `country_code` (string, optional) Identifier of the site (country) to which the Mercado Pago application that created the order belongs. - `status` (string, optional) Current status of the order. Possible enum values: - `created` The order has been created successfully. - `processed` All transactions have been successfully processed. - `action_required` Integrator action is required to complete processing. For example, the capture of an authorized payment. - `processing` The order is being processed and does not require any action from the integrator. For example, the payment may be pending manual review. This status may also be returned in the case of asynchronous payment creation. - `canceled` The order has been canceled and will not be processed further. - `status_detail` (string, optional) Details about payment status. Possible enum values: - `created` The order has been created successfully. - `accredited` Payment accredited. - `in_process` The payment is being processed. - `in_review` The payment is being reviewed. - `waiting_payment` The order is waiting for payment. - `waiting_capture` In cases of `status=action_required`, integrator action is required to complete processing. This `status_detail` indicates that the capture of an authorized payment is needed. - `waiting_transfer` The order is waiting for the transfer of funds. - `capture_mode` (string, optional) Order capture mode. Possible enum values: - `manual` Order's capture will be made manually. It allows the reservation of the transaction value in the payer's card, so the capture can be made afterwards, by using the endpoint [POST /v1/orders/{order_id}/capture](/developers/en/reference/online-payments/checkout-api/capture-order/post). - `automatic` Order's capture will be made automatically. Authorize and capture values at the same time. - `automatic_async` The order can be processed asynchronously. The order may remain in `status=processing` awaiting asynchronous update and the final status will be updated later through [webhooks](/developers/en/docs/checkout-api-orders/notifications) or queries. - `shipment` (object, optional) Shipping information. This parameter and its required attributes are needed only for PSE payments. - `shipment.address` (object, optional) Shipping address information. - `shipment.address.zip_code` (string, optional) Shipping address zip code. - `shipment.address.street_name` (string, optional) Shipping address street name. - `shipment.address.street_number` (string, optional) Shipping address street number. - `shipment.address.city` (string, optional) Shipping address city. - `shipment.address.state` (string, optional) Shipping address state. Can contain up to 50 characters. - `shipment.address.complement` (string, optional) Shipping address complement. - `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. - `transactions.payments[].paid_amount` (string, optional) Transaction paid amount. Represents the real amount paid including discounts or tips. - `transactions.payments[].reference_id` (string, optional) Reference ID of the transaction. - `transactions.payments[].status` (string, optional) Payment status. Possible enum values: - `created` The transaction has been created successfully. - `processed` All transactions have been successfully processed. - `action_required` Integrator action is required to complete processing. For example, the capture of an authorized payment. - `processing` The transaction is being processed and does not require any action from the integrator. For example, the payment may be pending manual review. - `transactions.payments[].status_detail` (string, optional) Details about payment status. Possible enum values: - `accredited` Payment accredited. - `waiting_capture` In cases of `status=action_required`, integrator action is required to complete processing. This `status_detail` indicates that the capture of an authorized payment is needed. - `created` The transaction has been created successfully. - `pending_review_manual` The payment is pending manual review. - `in_process` The payment is being processed. - `transactions.payments[].expiration_time` (string, optional) Transaction expiration date. - `transactions.payments[].payment_method` (object, optional) Information about the payment method. Access the endpoint [GET /v1/payment_methods](/developers/en/reference/online-payments/checkout-api/payment-methods/get) to check all available payment methods and get a list with the details of each one and their properties. - `transactions.payments[].payment_method.id` (string, optional) Identifier of the payment method selected to make the payment. If it's a card payment, it will show the brand. - `transactions.payments[].payment_method.type` (string, optional) Type of payment method selected to make the payment. - `transactions.payments[].payment_method.token` (string, optional) It is a mandatory field for card payments, as it is the token that identifies the card and contains its data securely. It has a minimum length of 32 characters, and a maximum length of 33. If you don't know how to generate it, go to the [card payment configuration](/developers/en/docs/checkout-api-orders/payment-integration/websites/cards). - `transactions.payments[].payment_method.installments` (integer, optional) Number of installments selected. - `transactions.payments[].payment_method.statement_descriptor` (string, optional) Description used to identify the charge on the buyer's payment method statement. Accepts up to 50 characters. - `transactions.payments[].payment_method.financial_institution` (string, optional) Financial institution. It is returned for the `pse` payment method. - `transactions.payments[].payment_method.redirect_url` (string, optional) Redirect URL for the "PSE" bank transfer. In a productive environment, the buyer must be redirected to this URL to complete the payment in their bank's online platform and, in a test environment (Sandbox), you can use this URL to test the `pse` integration. - `transactions.payments[].payment_method.transaction_security` (object, optional) Transaction security configuration for 3DS (3D Secure), an authentication protocol used in online transactions with card. After creating the order, the response will indicate if the challenge is required. If not required, the `status` field will have the value `processed`, allowing you to continue normally with the application flow. If the challenge is required, the order will be returned with `status=action_required`, `status_detail=pending_challenge` and the challenge URL will be available in the `url` field. The challenge must be displayed in an iframe using the URL returned, allowing the buyer to complete authentication without leaving the checkout flow. The buyer has 40 minutes to complete the challenge from when the URL is created. If not completed within this period, the bank will reject the transaction and Mercado Pago will consider the payment expired. For more details on the complete integration flow, see the [3DS 2.0](/developers/en/docs/checkout-api-orders/payment-management/integrate-3ds) documentation. - `transactions.payments[].payment_method.transaction_security.validation` (string, optional) Defines when the 3DS (3D Secure) flow should be executed. Possible enum values: - `on_fraud_risk` 3DS (3D Secure) is required according to transaction risk. Recommended to balance security and transaction approval. - `never` The 3DS (3D Secure) flow and challenge are never executed. This is the default value if the field is not sent. - `transactions.payments[].payment_method.transaction_security.liability_shift` (string, optional) Defines the financial responsibility in case of dispute. Should not be sent when `validation` is `never`. Possible enum values: - `required` The financial responsibility in case of dispute is of the card brand. This is the only value accepted for 3DS (3D Secure). - `transactions.payments[].payment_method.transaction_security.url` (string, optional) URL of the challenge displayed after creating an order returned with `status=action_required` and `status_detail=pending_challenge`. The challenge must be displayed in an iframe using the returned URL, allowing the buyer to complete authentication without leaving the checkout flow. The buyer has 40 minutes to complete the challenge from when the URL is created. If not completed within this period, the bank will reject the transaction and Mercado Pago will consider the payment expired. For more details on the complete integration flow, see the [3DS 2.0](/developers/en/docs/checkout-api-orders/payment-management/integrate-3ds) documentation. - `transactions.payments[].payment_method.transaction_security.id` (string, optional) ID of the challenge of the 3DS (3D Secure) security protocol. - `transactions.payments[].payment_method.transaction_security.type` (string, optional) Type of challenge. In the case of 3DS (3D Secure), the only possible value is `three_ds`. - `transactions.payments[].payment_method.transaction_security.status` (string, optional) Status of the challenge in the 3DS (3D Secure) security protocol. Possible enum values: - `AUTHENTICATED` Authentication performed by the responsible bank and forwarded to card brand validation. - `NOT_AUTHENTICATED` The challenge was not performed correctly or the responsible bank did not authorize the transaction due to some possible risk. - `CHALLENGE` The bank requested a challenge from the buyer and it has not yet been completed. - `ATTEMPTED` Authentication performed by the card brand. - `REJECTED` The responsible bank rejected the authentication due to some possible risk and also denied the possibility of challenge. - `ERROR` Missing some information required for 3DS authentication. Example: the `device_id` field was not filled. - `transactions.payments[].date_of_expiration` (string, optional) Date and time of the expiration of the payment. It is returned in the response to the request made to the endpoint [POST /v1/orders](/developers/en/reference/online-payments/checkout-api/create-order/post). If an `expiration_time` is not sent, this field adopts a default value that depends on the payment method. - `description` (string, optional) Description of the purchased product or service , the reason for the payment order, or the description of a product in the marketplace. - `items` (array, optional) Information about the list of items to be paid. - `items[].title` (string, optional) Item name. The character limit is 150. - `items[].unit_price` (string, optional) Unit price of the purchased item. This field must have a maximum of 18 characters. - `items[].quantity` (Integer, optional) Purchased items quantity. - `items[].description` (string, optional) Purchased item description. The character limit is 100. - `items[].external_code` (string, optional) Item External code. - `items[].picture_url` (string, optional) Image URL corresponding to the item. - `items[].category_id` (string, optional) Item category ID. - `items[].type` (string, optional) Item type. - `items[].warranty` (boolean, optional) If the item has a warranty. - `items[].event_date` (string, optional) Event date. - `client_token` (string, optional) Authentication token to execute operations on the client side. - `config` (object, optional) Specific settings configured for the order. - `config.online` (object, optional) Settings that apply only to online transactions with cards. - `config.online.callback_url` (string, optional) URL to which Mercado Pago will redirect the buyer after the payment is completed on the chosen bank's platform. Only for bank transfers via "PSE". ## 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 value sent in the `X-Idempotency-Key` header exceeded the allowed size. The header accepts values between 1 and 128 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 to execute the request was not sent. Check the message returned in the error details to find out what the problem was and try again. | | 400 | property_type | The wrong property type was submitted. For example, an `integer` value for a `string` property. Check the message returned in the error details to find out what the problem was and try again. | | 400 | minimum_items | The minimum number of items for some property was not sent. Check the message returned in the error details to find out what the problem was and try again. | | 400 | maximum_items | A greater number of items were sent than allowed for some property. Check the message returned in the error details to find out what the problem was and try again. | | 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. This error is also returned when the domain or content of `payer.email` is not allowed, when `config.location.state_id` is invalid for the site, or when the order-level `expiration_time` is not a valid ISO 8601 duration or exceeds 2920 hours. | | 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 was sent. Check the message returned in the error details to find out what the problem was and try again. | | 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_email_for_sandbox | Email format is invalid for sandbox environment, must contain `@testuser.com`. | | 400 | order_invalid_sponsor_id | Order `sponsor.id` is invalid. Make sure the ID is correct. | | 400 | invalid_header_value | Caller id (`caller_id`) not found. Make sure the ID is correct. | | 400 | order_builder_without_transactions | The `transactions` node of the order created in `manual` mode cannot be an empty `array`. Send it with the value `null` to try again. | | 400 | invalid_order_type | The order type provided is invalid or not supported. Expected one of: `online`. | | 401 | 401 | The value sent as Access Token is incorrect. Please check and try again with the correct value. | | 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. | | 403 | forbidden | The application does not have permission to access this resource. Please check that the Access Token used has the necessary permissions and scopes for this operation. | | 403 | PA_UNAUTHORIZED_RESULT_FROM_POLICIES | The account is blocked and its API keys have been revoked. At least one policy evaluated by the Policy Agent returned an `UNAUTHORIZED` result. | | 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. | | 423 | resource_locked | Idempotency key (`X-Idempotency-Key`) locked. Please retry after some time. | | 429 | too_many_requests | Client ID blocked by the gateway because the request limit for the ID in question was reached. Read the `Retry-After` header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests. | | 429 | usage_quota_exceeded | Quota enforced by the API backend because the per-client request limit was reached. Read the `Retry-After` header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests. | | 500 | idempotency_validation_failed | Idempotency validation failure. 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 ' \ -d '{ "type": "online", "external_reference": "ext_ref_1234", "transactions": { "payments": { "amount": "50.00", "payment_method": { "id": "master", "type": "credit_card", "token": "12345", "installments": 1, "statement_descriptor": "My Store", "financial_institution": "1051" }, "expiration_time": "P3Y6M4DT12H30M5S", "date_of_expiration": "2027-12-31T10:00:00.000-04:00" } }, "payer": { "email": "test@testuser.com", "entity_type": "individual", "first_name": "Sofia", "last_name": "Rodríguez", "identification": { "type": "NIT", "number": "123456789-0" }, "phone": { "area_code": "1", "number": "300-1234567" }, "address": { "zip_code": "110221", "street_name": "Rua Teste", "street_number": "93-09", "state": "Bogotá D.C.", "city": "Bogotá", "complement": "Apto 303" } }, "shipment": { "address": { "zip_code": "110221", "street_name": "Rua Teste", "street_number": "93-09", "city": "Bogotá", "state": "Bogotá D.C.", "complement": "Apto 303" } }, "total_amount": "50.00", "capture_mode": "automatic", "processing_mode": "automatic", "expiration_time": "PT2H", "description": "Smartphone", "integration_data": { "integrator_id": "dev_123", "platform_id": "1234567890", "corporation_id": "string", "sponsor": { "id": "446566691" } }, "items": [ { "title": "Smartphone", "unit_price": "24.50", "quantity": 4, "description": "Smartphone", "external_code": "1234", "picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png", "category_id": "MLB1055", "type": "MLB1055", "warranty": "true", "event_date": "2014-06-28T16:53:03.176-04:00" } ], "config": { "location": { "state_id": "CO-DC" }, "online": { "transaction_security": { "validation": "on_fraud_risk", "liability_shift": "required" }, "callback_url": "string" } }, "additional_info": { "payer": { "ip_address": "200.100.50.25" } }, "splits": [ { "receiver_id": "3085796294", "receiver_type": "owner", "amount": "250.00", "description": "Receptor primario" } ] }' ``` ## Response example ```json { "id": "ORD01J49MMW3SSBK5PSV3DFR32959", "type": "online", "processing_mode": "automatic", "expiration_time": "PT2H", "external_reference": "ext_ref_1234", "total_amount": "50.00", "total_paid_amount": "50.00", "integration_data": { "application_id": "1234", "integrator_id": "dev_123", "platform_id": "1234567890", "corporation_id": "string", "sponsor": { "id": "446566691" } }, "created_date": "2024-08-26T13:06:51.045317772Z", "last_updated_date": "2024-08-26T13:06:51.045317772Z", "country_code": "COL", "status": "processed", "status_detail": "accredited", "capture_mode": "automatic", "shipment": { "address": { "zip_code": "110221", "street_name": "Rua Teste", "street_number": "93-09", "city": "Bogotá", "state": "Bogotá D.C.", "complement": "Apto 303" } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.50", "paid_amount": "47.28", "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9", "status": "processed", "status_detail": "accredited", "expiration_time": "P3Y6M4DT12H30M5S", "payment_method": { "id": null, "type": null, "token": null, "installments": null, "statement_descriptor": null, "financial_institution": null, "redirect_url": null, "transaction_security": null }, "date_of_expiration": "2027-12-31T10:00:00.000-04:00" } ] }, "description": "Smartphone", "items": [ { "title": "Smartphone", "unit_price": "24.50", "quantity": 4, "description": "Smartphone", "external_code": "1234", "picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png", "category_id": "MLB1055", "type": "MLB1055", "warranty": "true", "event_date": "2014-06-28T16:53:03.176-04:00" } ], "client_token": "QWERTY12345.ASDFG67890", "config": { "online": { "callback_url": "https://merchant.com/pse/return" } } } ``` ## Use cases ### Create order with Split Payments 1:N ```bash curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "type": "online", "external_reference": "ext_ref_1234", "transactions": { "payments": { "amount": "500.00", "payment_method": { "id": "visa", "type": "credit_card", "token": "12345", "installments": 1 } } }, "payer": { "email": "test@testuser.com" }, "total_amount": "500.00", "processing_mode": "automatic", "integration_data": { "corporation_id": "string" }, "config": { "location": { "state_id": "CO-DC" }, "online": { "transaction_security": {}, "callback_url": "string" } }, "additional_info": { "payer": { "ip_address": "200.100.50.25" } }, "splits": [ { "receiver_id": "3085796294", "receiver_type": "owner", "amount": "250.00", "description": "todo ok 1" }, { "receiver_id": "f4d0f51c-be72-4652-8c06-919c9a36af1d", "receiver_type": "partner", "amount": "250.00", "description": "todo ok 2" } ] }' ``` ```json { "id": "ORDTST01KB0JDVXYPD6HPP2HSJDKH8FG", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "500.00", "total_paid_amount": "552.65", "integration_data": { "application_id": "874202490101010", "corporation_id": "string" }, "created_date": "2025-11-26T17:12:25.791Z", "last_updated_date": "2025-11-26T17:12:27.093Z", "country_code": "COL", "status": "processed", "status_detail": "accredited", "capture_mode": "automatic_async", "transactions": { "payments": [ { "id": "PAY01KB0JDVXYPD6HPP2HSMJS11QN", "amount": "50.00", "paid_amount": "47.28", "reference_id": "00076jffff", "status": "processed", "status_detail": "accredited", "payment_method": { "id": null, "type": null, "token": null, "installments": null, "redirect_url": null, "transaction_security": null } } ] }, "config": { "online": { "callback_url": "https://merchant.com/pse/return" } } } ``` ### Create payment with credit card ```bash curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "type": "online", "external_reference": "ext_ref_1234", "transactions": { "payments": { "amount": "50.00", "payment_method": { "id": "master", "type": "credit_card", "token": "1c87b6b301010101ddcd92f9bbbb3be2", "installments": 1 } } }, "payer": { "email": "test@testuser.com" }, "total_amount": "100.00", "processing_mode": "automatic", "integration_data": { "sponsor": {} }, "config": { "location": { "state_id": "CO-DC" }, "online": { "transaction_security": { "validation": "never" } } }, "additional_info": { "payer": { "ip_address": "200.100.50.25" } }, "splits": [ { "receiver_id": "3085796294", "receiver_type": "owner", "amount": "250.00", "description": "Receptor primario" } ] }' ``` ```json { "id": "ORDTST01KB0JDVXYPD6HPP2HSJDKH8FG", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "100.00", "total_paid_amount": "100.00", "integration_data": { "application_id": "874202490101010", "sponsor": {} }, "created_date": "2025-11-26T17:12:25.791Z", "last_updated_date": "2025-11-26T17:12:27.093Z", "country_code": "COL", "status": "processed", "status_detail": "accredited", "capture_mode": "automatic_async", "transactions": { "payments": [ { "id": "PAY01KB0JDVXYPD6HPP2HSMJS11QN", "amount": "100.00", "paid_amount": "100.00", "reference_id": "00076jffff", "status": "processed", "status_detail": "accredited", "payment_method": { "id": null, "type": null, "token": null, "installments": null, "transaction_security": null } } ] }, "config": { "online": {} } } ``` ### Create payment with debit card ```bash curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "type": "online", "external_reference": "ext_ref_123", "transactions": { "payments": { "amount": "100.00", "payment_method": { "id": "debvisa", "type": "debit_card", "token": "1c87b6b301010101ddcd92f9bbbb3be2" } } }, "payer": { "email": "test@testuser.com" }, "total_amount": "50.00", "processing_mode": "automatic", "integration_data": { "sponsor": {} }, "config": { "location": { "state_id": "CO-DC" }, "online": { "transaction_security": { "validation": "never" } } }, "additional_info": { "payer": { "ip_address": "200.100.50.25" } }, "splits": [ { "receiver_id": "3085796294", "receiver_type": "owner", "amount": "250.00", "description": "Receptor primario" } ] }' ``` ```json { "id": "ORDTST01KB0JDVXYPD6HPP2HSJDKH8FG", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_123", "total_amount": "100.00", "total_paid_amount": "100.00", "integration_data": { "application_id": "01010182923271683", "sponsor": {} }, "created_date": "2025-11-26T17:12:25.791Z", "last_updated_date": "2025-11-26T17:12:27.093Z", "country_code": "COL", "status": "processed", "status_detail": "accredited", "capture_mode": "automatic_async", "transactions": { "payments": [ { "id": "PAY01KB0JDVXYPD6HPP2HSMJS11QN", "amount": "100.00", "paid_amount": "100.00", "reference_id": "00076ggggg", "status": "processed", "status_detail": "accredited", "payment_method": { "id": null, "type": null, "token": null, "transaction_security": null } } ] }, "config": { "online": {} } } ```