# Flows

Sign-in, a payment and every agent protocol, step by step.

Every flow below is a numbered sequence diagram with the same steps written out underneath. Sign-in is in the OpenAPI contract. The payment flow, the protocol flows and the connectors are designed and marked that way.

## Sign-in

**Sign in with a signed client assertion.** In the OpenAPI contract.

Lanes: Your service, insimbi API, Audit record

1. Your service: Sign a client assertion (JWT, RS256) with your registered private key. Audience: the token endpoint.
2. Your service to insimbi API: POST /oauth2/token with grant_type, client_id, client_assertion and optional scope
3. insimbi API: Verify the signature against your registered key, reject replays, check your credential, grants and scopes
4. insimbi API to Audit record: Record token.issued (or security.rejected)
5. insimbi API to Your service: 200: access_token, token_type Bearer, expires_in (60 s at most), scope
6. Your service to insimbi API: GET /v1/merchant-accounts/{id} with Authorization: Bearer
7. insimbi API to Audit record: Record the access decision: authorization.allowed or authorization.denied
8. Audit record to insimbi API: Decision captured
9. insimbi API to Your service: 200 merchant account, or 403 insufficient_authority. X-Request-ID on every response.

## A payment

**Designed.** Payment endpoints are designed. Every check in this flow is written to the record.

**A payment, end to end.** Designed. Where the rule check, approval, rail choice and record happen.

Lanes: Your app or agent, insimbi API, Rules and mandate check, Operator, Rail, Record

1. Your app or agent to insimbi API: POST /v1/payments with an Idempotency-Key
2. insimbi API: Authenticate the token and record the access decision
3. insimbi API to Rules and mandate check: Check the payment against your rules and the agent's mandate
4. Rules and mandate check to Operator: Above your threshold: propose for approval
5. Operator to Rules and mandate check: A person approves
6. Rules and mandate check to insimbi API: Allowed. The routing rule chooses the rail.
7. insimbi API to Rail: Submit on the chosen rail
8. Rail to insimbi API: Rail result
9. insimbi API to Record: Write the ledger entry, fee lines cited to rules, and the ticket
10. insimbi API to Your app or agent: 201 with the ticket id
11. insimbi API to Your app or agent: Event delivered to your webhook endpoint

## Agent protocols

**Designed.** Protocol support is designed. Each flow follows the protocol's published specification, with insimbi on the merchant side.

**x402 with insimbi in the path.** Designed. Follows the x402 HTTP flow: 402, signed retry, verify, work, settle.

Lanes: Client (agent), Merchant API, insimbi, Facilitator (regulated partner)

1. Client (agent) to Merchant API: Request a resource
2. Merchant API to insimbi: Price it and check your rules for which assets and networks to accept
3. Merchant API to Client (agent): 402 Payment Required with a PAYMENT-REQUIRED header
4. Client (agent) to Merchant API: Retry with a signed payment in the PAYMENT-SIGNATURE header
5. Merchant API to insimbi: Check the payment against your rules and the agent's mandate
6. insimbi to Facilitator (regulated partner): POST /verify
7. Facilitator (regulated partner) to insimbi: Verification result (isValid, payer)
8. insimbi to Merchant API: Allowed
9. Merchant API: Perform the work
10. Merchant API to insimbi: Settle
11. insimbi to Facilitator (regulated partner): POST /settle
12. Facilitator (regulated partner) to insimbi: Settlement result (success, transaction, network)
13. insimbi: Write the ledger entry and fee lines to the record
14. Merchant API to Client (agent): Return the resource with a PAYMENT-RESPONSE header

**Agent Payments Protocol (AP2).** Designed. AP2 human-present journey, with insimbi as the merchant's payment processor.

Lanes: User (trusted surface), Shopping agent, Merchant, insimbi, Credentials provider and network

1. User (trusted surface) to Shopping agent: Give the agent a shopping task
2. Shopping agent to Merchant: Build a cart
3. Merchant to Shopping agent: Cart, signed by the merchant
4. Shopping agent to Credentials provider and network: Ask for an applicable payment method
5. Shopping agent to User (trusted surface): Show the cart and payment method
6. User (trusted surface) to Shopping agent: Approve: a signed Checkout Mandate
7. Shopping agent to Merchant: Submit the order with the Checkout Mandate and Payment Mandate
8. Merchant to insimbi: Authorize the payment
9. insimbi: Check the mandates against your rules, choose the rail
10. insimbi to Credentials provider and network: Authorization, with agent presence signals
11. Credentials provider and network to insimbi: Approved (or a challenge such as 3-D Secure)
12. insimbi to Merchant: Result, written to the record
13. Merchant to User (trusted surface): Order confirmed

**Agentic Commerce Protocol (ACP).** Designed. ACP checkout sessions and a delegated payment token, with insimbi charging for the merchant.

Lanes: Agent, Merchant, insimbi, Delegated payment provider

1. Agent to Merchant: POST /checkout_sessions (line items, currency)
2. Merchant to Agent: 201 with the authoritative cart, totals and fulfilment options
3. Agent to Merchant: POST /checkout_sessions/{id} to update choices
4. Agent to Delegated payment provider: POST /agentic_commerce/delegate_payment with an allowance
5. Delegated payment provider to Agent: Delegated token id
6. Agent to Merchant: POST /checkout_sessions/{id}/complete with payment_data
7. Merchant to insimbi: Charge the delegated token
8. insimbi: Check your rules and the allowance, choose the rail
9. insimbi to Delegated payment provider: Redeem the token within its allowance
10. Delegated payment provider to insimbi: Result
11. insimbi to Merchant: Result, written to the record
12. Merchant to Agent: Completed checkout and order

**Machine Payments Protocol (MPP).** Designed. MPP's Challenge, Credential and Receipt over HTTP 402.

Lanes: Client (agent), Merchant API, insimbi, Payment method (rail or regulated partner)

1. Client (agent) to Merchant API: Request a resource
2. Merchant API to insimbi: Price it and pick the payment methods your rules allow
3. Merchant API to Client (agent): 402 Payment Required with WWW-Authenticate: Payment (the Challenge)
4. Client (agent) to Payment method (rail or regulated partner): Pay with the method the Challenge names
5. Client (agent) to Merchant API: Retry with Authorization: Payment (the Credential)
6. Merchant API to insimbi: Verify the Credential is bound to the original Challenge
7. insimbi to Payment method (rail or regulated partner): Confirm the payment
8. Payment method (rail or regulated partner) to insimbi: Confirmed
9. insimbi: Write the ledger entry and fee lines to the record
10. Merchant API to Client (agent): 200 with a Payment-Receipt header

**Universal Commerce Protocol (UCP).** Designed. UCP discovery, payment handlers and complete checkout.

Lanes: Platform (agent), Business, insimbi, Payment handler

1. Platform (agent) to Business: GET /.well-known/ucp
2. Business to Platform (agent): Profile: version, services, capabilities, payment handlers
3. Platform (agent) to Business: Create checkout
4. Business to Platform (agent): Checkout, advertising the payment handlers it accepts
5. Platform (agent) to Payment handler: Execute the handler to get a token or credential
6. Payment handler to Platform (agent): Token
7. Platform (agent) to Business: Complete checkout with the token
8. Business to insimbi: Authorize
9. insimbi: Check your rules, choose the rail, write the record
10. insimbi to Business: Result (or a challenge for strong authentication)
11. Business to Platform (agent): Checkout completed

**Visa Intelligent Commerce.** Designed. Agent tokens, passkey-authenticated payment instructions and commerce signals.

Lanes: User, Agent, Visa, Merchant, insimbi

1. Agent to Visa: Enrol the card: an agent-specific token, cardholder step-up and a passkey
2. Agent to User: Recommend a purchase and ask to make it
3. User to Agent: Authenticate the payment instruction with the passkey
4. Agent to Visa: Submit the instruction and request payment credentials
5. Visa to Agent: Credentials that match the instruction
6. Agent to Merchant: Check out with the agent token
7. Merchant to insimbi: Authorize
8. insimbi to Visa: Authorization through the network, which checks merchant and amount against the instruction
9. Visa to insimbi: Result
10. insimbi to Merchant: Result, written to the record
11. Agent to Visa: Share the purchase outcome as commerce signals

**Visa Trusted Agent Protocol.** Designed. HTTP message signatures (RFC 9421) prove the agent before checkout.

Lanes: Agent, Merchant edge, Agent key directory, insimbi

1. Agent: Sign the request: Signature-Input and Signature over the authority and path, with created time, nonce and keyid
2. Agent to Merchant edge: Request the page or checkout with the signature headers
3. Merchant edge to Agent key directory: Fetch the public key for the keyid
4. Agent key directory to Merchant edge: Public key
5. Merchant edge: Verify the signature, the domain and path, the time window and the nonce
6. Merchant edge to insimbi: Pay, with the verified agent attached
7. insimbi: Record the agent verification with the payment
8. insimbi to Merchant edge: Result

**Mastercard Agent Pay.** Designed. Registered agents and Agentic Tokens.

Lanes: Consumer, Agent, Mastercard, Merchant, insimbi

1. Agent to Mastercard: Register and verify the agent
2. Consumer to Mastercard: Set what the agent may buy; an Agentic Token is issued
3. Consumer to Agent: Authenticate, for example with on-device biometrics
4. Agent to Merchant: Pay with the Agentic Token
5. Merchant to insimbi: Authorize
6. insimbi to Mastercard: Authorization through the network, identified as agent-initiated
7. Mastercard to insimbi: Result
8. insimbi to Merchant: Result, written to the record

**MCP tools.** Designed. Tool calls over MCP, with a person approving any wider access.

Lanes: Agent (MCP client), insimbi MCP server, insimbi API and record, Operator

1. Agent (MCP client) to insimbi MCP server: tools/list
2. insimbi MCP server to Agent (MCP client): quote_ticket, explain_decision, get_rule, open_mandate
3. Agent (MCP client) to insimbi MCP server: tools/call quote_ticket
4. insimbi MCP server to insimbi API and record: Price the payment against your rules. Nothing is submitted.
5. insimbi API and record to Agent (MCP client): Fee lines with rule citations and the perimeter decision
6. Agent (MCP client) to insimbi MCP server: tools/call open_mandate
7. insimbi MCP server to insimbi API and record: Propose the change (approval.proposed)
8. insimbi API and record to Operator: Ask a person to approve
9. Operator to insimbi API and record: Approve (approval.approved), bound to that exact change
10. insimbi API and record to Agent (MCP client): Mandate granted

## Connectors

**Designed.** Connectors are designed. Each one maps a partner's API to an insimbi rail or worker, and every call it makes is written to the record.

- **Event-contract venues**: Order entry, cancels, fills, positions, settlements and balances, read back into the record for reconciliation and cutoffs.
- **Stablecoin settlement**: Verify and settle agent payments through regulated partners, with each settlement matched to its ledger entry.
- **Connected-account platforms**: Onboard sub-merchants, split payments, transfers and payouts, with webhooks reconciled against the record.
- **Edge and bot verification**: Signed agent requests verified at the edge, and pay-per-request access with the charge recorded per request.

Request access: sales@insimbi.net

_insimbi is in early access with design partners._