# Paying, split payments and trade terms

> How an agent pays for a UCP checkout, splits it between gift cards and one card, and why a trade account's terms are not offered to agents.

Source: https://storeware.ai/docs/agents/payments

A UCP checkout is paid with the instruments in `payment.instruments` on complete. Each names a handler from the shop's `payment_handlers`, and the response's handlers are the ones that can pay that basket.

| Handler                     | Id                    | Pays with                                             |
| --------------------------- | --------------------- | ----------------------------------------------------- |
| `com.stripe.payments`       | `stripe_payments`     | A card or Link, tokenised with Stripe                 |
| `ai.storeware.x402`         | `storeware_x402`      | A stablecoin, see [x402](https://storeware.ai/docs/agents/x402)                |
| `ai.storeware.gift_card`    | `storeware_gift_card` | The shop's own gift card                              |
| `ai.storeware.test_payment` | `storeware_test`      | A pretend payment, at a demo or development shop only |

A shop that cannot take payment through UCP yet publishes `payment_handlers: {}`. The gift card handler is only ever published beside another one.

## Split payments

A shop declares split payments under both names the protocol gives it, `dev.ucp.common.payment.split_payments` and `dev.ucp.shopping.split_payments`. Its `allowed_combinations` are the mixes the shop settles:

```json
{
  "allowed_combinations": [
    [
      { "types": ["card", "link", "x402", "storeware_test"], "min": 1, "max": 1 },
      { "types": ["gift_card"], "min": 0, "max": 5 }
    ],
    [{ "types": ["gift_card"], "min": 1, "max": 5 }]
  ]
}
```

That is one card, Link or stablecoin payment with up to five gift cards, or gift cards alone when they cover the whole total. Two cards are never accepted: send one instrument for the rest.

### Gift card and card

```json
{
  "payment": {
    "instruments": [
      {
        "id": "pi_gc",
        "handler_id": "storeware_gift_card",
        "type": "gift_card",
        "credential": { "type": "gift_card", "token": "ABCD-EFGH-JKLM" }
      },
      {
        "id": "pi_card",
        "handler_id": "stripe_payments",
        "type": "card",
        "credential": { "type": "stripe_payment_token", "token": "tok_..." }
      }
    ]
  }
}
```

Gift cards are used first, in the order you list them, and the card is charged what they leave. Leave `amount` off: each card gives what it holds, up to what is left.

Once you negotiate split payments, every checkout response lists the basket's gift cards in `payment.instruments`, each with `amount` (what it pays towards this basket) and `display.last_digits`. On the completion the card follows them, with its `amount` once the order is placed. A gift card you submitted keeps your id. One added another way, through `ai.storeware.shopping.gift_card` or an earlier request, is listed as `gift_card_<id>`.

### The gift card handler

The credential is the code printed on the card, as `{ "type": "gift_card", "token": "<code>" }`. Spaces and hyphens in the code do not matter.

A gift card is redeemed when you submit it. Its value becomes store credit held for this checkout, on the account the basket is for. If the card payment then fails, the gift card's value stays held for the checkout rather than going back onto the card. Send the same gift card again with a new card: it is recognised as already applied and is not refused as used.

Gift cards alone that do not cover the total are refused with `invalid_payment_data`, saying what is left to pay. Their value stays held. Send them again with one card for the rest, or send the buyer to `continue_url`.

A balance already on a shopper's account is never spent through an agent. The shopper uses it themselves, signed in at the shop.

## Trade accounts and payment terms

A shop can let a trade account pay by invoice, due in a set number of days. Those terms are only ever used for an order the buyer places themselves, signed in at the shop. A basket an agent opens, or completes, is paid when it is placed, whatever the account has agreed. The account's prices and tax exemption do apply to a basket opened by an assistant the buyer linked.

So the shop does not declare `dev.ucp.common.payment.terms`. Every UCP checkout is paid in full on completion, which is what a checkout without that extension says. This holds for a basket an agent opened even when the buyer finishes it through `continue_url`. To use their terms, a trade buyer starts their own basket at the shop, signed in, and places the order there.

## Mandates and card checks

AP2 mandates and 3D Secure challenges are each declared under both names too: `dev.ucp.shopping.ap2_mandate` and `dev.ucp.common.payment.ap2_mandate`, and `dev.ucp.shopping.payment_authentication` and `dev.ucp.common.payment.authentication`. They behave the same. A challenge action is keyed `dev.ucp.common.payment.three_ds_challenge` when you negotiated only the newer name, and `dev.ucp.payment.three_ds_challenge` otherwise.

Loyalty is not declared. Shops have no points or membership programme to report.