Skip to content
Skills Library
Programming · Building & coding

ucp-split-payments

/ucp-split-payments

Implement the UCP Split Payments extension (`dev.ucp.common.payment.split_payments`) — paying a single checkout with multiple instruments, specified vs open amounts, allocation order, `allowed_combinations` config, and atomic completion. Use when supporting gift cards plus a card, or any multi-instrument checkout.

Licence
MIT
Last repository change
14.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Implement the UCP Split Payments extension (`dev.ucp.common.payment.split_payments`) — paying a single checkout with multiple instruments, specified vs open amounts, allocation order, `allowed_combinations` config, and atomic completion. Use when supporting gift cards plus a card, or any multi-instrument checkout.

Original author description

Implement the UCP Split Payments extension (`dev.ucp.common.payment.split_payments`) — paying a single checkout with multiple instruments, specified vs open amounts, allocation order, `allowed_combinations` config, and atomic completion. Use when supporting gift cards plus a card, or any multi-instrument checkout.

How it works

  1. Before writing code
  2. Conceptual Architecture
  3. Implementation Guidance
Original SKILL.md headings · 60 lines, 493 words
SKILL.md preview
---
name: ucp-split-payments
description: Implement the UCP Split Payments extension (`dev.ucp.common.payment.split_payments`) — paying a single checkout with multiple instruments, specified vs open amounts, allocation order, `allowed_combinations` config, and atomic completion. Use when supporting gift cards plus a card, or any multi-instrument checkout.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# UCP Split Payments Extension

## Before writing code

**Fetch live spec**: Web-search `site:ucp.dev specification payment extensions split-payments` and fetch the page for the exact `allowed_combinations` shape and the current failure-message codes. This extension governs money movement across multiple authorizations — implement it against the live spec, not from memory.

## Conceptual Architecture

### Scope

Split Payments (`dev.ucp.common.payment.split_payments`) lets a buyer pay with **multiple payment instruments in a single checkout**. The canonical case is a gift card covering part of the total with a card covering the rest.

### Two submission modes

- **Specified-amount** — the platform requests a specific contribution from an instrument.
- **Open-amount** — the business determines the contribution at processing time. This is what gift cards need: the balance is not known to the platform, so it asks the business to take whatever is there.

Each payment instrument gains an optional `amount` field, in **ISO 4217 minor units**.

### Allocation order

Instruments are processed **in submission order**, and that order establishes allocation priority:

> The first instrument gets first claim on the checkout total, the second gets next claim, and so on.

The business may *authorize* in any operational order it likes, but it must respect the array sequence when deciding **how much** each instrument covers. Practically: put the gift card first if you want it drained before the card is charged.

### `allowed_combinations`

Businesses declare which instrument groupings they accept. Each combination contains instrument groups specifying:

- `types` — accepted instrument types, **OR** logic within the group
- `min` — minimum instruments required (defaults to 0)
- `max` — maximum instruments allowed (defaults to 1)

Read this config before constructing a payment array; an unsupported combination fails at completion, after the buyer has committed.

### Atomicity — the rule that matters most

Split payments complete **atomically**. If the business cannot process a specified-amount instrument, or cannot reach the final total:

- it **MUST** return `payment_failed` in `messages[]`, and
- it **MUST** void or reverse any authorizations it already made.

There is no partial success. A buyer never ends up with a drained gift card and no order.

### Response `amount` is not state

Response `amount` fields convey **actual charges for buyer-facing UX and auditing only**. They do not persist as state across requests. Do not read an amount off a response and send it back on the next request expecting it to mean the same thing.

## Implementation Guidance

- Order the instrument array deliberately — it is the allocation policy, not just a list.
- Use open-amount for any instrument whose balance the platform cannot know; guessing produces avoidable `payment_failed`.
- On the business side, treat the void/reverse path as the primary path in testing. Partial-failure rollback is where real money is lost.
- Validate the proposed combination against `allowed_combinations` client-side before completion, so the buyer learns early.
- Combines with `ucp-payment-terms` (when payment is due) and `ucp-payment-handlers` (how each instrument is processed).
- Reference implementation: https://github.com/Universal-Commerce-Protocol/samples

Versions

The database has no other skills named ucp-split-payments.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 035745f8777e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90ucp-payment-terms
    Implement the UCP Payment Terms extension (`dev.ucp.common.payment.terms`) — offering the buyer a choice of when payment is due via payment terms and schedules (pay now, deposit plus balance, deferred). Use when building split-timing payment options into a UCP checkout.
  • 90ucp-discount
    Implement the UCP Discount extension — discount code application, validation, allocation tracking, and error handling. Use when adding promo code or discount logic to a UCP checkout.
  • 100ucp-assets
    Work with a Unity project's assets and files through the editor with `ucp asset`, `ucp files`, `ucp material`, `ucp references`, `ucp shader`, and `ucp script`: search and inspect assets, read and write ScriptableObject and material fields, move or rename assets without breaking…
  • 100ucp
    Use when the user wants to use the UCP CLI to find, compare, buy, or track products from online merchants, or to set up and troubleshoot the local UCP profile required for merchant-scoped operations. Covers global catalog search (\"find me X under $Y\"), named-merchant…
  • 100ucp-scene-authoring
    Build and inspect scene content in the live Unity Editor with `ucp scene`, `ucp object`, `ucp transform`, `ucp spatial`, and `ucp prefab`: snapshot and query the hierarchy, create visible primitives, add components, set serialized properties, move/rotate/scale/look-at objects,…
  • 90agentic-surface
    Use when building, probing, or auditing the machine-readable surface of a storefront — UCP profile, MCP cart/checkout/catalog endpoints, agentic-catalog eligibility, product route shape, or agent identity. Carries dated protocol cutovers.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.