Esempi di richieste di ordini e pagamenti per settore

Questi esempi mostrano corpi completi di richieste di ordini e pagamenti per ogni settore. Inizia con POST /v2/merchants/orders/purchase per creare e pagare un ordine inline in un’unica richiesta. La creazione separata dell’ordine con POST /merchants/orders è facoltativa.

Scegli il flusso della richiesta#

Flusso	Fine	Quando usarlo
Purchase V2 · Consigliato	`POST /v2/merchants/orders/purchase`	Invia insieme l’ordine inline, il pagatore e la fonte di pagamento tokenizzata. DEUNA crea l’ordine come parte della richiesta di pagamento.
Crea prima l’ordine · Facoltativo	`POST /merchants/orders`, quindi `POST /v2/merchants/orders/purchase`	Crea l’ordine separatamente solo quando l’integrazione richiede un `order_token` prima del pagamento, ad esempio per inizializzare Checkout, riutilizzare lo stesso ordine tra canali o recuperarlo prima del tentativo di pagamento.

Gli esempi seguenti supportano entrambi i flussi. Scegli un settore, passa da un tipo di richiesta all’altro e copia la richiesta JSON o cURL. Gli importi sono espressi nelle unità monetarie minori.

Quali campi sono obbligatori in order.items?#

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#

Ogni esempio identifica l’endpoint di destinazione. Purchase V2 · Consigliato contiene la richiesta di pagamento completa in un’unica chiamata. Crea prima l’ordine · Facoltativo contiene solo la richiesta che crea l’ordine; usa il order_token restituito nella richiesta Purchase V2.

Richiesta completa

QSR

Elabora il pagamento in una richiesta inviando inline l’ordine, il pagatore e la fonte di pagamento tokenizzata.

POST/v2/merchants/orders/purchase

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

{
  "payer_info": {
    "email": "alex@example.com",
    "external_registration_date": "2024-02-10T12:00:00Z"
  },
  "payment_source": {
    "method_type": "credit_card",
    "payment_method": "TOKENIZED_PAYMENT_METHOD"
  },
  "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.",
    "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#

Elaborare il pagamentoInvia l’ordine inline o fornisci un token di ordine esistente.Crea un ordine · FacoltativoCrea prima l’ordine solo quando l’integrazione richiede il token prima del pagamento.Confermare lo stato finaleRiconciliare gli aggiornamenti del provider asincroni prima della finalizzazione.

Scegli il flusso della richiestaChiedi ad Athia informazioni#

Quali campi sono obbligatori in order.items?Chiedi ad Athia informazioni#

Campi obbligatori a livello di ordine e regola di importo

Guida del campo verticaleChiedi ad Athia informazioni#

Esempi completiChiedi ad Athia informazioni#

QSR

Cosa rimane comuneChiedi ad Athia informazioni#

Procedere con l'integrazioneChiedi ad Athia informazioni#