Esempi di payload per ordini, per settore

Questi esempi mostrano i corpi di richiesta completi per POST /merchants/orders. Scegli un settore, ispeziona ogni campo e copia la richiesta JSON o cURL. Gli esempi seguono il contratto pubblico Create Order; gli importi sono espressi in unità monetarie minori.

Quali campi sono richiesti in order.items quando si crea un ordine?#

La risposta breve è che il validatore di richiesta di creazione ordine di base non definisce una proprietà universalmente richiesta all'interno di ciascun articolo. Verifica se l'array degli articoli è presente per un particolare tipo di ordine, non il contenuto di ciascun articolo.

Tipo di ordine	Oggetto richiesto	Comportamento contrattuale di base
`DEUNA_CHECKOUT`	`order.items`	Obbligatorio. Se fornito, il tipo di evasione accetta solo `dine_in`, `pickup`o `delivery`.
`SUBSCRIPTIONS`	`order.items`	Obbligatorio. Contrassegnare le linee applicabili con `included_in_subscription`.
`AIRLINE_ORDER`	`order.airline_information`	Obbligatorio. La matrice degli articoli rimane facoltativa a livello del contratto base.
`DEUNA_NOW`	Nessuno	La matrice degli articoli non è richiesta dal contratto di base. Includilo quando l'elaborazione a valle richiede dettagli sul prodotto.
`PAYMENT_LINK`	Nessuno	La matrice degli articoli non è richiesta dal contratto di base. Includilo quando l'esperienza ospitata o l'elaborazione downstream richiedono dettagli sul prodotto.

Un elemento vuoto non è un obiettivo di integrazione utile. I fornitori di servizi di pagamento, i controlli antifrode, la gestione fiscale, la rendicontazione e la tua riconciliazione potrebbero richiedere maggiori dettagli. A meno che una guida del fornitore non indichi un requisito più rigoroso, utilizza questa linea di base portatile per ogni articolo:

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
}

Il modello di articolo supporta i seguenti gruppi di campi:

Oggetto	Campi supportati
Identità dell'articolo del commerciante	`id`, `sku`, `upc`, `isbn`
Dettagli dell'articolo rivolto al cliente	`name`, `description`, `image_url`, `details_url`
Dettagli su quantità e prezzi	`quantity`, `uom`, `unit_price`, `total_amount`, `tax_amount`, `taxable`, `discounts`
Catalogo e dettaglio varianti	`brand`, `manufacturer`, `category`, `sub_category`, `color`, `size`, `weight`
Realizzazione e contesto aggiuntivo	`options`, `type`, `item_details`, `included_in_subscription`, `shipping_options`

Campo	Valori documentati
`type`	`physical`, `digital`, `event`, `service`

Mantieni allineate le valute degli articoli e degli ordini e calcola gli importi nelle unità valutarie minori.

Campi obbligatori a livello di ordine e regola di importo

Campo o regola	Requisito
`order_id`	Obbligatorio per ogni ordine.
`currency`	Obbligatorio per ogni ordine.
`total_amount`	Deve essere maggiore di zero per i normali ordini di acquisto. Una ricorrenza del primo utilizzo con valore zero è l'eccezione documentata di verifica della carta.
`sub_total + total_tax_amount = total_amount`	Applicato ogni volta che viene fornito un importo totale o parziale dell'imposta.

Guida del campo verticale#

QSR, cinema, servizi bancari e vendita al dettaglio sono modelli di documentazione basati sul tipo di ordine di pagamento standard. Non sono valori di tipo ordine separati. Le compagnie aeree utilizzano il contratto d'ordine della compagnia aerea dedicato.

Verticale	Tipo di ordine	Insieme di campi primari	Come usarlo
QSR	`DEUNA_CHECKOUT`	`items[].id`, `items[].sku`, `options`, `shipping_options`, `scheduled_at`, `user_instructions`	Identificare le righe e i modificatori del menu, la modalità di servizio e il negozio, il tempo di preparazione e le istruzioni di trasferimento. La matrice degli elementi è obbligatoria.
Compagnie aeree	`AIRLINE_ORDER`	`airline_information.booking_items`, `pnr`, `ticket_number`, `passenger`, `legs`, `ancillaries`	Invia prenotazione, biglietto, agenzia, passeggero, itinerario e dettagli del servizio a pagamento. Sono richieste le informazioni sulla compagnia aerea; l'array degli articoli è facoltativo a livello del contratto base.
Cinema	`DEUNA_CHECKOUT`	`items`, `type`, `options`, `shipping_options.details`, `expires_at`	Modella biglietti e concessioni come linee separate, identifica i biglietti per gli eventi e allega l'orario di proiezione, i posti, il luogo, il destinatario e la scadenza per la prenotazione del posto. La matrice degli elementi è obbligatoria.
Banca	`DEUNA_CHECKOUT`	`items`, `type`, `description`, `statement_descriptor`, `initiator_type`, `channel_type`, `metadata`	Modella il pagamento come servizio e invia riferimenti aziendali mascherati o tokenizzati. La matrice degli elementi è obbligatoria. Non inserire mai numeri di conto o credenziali completi nei metadati.
Commercio al dettaglio	`DEUNA_CHECKOUT`	`items`, `discounts`, `shipping_address`, `shipping_method`, `shipping_options`	Invia l'identità del prodotto e della variante, le promozioni, la destinazione, il metodo di consegna e il contesto di evasione. La matrice degli elementi è obbligatoria. Mantieni i riferimenti di sconto sugli articoli allineati con l'array di sconti a livello di ordine.

Esempi completi#

Payload completo dell’ordine

QSR

Menu, modificatori, modalità di servizio, sede, orario e istruzioni del cliente in un unico ordine di ristorazione.

Apri la guida del settore

itemsshipping_optionsscheduled_atuser_instructions

Corpo della richiestaJSON

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

Cosa rimane comune#

Ogni settore utilizza lo stesso contratto di base:

order_id, store_codee currency Identificare il contesto aziendale del commerciante.
Gli importi sono numeri interi in unità di valuta minori e devono corrispondere ai dettagli dell'articolo, delle tasse, degli sconti e della spedizione.
items Descrivere cosa il cliente sta acquistando o pagando.
payer_info, channel_typee initiator_type Chiarire chi ha avviato il processo e dove.
callback_urls e i dati restituiti order_token Collegare la richiesta sincrona al suo risultato finale.
metadata contiene riferimenti definiti dal commerciante; è preferibile utilizzare i campi di tipo supportati quando disponibili.

Procedere con l'integrazione#

Crea un ordineCaricare un esempio completo nel pannello di richiesta interattivo.Elaborare il pagamentoInviare il token dell'ordine insieme ai dati del pagatore e della fonte di pagamento.Confermare lo stato finaleConsumare gli aggiornamenti asincroni verificati prima della spedizione.