Facilitator HTTP integration
Use these native Facilitator HTTP endpoints with a self-hosted or operator-provided service. Hosted InvisiPay merchants use the separate Business Payments contract. HTTP messages show request formats; curl commands contact the selected service without executing financial operations. https://facilitator.example, EXAMPLE values and addresses are placeholders. Replace them with your operator's address, valid credentials, enabled asset and future deadline. base_usdc must be a published option; these examples do not establish service availability on Base.
1. Merchant creates a Session
Configure the merchant Key (inv_test_ or inv_live_ prefix) on the server and construct input from the authenticated order. Preserve the Idempotency-Key and semantic input when retrying the same order. The prefix does not select the network or finality policy. Never give this Key to the wallet or browser.
POST /v1/checkouts HTTP/1.1
Host: facilitator.example
Authorization: Bearer inv_test_EXAMPLE_MERCHANT_KEY
Content-Type: application/json
Accept: application/json
Idempotency-Key: order-EXAMPLE-001
{
"ippVersion": 1,
"mode": "payment",
"description": "Research report",
"options": [{
"id": "base_usdc",
"method": "invisi",
"network": "eip155:8453",
"asset": {
"address": "0x1111111111111111111111111111111111111111",
"symbol": "USDC",
"decimals": 6
},
"amount": "10000000"
}],
"expiresAt": "2026-12-18T08:05:00Z"
}
First creation returns 201, identical replay 200, and conflicting input under the same key 409. The startup response has no separate sessionId; obtain it by reading sessionUrl:
{
"ippVersion": 1,
"type": "checkout",
"sessionUrl": "https://facilitator.example/v1/sessions/ses_EXAMPLE",
"checkoutUrl": "https://dapp.invisipay.fi/checkout#sessionUrl=https%3A%2F%2Ffacilitator.example%2Fv1%2Fsessions%2Fses_EXAMPLE&token=EXAMPLE_SESSION_TOKEN",
"expiresAt": "2026-12-18T08:05:00Z"
}
Store the original entry with the order and deliver checkoutUrl through a trusted channel. The Token is in the cashier fragment; API requests use Bearer instead. Merchant-side queries may use the owning merchant Key, avoiding reliance on client-supplied JSON as a payment decision.
2. Wallet reads and confirms
This read-only call uses the original sessionUrl from creation. Use the returned full URL unchanged rather than appending or guessing a path.
curl --fail-with-body --silent --show-error \
'https://facilitator.example/v1/sessions/ses_EXAMPLE' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer EXAMPLE_SESSION_TOKEN'
Check the displayed merchant, real service origin, mode and options. Before confirmation, links.request is null. Follow links.confirm.href with its returned method; this example assumes it is exactly the following URL:
POST /v1/sessions/ses_EXAMPLE/confirm HTTP/1.1
Host: facilitator.example
Authorization: Bearer EXAMPLE_SESSION_TOKEN
Content-Type: application/json
Accept: application/json
Idempotency-Key: confirm-EXAMPLE-001
{"optionId":"base_usdc"}
The first response is 201 with the complete PaymentRequest/CreditRequest and its read URL in Location. Replay returns 200 and the original Request. Retain Location and the original sessionUrl. Only first confirmation generates material. Same-option retries restore it; another option conflicts. A merchant API Key cannot replace the Session Token here.
3. Execute, query and fulfill
Validate the complete Request using payment or credit rules, then authorize and execute through the wallet. Optional Credentials go to Request.links.credentials; 202 is not success. Background verification continues without Credential submission or polling.
Repeat the GET above to read the Session. HTTP 200 means the read succeeded; the Session may still be processing or failed. Success requires a receipt. The merchant checks status=succeeded, current evidenceStatus and business terms, enforcing fulfillment idempotency using its local order. Pure credit success establishes authorization only.
A paid API may create or reuse a Checkout, return 402 with the standard PaymentSession and deliver the same entry through Link relations ipp-session/ipp-checkout. After payment, the client retries the original operation under the merchant API's contract. The merchant verifies caller and original billing parameters, authenticates its own Session query and recovers or returns the original business result. A client reference does not grant entitlement, and one payment cannot be reused indefinitely.
Implementation endpoints and access recovery
| Method | Route | Authorization |
|---|---|---|
| POST | /v1/checkouts | Merchant API Key |
| GET | /v1/checkouts/{sessionId} | Owning merchant API Key |
| POST | /v1/checkouts/{sessionId}/access | Owning merchant API Key |
| GET | /v1/checkouts/{sessionId}/exceptions | Owning merchant API Key |
| GET | /v1/sessions/{sessionId} | Session Token or owning merchant API Key |
| POST | /v1/sessions/{sessionId}/confirm | Session Token |
| GET | /v1/sessions/{sessionId}/requests/{requestId} | Session Token |
| POST | /v1/sessions/{sessionId}/requests/{requestId}/credentials | Session Token |
The merchant-management endpoints in this table are Facilitator extensions. Payment clients targeting different services follow the full IPP links. access accepts POST without a body, returns a Checkout with a replacement Token and invalidates the old Token while preserving material and deadlines. exceptions returns {"data":[...]} with verified facts, without shared keys or decrypted state, and does not automatically refund funds.
Creation Idempotency-Key accepts 1–128 printable non-whitespace ASCII characters. Request bodies are limited to 64 KiB, with at most 100 options. Unknown fields, duplicate properties and noncanonical encoding are rejected. Respect Retry-After. Request-Id identifies an attempt for operator support. Keep Authorization, cashier fragments and complete private Requests out of logs.
Authorization, deadlines and recovery covers errors and safe retries. IPP has no separate Receipt read or manual redemption step.