Skip to main content

​
Endpoints

MethodPathDescription
GET/v1/payments/accountsList configured payment accounts (per provider).
POST/v1/payments/accounts/upsertCreate or update an encrypted payment account configuration.
GET/v1/payments/defaultsResolve workspace/product payment defaults used by the booking engine.
POST/v1/payments/bank/initStart a bank transfer session for a booking or wizard.
POST/v1/payments/bank/approveConfirm receipt of a bank transfer and trigger fulfilment workflows.
POST/v1/payments/startStart an online payment session (Netopia adapter today).
POST/v1/integrations/netopia/notifyReceive Netopia payment status webhooks.
GET/v1/integrations/netopia/redirectHandle customer return URLs after Netopia checkout.
Workspace-scoped API keys are required for all /v1/payments/* routes. The payments:read and payments:write scopes are enforced on the accounts APIs; the remaining endpoints rely on the base API guard. Inbound Netopia callbacks are unauthenticated and should be restricted via provider IP allow lists.

​
Key concepts

  • Payment account credentials (e.g. Netopia POS signature/API key) are encrypted with Google Cloud KMS before being stored. Ensure GCP_SERVICE_ACCOUNT_KEY and GCP_KMS_INTEGRATIONS_KEY_NAME (or a fallback KMS_ENCRYPTION_KEY in non-production) are configured.
  • Defaults merge workspace-level payment settings with optional product overrides located in catalog.product_payment_overrides. The API returns whichever payload is currently effective for the caller.
  • Bank transfer flows create payments.payment_sessions rows and push notifications to Trigger.dev jobs (payments.bank-transfer-init and payments.bank-transfer-approve) for invoicing, contracts, and messaging.
  • The generic /v1/payments/start endpoint resolves the active provider for the workspace. Netopia is the only adapter implemented today; additional providers will extend the same entry point.
  • Netopia redirect + notify endpoints record webhook payloads, update payment sessions, and fan-out to Trigger.dev orchestrators for downstream fulfilment (invoices, contracts, notifications).