Settlement

Commercial roles and payment flows in multi-party bookings.

Namespace URI: https://agenticbooking.org/folio/settlement/v1

1. Overview

When a guest books through an agent, multiple parties are involved:

Guest → Agent → Venue
         ↓
      Platform

Each party has a commercial role that determines who receives payment, who provides service, and who handles disputes.

2. Commercial Roles

2.1 Role Types

2.2 Role Declaration

{
  "settlement": {
    "merchant_of_record": {
      "party": "agent",
      "id": "did:web:travel.example.com"
    },
    "service_provider": {
      "party": "venue",
      "id": "did:web:theroste.co.uk"
    },
    "facilitator": {
      "party": "platform",
      "id": "did:web:platform.example.com"
    }
  }
}

2.3 Party Values

3. Settlement Models

How funds flow depends on who is Merchant of Record:

3.1 Venue Collects

Traditional model—venue receives payment directly.

Guest → Venue (MoR)
          ↓ commission
        Agent

{
  "settlement": {
    "model": "venue_collects",
    "merchant_of_record": { "party": "venue" }
  }
}

3.2 Agent Collects

Agent receives payment, remits to venue.

Guest → Agent (MoR)
          ↓ payout
        Venue

{
  "settlement": {
    "model": "agent_collects",
    "merchant_of_record": { "party": "agent" }
  }
}

3.3 Model Comparison

3.4 Payout Schedule

When funds flow from MoR to service provider, the payout timing can be specified:

{
  "settlement": {
    "model": "agent_collects",
    "merchant_of_record": { "party": "agent" },
    "payout_schedule": {
      "service_provider": "venue",
      "timing": "after_checkout",
      "delay_days": 2
    }
  }
}

4. Refund Authority

Who can initiate and execute refunds depends on MoR designation.

4.1 Authority Chain

{
  "refund_authority": {
    "initiators": ["guest", "agent", "venue"],
    "executor": "merchant_of_record",
    "requires_authorization": true
  }
}

4.2 Refund Scenarios

4.3 Cost Allocation

{
  "refund_cost_allocation": {
    "guest_cancellation": "per_policy",
    "venue_failure": "venue_reimburses",
    "agent_error": "agent_absorbs",
    "force_majeure": "negotiated"
  }
}

5. Liability Chain

Consumer protection responsibilities follow the MoR.

5.1 Consumer Responsibilities

5.2 Declaration

{
  "liability": {
    "consumer_contract": "merchant_of_record",
    "service_delivery": "service_provider",
    "dispute_first_contact": "merchant_of_record"
  }
}

5.3 Dispute Handling

The MoR is responsible for dispute resolution, but facilitators may provide supporting infrastructure:

{
  "dispute_support": {
    "evidence_sources": ["venue_pms", "booking_system", "communication_logs"],
    "facilitator_tooling": true
  }
}

The facilitator's role is to assist—not to assume liability or act as the customer's counterparty.

6. Multi-Party Bookings

Itineraries spanning multiple venues:

{
  "settlement": {
    "model": "agent_collects",
    "merchant_of_record": { "party": "agent" },
    "service_providers": [
      { "party": "venue", "id": "did:web:hotel.example.com", "portion": 60 },
      { "party": "venue", "id": "did:web:restaurant.example.com", "portion": 25 },
      { "party": "venue", "id": "did:web:tour.example.com", "portion": 15 }
    ]
  }
}

The MoR receives full payment and distributes to service providers per agreed terms.

7. Payment Token Requirements

When using payment tokens (SPT, AP2 mandates), hospitality requires:

See ACP Protocol for details.

8. Implementation Notes

What This Spec Defines

• Vocabulary for commercial roles
• Declaration format for settlement models
• Refund authority semantics
• Liability allocation patterns

What This Spec Does Not Define

• Payment provider APIs
• Fee structures or percentages
• Account onboarding flows
• Transaction reconciliation

These are implementation concerns left to platforms and payment providers.

Related Specifications

• Folio Spec — Payment schedules and policies
• AP2 Protocol — Mandate authorization
• ACP Protocol — Checkout and SPT