Payment accounts

1. Create your client

A client is your organization; payment accounts belong to it. Create one (or look yours up) once:

POST /api/clients

{
  "customer_id": "city-of-example",
  "name": "City of Example",
  "timezone": "Mountain Standard Time",
  "subdomain": "city-of-example"
}

To find an existing client instead of creating a duplicate:

GET /api/clients?$filter=name eq 'City of Example'&$top=1

2. Create a payment account

One per merchant configuration (e.g., per fund or department with its own processor account):

POST /api/paymentaccounts

{
  "client_id": "{client.uid}",
  "name": "Utilities",
  "processor": "zift",
  "external_account_id": "{processorAccountId}",
  "external_merchant_id": "{processorMerchantId}",
  "active": true,
  "enable_ach": true,
  "enable_credit_card": true,
  "minimum_payment_amount": 0.0,
  "maximum_payment_amount": 999999.99,
  "callback_url": "https://yourserver.example/webhooks/payments",
  "webhook_enabled": true
}

The returned uid is your X-Payment-Account-Uid for all account-scoped calls. Before creating, check GET /api/paymentaccounts for an existing account with the same external_account_id + external_merchant_id and reuse it — accounts are long-lived.

3. Configure webhooks

PUT /api/webhooks/subscriptions
X-Payment-Account-Uid: {uid}

{
  "subscriptions": [
    { "event_type": "payment.completed", "enabled": true },
    { "event_type": "payment.failed", "enabled": true },
    { "event_type": "payment.refunded", "enabled": true },
    { "event_type": "checkout_session.completed", "enabled": true }
  ]
}

Fetch your signing secret with GET /api/webhooks/secret and verify every delivery — see the webhooks guide. The full event catalog (provider.chargeback, provider.nsf, provider.noc, provider.reversal, provider.bankbillpay, ivr.completed, …) is at GET /api/webhooks/types.

4. Checkout config (optional)

If you’ll use hosted/embedded checkout, there are no per-account API keys to provision. Your server creates sessions with the same Cognito admin token used here (plus the X-Payment-Account-Uid header), and the browser uses a per-session credential. Configure the account’s browser origin allowlist and checkout defaults via its checkout config:

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

See Get your credentials.