G

Payment Intent Lifecycle

Payment Intent Lifecycle

End-to-end flow from intent creation to canonical receipt — covering both human-initiated and agent-initiated payment paths.

Overview#

A Payment Intent is the atomic unit of settlement in Gao Payment. Every value transfer — whether initiated by a human, an AI agent, or an infrastructure node — begins as a payment intent and follows a deterministic lifecycle.

No funds move until the intent reaches the AUTHORIZED state via a user-signed transaction. No intent completes without emitting a canonical receipt.

Intent States#

CREATED  
   │  
   ▼  
VALIDATED ──── validation failure ──▶️ REJECTED (receipt emitted)  
   │  
   ▼  
RISK_ASSESSED ── Tier 3 ──────────────▶️ AWAITING_HUMAN_AUTH  
   │                                           │  
   │ Tier 0–2                       authorized │  
   ▼                                           │  
PENDING_AUTH ◀️─────────────────────────────────┘  
   │  
   │── Tier 2: in-band confirmation ──▶️ AWAITING_CONFIRMATION  
   │                                           │  
   │ Tier 0–1 auto-approved         confirmed │  
   ▼                                           │  
AUTHORIZED ◀️───────────────────────────────────┘  
   │  
   ▼  
SUBMITTED ──── broadcast failure ──▶️ BROADCAST_FAILED (retryable)  
   │  
   ▼  
CONFIRMING ──── timeout ──────────▶️ CONFIRMATION_TIMEOUT (receipt emitted)  
   │  
   ▼  
SETTLED ──────────────────────────▶️ RECEIPT_EMITTED  
   │  
   ▼ (if commerce layer attached)  
FULFILLED

Every terminal state — SETTLED, REJECTED, BROADCAST_FAILED, CONFIRMATION_TIMEOUT — produces a receipt. No intent is silent.

State Definitions#

State

Description

CREATED

Intent constructed; not yet validated

VALIDATED

CAP token, domain scope, and budget limits confirmed valid

REJECTED

Validation failed; no funds moved; failure receipt emitted

RISK_ASSESSED

Risk tier assigned (0–2 auto-path; 3 escalation path)

AWAITING_HUMAN_AUTH

Tier 3: execution paused; human contact notified

PENDING_AUTH

Waiting for wallet signature

AWAITING_CONFIRMATION

Tier 2: waiting for in-band user confirmation

AUTHORIZED

User signature received; ready for broadcast

SUBMITTED

Transaction broadcast to network

CONFIRMING

Awaiting on-chain confirmation

SETTLED

On-chain confirmation received

RECEIPT_EMITTED

Canonical receipt written to ledger

FULFILLED

Commerce layer fulfilled (if applicable)

BROADCAST_FAILED

Network broadcast failed; retryable

CONFIRMATION_TIMEOUT

Confirmation window exceeded

Creation#

A payment intent is created with the following required fields:

{  
  "intent_id": "pi_abc123",  
  "payer_domain": "alice.gao",  
  "payee_domain": "shop.gao",  
  "amount": "25.00",  
  "currency": "USDC",  
  "network": "base",  
  "cap_token_id": "cap_xyz456",  
  "idempotency_key": "order-12345-payment",  
  "metadata": {  
    "order_ref": "order-12345",  
    "initiated_by": "seal:order-processor"  
  },  
  "created_at": "2026-03-01T10:00:00Z",  
  "expires_at": "2026-03-01T10:15:00Z"  
}

Field notes:

  • idempotency_key — prevents duplicate intents; scoped to (payer_domain, cap_token_id); 24-hour deduplication window

  • expires_at — intents expire if not authorized within the window (default: 15 minutes)

  • metadata — arbitrary key-value store for upstream context; included in receipt

Validation Phase#

The Payment Intent Engine validates:

Check

Failure Behavior

CAP token exists and not expired

→ REJECTED with PAY_001

CAP token domain_scope matches payee_domain

→ REJECTED with PAY_002

Amount ≤ settlement_ceiling in CAP token

→ REJECTED with PAY_003

Daily/aggregate budget not exceeded

→ REJECTED with PAY_004

Currency in approved asset list

→ REJECTED with PAY_005

Network in governance-approved list

→ REJECTED with PAY_006

Intent not expired

→ REJECTED with PAY_007

Idempotency key not duplicate (active dedup window)

→ returns existing intent

All validation is synchronous. Rejection is immediate and final — a failed validation does not consume budget.

Risk Assessment#

After validation, the risk tier is assigned:

risk_tier = classify(amount, network, cap_token.risk_tier, payee_reputation)  
  
if risk_tier == 3:  
    → AWAITING_HUMAN_AUTH  
    → notify(cap_token.override_contacts)  
    → await signed_authorization (timeout: 10 minutes default)  
  
elif risk_tier == 2:  
    → PENDING_AUTH  
    → prompt in-band confirmation to payer  
  
else:  # tier 0–1  
    → PENDING_AUTH (auto-approved within policy)

The assigned risk tier is immutable once set and is recorded in the receipt.

Authorization#

Human Wallet Authorization

The payer’s wallet is presented with a structured signing request:

{  
  "type": "gao_payment_authorization",  
  "intent_id": "pi_abc123",  
  "amount": "25.00 USDC",  
  "payee": "shop.gao",  
  "risk_tier": 2,  
  "policy_hash": "0xabc...",  
  "expires_at": "2026-03-01T10:10:00Z"  
}

The wallet signature covers the full intent payload hash. Partial or reconstructed signatures are rejected.

Agent Authorization (Tier 0–1)

For Tier 0–1 intents initiated by an AI agent with a valid payment:autopay CAP capability, authorization is automatic provided:

  • M2M mode is enabled by the domain owner

  • Payee domain is on the allowlist

  • No active dispute flag on payee

  • Amount is within M2M budget ceiling

The agent does not sign the transaction — the protocol uses the domain owner’s pre-authorized M2M signing key.

Settlement#

Once authorized:

  1. Routing — the Currency Router selects the optimal network path (see Capability & Policy Model for routing logic)

  2. Broadcast — signed transaction broadcast to the selected network

  3. Confirmation monitoring — the Settlement Engine monitors for on-chain confirmation

  4. Finality — confirmation depth required varies by risk tier:

  • Tier 0–1: optimistic (1 confirmation)

  • Tier 2: standard (network default)

  • Tier 3: deep finality (6+ confirmations or chain-specific equivalent)

Receipt Emission#

On settlement, the Receipt Engine emits a canonical receipt. See Receipt Schema for the full format.

The receipt is:

  • Written to the append-only receipt ledger

  • Linked to the intent ID and CAP token

  • Linked to the on-chain transaction hash

  • Queryable via SDK and Gao Workspace

Receipt emission is mandatory. If the ledger write fails, the engine retries up to 3×. Extended failure escalates to operator alert — the on-chain transaction remains valid regardless.

Commerce Fulfillment#

If the intent is attached to a Gao Commerce order, the SETTLED state triggers the fulfillment hook:

SETTLED → notify(commerce_gateway, intent_id)  
        → commerce_gateway.fulfill(order_ref)  
        → order.state = FULFILLED

Fulfillment is always downstream of settlement. Orders cannot be fulfilled before the required finality level is reached.

Failure & Retry#

Failure

Retryable

Behavior

BROADCAST_FAILED

Yes

Retry up to 3× with exponential backoff

CONFIRMATION_TIMEOUT

Yes (new intent)

Emit timeout receipt; caller creates new intent

REJECTED

No

Failure receipt emitted; root cause in receipt

AWAITING_HUMAN_AUTH timeout

No

Abort receipt emitted; new intent required

Duplicate retry via idempotency key returns the original intent result if within dedup window.

Idempotency Semantics#

  • Scope: (payer_domain, cap_token_id, idempotency_key)

  • Dedup window: 24 hours from intent creation

  • During dedup window: same key returns existing intent state (including receipt if completed)

  • After dedup window: same key starts a new intent

The Payment Intent is the canonical unit of settlement in Gao Payment. All value transfer on the Gao Internet stack — human-initiated, agent-initiated, or M2M — follows this lifecycle.