Ejemplos de payloads de pedidos por industria

Estos ejemplos muestran los cuerpos de solicitud completos para POST /merchants/orders. Elija una industria, inspeccione todos los campos y copie la solicitud JSON o cURL. Los ejemplos siguen el contrato público Crear orden; Los importes se expresan en unidades monetarias menores.

¿Qué campos son obligatorios en order.items al crear un pedido?#

La respuesta corta es que el validador de solicitudes básico Crear pedido no define una propiedad requerida universalmente dentro de cada artículo. Valida si la matriz de artículos está presente para un tipo de pedido en particular, no el contenido de cada artículo.

Tipo de orden	Objeto requerido	Comportamiento del contrato base
`DEUNA_CHECKOUT`	`order.items`	Requerido. Cuando se suministra, el tipo de cumplimiento acepta solo `dine_in`, `pickup`o `delivery`.
`SUBSCRIPTIONS`	`order.items`	Requerido. Marque las líneas aplicables con `included_in_subscription`.
`AIRLINE_ORDER`	`order.airline_information`	Requerido. La matriz de elementos sigue siendo opcional en el nivel del contrato base.
`DEUNA_NOW`	Ninguno	El contrato base no requiere la matriz de elementos. Inclúyalo cuando el procesamiento posterior necesite detalles del producto.
`PAYMENT_LINK`	Ninguno	El contrato base no requiere la matriz de elementos. Inclúyalo cuando la experiencia alojada o el procesamiento posterior necesiten detalles del producto.

Un elemento vacío no es un objetivo de integración útil. Es posible que los proveedores de pagos, los controles de fraude, el manejo de impuestos, los informes y su propia conciliación necesiten más detalles. A menos que una guía del proveedor establezca un requisito más estricto, utilice esta línea de base portátil para cada artículo:

JSON

{
  "id": "merchant-item-001",
  "sku": "SKU-001",
  "name": "Product name",
  "quantity": 1,
  "unit_price": {
    "amount": 2500,
    "currency": "USD"
  },
  "total_amount": {
    "amount": 2500,
    "original_amount": 2500,
    "total_discount": 0,
    "currency": "USD"
  },
  "tax_amount": {
    "amount": 0,
    "currency": "USD"
  },
  "category": "products",
  "type": "physical",
  "taxable": false
}

El modelo de artículo admite los siguientes grupos de campos:

Propósito	Campos admitidos
Identidad del artículo comercial	`id`, `sku`, `upc`, `isbn`
Detalle del artículo de cara al cliente	`name`, `description`, `image_url`, `details_url`
Detalle de cantidad y precio	`quantity`, `uom`, `unit_price`, `total_amount`, `tax_amount`, `taxable`, `discounts`
Detalle de catálogo y variantes.	`brand`, `manufacturer`, `category`, `sub_category`, `color`, `size`, `weight`
Cumplimiento y contexto adicional	`options`, `type`, `item_details`, `included_in_subscription`, `shipping_options`

Campo	Valores documentados
`type`	`physical`, `digital`, `event`, `service`

Mantenga alineadas las monedas de los artículos y los pedidos y calcule los montos en unidades monetarias menores.

Campos obligatorios a nivel de pedido y regla de importe

Campo o regla	Requisito
`order_id`	Requerido para cada pedido.
`currency`	Requerido para cada pedido.
`total_amount`	Debe ser mayor que cero para órdenes de compra normales. Una recurrencia de primer uso de valor cero es la excepción de verificación de tarjeta documentada.
`sub_total + total_tax_amount = total_amount`	Se aplica siempre que se proporciona un importe de impuesto total o subtotal.

Guía de campo vertical#

QSR, cine, banca y comercio minorista son patrones de documentación basados en el tipo de orden de pago estándar. No son valores de tipo de orden separados. Las aerolíneas utilizan el contrato de pedido de aerolínea exclusivo.

verticales	Tipo de orden	Conjunto de campos primarios	como usarlo
QSR	`DEUNA_CHECKOUT`	`items[].id`, `items[].sku`, `options`, `shipping_options`, `scheduled_at`, `user_instructions`	Identifique líneas de menú y modificadores, el modo de servicio y la tienda, el tiempo de preparación y las instrucciones de entrega. La matriz de elementos es obligatoria.
Aerolíneas	`AIRLINE_ORDER`	`airline_information.booking_items`, `pnr`, `ticket_number`, `passenger`, `legs`, `ancillaries`	Enviar detalles de reserva, boleto, agencia, pasajero, itinerario y servicio pago. Se requiere información de la aerolínea; la matriz de elementos es opcional en el nivel de contrato base.
Cine	`DEUNA_CHECKOUT`	`items`, `type`, `options`, `shipping_options.details`, `expires_at`	Modele boletos y concesiones como líneas separadas, identifique boletos para eventos y adjunte la hora de proyección, los asientos, el lugar, el destinatario y la fecha límite para reservar asientos. La matriz de elementos es obligatoria.
Bancos	`DEUNA_CHECKOUT`	`items`, `type`, `description`, `statement_descriptor`, `initiator_type`, `channel_type`, `metadata`	Modele el pago como un servicio y envíe referencias comerciales enmascaradas o tokenizadas. La matriz de elementos es obligatoria. Nunca incluya números de cuenta completos o credenciales en metadatos.
Comercio minorista	`DEUNA_CHECKOUT`	`items`, `discounts`, `shipping_address`, `shipping_method`, `shipping_options`	Envíe identidad de producto y variante, promociones, destino, método de entrega y contexto de cumplimiento. La matriz de elementos es obligatoria. Mantenga las referencias de descuento de artículos alineadas con la matriz de descuentos a nivel de pedido.

Ejemplos completos#

Payload completo de la orden

QSR

Menú, modificadores, modalidad de servicio, ubicación, horario e instrucciones del cliente en una sola orden de restaurante.

Abrir guía de la industria

itemsshipping_optionsscheduled_atuser_instructions

Cuerpo de la solicitudJSON

{
  "order_type": "DEUNA_CHECKOUT",
  "order": {
    "order_id": "qsr-2048",
    "store_code": "mad-gran-via-01",
    "currency": "EUR",
    "items_total_amount": 2890,
    "sub_total": 2890,
    "total_tax_amount": 286,
    "total_amount": 3176,
    "items": [
      {
        "id": "meal-smash-01",
        "sku": "SMASH-COMBO",
        "name": "Smash burger combo",
        "description": "Burger, fries, and drink",
        "options": "medium; no onions; sparkling water",
        "quantity": 1,
        "category": "combos",
        "taxable": true,
        "unit_price": {
          "amount": 1890,
          "currency": "EUR",
          "currency_symbol": "€"
        },
        "total_amount": {
          "amount": 1890,
          "original_amount": 1890,
          "currency": "EUR",
          "currency_symbol": "€",
          "total_discount": 0
        },
        "tax_amount": {
          "amount": 172,
          "currency": "EUR",
          "currency_symbol": "€"
        }
      },
      {
        "id": "side-wings-06",
        "sku": "WINGS-6",
        "name": "Six hot wings",
        "options": "chipotle sauce",
        "quantity": 1,
        "category": "sides",
        "taxable": true,
        "unit_price": {
          "amount": 1000,
          "currency": "EUR",
          "currency_symbol": "€"
        },
        "total_amount": {
          "amount": 1000,
          "original_amount": 1000,
          "currency": "EUR",
          "currency_symbol": "€",
          "total_discount": 0
        },
        "tax_amount": {
          "amount": 114,
          "currency": "EUR",
          "currency_symbol": "€"
        }
      }
    ],
    "shipping_options": {
      "type": "pickup",
      "method": "counter",
      "requires_shipping": false,
      "details": {
        "store_id": "mad-gran-via-01",
        "store_name": "Gran Vía",
        "address": "Calle Gran Vía 42, Madrid",
        "address_coordinates": {
          "lat": 40.4201,
          "lng": -3.7058
        },
        "contact": {
          "name": "Gran Vía team",
          "phone": "+34910000000"
        },
        "additional_details": {
          "pickup_time": "2026-10-03T18:30:00Z",
          "stock_location": "Front counter"
        }
      }
    },
    "scheduled_at": "2026-10-03T18:30:00Z",
    "user_instructions": "Label the order for Alex. Include napkins.",
    "payer_info": {
      "email": "alex@example.com",
      "external_registration_date": "2024-02-10T12:00:00Z"
    },
    "channel_type": "mobile_app_ios",
    "metadata": {
      "vertical": "qsr",
      "service_mode": "pickup",
      "loyalty_member_id": "LOY-88201"
    },
    "callback_urls": {
      "on_success": "https://merchant.example.com/payments/success",
      "on_pending": "https://merchant.example.com/payments/pending",
      "on_reject": "https://merchant.example.com/payments/rejected",
      "on_canceled": "https://merchant.example.com/payments/canceled",
      "on_failed": "https://merchant.example.com/payments/failed"
    }
  }
}

Qué es común#

Cada sector utiliza el mismo contrato básico:

order_id, store_codey currency identificar el contexto del negocio del comerciante.
Los importes son enteros en unidades monetarias menores y deben coincidir con los detalles de los artículos, impuestos, descuentos y envío.
items describir lo que el cliente está comprando o pagando.
payer_info, channel_typey initiator_type clarificar quién inició el flujo y dónde.
callback_urls y el order_token conecta la solicitud sincrónica con su resultado final.
metadata transporta referencias definidas por el comerciante; se deben preferir los campos de tipo cuando existan.

Continúe con la integración#

Crear un pedidoCargue un ejemplo completo en el panel de solicitud interactivo.Procese el pagoEnvíe el token del pedido con los datos del pagador y la fuente de pago.Confirmar el estado finalConsuma las actualizaciones asíncronas verificadas antes de la entrega.