# Provider accounts & project routing

Use separate credentials, shared credentials, or a mixture without mixing project data.

## Organization → project → environment → assignment

A provider account owns one encrypted credential set in one organization and environment type. A project environment assigns that account through a connection. A project may use dedicated Paystack credentials and shared Flutterwave credentials at the same time.

Every public API key is bound to one project environment. API requests never select another project through a project_id field or a header, and shared provider credentials never combine the projects’ payment lists.

## Configure dedicated or shared accounts

1. In a project’s sandbox/live provider page, choose Connect a new account for separate credentials, or Use an existing account for an eligible shared/unassigned account.
2. Sharing is off by default. An owner/admin can enable it for reuse in another project of the same organization and environment type.
3. Assign the saved account separately in each project that will use it. Sharing cannot be disabled while multiple current assignments exist.
4. Copy the incoming account webhook URL into the provider dashboard. Then configure each project’s outgoing webhook URL and signing secret separately.

## How incoming events find the right project

Veyqo verifies the provider signature for the incoming account, then matches the stored payment within that account and organization. It prefers the unique Veyqo payment ID and requires an unambiguous match for a provider reference fallback.

Merchant order references and untrusted project metadata are not sufficient routing instructions. Two projects can both use ORDER-1001 because Veyqo sends its own unique payment identifier to the provider. Account-scoped event deduplication prevents duplicate processing across old URL aliases.

Unknown or ambiguous events are retained for investigation instead of being broadcast to projects. Outgoing normalized events go only to the owning project’s subscribed endpoints.

## Switch, rotate and disconnect mean different things

| Action | Effect |
| --- | --- |
| Switch account | Creates a new assignment for future payments. Existing payments, refunds and late webhooks retain the original account. |
| Update credentials | Rotates the account-wide active credentials for every project using it. Use only for keys belonging to the same external provider account. |
| Disconnect | Detaches the selected project assignment; shared projects and historical reconciliation keep their account relationship. |
| Reuse account | Uses the saved credential set without copying secret credentials into another project. |

> Do not connect multiple Veyqo accounts using different keys for the same external provider account and assume events will route across them. Exact duplicate credential sets are refused for new accounts, but external account identity cannot be inferred generically from different keys. Review legacy duplicate accounts before moving provider webhook URLs.

## Public API behavior

The public payment API remains unchanged. Pass a provider slug when needed; the environment key resolves its current assignment. Provider account IDs and credentials are managed through the dashboard, not the public payments API. Veyqo’s platform billing account is never available for merchant sharing.