Exemplos de payloads de pedidos por setor

Estes exemplos demonstram os corpos de requisição completos para POST /merchants/orders. Escolha um setor, inspecione cada campo e copie a solicitação JSON ou cURL. Os exemplos seguem o contrato público Create Order; os valores são expressos em unidades monetárias menores.

Quais campos são obrigatórios em order.items ao criar um pedido?#

A resposta curta é que o validador base da solicitação Criar Pedido não define uma propriedade universalmente exigida dentro de cada item. Ele valida se a matriz de itens está presente para um determinado tipo de pedido, e não o conteúdo de cada item.

Tipo de pedido	Objeto obrigatório	Comportamento básico do contrato
`DEUNA_CHECKOUT`	`order.items`	Obrigatório. Quando fornecido, o tipo de atendimento aceita apenas `dine_in`, `pickup`, ou `delivery`.
`SUBSCRIPTIONS`	`order.items`	Obrigatório. Marque as linhas aplicáveis com `included_in_subscription`.
`AIRLINE_ORDER`	`order.airline_information`	Obrigatório. A matriz de itens permanece opcional no nível do contrato base.
`DEUNA_NOW`	Nenhum	A matriz de itens não é exigida pelo contrato base. Inclua-o quando o processamento posterior precisar de detalhes do produto.
`PAYMENT_LINK`	Nenhum	A matriz de itens não é exigida pelo contrato base. Inclua-o quando a experiência hospedada ou o processamento downstream precisar de detalhes do produto.

Um item vazio não é um alvo de integração útil. Provedores de pagamento, verificações de fraude, tratamento fiscal, relatórios e sua própria reconciliação podem precisar de mais detalhes. A menos que um guia do fornecedor estabeleça um requisito mais rigoroso, use esta linha de base portátil para cada item:

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
}

O modelo de item oferece suporte aos seguintes grupos de campos:

Objetivo	Campos suportados
Identidade do item do comerciante	`id`, `sku`, `upc`, `isbn`
Detalhe do item voltado para o cliente	`name`, `description`, `image_url`, `details_url`
Detalhes de quantidade e preço	`quantity`, `uom`, `unit_price`, `total_amount`, `tax_amount`, `taxable`, `discounts`
Detalhe do catálogo e da variante	`brand`, `manufacturer`, `category`, `sub_category`, `color`, `size`, `weight`
Cumprimento e contexto adicional	`options`, `type`, `item_details`, `included_in_subscription`, `shipping_options`

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

Mantenha as moedas dos itens e dos pedidos alinhadas e calcule os valores em unidades monetárias menores.

Campos obrigatórios no nível do pedido e regra de valor

Campo ou regra	Requisito
`order_id`	Obrigatório para cada pedido.
`currency`	Obrigatório para cada pedido.
`total_amount`	Deve ser maior que zero para pedidos de compra normais. Uma recorrência de valor zero no primeiro uso é a exceção documentada de verificação do cartão.
`sub_total + total_tax_amount = total_amount`	Aplicado sempre que um valor de imposto subtotal ou total é fornecido.

Guia de campo vertical#

QSR, cinema, bancos e varejo são padrões de documentação baseados no tipo de pedido de checkout padrão. Eles não são valores de tipo de pedido separados. As companhias aéreas usam o contrato de pedido de companhia aérea dedicado.

Verticais	Tipo de pedido	Conjunto de campos primários	Como usar
QSR	`DEUNA_CHECKOUT`	`items[].id`, `items[].sku`, `options`, `shipping_options`, `scheduled_at`, `user_instructions`	Identifique as linhas e modificadores do menu, o modo de serviço e armazenamento, o tempo de preparação e as instruções de transferência. A matriz de itens é obrigatória.
Companhias aéreas	`AIRLINE_ORDER`	`airline_information.booking_items`, `pnr`, `ticket_number`, `passenger`, `legs`, `ancillaries`	Envie detalhes de reserva, passagem, agência, passageiro, itinerário e serviço pago. São necessárias informações da companhia aérea; a matriz de itens é opcional no nível do contrato base.
Cinema	`DEUNA_CHECKOUT`	`items`, `type`, `options`, `shipping_options.details`, `expires_at`	Modele ingressos e concessões como linhas separadas, identifique ingressos para eventos e anexe horário de exibição, assentos, local, destinatário e prazo de reserva de assento. A matriz de itens é obrigatória.
Bancos	`DEUNA_CHECKOUT`	`items`, `type`, `description`, `statement_descriptor`, `initiator_type`, `channel_type`, `metadata`	Modele o pagamento como um serviço e envie referências comerciais mascaradas ou tokenizadas. A matriz de itens é obrigatória. Nunca coloque números de conta completos ou credenciais em metadados.
Varejo	`DEUNA_CHECKOUT`	`items`, `discounts`, `shipping_address`, `shipping_method`, `shipping_options`	Envie a identidade do produto e da variante, promoções, destino, método de entrega e contexto de atendimento. A matriz de itens é obrigatória. Mantenha as referências de descontos de itens alinhadas com a matriz de descontos no nível do pedido.

Exemplos completos#

Payload completo do pedido

QSR

Cardápio, modificadores, modalidade de serviço, local, horário e instruções do cliente em um único pedido de restaurante.

Abrir guia do setor

itemsshipping_optionsscheduled_atuser_instructions

Corpo da solicitaçãoJSON

{
  "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"
    }
  }
}

O que permanece constante#

Cada setor utiliza o mesmo contrato básico:

order_id, store_codee currency Identifique o contexto de negócios do comerciante.
Os valores são inteiros em unidades monetárias menores e devem corresponder aos detalhes do item, impostos, descontos e frete.
items Descreva o que o cliente está comprando ou pagando.
payer_info, channel_typee initiator_type Especifique quem iniciou o processo e onde.
callback_urls e o valor retornado order_token Conecte a solicitação síncrona ao seu resultado final.
metadata Transporta referências definidas pelo comerciante; os campos de tipo suportados devem ser preferidos sempre que possível.

Continue a integração#

Criar um pedidoCarregue um exemplo completo na área de solicitação interativa.Processar o pagamentoEnvie o token de pedido com os dados do pagador e da fonte de pagamento.Confirme o estado finalConsuma as atualizações assíncronas verificadas antes da entrega.