paybondpaybond
Sign in

Intent lifecycle

How a Paybond intent moves from creation and funding through evidence, settlement, refund, or dispute.

A Paybond intent is the signed record of a commercial commitment between a principal and a payee. It defines the amount at stake, the evidence the payee can submit, and the rule used to decide whether funds are released or refunded.

As the intent progresses, Paybond records each state change in Harbor and reflects terminal outcomes in Signal.

State diagram

stateDiagram-v2
  [*] --> created
  created --> funded: funding authorized
  funded --> evidence_submitted: evidence submitted
  evidence_submitted --> released: evidence accepted, release confirmed
  evidence_submitted --> refunded: evidence rejected, refund confirmed
  funded --> disputed: dispute opened
  evidence_submitted --> disputed: dispute opened
  disputed --> released: dispute resolved to release
  disputed --> refunded: dispute resolved to refund
  released --> [*]
  refunded --> [*]

Transitions

1. Create (POST /intents)

  • The principal creates a signed intent describing the amount, currency, deadline, parties, evidence requirements, and release rule for the transaction.
  • Paybond validates the intent before accepting it, including the evidence rule that will be used later during evaluation.
  • Retrying the same create request with the same idempotency key returns the original result instead of creating a duplicate intent.

2. Fund (funded)

  • The intent moves to funded when the underlying funding source is authorized.
  • In Stripe Connect deployments, that means the rail has authorized the funding during intent creation where the tenant and runtime are configured for Stripe.
  • For stripe_ach_debit, ACH debit is delayed-confirmation funding. Harbor records the funding attempt while the bank debit is pending and moves the intent to funded only after Paybond receives final rail confirmation.
  • For x402_usdc_base, the POST /intents/{id}/fund route advances the payment-session handshake and moves the intent to funded after authorization succeeds.
  • In simulated or disabled runtimes, responses reflect the configured non-production behavior instead of promising live money movement.

3. Submit evidence (POST /intents/{id}/evidence)

  • The payee submits signed evidence for the intent. Paybond evaluates that evidence against the rule attached to the intent and returns an evaluation report.
  • A passing evaluation makes the intent eligible for release. A failing evaluation is recorded as part of the lifecycle rather than treated as a malformed request, and the intent can then proceed to refund or dispute review.

4. Confirm settlement (POST /intents/{id}/settlement/confirm)

  • Settlement confirmation turns the recorded predicate result into a money outcome.
  • If the predicate passed, Harbor releases funds to the payee and moves the intent to released.
  • If the predicate failed, Harbor refunds or cancels through the active rail and moves the intent to refunded.
  • The caller does not choose the release/refund outcome on this route; Harbor derives it from the evidence evaluation already attached to the intent.
  • If Paybond and the payment rail fall out of sync, operators can use recovery workflows described in Operational surfaces.

5. Dispute

  • A dispute can be opened after funding or after evidence submission. This freezes settlement and moves the intent to disputed.
  • Paybond keeps a tenant-scoped dispute case with timeline, evidence references, internal notes, and an exportable arbitration handoff packet. See /v1/disputes/cases/* in the Gateway API.
  • Harbor resolves money movement from disputed to released or refunded. Gateway dispute cases can also record non-rail case statuses such as resolved_split or escalated_external; those are case workflow statuses, not Harbor intent states.

Terminal outcomes and case statuses

State or statusMeaning
releasedHarbor terminal money state. Funds have been released to the payee.
refundedHarbor terminal money state. Funds have been returned to the principal.
disputedHarbor review/freeze state. Signal v1 records the dispute event as a disputed outcome when it is the first ingested terminal outcome for the intent.
resolved_splitGateway dispute-case status for a split or other off-rail resolution; not a Harbor intent state.
escalated_externalGateway dispute-case status for external review or arbitration handoff; not a Harbor intent state.

Signal recomputes scores when it ingests signed Harbor outcome events (released, refunded, or disputed). Outcome rows are idempotent per intent, so later review workflow updates do not silently rewrite the signed score. Lifecycle latency is measured from intent creation to the ingested outcome event.

Signing versions

VersionPayloadNotes
IntentCreationSignV4Standard signed intent format for current integrations.Used for intents that carry their own release rule and binds the requested settlement_rail.
IntentCreationSignV5Extends the signed payload with managed-policy binding.Used automatically when policy_binding is set and also binds the requested settlement_rail.

SDKs and hosted integrations choose the correct signing version automatically. If you are implementing an offline signer, follow the Harbor API and SDK signing rules so the payload matches Paybond's canonical format.

Recovery and idempotency

  • Paybond includes recovery workflows for intents that become stuck after a crash, timeout, or payment-provider outage.
  • Operators can list intents that need recovery attention and reconcile them before retrying settlement.
  • All mutating POST endpoints honor tenant-scoped, operation-scoped idempotency-key values so retries do not create duplicate lifecycle actions.