Express checkout

Available from Yuno iOS SDK 2.24.0. Order breakdown, shipping address updates, and a shipping method selector turn the Apple Pay sheet into an express checkout:

Order breakdown: show subtotal, shipping, taxes, and discounts instead of a single total.
Shipping address updates: recalculate the order when the customer picks or changes their shipping address, without leaving the sheet.
Shipping method selector: let the customer choose Standard, Express, or Same-day on the sheet, with instant price updates.

Each capability is opt-in. If you don’t use them, your Apple Pay integration works exactly as before.

Requirements

Requirement	Value
Yuno iOS SDK	2.24.0 or newer
Apple Pay	Set up in your app and enabled on your Yuno account
Shipping address on the sheet	Requested automatically as soon as the session has `shipping_methods` or your app registers the handler. You don’t need to enable it in the Checkout Builder.

How it works

Your backend adds summary_items and/or shipping_methods when it creates the checkout session.
Your app implements onShippingAddressChanged on the delegate it already passes to the payment flow.
On the Apple Pay sheet, switching shipping method updates the price instantly without calling your app. Picking or changing the shipping address calls your handler, so you can return new totals, new methods, or an error.
After the customer authorizes, the one-time token includes a shipping object with the selected method and the full address.

Two rules apply everywhere:

Every summary_items list must end with the grand total. Its amount is the total shown on the sheet, and its label is shown next to it as the payee line (we recommend your store name).
All amounts must use the session currency. A different currency makes the SDK ignore that breakdown or response.

Step 1: Show an order breakdown (backend only)

Add summary_items when you create the checkout session:

{
  "amount": { "currency": "USD", "value": 108.00 },
  "customer_id": "customer-uuid",
  "merchant_order_id": "order-123",
  "country": "US",
  "summary_items": [
    { "id": "subtotal", "label": "Subtotal", "amount": { "currency": "USD", "value": 100.00 } },
    { "id": "tax", "label": "Tax", "amount": { "currency": "USD", "value": 8.00 } },
    { "id": "total", "label": "ACME Inc.", "amount": { "currency": "USD", "value": 108.00 } }
  ]
}

The sheet now shows the breakdown with the total labeled “ACME Inc.”. No app code is needed.

The last entry is displayed as the grand total and its label as the payee line.
Discounts can be negative, for example -5.00.
When you also send shipping_methods (Step 2), the sheet opens with the first method’s breakdown and this list is ignored.
Without summary_items and without shipping_methods, the sheet shows a single line with the session amount.

Step 2: Offer shipping methods on the sheet

Add shipping_methods to the checkout session. Each method has its own summary_items, so the sheet can update the price as soon as the customer switches method:

"shipping_methods": [
  {
    "id": "standard",
    "label": "Standard shipping",
    "detail": "Arrives in 3-5 business days",
    "amount": { "currency": "USD", "value": 5.00 },
    "delivery_estimate": { "from": "2026-10-12", "to": "2026-10-14" },
    "summary_items": [
      { "id": "subtotal", "label": "Subtotal", "amount": { "currency": "USD", "value": 100.00 } },
      { "id": "shipping", "label": "Shipping", "amount": { "currency": "USD", "value": 5.00 } },
      { "id": "total", "label": "ACME Inc.", "amount": { "currency": "USD", "value": 105.00 } }
    ]
  },
  {
    "id": "express",
    "label": "Express shipping",
    "detail": "Arrives in 1-2 business days",
    "amount": { "currency": "USD", "value": 12.00 },
    "summary_items": [
      { "id": "subtotal", "label": "Subtotal", "amount": { "currency": "USD", "value": 100.00 } },
      { "id": "shipping", "label": "Shipping", "amount": { "currency": "USD", "value": 12.00 } },
      { "id": "total", "label": "ACME Inc.", "amount": { "currency": "USD", "value": 112.00 } }
    ]
  }
]

The first method is preselected and its breakdown is the one the sheet opens with.
label is the option name and detail its description. Apple Pay shows the price next to the option.
Switching methods never calls your app or your backend. The total comes from that method’s summary_items. A method without a breakdown keeps the totals already on the sheet.
delivery_estimate is a from and to pair of YYYY-MM-DD dates. On iOS 15 and later it is rendered as a date range next to the option. A reversed or malformed range is not shown.
The sheet accepts up to 100 methods, 100 summary items, and 100 items per method. Above that, the SDK opens the sheet without shipping methods.

Step 3: React to shipping address changes

Conform the delegate you already pass to the payment flow to YunoShippingDelegate and implement onShippingAddressChanged. It works with every flow that takes a YunoPaymentDelegate: startCheckout, startPaymentLite, and the payment methods list of Full mode.

import YunoSDK

final class CheckoutDelegate: YunoShippingDelegate {

    // ... your YunoPaymentDelegate implementation (checkoutSession, countryCode, yunoPaymentResult, ...)

    func onShippingAddressChanged(
        _ paymentMethodType: String,
        shippingInfo: YunoShippingInfo
    ) async -> YunoShippingUpdate? {
        // paymentMethodType is "APPLE_PAY"
        await myShippingService.quote(shippingInfo.shippingAddress) // a YunoShippingUpdate, or nil to keep the current values
    }
}

If you don’t use async, or you integrate from Objective-C, implement the completion-based variant that YunoPaymentDelegate declares as optional instead:

func onShippingAddressChanged(
    paymentMethodType: String,
    shippingInfo: YunoShippingInfo,
    completion: @escaping (YunoShippingUpdate?) -> Void
) {
    myShippingService.quote(shippingInfo.shippingAddress) { quote in
        completion(quote)
    }
}

Implement one of the two. When both exist, the SDK calls the async one.

What you receive: YunoShippingInfo

Before authorization, Apple Pay shares only part of the address, which is enough to quote shipping and taxes:

Field	Type	Example
`shippingAddress.city`	`String?`	`"Cupertino"`
`shippingAddress.state`	`String?`	`"CA"`
`shippingAddress.postalCode`	`String?`	`"95014"` (may be shortened in some countries)
`shippingAddress.countryCode`	`String?`	`"US"`

Every field can be nil. The full address arrives in the one-time token (Step 4).

What you return: YunoShippingUpdate

Return any combination of these, or nil to keep the sheet as it is:

// A) New totals for this address
YunoShippingUpdate(
    summaryItems: [
        YunoSummaryItem(id: "subtotal", label: "Subtotal", amount: YunoShippingAmount(currency: "USD", value: 100.00)),
        YunoSummaryItem(id: "tax", label: "Tax", amount: YunoShippingAmount(currency: "USD", value: 10.00)),
        YunoSummaryItem(id: "total", label: "ACME Inc.", amount: YunoShippingAmount(currency: "USD", value: 110.00)) // must be last
    ]
)

// B) New shipping methods for this address
YunoShippingUpdate(
    shippingMethods: [
        YunoShippingMethod(
            id: "same-day", label: "Same-day delivery", detail: "Today before 9pm",
            amount: YunoShippingAmount(currency: "USD", value: 15.00),
            deliveryEstimate: YunoShippingDeliveryEstimate(from: "2026-10-10", to: "2026-10-10"),
            summaryItems: [
                YunoSummaryItem(id: "subtotal", label: "Subtotal", amount: YunoShippingAmount(currency: "USD", value: 100.00)),
                YunoSummaryItem(id: "shipping", label: "Shipping", amount: YunoShippingAmount(currency: "USD", value: 15.00)),
                YunoSummaryItem(id: "total", label: "ACME Inc.", amount: YunoShippingAmount(currency: "USD", value: 115.00))
            ]
        )
    ]
)

// C) An address you can't serve
YunoShippingUpdate(
    errors: [
        YunoShippingError(code: "CITY_NOT_SUPPORTED", message: "We don't ship to this city yet") // shown to the customer
    ]
)

Rules

Situation	What happens
You return `nil`	The current values stay.
You answer late	The SDK sets no deadline of its own: the sheet stays open while you answer. If Apple’s own time limit passes first, Apple dismisses the sheet and the SDK reports `CANCELED_BY_USER`. Answer as fast as you can.
A currency differs from the session	The whole response is ignored.
You send `summaryItems`	The list must end with the grand total, which becomes the sheet total. It applies to the method currently selected; switching to another method restores that method’s own breakdown.
You send `shippingMethods`	They replace the options and the first one is preselected. Include `summaryItems` in each method, otherwise the total doesn’t change when the customer switches.
You send `errors`	Apple Pay shows the message on the sheet and blocks the payment until the customer picks another address. `CITY_NOT_SUPPORTED`, `STATE_NOT_SUPPORTED`, `COUNTRY_NOT_SUPPORTED` and `POSTAL_CODE_INVALID` point at that address field. Any other code is shown as a generic “can’t ship to this address” error.
More than 100 entries	The whole response is ignored.
The sheet opens	Apple Pay calls your handler right away with the customer’s default address. Make your handler safe to call more than once, and don’t depend on that first call. If you return methods on that call, they replace the session’s methods; return `nil` to keep them.
The customer changes the address again while you are still answering	The previous call is cancelled and only the answer to the latest address is applied.

Unlike Google Pay, an error on the Apple Pay sheet does block the payment: the customer has to pick another address before paying. Still validate the address on your server when you create the payment.

Step 4: Read the result in the one-time token

After the customer authorizes, the one-time token you receive in yunoCreatePayment includes a shipping object with the selected method and the full address:

"shipping": {
  "method": {
    "id": "express",
    "label": "Express shipping",
    "amount": { "currency": "USD", "value": 12.00 }
  },
  "address": {
    "address_line_1": "1 Apple Park Way",
    "address_line_2": "",
    "city": "Cupertino",
    "state": "CA",
    "zip_code": "95014",
    "country": "US"
  }
}

method is the one selected on the sheet, or the first one if the customer didn’t change it.
summary_items are not sent back.
The object is included whenever the sheet collected a shipping method or an address, with or without a handler. Payments without either don’t include shipping.

Use this object on your server to charge the final amount, validate the address, and ship the order.

What happens in each case

Handler implemented	`summary_items` in session	`shipping_methods` in session	Apple Pay sheet
No	No	No	Same as before (single total)
No	Yes	No	Breakdown, no address updates
No	Any	Yes	Selector with instant method switches. The sheet asks for the address, but your app is not called
Yes	No	No	Address updates; totals change with your answers. No selector unless you return methods
Yes	Yes	No	Breakdown first; your answers can update it
Yes	Any	Yes	Full experience: selector, instant method switches, and address updates

Good to know

Apple Pay is not supported in the iOS Simulator. Test on a physical device.
Apple Pay redacts the address until the payment is authorized, so your handler never sees street lines.
The selected method stays selected when the customer changes the address, unless you return new methods.
Privacy: the SDK never logs addresses, emails, or payment data.

Testing checklist

Upgrade to SDK 2.24.0 or newer and build.
Create a session with summary_items only. The sheet shows the breakdown and the right total.
Create a session with shipping_methods. The sheet shows the selector with the first method selected and asks for a shipping address.
Switch methods. The price updates and your handler is not called.
Implement the handler and change the address. Your handler receives it; return new totals and check the sheet updates.
Return an error for an address you don’t serve. The sheet shows your message and the customer cannot pay until they pick another address.
Authorize. The token includes shipping with the method and the full address.
Remove the handler and the session fields. Everything works as before.

Troubleshooting

Symptom	Likely cause
The selector doesn’t appear	The session has no valid `shipping_methods`, a currency differs from the session, or the session exceeds 100 methods, summary items, or items per method.
The breakdown doesn’t appear	`summary_items` is invalid (no total, empty label, mixed currencies).
The sheet doesn’t ask for a shipping address	The session has no `shipping_methods` and your app doesn’t implement the handler. Add either, or enable the shipping address as a required field in the Checkout Builder.
My handler is never called	Your delegate doesn’t conform to `YunoShippingDelegate` and doesn’t implement the completion-based variant either.
My methods replaced the session’s when the sheet opened	Apple Pay calls your handler when the sheet opens, and your answer is applied. Return `nil` on that call to keep the session’s methods.
Switching methods doesn’t change the total	The methods have no `summaryItems`. Send a breakdown for each method.
The sheet keeps the old totals after my answer	A currency differs from the session, the response has more than 100 entries, or the customer changed the address again before you answered.
Delivery dates don’t show	The device runs iOS 14 or earlier, or `from` is later than `to`.
The sheet closed on its own and I got `CANCELED_BY_USER`	Your handler took longer than Apple’s time limit. Answer faster, or return `nil` and quote on your server when you create the payment.

Setup and one-time payments
Google Pay express checkout on Android
Fast Checkout Shipping. The same session fields and shipping node on wallets that pick the address inside the widget.
iOS SDK changelog

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

Requirements

How it works

Step 1: Show an order breakdown (backend only)

Step 2: Offer shipping methods on the sheet

Step 3: React to shipping address changes

What you receive: YunoShippingInfo

What you return: YunoShippingUpdate

Rules

Step 4: Read the result in the one-time token

What happens in each case

Good to know

Testing checklist

Troubleshooting

​Requirements

​How it works

​Step 1: Show an order breakdown (backend only)

​Step 2: Offer shipping methods on the sheet

​Step 3: React to shipping address changes

​What you receive: YunoShippingInfo

​What you return: YunoShippingUpdate

​Rules

​Step 4: Read the result in the one-time token

​What happens in each case

​Good to know

​Testing checklist

​Troubleshooting

​Related documentation

Requirements

How it works

Step 1: Show an order breakdown (backend only)

Step 2: Offer shipping methods on the sheet

Step 3: React to shipping address changes

What you receive: YunoShippingInfo

What you return: YunoShippingUpdate

Rules

Step 4: Read the result in the one-time token

What happens in each case

Good to know

Testing checklist

Troubleshooting

Related documentation