mercadopago.orders.create-order

Creates an Order for processing payment transactions. Supports automatic (single-stage, set processing_mode=automatic) and manual (multi-stage, set processing_mode=manual) modes. In automatic mode, include the transactions.payments array with the payment method. In manual mode, omit transactions and add them later via POST /v1/orders/{id}/transactions, then trigger processing with POST /v1/orders/{id}/process. Available for: credit card, debit card, Pix (MLB), Boleto (MLB), OXXO (MLM), SPEI (MLM), PSE (MCO), Rapipago (MLA), Pago Fácil (MLA).

Create an order

Overview

Property	Value
Workflow type	Atomic
Library	App-mercadopago
Version	1.0

Input Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Mercadopago API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
x_idempotency_key	string	Yes	—	Unique key per order creation attempt. Prevents duplicate orders on retry.
type	string	Yes	—	Order type. Only "online" is supported for online payments.
processing_mode	string	No	—	automatic — MP processes all transactions immediately in a single stage. manual — transactions are processed in configurable stages; use the /process endpoint to trigger processing after creation.
capture_mode	string	No	—	automatic — authorize and capture funds at the same time. manual — authorize only (reserve funds); capture later with /capture endpoint. automatic_async — order may remain in status=processing while awaiting async update; final status delivered via webhook.
total_amount	string	Yes	—	Total amount to be paid as a decimal string. Must equal the sum of all payment transaction amounts. Example: "100.00".
external_reference	string	No	—	Your internal order reference ID. Returned in all order responses.
description	string	No	—	Description of the purchased product or service.
payer	json	Yes	—	—
transactions	json	Yes	—	Payment transactions for this order. Currently supports one transaction.
config	json	No	—	Optional settings for the order.
items	list	No	—	Items included in the order.
shipment	json	No	—	—
additional_info	json	No	—	Additional information required for specific payment methods (e.g. PSE).
integration_data	json	No	—	Integration metadata used by MercadoPago internally.

Output Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Mercadopago API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
x_idempotency_key	string	Yes	—	Unique key per order creation attempt. Prevents duplicate orders on retry.
type	string	Yes	—	Order type. Only "online" is supported for online payments.
processing_mode	string	No	—	automatic — MP processes all transactions immediately in a single stage. manual — transactions are processed in configurable stages; use the /process endpoint to trigger processing after creation.
capture_mode	string	No	—	automatic — authorize and capture funds at the same time. manual — authorize only (reserve funds); capture later with /capture endpoint. automatic_async — order may remain in status=processing while awaiting async update; final status delivered via webhook.
total_amount	string	Yes	—	Total amount to be paid as a decimal string. Must equal the sum of all payment transaction amounts. Example: "100.00".
external_reference	string	No	—	Your internal order reference ID. Returned in all order responses.
description	string	No	—	Description of the purchased product or service.
payer	json	Yes	—	—
transactions	json	Yes	—	Payment transactions for this order. Currently supports one transaction.
config	json	No	—	Optional settings for the order.
items	list	No	—	Items included in the order.
shipment	json	No	—	—
additional_info	json	No	—	Additional information required for specific payment methods (e.g. PSE).
integration_data	json	No	—	Integration metadata used by MercadoPago internally.
status_code	integer	No	—	HTTP status code of the completed call
response	json	No	—	Parsed JSON response body
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_at	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
failed_at_state	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Waiting to call POST /v1/orders
completed	No	Yes	Yes	—	HTTP call succeeded
failed	No	Yes	No	—	HTTP call failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	Perform POST /v1/orders
* (any state)	fail	failed	Record the failure reason

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "mercadopago.orders.create-order",
  "initial_data": {
    "base_url": "value",
    "x_idempotency_key": "value",
    "type": "value",
    "total_amount": "value"
  }
}