# PCX Developer Docs

## Docs

- [Create currency account](https://docs.pcxpay.com/api-reference/accounts/create-currency-account.md): Creates a fiat currency virtual account for a customer. The account is associated with both an `org_id` and a `user_id`.
- [Create internal bank account](https://docs.pcxpay.com/api-reference/accounts/create-internal-bank-account.md): Provisions an internal bank virtual account for a customer under a given organisation. Requires `internal-admin` role.
- [Create internal crypto account](https://docs.pcxpay.com/api-reference/accounts/create-internal-crypto-account.md): Provisions an internal crypto virtual account for a customer. Requires `internal-admin` role.
- [Delete all accounts for an org](https://docs.pcxpay.com/api-reference/accounts/delete-all-accounts-for-an-org.md): Deletes every virtual account belonging to the specified organisation. Requires `internal-admin` role.
- [Delete virtual account](https://docs.pcxpay.com/api-reference/accounts/delete-virtual-account.md): Deletes a specific virtual account. Requires `internal-admin` role.
- [Get internal accounts by user (admin)](https://docs.pcxpay.com/api-reference/accounts/get-internal-accounts-by-user-admin.md): Returns all internal (bank + crypto) virtual accounts for a user. Requires `internal-admin` role.
- [Get virtual accounts by org](https://docs.pcxpay.com/api-reference/accounts/get-virtual-accounts-by-org.md): Returns all virtual accounts associated with the given organisation.
- [Get virtual accounts by user](https://docs.pcxpay.com/api-reference/accounts/get-virtual-accounts-by-user.md): Returns all virtual accounts owned by the specified user.
- [List all currency accounts (admin)](https://docs.pcxpay.com/api-reference/accounts/list-all-currency-accounts-admin.md): Paginated list of all currency virtual accounts across all organisations. Requires `internal-admin` role.
- [Receive provider webhook](https://docs.pcxpay.com/api-reference/accounts/receive-provider-webhook.md): Webhook receiver for virtual account provider events (e.g. Bridge, SquadCo). The `provider_name` path segment identifies the originating provider. Authentication is provider-specific and handled internally.
- [Update account status](https://docs.pcxpay.com/api-reference/accounts/update-account-status.md): Activates or deactivates a virtual account. Requires `internal-admin` role.
- [Update virtual account](https://docs.pcxpay.com/api-reference/accounts/update-virtual-account.md): Updates account metadata such as the display name. Requires `internal-admin` role.
- [Account registry (admin)](https://docs.pcxpay.com/api-reference/admin/account-registry-admin.md): Full paginated registry of all virtual accounts with admin-level detail. Requires `internal-admin` role.
- [Admin dashboard metrics](https://docs.pcxpay.com/api-reference/admin/admin-dashboard-metrics.md): Returns high-level aggregate metrics for the admin dashboard: total accounts, balances, and platform-wide KPIs. Requires `internal-admin` role.
- [Admin dashboard recent transactions](https://docs.pcxpay.com/api-reference/admin/admin-dashboard-recent-transactions.md): Returns the most recent virtual account transactions for the admin dashboard. Requires `internal-admin` role.
- [Admin dashboard system health](https://docs.pcxpay.com/api-reference/admin/admin-dashboard-system-health.md): Returns system health indicators for the virtual accounts platform. Requires `internal-admin` role.
- [Admin dashboard trends](https://docs.pcxpay.com/api-reference/admin/admin-dashboard-trends.md): Returns time-series trend data for the admin dashboard. Requires `internal-admin` role.
- [Approve or deny a feature request](https://docs.pcxpay.com/api-reference/admin/approve-or-deny-a-feature-request.md): Requires role `internal-admin`.
- [Approve pending withdrawal](https://docs.pcxpay.com/api-reference/admin/approve-pending-withdrawal.md): Approves a pending NGN withdrawal that requires admin review before processing. Requires `internal-admin` role.
- [Delete an organization](https://docs.pcxpay.com/api-reference/admin/delete-an-organization.md): Requires role `internal-admin`.
- [Disable an organization](https://docs.pcxpay.com/api-reference/admin/disable-an-organization.md): Requires role `internal-admin`. No request body.
- [Get account detail (admin)](https://docs.pcxpay.com/api-reference/admin/get-account-detail-admin.md): Returns full admin-level details for a single virtual account.
- [Get transaction detail (admin)](https://docs.pcxpay.com/api-reference/admin/get-transaction-detail-admin.md): Returns admin-level detail for a single transaction.
- [List all beneficiaries (admin)](https://docs.pcxpay.com/api-reference/admin/list-all-beneficiaries-admin.md): Returns a paginated list of every beneficiary across all users. Requires the `internal-admin` role. Pagination supports either cursor-based (`last_evaluated_key`) or page-number-based (`page`) navigation. When `page > 1` and no `last_evaluated_key` is supplied, the service sequentially scans through…
- [List all organizations](https://docs.pcxpay.com/api-reference/admin/list-all-organizations.md): Requires role `internal-admin`.
- [List all transactions (admin)](https://docs.pcxpay.com/api-reference/admin/list-all-transactions-admin.md): Paginated list of all virtual account transactions across the platform. Requires `internal-admin` role.
- [List approved feature requests](https://docs.pcxpay.com/api-reference/admin/list-approved-feature-requests.md): Requires role `internal-admin`.
- [List beneficiaries by organisation](https://docs.pcxpay.com/api-reference/admin/list-beneficiaries-by-organisation.md): Returns beneficiaries (typically `loan_client` type) that belong to the given organisation. Requires `internal-admin` or `org-admin` role. Supports an optional `query` search parameter and DynamoDB cursor pagination via `next_token` (a JSON-encoded key passed as a query string).
- [List denied feature requests](https://docs.pcxpay.com/api-reference/admin/list-denied-feature-requests.md): Requires role `internal-admin`.
- [List pending feature requests](https://docs.pcxpay.com/api-reference/admin/list-pending-feature-requests.md): Requires role `internal-admin`.
- [Platform analytics (admin)](https://docs.pcxpay.com/api-reference/admin/platform-analytics-admin.md): Aggregated analytics across all virtual accounts: volume, transaction counts, active accounts. Requires `internal-admin` role.
- [Reject pending withdrawal](https://docs.pcxpay.com/api-reference/admin/reject-pending-withdrawal.md): Rejects a pending NGN withdrawal. The account balance is restored. Requires `internal-admin` role.
- [Trigger cross-rail payout](https://docs.pcxpay.com/api-reference/admin/trigger-cross-rail-payout.md): Manually triggers a cross-rail payout for a transaction that has already been funded on one payment rail and needs to be disbursed on another. Requires `internal-admin` role.
- [Update organization status](https://docs.pcxpay.com/api-reference/admin/update-organization-status.md): Requires role `internal-admin`.
- [All-transaction analytics (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/all-transaction-analytics-admin.md): Platform-wide aggregate metrics. Requires `internal-admin`.
- [Analytics for all users combined (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/analytics-for-all-users-combined-admin.md): Aggregate metrics across all users. Requires `internal-admin`.
- [Average transactions per user (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/average-transactions-per-user-admin.md): Requires `internal-admin`.
- [Completed transactions in the last 24 hours (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/completed-transactions-in-the-last-24-hours-admin.md): Requires `internal-admin`.
- [Domestic vs cross-border split (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/domestic-vs-cross-border-split-admin.md): Requires `internal-admin`.
- [Global currency distribution (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/global-currency-distribution-admin.md): Requires `internal-admin`.
- [Global payment method distribution (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/global-payment-method-distribution-admin.md): Requires `internal-admin`.
- [Global status distribution (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/global-status-distribution-admin.md): Requires `internal-admin`.
- [Overall transaction success rate](https://docs.pcxpay.com/api-reference/analytics-—-global/overall-transaction-success-rate.md): Success rate computed only over transactions that have reached a conclusive terminal state (`completed` or `failed`). Open to all authenticated users.
- [Payment method preferences (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/payment-method-preferences-admin.md): Aggregated payment method preference data across all users. Requires `internal-admin`.
- [Peak transaction hours (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/peak-transaction-hours-admin.md): Requires `internal-admin`.
- [Success rate by payment method (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/success-rate-by-payment-method-admin.md): Requires `internal-admin`.
- [Successful transactions in the last 24 hours (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/successful-transactions-in-the-last-24-hours-admin.md): Requires `internal-admin`.
- [Total remittance volume in the last 24 hours (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/total-remittance-volume-in-the-last-24-hours-admin.md): Requires `internal-admin`.
- [Total transaction count (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/total-transaction-count-admin.md): Requires `internal-admin`.
- [Transaction failure analysis (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/transaction-failure-analysis-admin.md): Failure rate and reasons breakdown. Requires `internal-admin`.
- [Transaction trends (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/transaction-trends-admin.md): Time-series trend data. Requires `internal-admin`.
- [Transaction value distribution (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/transaction-value-distribution-admin.md): Requires `internal-admin`.
- [User activation rate (admin)](https://docs.pcxpay.com/api-reference/analytics-—-global/user-activation-rate-admin.md): Percentage of registered users who have made at least one transaction. Requires `internal-admin`.
- [Organisation analytics (admin)](https://docs.pcxpay.com/api-reference/analytics-—-org/organisation-analytics-admin.md): Aggregate transaction metrics for a specific organisation. Requires `internal-admin`.
- [Currency distribution for a user (admin)](https://docs.pcxpay.com/api-reference/analytics-—-user/currency-distribution-for-a-user-admin.md)
- [Payment method distribution for a user (admin)](https://docs.pcxpay.com/api-reference/analytics-—-user/payment-method-distribution-for-a-user-admin.md)
- [Status distribution for a user (admin)](https://docs.pcxpay.com/api-reference/analytics-—-user/status-distribution-for-a-user-admin.md)
- [User transaction analytics (admin)](https://docs.pcxpay.com/api-reference/analytics-—-user/user-transaction-analytics-admin.md): Aggregate metrics for a specific user's transactions. Requires `internal-admin`.
- [Average number of users per organization](https://docs.pcxpay.com/api-reference/analytics/average-number-of-users-per-organization.md): Requires role `internal-admin`.
- [Average transaction volume per organization](https://docs.pcxpay.com/api-reference/analytics/average-transaction-volume-per-organization.md): Requires role `internal-admin`.
- [Average transactions per user](https://docs.pcxpay.com/api-reference/analytics/average-transactions-per-user.md): Returns average transaction count per user. Requires `internal-admin` role.
- [Comprehensive user analytics](https://docs.pcxpay.com/api-reference/analytics/comprehensive-user-analytics.md): Returns an aggregated analytics snapshot across users. Requires `internal-admin` role.
- [Geographic distribution](https://docs.pcxpay.com/api-reference/analytics/geographic-distribution.md): Returns user counts grouped by country. Requires `internal-admin` role.
- [KYB completion rate across all organizations](https://docs.pcxpay.com/api-reference/analytics/kyb-completion-rate-across-all-organizations.md): Requires role `internal-admin`.
- [KYB funnel analysis — org counts at each KYB stage](https://docs.pcxpay.com/api-reference/analytics/kyb-funnel-analysis-—-org-counts-at-each-kyb-stage.md): Requires role `internal-admin`.
- [KYC compliance rate](https://docs.pcxpay.com/api-reference/analytics/kyc-compliance-rate.md): Returns KYC completion and pass-rate statistics. Requires `internal-admin` role.
- [KYC funnel analysis](https://docs.pcxpay.com/api-reference/analytics/kyc-funnel-analysis.md): Returns a funnel showing user progression through KYC stages. Requires `internal-admin` role.
- [Organization growth rate](https://docs.pcxpay.com/api-reference/analytics/organization-growth-rate.md): Requires role `internal-admin`.
- [Payment analytics (admin)](https://docs.pcxpay.com/api-reference/analytics/payment-analytics-admin.md): Aggregate payment metrics. Requires `internal-admin`.
- [Provider analytics (admin)](https://docs.pcxpay.com/api-reference/analytics/provider-analytics-admin.md): Breakdown of payment metrics by provider. Requires `internal-admin`.
- [Top organizations by payment volume](https://docs.pcxpay.com/api-reference/analytics/top-organizations-by-payment-volume.md): Requires role `internal-admin`.
- [Total active users](https://docs.pcxpay.com/api-reference/analytics/total-active-users.md): Returns the count of active users. Requires `internal-admin` role.
- [Total count of active organizations](https://docs.pcxpay.com/api-reference/analytics/total-count-of-active-organizations.md): Requires role `internal-admin`.
- [User growth rate](https://docs.pcxpay.com/api-reference/analytics/user-growth-rate.md): Returns user growth metrics over the specified window. Requires `internal-admin` role.
- [User role distribution](https://docs.pcxpay.com/api-reference/analytics/user-role-distribution.md): Returns a breakdown of users by role. Requires `internal-admin` role.
- [User status distribution](https://docs.pcxpay.com/api-reference/analytics/user-status-distribution.md): Returns a breakdown of users by status. Requires `internal-admin` role.
- [Create API key](https://docs.pcxpay.com/api-reference/api-keys/create-api-key.md): Creates a new API key for the given organisation and user. The full key value is returned once at creation and is not retrievable afterwards — store it securely.
- [Delete API key](https://docs.pcxpay.com/api-reference/api-keys/delete-api-key.md): Permanently deletes an API key identified by its prefix. This action is irreversible — any integration using this key will immediately lose access.
- [List API keys](https://docs.pcxpay.com/api-reference/api-keys/list-api-keys.md): Returns a paginated list of API keys for an organisation. Filter by `org_id` to scope results to a specific organisation.
- [Revoke API key](https://docs.pcxpay.com/api-reference/api-keys/revoke-api-key.md): Disables an API key without deleting it. The key record is preserved for audit purposes but will be rejected on all subsequent requests. Can be re-activated if needed.
- [Exchange TrueLayer auth code for tokens](https://docs.pcxpay.com/api-reference/bank-validation/exchange-truelayer-auth-code-for-tokens.md): Called after the TrueLayer redirect. Exchanges the `code` for access and refresh tokens. Use the returned `access_token` for account holder verification.
- [Initiate TrueLayer OAuth flow](https://docs.pcxpay.com/api-reference/bank-validation/initiate-truelayer-oauth-flow.md): Returns an `auth_url` that the frontend must redirect the user to in order to grant TrueLayer access to their bank account. The `state` parameter is set to the authenticated user's ID.
- [List supported Nigerian banks](https://docs.pcxpay.com/api-reference/bank-validation/list-supported-nigerian-banks.md): Returns the Paystack list of Nigerian banks with their bank codes.
- [List supported UK banks](https://docs.pcxpay.com/api-reference/bank-validation/list-supported-uk-banks.md): Returns the list of UK bank provider IDs accepted by the TrueLayer OAuth flow.
- [Validate Nigerian bank account](https://docs.pcxpay.com/api-reference/bank-validation/validate-nigerian-bank-account.md): Resolves an account number against its bank via Paystack.
- [Validate UK account format](https://docs.pcxpay.com/api-reference/bank-validation/validate-uk-account-format.md): Performs basic format validation on a UK sort code and account number. Does not verify account ownership — use the TrueLayer OAuth flow for identity verification.
- [Validate UK account via modulus check](https://docs.pcxpay.com/api-reference/bank-validation/validate-uk-account-via-modulus-check.md): Performs full modulus checking on a UK sort code and account number via the BankAccountChecker API. No OAuth required — instant validation.
- [Verify UK account holder name](https://docs.pcxpay.com/api-reference/bank-validation/verify-uk-account-holder-name.md): Verifies that a given name matches the account holder on record via TrueLayer. Requires an `accessToken` obtained from the TrueLayer OAuth flow.
- [Create a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/create-a-beneficiary.md): Creates a new beneficiary for the authenticated user. The `beneficiary_of` field is derived from the authenticated user's credentials, or from the `beneficiary_of` field in the request body. For loan-client beneficiaries created on behalf of an organisation, pass `org_id` in the request body. **Vali…
- [Delete a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/delete-a-beneficiary.md): Permanently deletes a beneficiary. Ownership is verified via the authenticated user's credentials.
- [Get a beneficiary by ID](https://docs.pcxpay.com/api-reference/beneficiaries/get-a-beneficiary-by-id.md): Returns a single beneficiary. The service enforces ownership — the authenticated user must own the beneficiary unless the caller holds a privileged role.
- [List beneficiaries for the current user](https://docs.pcxpay.com/api-reference/beneficiaries/list-beneficiaries-for-the-current-user.md): Returns a paginated list of beneficiaries belonging to the authenticated user. The authenticated user's identity is resolved from credentials; optionally pass `user_id` as a query parameter to scope the list.
- [Update a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/update-a-beneficiary.md): Updates mutable fields on an existing beneficiary. Only fields present in the request body are changed (partial update). Extra fields not in the schema are rejected with a 400.
- [Beneficiary Service](https://docs.pcxpay.com/api-reference/beneficiary/introduction.md): Create and manage the payment recipients for PCX transactions.
- [Payment distribution by beneficiary (admin)](https://docs.pcxpay.com/api-reference/distributions/payment-distribution-by-beneficiary-admin.md): Breakdown of payment volume across beneficiaries for a user. Requires `internal-admin`.
- [Add a manual exchange rate](https://docs.pcxpay.com/api-reference/exchange-rates/add-a-manual-exchange-rate.md): Requires role `internal-admin`. Minimum required fields validated in resources layer. Full body passed to usecase — additional fields may be accepted but are not statically defined here.
- [Add an active rate with configuration](https://docs.pcxpay.com/api-reference/exchange-rates/add-an-active-rate-with-configuration.md): No auth enforced at resource level.
- [Deactivate a rate](https://docs.pcxpay.com/api-reference/exchange-rates/deactivate-a-rate.md): Requires role `internal-admin`. No request body.
- [Delete a rate](https://docs.pcxpay.com/api-reference/exchange-rates/delete-a-rate.md): Requires role `internal-admin`. No request body.
- [Get active rates for an organization](https://docs.pcxpay.com/api-reference/exchange-rates/get-active-rates-for-an-organization.md): Requires role `internal-admin`.
- [Get all rates for an organization](https://docs.pcxpay.com/api-reference/exchange-rates/get-all-rates-for-an-organization.md): Requires role `internal-admin`.
- [Get exchange rate for an org and currency pair](https://docs.pcxpay.com/api-reference/exchange-rates/get-exchange-rate-for-an-org-and-currency-pair.md): Requires role `internal-admin` or `org-admin`.
- [Link external account](https://docs.pcxpay.com/api-reference/external-accounts/link-external-account.md): Links an external bank account to a customer via the Bridge provider. Supports multi-currency account fields including IBAN/BIC for SEPA and sort code/routing number for domestic rails.
- [List linked external accounts](https://docs.pcxpay.com/api-reference/external-accounts/list-linked-external-accounts.md): Returns all external accounts linked to a customer.
- [Unlink external account](https://docs.pcxpay.com/api-reference/external-accounts/unlink-external-account.md): Removes a linked external account from a customer.
- [Create fee configuration](https://docs.pcxpay.com/api-reference/fee-configurations/create-fee-configuration.md): Creates a fee configuration for a specific currency and transaction type. Requires `internal-admin` role.
- [Delete fee configuration](https://docs.pcxpay.com/api-reference/fee-configurations/delete-fee-configuration.md): Deletes a fee configuration. Requires `internal-admin` role.
- [Get fee configuration](https://docs.pcxpay.com/api-reference/fee-configurations/get-fee-configuration.md): Returns a single fee configuration by its ID.
- [List fee configurations](https://docs.pcxpay.com/api-reference/fee-configurations/list-fee-configurations.md): Returns all configured fee structures.
- [Preview transaction fee](https://docs.pcxpay.com/api-reference/fee-configurations/preview-transaction-fee.md): Calculates and returns the estimated fee for a transaction before it is executed. Useful for showing users the cost breakdown upfront.
- [Update fee configuration](https://docs.pcxpay.com/api-reference/fee-configurations/update-fee-configuration.md): Updates an existing fee configuration. Requires `internal-admin` role.
- [Deposit funds (admin)](https://docs.pcxpay.com/api-reference/fund-operations/deposit-funds-admin.md): Credits funds to a virtual account. Requires `internal-admin` role. For NGN accounts, deposits are processed via SquadCo.
- [Fund account via crypto](https://docs.pcxpay.com/api-reference/fund-operations/fund-account-via-crypto.md): Initiates a crypto-rail deposit to a virtual account via the Bridge provider. Specify the `payment_rail` and `currency` (e.g. `ethereum`, `usdc`).
- [NGN account lookup (Sarepay)](https://docs.pcxpay.com/api-reference/fund-operations/ngn-account-lookup-sarepay.md): Looks up a Nigerian bank account via Sarepay and returns the verified account name. Requires `internal-admin` role.
- [Transfer between accounts](https://docs.pcxpay.com/api-reference/fund-operations/transfer-between-accounts.md): Transfers funds between two virtual accounts within the platform.
- [Withdraw funds](https://docs.pcxpay.com/api-reference/fund-operations/withdraw-funds.md): Initiates a fiat withdrawal from a virtual account to an external account or bank. NGN withdrawals require admin approval before processing. Requires `internal-admin` or `org-admin` role.
- [Withdraw funds to crypto](https://docs.pcxpay.com/api-reference/fund-operations/withdraw-funds-to-crypto.md): Initiates a crypto-rail withdrawal from a virtual account to an on-chain address via the Bridge provider.
- [Delete an invite](https://docs.pcxpay.com/api-reference/invites/delete-an-invite.md): Requires role `internal-admin`.
- [Generate an invite](https://docs.pcxpay.com/api-reference/invites/generate-an-invite.md): Requires role `internal-admin` or `org-admin`.
- [Get invite by ID](https://docs.pcxpay.com/api-reference/invites/get-invite-by-id.md): Requires role `internal-admin`.
- [List invites for an organization](https://docs.pcxpay.com/api-reference/invites/list-invites-for-an-organization.md): Requires role `internal-admin` or `org-admin`.
- [Revoke an invite](https://docs.pcxpay.com/api-reference/invites/revoke-an-invite.md): Requires role `internal-admin`.
- [Verify an invite](https://docs.pcxpay.com/api-reference/invites/verify-an-invite.md): No auth required.
- [Create a KYB record](https://docs.pcxpay.com/api-reference/kyb/create-a-kyb-record.md): Requires role `internal-admin` or `org-admin`.
- [Get Identomat session result](https://docs.pcxpay.com/api-reference/kyb/get-identomat-session-result.md): Requires role `internal-admin` or `org-admin`.
- [Get KYB record by ID](https://docs.pcxpay.com/api-reference/kyb/get-kyb-record-by-id.md)
- [Initiate an Identomat KYB session](https://docs.pcxpay.com/api-reference/kyb/initiate-an-identomat-kyb-session.md): Requires role `internal-admin` or `org-admin`.
- [Initiate Bridge KYB for an organization](https://docs.pcxpay.com/api-reference/kyb/initiate-bridge-kyb-for-an-organization.md): Requires role `internal-admin` or `org-admin`. Delegates to virtual-accounts-service.
- [List KYB records](https://docs.pcxpay.com/api-reference/kyb/list-kyb-records.md): Requires role `internal-admin`.
- [Update KYB status](https://docs.pcxpay.com/api-reference/kyb/update-kyb-status.md): Requires role `internal-admin`.
- [Initiate Bridge KYC](https://docs.pcxpay.com/api-reference/kyc/initiate-bridge-kyc.md): Creates a Bridge customer for the user via the virtual-accounts service and stores the returned `bridge_customer_id` on the user record. Returns the Bridge terms-of-service link for the user to accept.
- [Update KYC status](https://docs.pcxpay.com/api-reference/kyc/update-kyc-status.md): Sets the KYC session ID and KYC status on the user record. Called by internal systems after a KYC verification session completes.
- [Get log metrics](https://docs.pcxpay.com/api-reference/logs/get-log-metrics.md): Aggregated metrics over account activity logs. Filter by org or account.
- [List account logs (admin)](https://docs.pcxpay.com/api-reference/logs/list-account-logs-admin.md): Paginated activity logs for virtual accounts. Filter by org, account, date range, and event type. Requires `internal-admin` role.
- [Send KYC notification](https://docs.pcxpay.com/api-reference/notifications/send-kyc-notification.md): Triggers a KYC-related notification (email, SMS, push) to a user. Fetches the user's current KYC status and dispatches the notification via the notifications Lambda.
- [Send verification data request notification](https://docs.pcxpay.com/api-reference/notifications/send-verification-data-request-notification.md): Notifies a beneficiary, sender, or both that a BVN or NIN is required for a pending transaction. Creates a `VerificationRequest` tracking record for each notified party. Returns HTTP 207 (Multi-Status) when `target_type` is `both` and at least one notification fails.
- [Initiate KYC](https://docs.pcxpay.com/api-reference/onboarding/initiate-kyc.md): Initiates the KYC process for a customer by email and customer type. Returns a `customer_id` and a link to the terms-of-service acceptance flow.
- [Onboard a customer](https://docs.pcxpay.com/api-reference/onboarding/onboard-a-customer.md): Creates a new virtual-account customer, provisioning internal accounts and optionally setting an initial balance. Requires `internal-admin` role.
- [Add a member to an organization](https://docs.pcxpay.com/api-reference/org-members/add-a-member-to-an-organization.md)
- [Disable a member](https://docs.pcxpay.com/api-reference/org-members/disable-a-member.md): Requires role `internal-admin` or `org-admin`.
- [Get a specific org member](https://docs.pcxpay.com/api-reference/org-members/get-a-specific-org-member.md): Requires role `internal-admin` or `org-admin`.
- [List members of an organization](https://docs.pcxpay.com/api-reference/org-members/list-members-of-an-organization.md): Requires role `internal-admin` or `org-admin`.
- [Remove a member from an organization](https://docs.pcxpay.com/api-reference/org-members/remove-a-member-from-an-organization.md): Requires role `internal-admin` or `org-admin`.
- [Update a member's role](https://docs.pcxpay.com/api-reference/org-members/update-a-members-role.md): Requires role `internal-admin` or `org-admin`.
- [Create org payment config (admin)](https://docs.pcxpay.com/api-reference/org-payment-configs/create-org-payment-config-admin.md): Creates a new payment configuration for an organisation. Requires `internal-admin`.
- [Delete org payment config (admin)](https://docs.pcxpay.com/api-reference/org-payment-configs/delete-org-payment-config-admin.md)
- [Get org payment config (admin)](https://docs.pcxpay.com/api-reference/org-payment-configs/get-org-payment-config-admin.md)
- [List org payment configs (admin)](https://docs.pcxpay.com/api-reference/org-payment-configs/list-org-payment-configs-admin.md): Returns all org-level payment configurations. Requires `internal-admin`.
- [Update org payment config (admin)](https://docs.pcxpay.com/api-reference/org-payment-configs/update-org-payment-config-admin.md)
- [Create an organization](https://docs.pcxpay.com/api-reference/organizations/create-an-organization.md)
- [Filter organizations](https://docs.pcxpay.com/api-reference/organizations/filter-organizations.md)
- [Get organization by ID](https://docs.pcxpay.com/api-reference/organizations/get-organization-by-id.md): Requires role `internal-admin`, `org-admin`, `user`, or `staff`.
- [Get organization by name](https://docs.pcxpay.com/api-reference/organizations/get-organization-by-name.md)
- [Get organizations grouped by country](https://docs.pcxpay.com/api-reference/organizations/get-organizations-grouped-by-country.md)
- [Organizations](https://docs.pcxpay.com/api-reference/organizations/introduction.md): Manage organizations, members, KYB, invites, and permissions
- [List payment links for an organization](https://docs.pcxpay.com/api-reference/organizations/list-payment-links-for-an-organization.md): Returns all payment links created under the specified organization, along with a total count. Requires `internal-admin` or `org-admin` role.
- [Send OTP to email](https://docs.pcxpay.com/api-reference/otp/send-otp-to-email.md): Sends a one-time password to the specified email address. The OTP is used to gate access to a payment link. No authentication required.
- [Verify OTP and obtain access token](https://docs.pcxpay.com/api-reference/otp/verify-otp-and-obtain-access-token.md): Verifies the OTP sent to the customer's email and, on success, returns a short-lived JWT (`type: "payment_link"`, 24 h expiry) that can be used to access OTP-gated payment links. No authentication required.
- [API Reference Overview](https://docs.pcxpay.com/api-reference/overview.md): PCX service API surface area
- [Payment Link Service](https://docs.pcxpay.com/api-reference/payment-link/introduction.md): Generate and manage one-time payment links for customer checkout flows
- [Create a payment link](https://docs.pcxpay.com/api-reference/payment-links/create-a-payment-link.md): Generates a new payment link for the specified recipient. The link is tied to an organization and optionally to a transaction ID and payment amount. Requires `internal-admin` or `org-admin` role.
- [Get a payment link](https://docs.pcxpay.com/api-reference/payment-links/get-a-payment-link.md): Retrieves and verifies a payment link by its ID. No authentication required — used by customer-facing checkout flows.
- [Revoke payment link(s)](https://docs.pcxpay.com/api-reference/payment-links/revoke-payment-links.md): Revokes one or more payment links. At least one of `link_id` (body) or `email` must be provided. If `email` is given, all active links for that email address are revoked. Requires `internal-admin` or `org-admin` role.
- [Verify a payment link](https://docs.pcxpay.com/api-reference/payment-links/verify-a-payment-link.md): Checks whether a payment link is valid and has not expired or been revoked. No authentication required — intended for use by customer-facing checkout pages.
- [Payment Service](https://docs.pcxpay.com/api-reference/payment/introduction.md): Payment lifecycle management, bank account validation, and payment provider configuration.
- [Create a payment](https://docs.pcxpay.com/api-reference/payments/create-a-payment.md): Initiates a new payment. Internally the service calls the Transaction Lambda synchronously to obtain a `transaction_id` before persisting the payment record.
- [Get a payment](https://docs.pcxpay.com/api-reference/payments/get-a-payment.md)
- [Get payment by provider payment ID](https://docs.pcxpay.com/api-reference/payments/get-payment-by-provider-payment-id.md)
- [Get payment by transaction ID](https://docs.pcxpay.com/api-reference/payments/get-payment-by-transaction-id.md)
- [List all org payments (admin)](https://docs.pcxpay.com/api-reference/payments/list-all-org-payments-admin.md)
- [List all payments (admin)](https://docs.pcxpay.com/api-reference/payments/list-all-payments-admin.md): Returns all payments across all users. Requires `internal-admin`.
- [List my payments](https://docs.pcxpay.com/api-reference/payments/list-my-payments.md): Returns a paginated list of payments for the authenticated user.
- [List org payments by entity type](https://docs.pcxpay.com/api-reference/payments/list-org-payments-by-entity-type.md)
- [List org payments by status](https://docs.pcxpay.com/api-reference/payments/list-org-payments-by-status.md)
- [List payments by organisation (admin)](https://docs.pcxpay.com/api-reference/payments/list-payments-by-organisation-admin.md): Returns payments belonging to a specific organisation. Requires `internal-admin`.
- [List payments by status (admin)](https://docs.pcxpay.com/api-reference/payments/list-payments-by-status-admin.md): Returns all payments with the given status. Requires `internal-admin`.
- [Update a payment (admin)](https://docs.pcxpay.com/api-reference/payments/update-a-payment-admin.md): Update mutable fields on a payment record. Requires `internal-admin`.
- [Webhook status update](https://docs.pcxpay.com/api-reference/payments/webhook-status-update.md): Internal endpoint used by provider webhooks to update payment status. Called by the webhook handler Lambda, not directly by end clients.
- [Check if a user has a specific permission](https://docs.pcxpay.com/api-reference/permissions/check-if-a-user-has-a-specific-permission.md): No auth — used internally by other services.
- [Get member permissions](https://docs.pcxpay.com/api-reference/permissions/get-member-permissions.md): Requires role `org-admin` or `staff`.
- [Grant a permission to a member](https://docs.pcxpay.com/api-reference/permissions/grant-a-permission-to-a-member.md): Requires role `org-admin`.
- [Revoke a member permission](https://docs.pcxpay.com/api-reference/permissions/revoke-a-member-permission.md): Requires role `org-admin`.
- [Update a member permission](https://docs.pcxpay.com/api-reference/permissions/update-a-member-permission.md): Requires role `org-admin`.
- [Create provider config (admin)](https://docs.pcxpay.com/api-reference/provider-configs/create-provider-config-admin.md): Creates a new payment provider routing rule. Requires `internal-admin`.
- [Delete provider config by config ID (admin)](https://docs.pcxpay.com/api-reference/provider-configs/delete-provider-config-by-config-id-admin.md)
- [Delete provider config by provider + config ID (admin)](https://docs.pcxpay.com/api-reference/provider-configs/delete-provider-config-by-provider-+-config-id-admin.md)
- [Get provider config by config ID (admin)](https://docs.pcxpay.com/api-reference/provider-configs/get-provider-config-by-config-id-admin.md)
- [Get provider config by provider + config ID (admin)](https://docs.pcxpay.com/api-reference/provider-configs/get-provider-config-by-provider-+-config-id-admin.md)
- [List provider configs (admin)](https://docs.pcxpay.com/api-reference/provider-configs/list-provider-configs-admin.md): Returns all provider routing configurations. Requires `internal-admin`.
- [Update provider config by config ID (admin)](https://docs.pcxpay.com/api-reference/provider-configs/update-provider-config-by-config-id-admin.md)
- [Update provider config by provider + config ID (admin)](https://docs.pcxpay.com/api-reference/provider-configs/update-provider-config-by-provider-+-config-id-admin.md)
- [Public API](https://docs.pcxpay.com/api-reference/public/introduction.md): The PCX externally-facing API. Authenticate with an API key to manage keys, register webhooks, and receive transaction notifications.
- [Add a rate config](https://docs.pcxpay.com/api-reference/rate-configs/add-a-rate-config.md): Requires role `internal-admin`. Body is passed as-is to the usecase — required fields not validated at controller level. Refer to OrganizationConfig entity for expected shape.
- [Get active configs (alternate endpoint)](https://docs.pcxpay.com/api-reference/rate-configs/get-active-configs-alternate-endpoint.md): No auth enforced at resource level. Requires org_id in request body — unusual pattern for a GET endpoint.
- [Get active rate configs for an organization](https://docs.pcxpay.com/api-reference/rate-configs/get-active-rate-configs-for-an-organization.md): No auth enforced at resource level.
- [Get rate configs for an organization](https://docs.pcxpay.com/api-reference/rate-configs/get-rate-configs-for-an-organization.md): Requires role `internal-admin`.
- [Update a rate config for an organization](https://docs.pcxpay.com/api-reference/rate-configs/update-a-rate-config-for-an-organization.md): Requires role `internal-admin`. Body passed as-is to usecase — updatable fields not statically validated at controller level.
- [Register a new user](https://docs.pcxpay.com/api-reference/registration/register-a-new-user.md): Registers a user in Cognito and creates their profile. If `org_name` is provided without `org_id`, a new organization is created automatically. If `org_id` is provided, the user is added as an org member.
- [Generate a pre-signed S3 upload URL](https://docs.pcxpay.com/api-reference/s3/generate-a-pre-signed-s3-upload-url.md): Requires role `internal-admin` or `org-admin`.
- [Generate a pre-signed S3 view URL](https://docs.pcxpay.com/api-reference/s3/generate-a-pre-signed-s3-view-url.md): Requires role `internal-admin` or `org-admin`.
- [Trigger scheduled payment link emails](https://docs.pcxpay.com/api-reference/scheduled/trigger-scheduled-payment-link-emails.md): Internal endpoint used by a scheduled job to find all payment links due within a given window and send reminder emails. Provide the target date (`scheduled_at`) and a look-ahead `period` in hours. No authentication required (internal trigger).
- [Create SquadCo virtual account](https://docs.pcxpay.com/api-reference/squadco-admin/create-squadco-virtual-account.md): Provisions a new NGN virtual account via SquadCo for an existing customer. Requires `internal-admin` role.
- [Get SquadCo account detail](https://docs.pcxpay.com/api-reference/squadco-admin/get-squadco-account-detail.md): Returns detail for a specific SquadCo-backed NGN account.
- [Get SquadCo wallet balance](https://docs.pcxpay.com/api-reference/squadco-admin/get-squadco-wallet-balance.md): Returns the current NGN wallet balance held in the SquadCo provider account. Requires `internal-admin` role.
- [List pending NGN withdrawals](https://docs.pcxpay.com/api-reference/squadco-admin/list-pending-ngn-withdrawals.md): Lists all SquadCo NGN withdrawals awaiting admin approval. Requires `internal-admin` role.
- [List SquadCo transactions](https://docs.pcxpay.com/api-reference/squadco-admin/list-squadco-transactions.md): Paginated list of NGN transactions processed through SquadCo. Requires `internal-admin` role.
- [List SquadCo virtual accounts](https://docs.pcxpay.com/api-reference/squadco-admin/list-squadco-virtual-accounts.md): Lists all NGN SquadCo virtual accounts provisioned on the platform. Requires `internal-admin` role.
- [Process NGN withdrawal](https://docs.pcxpay.com/api-reference/squadco-admin/process-ngn-withdrawal.md): Manually processes an approved SquadCo NGN withdrawal. Initiates the actual bank transfer via Sarepay. Requires `internal-admin` role.
- [Transaction Service](https://docs.pcxpay.com/api-reference/transaction/introduction.md): Financial ledger for every payment, loan, and payout on the PCX platform, with deep analytics.
- [Filter transactions](https://docs.pcxpay.com/api-reference/transactions/filter-transactions.md): Returns transactions matching the supplied criteria. Supports multi-dimensional filtering across country, currency, payment method, status, user, org, and date range.
- [Get a transaction](https://docs.pcxpay.com/api-reference/transactions/get-a-transaction.md)
- [Get recent transactions (admin)](https://docs.pcxpay.com/api-reference/transactions/get-recent-transactions-admin.md): Returns the 10 most recent transactions for a user. Requires `internal-admin`.
- [Get Sarepay transaction status](https://docs.pcxpay.com/api-reference/transactions/get-sarepay-transaction-status.md): Checks the status of an NGN transaction through Sarepay using either `transaction_id` or `reference`. The acting user is identified from the JWT claims in the `Authorization` header.
- [Get transaction by ID](https://docs.pcxpay.com/api-reference/transactions/get-transaction-by-id.md): Returns a single virtual account transaction. The user identity is resolved from the authentication credentials.
- [Get transaction by payment ID](https://docs.pcxpay.com/api-reference/transactions/get-transaction-by-payment-id.md)
- [List all transactions (admin)](https://docs.pcxpay.com/api-reference/transactions/list-all-transactions-admin.md): Returns all transactions across all users with optional filters. Requires `internal-admin`.
- [List my transactions](https://docs.pcxpay.com/api-reference/transactions/list-my-transactions.md): Returns a paginated list of transactions for the authenticated user.
- [List org loans / payouts (admin, org-admin)](https://docs.pcxpay.com/api-reference/transactions/list-org-loans-payouts-admin-org-admin.md): Returns loan and payout transactions for an organisation. Supports optional metrics aggregation via `includeMetrics=true`. Requires `internal-admin` or `org-admin`.
- [List transactions for an account](https://docs.pcxpay.com/api-reference/transactions/list-transactions-for-an-account.md): Paginated list of transactions for a specific virtual account. Filter by `type` and `status`, and narrow by date range. The acting user is identified from the JWT claims in the `Authorization` header.
- [Update a transaction (admin)](https://docs.pcxpay.com/api-reference/transactions/update-a-transaction-admin.md): Update mutable fields on a transaction. Requires `internal-admin`.
- [Admin status change](https://docs.pcxpay.com/api-reference/users/admin-status-change.md): Sets the user to any allowed status. Requires `internal-admin` role. This endpoint supersedes the original activate-only behaviour — it now accepts any target status.
- [Create a user (internal)](https://docs.pcxpay.com/api-reference/users/create-a-user-internal.md): Directly creates a user record without Cognito registration. Used for internal/programmatic user creation where Cognito signup has already occurred separately.
- [Deactivate user](https://docs.pcxpay.com/api-reference/users/deactivate-user.md): Sets the user's status to `rejected`. Requires `internal-admin` role.
- [Delete user](https://docs.pcxpay.com/api-reference/users/delete-user.md): Deletes the user record. Requires authentication.
- [Get user by email or Cognito username](https://docs.pcxpay.com/api-reference/users/get-user-by-email-or-cognito-username.md): Looks up a user by `email` or `cognito_username` query parameter. Exactly one parameter must be provided.
- [Get user by ID](https://docs.pcxpay.com/api-reference/users/get-user-by-id.md)
- [User Service](https://docs.pcxpay.com/api-reference/users/introduction.md): Registration, identity verification, profile management, and user analytics.
- [List users](https://docs.pcxpay.com/api-reference/users/list-users.md): Returns a paginated list of users with optional filters. Requires `internal-admin` role.
- [Update user profile](https://docs.pcxpay.com/api-reference/users/update-user-profile.md): Updates mutable profile fields. Requires authentication.
- [Update user status](https://docs.pcxpay.com/api-reference/users/update-user-status.md): Updates the user's account status. Valid transitions: `active`, `pending_verification`, `rejected`, `not_verified`.
- [Get verification request status](https://docs.pcxpay.com/api-reference/verification-requests/get-verification-request-status.md)
- [List verification requests](https://docs.pcxpay.com/api-reference/verification-requests/list-verification-requests.md): Returns verification requests filtered by `user_id`, `beneficiary_id`, or `transaction_id`. If none are provided, lists all requests with optional status filtering and DynamoDB cursor pagination.
- [Submit verification data](https://docs.pcxpay.com/api-reference/verification-requests/submit-verification-data.md): Submits the actual BVN or NIN value for a pending verification request. The request must be in `pending` status.
- [Virtual Accounts](https://docs.pcxpay.com/api-reference/virtual-accounts/introduction.md): Manage multi-currency virtual accounts, fund operations, fee configurations, and the full admin layer for the PCX virtual-accounts service.
- [Bridge KYC webhook](https://docs.pcxpay.com/api-reference/webhooks/bridge-kyc-webhook.md): Receives Bridge `customer.updated.status_transitioned` events and updates the user's Bridge KYC status accordingly.
- [KYC provider callback](https://docs.pcxpay.com/api-reference/webhooks/kyc-provider-callback.md): Receives callback events from the KYC provider (Veriff or equivalent). Looks up the user by `vendorData` (email), updates their KYC and account status based on the verification result, and fires an async log event.
- [Notify transaction update](https://docs.pcxpay.com/api-reference/webhooks/notify-transaction-update.md): Dispatches a transaction update notification to all registered webhook endpoints for the specified organisation. Use this to push real-time transaction status changes (e.g. from `pending` to `completed`) to subscriber systems.
- [Register webhook](https://docs.pcxpay.com/api-reference/webhooks/register-webhook.md): Registers a webhook endpoint URL for the authenticated organisation. PCX will POST transaction update events to this URL as they occur. The organisation identity is derived from the API key — no explicit `org_id` is needed in the request body.
- [Authentication](https://docs.pcxpay.com/authentication.md): How to authenticate with the PCX API using API keys or Cognito JWTs
- [Changelog](https://docs.pcxpay.com/changelog/index.md): API and platform changes
- [Organizations](https://docs.pcxpay.com/concepts/organizations.md): How organizations work in PCX
- [Payments](https://docs.pcxpay.com/concepts/payments.md): How payments work in PCX
- [Virtual Accounts](https://docs.pcxpay.com/concepts/virtual-accounts.md): Multi-currency virtual accounts for organizations and users
- [Webhooks](https://docs.pcxpay.com/concepts/webhooks.md): Receive real-time events from PCX
- [Introduction](https://docs.pcxpay.com/introduction.md): PCX cross-border payment infrastructure for developers
- [Quickstart](https://docs.pcxpay.com/quickstart.md): Create an organization and make your first API call

## OpenAPI Specs

- [openapi](https://docs.pcxpay.com/api-reference/virtual-accounts/openapi.yaml)