Platform API — overview & authentication

Beyond hosted sessions, the Payments API exposes the full platform surface: clients and payment accounts, direct payment processing (validate → capture → refund), customers and saved payment methods (wallets), terminals, and webhooks. Browse every operation in the API console.

The only credentials you need from us are a client id and client secret. Everything else — accounts, API keys, webhook secrets — you provision yourself through the API.

Authentication

The API uses OAuth 2.0 client credentials against our identity provider. Exchange your client id/secret for a bearer token:

curl -X POST https://{cognito-domain}/oauth2/token \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=com.govineer.payments/admin"

{ "access_token": "eyJraWQi…", "expires_in": 3600, "token_type": "Bearer" }

Tokens live one hour — cache them and refresh a few minutes before expiry (don’t request a new token per call).

Request headers

Every API call carries the bearer token; account-scoped operations also carry the payment-account header:

Authorization: Bearer {access_token}
X-Payment-Account-Uid: {paymentAccountUid}
Content-Type: application/json

Routes that are account-agnostic (/api/clients, /api/paymentaccounts) or that resolve the account from an API key (/v1/hosted-sessions) don’t need the header.

Conventions

• snake_case JSON on the wire, both directions.
• Amounts are integer minor units (cents): 12345 = $123.45.
• List endpoints support OData: GET /api/clients?$filter=name eq 'City of Example'&$top=1.
• Unknown JSON properties are rejected — match the documented shapes exactly.

The object model

Client (your organization / tenant)
└── PaymentAccount (one per merchant configuration; processor credentials,
    │                fee rules, branding, webhook endpoint, API keys)
    ├── Payments / Transactions
    ├── Customers ── SavedPaymentMethods (wallets)
    ├── HostedSessions
    ├── Terminals
    └── WebhookSubscriptions

Start with payment accounts, then process a payment.