Developer guide

Escrow and conditional payments

5 min read

Roadmap A conditional payment holds funds until an agreed condition is met and releases them when somebody with the right to do so approves. ChatterPay B2B plans this as a capability of the platform, with Trustless Work smart-contract infrastructure on Stellar and Soroban as its provider.

Status: planned, targeting Testnet first. Everything on this page is on the Roadmap.

What it is, and where it sits

Roadmap An ordinary transfer moves value now. An agreement holds it against a condition, and that difference is what makes it its own product object with its own lifecycle, its own state and its own endpoints, rather than a flag on a transfer.

The capability belongs to the platform and the provider resolves it. A payment goes straight over the payment rail; an agreement goes through the provider and settles on the same rail underneath.

flowchart TD
    CP[ChatterPay]
    PAY[Payments]
    ESC[Escrow and conditional payments]
    TW[Trustless Work provider]
    ST[Stellar and Soroban]
    CP --> PAY
    CP --> ESC
    PAY --> ST
    ESC --> TW
    TW --> ST

Who takes part

Roadmap An agreement names the roles that decide what happens to the funds:

  • Creator — who opens the agreement and states its terms.
  • Funder — who puts the funds in.
  • Receiver — who the funds are for.
  • Approver — who confirms that the condition is met.
  • Release signer — who authorizes the release.
  • Dispute resolver — who decides when the parties disagree.

One person can hold several roles, and separating them is what makes the same primitive serve a supplier, a freelancer, a service, a milestone, a purchase, a marketplace order, a payment between agents and a payment between two people.

Lifecycle

Roadmap The first scope is one path, end to end:

  1. Create. The agreement is created with its roles, its asset and its amount, and gets an identifier that travels with it.
  2. Fund. The funds are placed into the agreement, authorized the same way any other movement of funds is.
  3. Status. The agreement's state can be read at any point, from the API and from the SDK.
  4. Approve and release. Approval releases the funds to the receiver.
  5. Reconcile. The resulting Stellar transaction is correlated with the agreement, and the outcome is reconciled in the ledger like any other movement.

Escrow flow

Roadmap This flow describes the capability as it is designed, and is on the Roadmap rather than available today.

sequenceDiagram
    autonumber
    participant C as Channel or Partner backend
    participant API as B2B API
    participant ES as Escrow service
    participant TW as Trustless Work provider
    participant AU as Authorization provider
    participant N as Stellar / Soroban
    participant R as Observer/Reconciler
    C->>API: Escrow intent (roles, asset, amount, condition)
    API->>ES: Operation + agreement
    ES->>TW: Create agreement
    TW-->>ES: Agreement identifier
    ES->>AU: Authorization request to fund
    AU-->>ES: Authorized transaction
    ES->>N: Fund the agreement
    C->>API: Approve and release
    ES->>TW: Release
    TW->>N: Settle the release
    R->>N: Observe finality
    R->>ES: Correlate transaction and reconcile
    ES-->>C: Webhook / state

Public surfaces

Roadmap The agreement is read and driven through the API and typed in the SDK, and every transition arrives at the Partner's backend as a signed webhook with the same contract and the same signature as the events of any other operation.

The capability is reached from the supported surfaces alike — the API, the SDK, a conversational channel or a web interface. The surface changes how the request is expressed; the agreement, its roles and its rules stay the same.

What the first scope leaves out

Roadmap Advanced disputes, several sophisticated milestone models, marketplace, reputation, matching, fiat and mainnet are later work. They are listed on the Roadmap with the status they actually have.

References

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

  • Escrow agreement as a product capability — An agreement holds funds until an agreed condition is met, and it carries the roles that decide: who creates it, who funds it, who receives, who approves, who releases and who resolves a dispute. It covers a supplier, a freelancer, a milestone, a purchase and a person-to-person payment alike.

  • Trustless Work as the escrow provider — The agreement runs on Trustless Work's smart-contract infrastructure on Stellar and Soroban. The provider resolves the escrow capability; ordinary transfers keep going straight over the payment rail, so an escrow is a choice and never a toll on every payment.

  • Create, fund, release and reconcile — The whole path in one capability: the agreement is created and gets an identifier, it is funded, its state can be read at any point, approval releases the funds, and the resulting Stellar transaction is correlated and reconciled in the ledger like any other movement.

  • Agreement state on API and SDK — The agreement has its own domain and its own endpoints, because holding funds against a condition carries a lifecycle, a state and a set of roles of its own. Its state, its roles and its history are read through the API and typed in the SDK.

  • Signed webhooks for every transition — Every transition of the agreement — created, funded, approved, released — arrives at the Partner's backend as a signed webhook, with the same contract and the same signature as the events of any other operation.

  • Available from every supported surface — The capability belongs to the platform, so it is reached from the API, the SDK, a conversational channel or a web interface alike. The surface changes how the request is expressed, and the agreement, its roles and its rules stay the same.