RFC: Payment terms and scheduled payments

[raginpirate]

Summary

Add a Checkout and Orders extension for payment terms: buyer-facing payment plans composed of one or more payment schedules. This supports cases where a checkout is authorized/completed now, but one or more payments are due later.

Motivating use cases include:

• Lodging and reservations, where the buyer pays a deposit at booking and the balance at check-in
• Try before you buy, where the checkout is completed now but the full payment is due at a later date
• Net terms, where a deposit may be due now and the balance due net-30/net-60
• Installments / Buy Now Pay Later, where the first payment is immediate and the remainder follows a recurring schedule

This should be modelled as payment terms for the current checkout, independent of purchase options which influence catalogue and involve details like order recurrence or fulfillment.

Goals

• Allow businesses to disclose available payment terms for a checkout.
• Allow platforms to select a payment term for specific line items.
• Allow schedules inside a term to express:
  • immediate payment,
  • deferred payment,
  • recurring/installment-style payment.
• Allow payment instruments to be assigned terms or schedules.
• Allow payment handlers to constrain which instruments can satisfy which terms/schedules.
• Keep schedule types extensible; avoid closed enums.
• Preserve compatibility with Split Payments for cases where multiple instruments contribute to the same or separate schedules.

Non-goals

• Modelling how to advertise purchase options at an edge like catalogue.
• Modelling fulfillment timing to empower behaviour like subscriptions, pre-orders, or ROPIS.
• Defining payment processor-specific capture, vaulting, or mandate mechanics.
• Supporting a mixed-payment term checkout (line item A has term 1 while line item B gets term 2).

Core invariants

A good payment-schedules solution should preserve these properties, regardless of the exact schema shape:

• Complete obligation disclosure: before authorization, the buyer/platform can understand what is owed, when it is owed, and what event or date makes it due.
  • A quote from an old Visa framework document:
  • Details about the underlying purchase must be made available to the cardholder, minimally online, including: • Description of each individual purchase, including the name of the seller • Amount and date of each individual purchase • Amount of each installment transaction • Number of installments paid and number of installments remaining
• Amount conservation: scheduled payments cover the agreed payable obligation exactly once; no ambiguous allocation.
• Timing determinism: due times resolve unambiguously from the authorized checkout context, including relative and recurring schedules.
• Authorization coverage: every scheduled payment is backed by an eligible payment method and authorization appropriate for that timing.
• No hidden commerce: payment schedules exclusively solve payments concerns. They do not silently create future purchases, subscriptions, or fulfillment obligations.
• Recoverable failure: invalid schedules, unsupported payment methods, or insufficient authorization produce actionable errors before completion.
• Interoperable with Split Payments: one instrument can satisfy an immediate schedule while another covers a deferred schedule, or two instruments can split a single scheduled payment.
• Authorization: Payment schedules are disclosure and selection primitives. They do not by themselves define:
  • credential vaulting,
  • future capture authorization,
  • mandate format,
  • card network compliance,
  • regulatory disclosures,
  • cancellation/refund behavior. Businesses and payment handlers remain responsible for ensuring future payments are authorized and compliant. If AP2 or another mandate mechanism is active, scheduled payment obligations should be included in the authorized checkout terms.

Examples of terms we want to solve for

Example 1: lodging deposit and balance at check-in

The business returns one available term with two schedules: one immediate payment for the first night, and one deferred payment anchored to check-in time.

{
  "payment": {
    "available_terms": [
      {
        "id": "pt_first_night_balance",
        "name": "First night now, balance at check-in",
        "schedules": [
          {
            "id": "sched_first_night",
            "type": "immediate",
            "amount": 1000
          },
          {
            "id": "sched_check_in_balance",
            "type": "deferred",
            "due_at": {
              "anchor_date": "2026-09-01T15:00:00-07:00"
            },
            "amount": 90000
          }
        ]
      }
    ]
  }
}

The platform selects the term and can either assign one instrument to the whole term, or assign instruments to individual schedules.

{
  "payment": {
    "instruments": [
      {
        "id": "pi_card_1",
        "handler_id": "handler_1",
        "type": "card",
        "credential": {
          "type": "token",
          "token": "tok_visa_xxxx"
        },
        "term_refs": [
          { "id": "pt_first_night_balance" }
        ]
      }
    ]
  }
}

Example 2: installments and instrument constraints

A recurring deferred schedule can represent the remaining three payments in a "Pay in 4" plan.

{
  "id": "pt_pay_in_4",
  "name": "Pay in 4",
  "schedules": [
    {
      "id": "sched_installment_1",
      "type": "immediate",
      "percentage": 25
    },
    {
      "id": "sched_installments_2_to_4",
      "type": "deferred",
      "due_at": {
        "offset": "P2W",
        "interval": "P2W",
        "occurrences": 3
      },
      "percentage": 25
    }
  ]
}

Payment handlers use the same term_refs shape for constraints. For example, a gift card can be limited to immediate schedules:

{
  "type": "gift_card",
  "constraints": {
    "term_refs": [
      { "schedule_type": "immediate" }
    ]
  }
}

Within term_refs, id matches a payment term, schedule_id matches a payment schedule, and schedule_type matches a schedule type. Compound refs use AND semantics.

Example 3: Split payments with terms

You can choose to provide different methods for different term schedules; splitting within one schedule id, or splitting between schedules.

A realistic scenario: you use a gift card, which cannot be vaulted, to pay for part of the deposit. You use your first credit card for the rest of the deposit, and you use your second credit card for the whole of the final balance.

   {                                                                                                                                      
     "payment": {
       "instruments": [                                                                                                                   
         {                                                                                                                                
           "id": "pi_gift_card_1",                                                                                                        
           "handler_id": "handler_gift_card",                                                                                             
           "type": "gift_card",                                                                                                           
           "credential": {                                                                                                                
             "type": "token",                                                                                                             
             "token": "gc_abc123"                                                                                                         
           },                                                                                                                             
           "amount": 10000,                                                                                                               
           "term_refs": [                                                                                                                 
             {                                                                                                                            
               "id": "pt_first_night_balance",                                                                                            
               "schedule_id": "sched_first_night"                                                                                         
             }                                                                                                                            
           ]                                                                                                                              
         },                                                                                                                               
         {                                                                                                                                
           "id": "pi_card_deposit",                                                                                                       
           "handler_id": "handler_card",                                                                                                  
           "type": "card",                                                                                                                
           "credential": {                                                                                                                
             "type": "token",                                                                                                             
             "token": "tok_visa_deposit"                                                                                                  
           },                                                                                                                             
           "amount": 20000,                                                                                                               
           "term_refs": [                                                                                                                 
             {                                                                                                                            
               "id": "pt_first_night_balance",                                                                                            
               "schedule_id": "sched_first_night"                                                                                         
             }                                                                                                                            
           ]                                                                                                                              
         },                                                                                                                               
         {                                                                                                                                
           "id": "pi_card_balance",                                                                                                       
           "handler_id": "handler_card",                                                                                                  
           "type": "card",                                                                                                                
           "credential": {                                                                                                                
             "type": "token",                                                                                                             
             "token": "tok_visa_balance"                                                                                                  
           },                                                                                                                             
           "term_refs": [                                                                                                                 
             {                                                                                                                            
               "id": "pt_first_night_balance",                                                                                            
               "schedule_id": "sched_check_in_balance"                                                                                    
             }                                                                                                                            
           ]                                                                                                                              
         }                                                                                                                                
       ]                                                                                                                                  
     }                                                                                                                                    
   }

[raginpirate]

Thanks everyone for a great first deepdive. I've summarized the comments and actioned on a few of them. I will aim to propose a draft PR which we can all review ahead of our TC this week to continue the discussion.

Feedback from our first review

• A strong push to simplify:
  • Remove line-item specific payment terms from scope: the strong first deliverable here does not need that level of complexity. That complexity can be a non-breaking addition.
  • Remove split payments if it adds complexity; I've provided an example so we can understand the inherent value (gift cards being only applicable to one part of the schedule) and see if the complexity is deemed low enough that we're happy keeping this invariant.
• Is there a model here that leans on simple policies over deterministic schedule shapes?
  • Great question on integrator shape if we push in this direction. Pushes back on shapes like Apple’s recurring line items. Simplifies the proposal, but risks encoding weak information into AP2 mandates / actions needing to be used to express date pickers, etc. Our objective needs to be: shape the minimum, compliant body that enables us to be interoperable across regulations, and that simple shape might be a text field. I will propose a second draft using policies to compare shape.
• ROPIS was mentioned; are we solving for that here?
  • A: No. ROPIS is a more complex model than this PR target. A few examples edges of ROPIS we still do not have after this RFC concludes:
    • The glue between fulfillment and the payment term and the line item. This is what I'll call a purchase option, the model behind subscriptions.
    • The total of the checkout has a non-zero deferred amount, but no instrument is required at checkout. We are not solving for invoicing / alternative collection approaches right now.
• How do we handle complex fee changes, taxes, etc?
  • Consider replacing the amount field with totals to express these changes clearly.

And just a fun fact; I actually published a Shopify app a long time ago for ROPIS; just never knew that acronym! 😂

[raginpirate]

👋 Hey folks! Here's the first pair of draft PRs, as promised:
#602 vs. #603

Please take a look at https://gist.github.com/raginpirate/dacd86b1bbf5b63dbb360c8877481cf6 for a comparison of shapes!

[gforgab]

Chiming in from the Mercado Pago / agentic-commerce side with a Latin America lens. Modeling installments as payment terms is very welcome, and totals-per-schedule already covers how much is due per occurrence, including when financing raises the total. One thing still isn't expressible: whether a plan is interest-free or financed, and how much the financing adds to what the buyer owes.

That's not hypothetical — it's what regional PSPs already return:

• Mercado Pago: per plan, installment_rate, total_amount, installment_amount, and installment_rate_collector (whether Mercado Pago itself or a third party collects the financing cost).
• PagSeguro: interest_free (boolean) + total.
• Stripe and Adyen, by contrast, don't surface a financing-cost field at all — installments there are count/interval/plan-type only.

Why it matters for the buyer-facing obligation: in much of LatAm the buyer picks "3× interest-free" vs "6× where the total is higher," and the difference in what they'll owe is real and material. That's squarely the "what is owed" side of the complete obligation disclosure invariant — and deliberately distinct from regulatory disclosure (CET/CFT and the like), which I see is a non-goal and I'm not proposing UCP become the channel for.

Strawman, to make the requirement concrete (not a shape to lock in): a small, optional term-level financing flag —

{ "id": "pt_12x", "financing": { "type": "financed", "cost": 12345 } }

where type is interest_free | financed (open string) and cost is how much this term's totals exceed the equivalent interest-free/base total (minor units; the schedule totals already carry the per-occurrence figures). Interest-free plans set type: "interest_free" or omit it. A handler wrapping MP or PagSeguro can fill this straight from what those APIs already return.

Given the simplification direction, this could just as easily live as a value inside policies[] (#572) or whatever shape you converge on — I'm flagging the requirement, not the schema. "Who ultimately bears the cost" (issuer / acquirer / merchant) is a secondary question I'd park unless it proves needed. Not a vote on #602 vs #603 — happy to defer to the TC, and glad to bring real LatAm test cases (financed and interest-free).

[sw-tang]

I'm also chiming in from Booking.com side. Very happy to see the extensions. In order to make it work for lodging, I do think that we will need additional fields with the following rationale:

• Add handler_ids on schedules: Not all payment methods are allowed for certain payment timings (or schedules the specs). It can be that a country specific, non-card based payment method doesn't support deferred charges (for example iDEAL, a widely used payment method in the Netherlands only supports immediate payments). Such payment method can only be offered for immediate schedule type, so we should limit possible handler_ids per schedule.
• Add 'guarantee' schedule type: A common payment timing within Lodging is 'Pay at Property', where instrument/card credentials are collected as guarantee but is not being used for the actual charge as the booker will pay on arrival at the property. It could in theory also be fit in deferred but then we need to something that also indicate that the booker won't be charged when this timing/schedule is selected. Suggestion is to introduce a new guarantee type, next to immediate and deferred.

In other words:

1. handler_ids on schedules

Platforms need to know which handlers are eligible for each schedule without cross-referencing handler-side constraints. The business already knows — surface it directly.

{
  "id": "sched_now",
  "type": "immediate",
  "totals": [{"type": "total", "amount": 25700}],
  "handler_ids": ["handler_1", "handler_2"]
}

This matters because handler eligibility varies by schedule. Some payment methods support immediate payments but cannot vault credentials for future charges. Cards may support all schedule types. Without handler_ids, platforms discover eligibility through trial-and-error — submit, get rejected, retry with a different handler.

2. guarantee schedule type

Lodging requires collecting a payment credential that is stored but not charged. The credential serves as protection against no-show or late cancellation. Neither immediate nor deferred fits:

• immediate → implies charge now (nothing is charged)
• deferred → implies deterministic future charge at due_at (charge is contingent on a breach event and may never happen)

{
  "id": "sched_property",
  "type": "guarantee",
  "totals": [{"type": "total", "amount": 25700}],
  "handler_ids": ["handler_1"]
}

Type	Instrument is...	Charge trigger
immediate	Charged now	Checkout completion
deferred	Charged at due_at	Passage of time
guarantee	Stored, not charged	Breach event (no-show, late cancel)

due_at is not applicable for guarantee — the charge timing is undefined and event-driven. The obligation amount and timing are communicated via the term's description.

---

Lodging Example: Three Available Terms

{
  "payment": {
    "available_terms": [
      {
        "id": "pt_pay_now",
        "name": "Pay now",
        "description": "Full payment collected immediately.",
        "schedules": [
          {"id": "s1", "type": "immediate", "totals": [{"type": "total", "amount": 25700}], "handler_ids": ["handler_1", "handler_2"]}
        ]
      },
      {
        "id": "pt_pay_later",
        "name": "Pay later",
        "description": "Full payment charged on Aug 13, 2026.",
        "schedules": [
          {"id": "s2", "type": "deferred", "due_at": {"anchor_date": "2026-08-13T12:00:00Z"}, "totals": [{"type": "total", "amount": 25700}], "handler_ids": ["handler_1"]}
        ]
      },
      {
        "id": "pt_pay_at_property",
        "name": "Pay at property",
        "description": "Your card won't be charged. We need your payment details to reserve your booking.",
        "schedules": [
          {"id": "s3", "type": "guarantee", "totals": [{"type": "total", "amount": 25700}], "handler_ids": ["handler_1"]}
        ]
      }
    ]
  }
}

Selection on complete:

{
  "payment": {
    "instruments": [
      {"id": "pi_1", "handler_id": "handler_1", "type": "card", "credential": {"type": "token", "token": "tok_xxx"}, "term_refs": [{"id": "pt_pay_at_property"}]}
    ]
  }
}