Get your credentials

Everything in Govifi Checkout is scoped to a payment account — your merchant configuration (processor settings, branding, fee rules, webhook endpoint). Your Govifi representative provisions the account; your server then authenticates to it with your Cognito admin access token.

Two credentials, two scopes

Govifi Checkout uses exactly two credentials. There are no per-account API keys — no publishable key and no secret key.

Credential	Where it lives	What it can do
Cognito admin token (JWT access token)	Your server, secret manager, CI secrets	Create, update, and expire hosted sessions; manage payment accounts
Session credential cs_…_secret_…	The browser, for one session only	Every browser call for that session: read config, quote fees, run challenges, confirm

The Cognito admin token is the same access token that authenticates the platform API (/api/paymentaccounts, …). Send it on the server-side checkout operations as Authorization: Bearer <cognito-access-token>, and identify the target payment account with the X-Payment-Account-Uid header:

POST /v1/hosted-sessions
Authorization: Bearer <cognito-access-token>
X-Payment-Account-Uid: {accountUid}

Note

The Cognito token is not yet scoped to a single payment account — the tenant is identified by the X-Payment-Account-Uid header. Per-payment-account scoping is a known future enhancement.

The session credential is the client_secret returned when you create a hosted session. It is minted per session, short-lived (expires with the session), and is the only credential the browser ever holds. The component sends it as Authorization: Bearer cs_…_secret_… on every call it makes. See Create a hosted session.

Origin allowlist

Browser (session-credential) requests are only accepted from origins you register. Set them on the payment account (and update later) via its checkout config:

PUT /api/paymentaccounts/{accountUid}/checkout-config

{
  "allowed_origins": [
    "https://payments.yourcity.gov",
    "https://billing.yourcity.gov"
  ]
}

Requests from any other origin get 403, so a leaked session credential can’t be used from someone else’s site. Browser endpoints are also rate-limited per session credential.

allowed_origins is additive: each call unions the origins you send into the account’s existing list rather than replacing it, so you can register origins incrementally without re-sending the full set. (Removing an origin is not yet supported through this endpoint.) To read the accumulated config — origins, branding, AVS fields, and page message — GET the same path:

GET /api/paymentaccounts/{accountUid}/checkout-config

Checkout defaults

Your account carries defaults that every session inherits unless overridden at creation: branding (display name, logo, accent color), required AVS fields, and an optional payment-page message. Set them once:

PUT /api/paymentaccounts/{accountUid}/checkout-config

{
  "branding": {
    "merchant_display_name": "City of Example Utilities",
    "accent_color": "#0B5FFF"
  },
  "required_avs_fields": ["cardholder", "zip"],
  "payment_page_message": "Payments post to your account within 1 business day."
}