Skip to main content
All systems operationalChangelogv1
Log in
Payments

Retail payments and orders

Build retail checkout with product, variant, promotion, shipping, fulfillment, and customer context.

On this page

Connect product-rich checkout to payment orchestration without losing the data required for fulfillment and support. DEUNA keeps catalog, promotion, delivery, and customer context on the same order used throughout the payment lifecycle.

Use this guide for digital-commerce implementations that need documented product, promotion, delivery, and fulfillment fields. The public API does not expose a separate DIGITAL_COMMERCE order type.

Catalog depthCarry SKU, UPC, brand, category, variant, image, weight, quantity, and item pricing.Promotion contextRepresent order and item discounts with stable campaign and coupon references.FulfillmentAttach delivery address, carrier, shipping method, dates, cost, and location context.

Complete retail order payload#

This example includes a product variant, an item-level discount reference, the matching order discount, a delivery address, and a selected shipping method.

Complete request

Retail

Process the payment in one request by sending the order, payer, and tokenized payment source inline.

POST/v2/merchants/orders/purchase

Product variants, promotion, delivery address, shipping method, and fulfillment context for commerce.

Open industry guide
itemsdiscountsshipping_addressshipping_method
Request bodyJSON
{
  "payer_info": {
    "email": "alex@example.com"
  },
  "payment_source": {
    "method_type": "credit_card",
    "payment_method": "TOKENIZED_PAYMENT_METHOD"
  },
  "order_type": "DEUNA_CHECKOUT",
  "order": {
    "order_id": "retail-93418",
    "store_code": "es-online",
    "currency": "EUR",
    "items_total_amount": 10900,
    "sub_total": 11400,
    "shipping_amount": 500,
    "total_tax_amount": 2152,
    "total_discount": 1000,
    "total_amount": 13552,
    "items": [
      {
        "id": "shoe-runner-42-blue",
        "sku": "RUNNER-BLU-42",
        "upc": "8437012345678",
        "name": "Runner trainers",
        "description": "Everyday lightweight trainers",
        "quantity": 1,
        "brand": "Northline",
        "category": "footwear",
        "sub_category": "trainers",
        "color": "navy",
        "size": "42",
        "taxable": true,
        "image_url": "https://merchant.example.com/products/runner-blue.jpg",
        "details_url": "https://merchant.example.com/products/runner-blue",
        "unit_price": {
          "amount": 11900,
          "currency": "EUR",
          "currency_symbol": "€"
        },
        "total_amount": {
          "amount": 10900,
          "original_amount": 11900,
          "currency": "EUR",
          "currency_symbol": "€",
          "total_discount": 1000
        },
        "tax_amount": {
          "amount": 2052,
          "currency": "EUR",
          "currency_symbol": "€"
        },
        "weight": {
          "weight": 850,
          "unit": "g"
        },
        "discounts": [
          {
            "amount": 1000,
            "ref_idx": 0
          }
        ]
      }
    ],
    "discounts": [
      {
        "amount": 1000,
        "code": "WELCOME10",
        "reference": "campaign-2026-welcome",
        "description": "Welcome discount",
        "details_url": "https://merchant.example.com/promotions/welcome10",
        "free_shipping": {
          "is_free_shipping": false,
          "maximum_cost_allowed": 0
        },
        "discount_category": "coupon",
        "target_type": "items",
        "type": "fixed_amount"
      }
    ],
    "shipping_address": {
      "first_name": "Alex",
      "last_name": "Morgan",
      "email": "alex@example.com",
      "phone": "+34600000000",
      "address1": "Calle de Alcalá 125",
      "address2": "3B",
      "city": "Madrid",
      "zipcode": "28009",
      "state_name": "Madrid",
      "state_code": "MD",
      "country_code": "ES",
      "address_type": "home",
      "is_default": true
    },
    "shipping_method": {
      "code": "standard-48h",
      "name": "Standard delivery",
      "min_delivery_date": "2026-10-05",
      "max_delivery_date": "2026-10-06",
      "cost": 500,
      "display_cost": "€5.00",
      "tax_amount": 100,
      "display_tax_amount": "€1.00",
      "scheduler": []
    },
    "shipping_options": {
      "type": "delivery",
      "method": "standard-48h",
      "carrier": "Merchant Logistics",
      "price": {
        "amount": 500,
        "currency": "EUR"
      },
      "requires_shipping": true,
      "details": {
        "store_id": "es-online",
        "store_name": "Online store",
        "address": "Calle de Alcalá 125, Madrid",
        "address_coordinates": {
          "lat": 40.4217,
          "lng": -3.6772
        },
        "contact": {
          "name": "Customer care",
          "phone": "+34910000000"
        },
        "additional_details": {
          "address_notes": "Leave with the concierge."
        }
      }
    },
    "channel_type": "desktop_web",
    "metadata": {
      "vertical": "retail",
      "fulfillment_node": "warehouse-mad-02"
    }
  },
  "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"
  }
}

Model the business context#

RequirementOrder fields
Product identityitems[].id, sku, upc, brand, category, sub_category
Variant and presentationcolor, size, image_url, details_url, weight
Promotiondiscounts[] and item discounts[].ref_idx
Deliveryshipping_address, shipping_method, shipping_options
Fulfillment operationsStore, warehouse, carrier, delivery dates, and merchant metadata

Production checklist#

  • Use immutable product and variant identifiers rather than display names as keys.
  • Keep discount references aligned between items and the order-level discounts array.
  • Validate postal address, carrier, shipping dates, and delivery cost before payment.
  • Preserve the original order token for capture, refund, cancellation, and support flows.
  • Test promotion changes, out-of-stock items, split fulfillment, partial refund, and retry scenarios.

Continue with Checkout modules, Capture and refunds, and Create payment.