insimbi

Docs · Flows

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.
Sign in with a signed client assertionSequence diagram with 3 lanes (Your service, insimbi API, Audit record) and 9 numbered steps. The same steps are listed in text below the diagram.Your serviceinsimbi APIAudit record1Sign a client assertion (JWT, RS256)with your registered private key.Audience: the token endpoint.2POST /oauth2/tokenwith grant_type,client_id,client_assertion andoptional scope3Verify the signature against yourregistered key, reject replays, checkyour credential, grants and scopes4Record token.issued(orsecurity.rejected)5200: access_token,token_type Bearer,expires_in (60 s atmost), scope6GET/v1/merchant-accounts/{id}with Authorization:Bearer7Record the accessdecision:authorization.allowedorauthorization.denied8Decision captured9200 merchant account,or 403insufficient_authority.X-Request-ID on everyresponse.

Steps in text

  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.
A payment, end to endSequence diagram with 6 lanes (Your app or agent, insimbi API, Rules and mandate check, Operator, Rail, Record) and 11 numbered steps. The same steps are listed in text below the diagram.Your appor agentinsimbi APIRules andmandate checkOperatorRailRecord1POST /v1/paymentswith anIdempotency-Key2Authenticate the token and record theaccess decision3Check the paymentagainst your rulesand the agent'smandate4Above your threshold:propose for approval5A person approves6Allowed. The routingrule chooses therail.7Submit on the chosen rail8Rail result9Write the ledger entry, fee lines cited to rules, and the ticket10201 with the ticketid11Event delivered toyour webhook endpoint

Steps in text

  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.
x402 with insimbi in the pathSequence diagram with 4 lanes (Client (agent), Merchant API, insimbi, Facilitator (regulated partner)) and 14 numbered steps. The same steps are listed in text below the diagram.Client(agent)Merchant APIinsimbiFacilitator(regulated partner)1Request a resource2Price it and checkyour rules for whichassets and networksto accept3402 Payment Requiredwith aPAYMENT-REQUIREDheader4Retry with a signedpayment in thePAYMENT-SIGNATUREheader5Check the paymentagainst your rulesand the agent'smandate6POST /verify7Verification result(isValid, payer)8Allowed9Perform the work10Settle11POST /settle12Settlement result(success,transaction, network)13Write the ledger entry and fee lines tothe record14Return the resourcewith aPAYMENT-RESPONSEheader

Steps in text

  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.
Agent Payments Protocol (AP2)Sequence diagram with 5 lanes (User (trusted surface), Shopping agent, Merchant, insimbi, Credentials provider and network) and 13 numbered steps. The same steps are listed in text below the diagram.User(trusted surface)Shopping agentMerchantinsimbiCredentials providerand network1Give the agent ashopping task2Build a cart3Cart, signed by themerchant4Ask for an applicable payment method5Show the cart andpayment method6Approve: a signedCheckout Mandate7Submit the order withthe Checkout Mandateand Payment Mandate8Authorize the payment9Check the mandates against your rules,choose the rail10Authorization, withagent presencesignals11Approved (or achallenge such as 3-DSecure)12Result, written tothe record13Order confirmed

Steps in text

  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.
Agentic Commerce Protocol (ACP)Sequence diagram with 4 lanes (Agent, Merchant, insimbi, Delegated payment provider) and 12 numbered steps. The same steps are listed in text below the diagram.AgentMerchantinsimbiDelegated paymentprovider1POST/checkout_sessions(line items,currency)2201 with theauthoritative cart,totals and fulfilmentoptions3POST/checkout_sessions/{id}to update choices4POST /agentic_commerce/delegate_payment with an allowance5Delegated token id6POST/checkout_sessions/{id}/completewith payment_data7Charge the delegatedtoken8Check your rules and the allowance,choose the rail9Redeem the tokenwithin its allowance10Result11Result, written tothe record12Completed checkoutand order

Steps in text

  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.
Machine Payments Protocol (MPP)Sequence diagram with 4 lanes (Client (agent), Merchant API, insimbi, Payment method (rail or regulated partner)) and 10 numbered steps. The same steps are listed in text below the diagram.Client(agent)Merchant APIinsimbiPayment method(rail or regulated partner)1Request a resource2Price it and pick thepayment methods yourrules allow3402 Payment RequiredwithWWW-Authenticate:Payment (theChallenge)4Pay with the method the Challenge names5Retry withAuthorization:Payment (theCredential)6Verify the Credentialis bound to theoriginal Challenge7Confirm the payment8Confirmed9Write the ledger entry and fee lines tothe record10200 with aPayment-Receiptheader

Steps in text

  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.
Universal Commerce Protocol (UCP)Sequence diagram with 4 lanes (Platform (agent), Business, insimbi, Payment handler) and 11 numbered steps. The same steps are listed in text below the diagram.Platform(agent)BusinessinsimbiPayment handler1GET /.well-known/ucp2Profile: version,services,capabilities, paymenthandlers3Create checkout4Checkout, advertisingthe payment handlersit accepts5Execute the handler to get a token or credential6Token7Complete checkoutwith the token8Authorize9Check your rules, choose the rail,write the record10Result (or achallenge for strongauthentication)11Checkout completed

Steps in text

  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.
Visa Intelligent CommerceSequence diagram with 5 lanes (User, Agent, Visa, Merchant, insimbi) and 11 numbered steps. The same steps are listed in text below the diagram.UserAgentVisaMerchantinsimbi1Enrol the card: anagent-specific token,cardholder step-upand a passkey2Recommend a purchaseand ask to make it3Authenticate thepayment instructionwith the passkey4Submit theinstruction andrequest paymentcredentials5Credentials thatmatch the instruction6Check out with the agent token7Authorize8Authorization through the network, which checksmerchant and amount against the instruction9Result10Result, written tothe record11Share the purchaseoutcome as commercesignals

Steps in text

  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.
Visa Trusted Agent ProtocolSequence diagram with 4 lanes (Agent, Merchant edge, Agent key directory, insimbi) and 8 numbered steps. The same steps are listed in text below the diagram.AgentMerchant edgeAgent keydirectoryinsimbi1Sign the request: Signature-Input andSignature over the authority and path,with created time, nonce and keyid2Request the page orcheckout with thesignature headers3Fetch the public keyfor the keyid4Public key5Verify the signature, the domain andpath, the time window and the nonce6Pay, with the verified agent attached7Record the agent verification with thepayment8Result

Steps in text

  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.
Mastercard Agent PaySequence diagram with 5 lanes (Consumer, Agent, Mastercard, Merchant, insimbi) and 8 numbered steps. The same steps are listed in text below the diagram.ConsumerAgentMastercardMerchantinsimbi1Register and verifythe agent2Set what the agent may buy; an Agentic Token isissued3Authenticate, forexample withon-device biometrics4Pay with the Agentic Token5Authorize6Authorization through the network, identifiedas agent-initiated7Result8Result, written tothe record

Steps in text

  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.
MCP toolsSequence diagram with 4 lanes (Agent (MCP client), insimbi MCP server, insimbi API and record, Operator) and 10 numbered steps. The same steps are listed in text below the diagram.Agent(MCP client)insimbi MCP serverinsimbi APIand recordOperator1tools/list2quote_ticket,explain_decision,get_rule,open_mandate3tools/callquote_ticket4Price the paymentagainst your rules.Nothing is submitted.5Fee lines with rule citations and the perimeterdecision6tools/callopen_mandate7Propose the change(approval.proposed)8Ask a person toapprove9Approve(approval.approved),bound to that exactchange10Mandate granted

Steps in text

  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 venuesOrder entry, cancels, fills, positions, settlements and balances, read back into the record for reconciliation and cutoffs.
Stablecoin settlementVerify and settle agent payments through regulated partners, with each settlement matched to its ledger entry.
Connected-account platformsOnboard sub-merchants, split payments, transfers and payouts, with webhooks reconciled against the record.
Edge and bot verificationSigned agent requests verified at the edge, and pay-per-request access with the charge recorded per request.

Request access

insimbi is in early access with design partners.