Overview

Govifi Hosted Sessions API 1.0.0

Session-based checkout endpoints. A session is a short-lived (default 30min) handle for a single payment intent. The browser (component) authenticates every call with the session’s client_secret; the merchant backend creates, updates, and expires sessions with the Cognito admin access token. There are no per-account API keys (no publishable key, no secret key).

Auth modes:

cognito-admin (server: create / update / expire) — Authorization: Bearer <cognito-access-token> plus the X-Payment-Account-Uid header to identify the tenant. The same Cognito admin auth that /api/paymentaccounts uses. (The Cognito token is not yet scoped to a single payment account — a known future enhancement, acceptable for now.)
session-credential (browser) — Authorization: Bearer cs_..._secret_... — the session’s client_secret, sent as Bearer on ALL browser calls (read sanitized config, quote-fee, challenge/send, confirm). Replaces the old publishable-key. Browser-safe: scoped to one session, short-lived, origin-allowlisted, rate-limited per session credential. A wallet-scoped credential is rejected (403 insufficient_scope) at payment endpoints.

Information

OpenAPI version: 3.1.0

Authentication

cognitoAdmin

The Cognito admin access token — Authorization: Bearer <cognito-access-token>. The same auth /api/paymentaccounts uses. Required (with the X-Payment-Account-Uid header) for the server-side operations: create / update / expire sessions. The token is not yet scoped to a single payment account — a known future enhancement, acceptable for now; the tenant is identified by the X-Payment-Account-Uid header.

Security scheme type: http

Bearer format: JWT

sessionCredential

The hosted session’s client_secret (CreatedSession.client_secret), sent as Authorization: Bearer cs_..._secret_... on ALL browser calls. Replaces the old publishable-key. Scoped to one session, short-lived, origin-allowlisted, and rate limited per session credential. A wallet-scoped credential is rejected (403 insufficient_scope) at payment endpoints.