Ejemplos de solicitudes de órdenes y pagos por industria

Estos ejemplos muestran cuerpos completos de solicitudes de órdenes y pagos para cada industria. Comienza con POST /v2/merchants/orders/purchase para crear y pagar una orden en línea en una sola solicitud. Crear la orden por separado con POST /merchants/orders es opcional.

Elige el flujo de solicitud#

Flujo	Punto final	Cuando usarlo
Purchase V2 · Recomendado	`POST /v2/merchants/orders/purchase`	Envía juntos la orden en línea, el pagador y la fuente de pago tokenizada. DEUNA crea la orden como parte de la solicitud de pago.
Crear primero la orden · Opcional	`POST /merchants/orders`, luego `POST /v2/merchants/orders/purchase`	Crea la orden por separado solo cuando tu integración necesite un `order_token` antes del pago; por ejemplo, para inicializar Checkout, reutilizar la misma orden entre canales o recuperarla antes del intento de pago.

Los ejemplos siguientes admiten ambos flujos. Elige una industria, cambia entre los dos tipos de solicitud y copia la solicitud JSON o cURL. Los importes se expresan en unidades monetarias menores.

¿Qué campos son obligatorios en order.items?#

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#

Cada ejemplo identifica el endpoint al que se dirige. Purchase V2 · Recomendado contiene la solicitud de pago completa de una sola llamada. Crear primero la orden · Opcional contiene solo la solicitud que crea la orden; usa el order_token devuelto en la solicitud de Purchase V2.

Solicitud completa

QSR

Procesa el pago en una solicitud enviando en línea la orden, el pagador y la fuente de pago tokenizada.

POST/v2/merchants/orders/purchase

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

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

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#

Procese el pagoEnvía la orden en línea o proporciona un token de orden existente.Crear una orden · OpcionalCrea primero la orden solo cuando tu integración necesite el token antes del pago.Confirmar el estado finalReconcile las actualizaciones del proveedor asíncronas antes de la finalización.

Elige el flujo de solicitudPreguntar a Athia sobre esto#

¿Qué campos son obligatorios en order.items?Preguntar a Athia sobre esto#

Campos obligatorios a nivel de pedido y regla de importe

Guía de campo verticalPreguntar a Athia sobre esto#

Ejemplos completosPreguntar a Athia sobre esto#

QSR

Qué es comúnPreguntar a Athia sobre esto#

Continúe con la integraciónPreguntar a Athia sobre esto#