> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments API

> Configure settlement accounts, retrieve defaults, and orchestrate checkout flows (card and bank transfer).

## Endpoints

| Method | Path                                | Description                                                            |
| ------ | ----------------------------------- | ---------------------------------------------------------------------- |
| GET    | `/v1/payments/accounts`             | List configured payment accounts (per provider).                       |
| POST   | `/v1/payments/accounts/upsert`      | Create or update an encrypted payment account configuration.           |
| GET    | `/v1/payments/defaults`             | Resolve workspace/product payment defaults used by the booking engine. |
| POST   | `/v1/payments/bank/init`            | Start a bank transfer session for a booking or wizard.                 |
| POST   | `/v1/payments/bank/approve`         | Confirm receipt of a bank transfer and trigger fulfilment workflows.   |
| POST   | `/v1/payments/start`                | Start an online payment session (Netopia adapter today).               |
| POST   | `/v1/integrations/netopia/notify`   | Receive Netopia payment status webhooks.                               |
| GET    | `/v1/integrations/netopia/redirect` | Handle customer return URLs after Netopia checkout.                    |

<Info>
  Workspace-scoped API keys are required for all `/v1/payments/*` routes. The <code>payments:read</code> and <code>payments:write</code> 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.
</Info>

## Key concepts

* Payment account credentials (e.g. Netopia POS signature/API key) are encrypted with Google Cloud KMS before being stored. Ensure <code>GCP\_SERVICE\_ACCOUNT\_KEY</code> and <code>GCP\_KMS\_INTEGRATIONS\_KEY\_NAME</code> (or a fallback <code>KMS\_ENCRYPTION\_KEY</code> in non-production) are configured.
* Defaults merge workspace-level payment settings with optional product overrides located in <code>catalog.product\_payment\_overrides</code>. The API returns whichever payload is currently effective for the caller.
* Bank transfer flows create <code>payments.payment\_sessions</code> rows and push notifications to Trigger.dev jobs (<code>payments.bank-transfer-init</code> and <code>payments.bank-transfer-approve</code>) for invoicing, contracts, and messaging.
* The generic <code>/v1/payments/start</code> 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).