# PCX Developer Docs - [Introduction](https://docs.pcxpay.com/introduction.md): PCX cross-border payment infrastructure — internal developer reference - [Quickstart](https://docs.pcxpay.com/quickstart.md): Create an organization and make your first API call - [Authentication](https://docs.pcxpay.com/guides/essentials/authentication.md): How to authenticate with the PCX API using an API key - [Errors](https://docs.pcxpay.com/guides/essentials/errors.md): Standard error responses, HTTP status codes, decimal handling, and idempotency across all PCX services - [Pagination](https://docs.pcxpay.com/guides/essentials/pagination.md): Cursor-based pagination across all PCX services - [Webhooks](https://docs.pcxpay.com/guides/essentials/webhooks.md): Receive real-time payment and platform events at your HTTPS endpoint - [iFrame Integration](https://docs.pcxpay.com/guides/iframe/overview.md): Embed a PCX-hosted payment UI into your platform using a redirect URL — no custom payment UI required - [Payment Initiation](https://docs.pcxpay.com/guides/iframe/session-initialisation.md): Initiate a payment on your platform and receive the iFrame redirect URL from PCX - [Embedding](https://docs.pcxpay.com/guides/iframe/embedding.md): Render the PCX-hosted payment form inside your page using a standard HTML iFrame - [Payment Confirmation](https://docs.pcxpay.com/guides/iframe/redirect-handling.md): How PCX confirms payment completion and how to verify the result on your server - [Host to Host (H2H)](https://docs.pcxpay.com/guides/h2h/overview.md): Direct payment link integration for bank transfer payments via PCX - [Initiating a Payment](https://docs.pcxpay.com/guides/h2h/initiating-a-payment.md): How to create and share a payment link via the PCX API - [Payment Status and Webhooks](https://docs.pcxpay.com/guides/h2h/payment-status.md): How to track payment status and receive real-time notifications - [Error Handling](https://docs.pcxpay.com/guides/h2h/error-handling.md): Common errors and how to handle them - [Payouts Overview](https://docs.pcxpay.com/guides/payouts/overview.md): Disburse funds to bank accounts, mobile money wallets, and crypto addresses across Africa and beyond - [Beneficiary Validation](https://docs.pcxpay.com/guides/payouts/beneficiary-validation.md): Validate bank account details and resolve account holder names before initiating a payout - [Bank Payouts](https://docs.pcxpay.com/guides/payouts/bank-payouts.md): Disburse funds to bank accounts and mobile money wallets across supported corridors - [Crypto Payouts](https://docs.pcxpay.com/guides/payouts/crypto-payouts.md): Withdraw stablecoins from virtual accounts or settle fiat to a beneficiary via off-ramp - [Exchange Rates and Fees](https://docs.pcxpay.com/guides/settlement/exchange-rates-and-fees.md): How PCX manages exchange rates, rate locking, spread configs, and fee handling for cross-border payments - [PCX API Reference](https://docs.pcxpay.com/api-reference/external/introduction.md): Integration guide for direct API access - [Initiate a payment](https://docs.pcxpay.com/api-reference/payment-initiation/initiate-a-payment.md): Initiate a payin or payout. `org_id` and `user_id` are injected automatically from the authenticated API key, so you do not need to include them in the request body. Same-currency and cross-currency flows are both supported — for cross-currency flows, lock a rate first and pass its `org_rate_id`. - [Submit a payment action](https://docs.pcxpay.com/api-reference/payment-initiation/submit-a-payment-action.md): Continue a pending payment that is awaiting a customer action — for example when the initiation response returned `next_action: collect_otp`. Supported actions are `submit_otp`, `verify`, and `cancel`. The payment must be in `pending` status. - [Browser callback after hosted checkout](https://docs.pcxpay.com/api-reference/payment-initiation/browser-callback-after-hosted-checkout.md): Browser redirect endpoint that payment providers send the customer to after hosted checkout finishes. You do not call this endpoint yourself — PCX registers it with the provider during redirect checkout flows (`next_action: redirect`). It requires no authentication. - [Initiate a crypto ramp](https://docs.pcxpay.com/api-reference/payment-initiation/initiate-a-crypto-ramp.md): Initiate an on-ramp (fiat → crypto) or off-ramp (crypto → fiat) conversion. PCX acts as the orchestrator — your users send or receive fiat, and PCX handles the crypto settlement automatically. - [List available payment networks](https://docs.pcxpay.com/api-reference/payment-initiation/list-available-payment-networks.md): Returns the available payment networks (banks and mobile money operators) for a given country. The upstream provider is selected automatically based on the country code. - [Initiate a payment (deprecated)](https://docs.pcxpay.com/api-reference/payment-initiation/initiate-a-payment-deprecated.md): **Deprecated.** This endpoint has been consolidated into `POST /payments-init/initiate`, which accepts the same API-key authentication and also supports cross-currency flows. Use `/payments-init/initiate` instead. - [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. - [Create API key](https://docs.pcxpay.com/api-reference/api-keys/create-api-key.md): Creates a new API key. The full key value is returned once at creation and cannot be retrieved again — store it securely. - [Validate API key](https://docs.pcxpay.com/api-reference/api-keys/validate-api-key.md): Checks whether a given API key is valid and active. Returns the associated `user_id`, `org_id`, and key status. No authentication is required on this endpoint — pass `NONE` for both headers. - [Delete API key](https://docs.pcxpay.com/api-reference/api-keys/delete-api-key.md): Permanently deletes an API key. Any integration using this key will immediately lose access. - [Revoke API key](https://docs.pcxpay.com/api-reference/api-keys/revoke-api-key.md): Disables an API key without deleting it. The key is preserved for audit purposes but rejected on all subsequent requests. - [Register webhook](https://docs.pcxpay.com/api-reference/webhooks/register-webhook.md): Registers an HTTPS endpoint to receive event notifications. PCX will POST events to this URL as they occur. The organisation identity is derived from your API key. The response includes the `secret_key` used to sign every delivery — it is returned only once, so store it securely. - [Get webhook configuration](https://docs.pcxpay.com/api-reference/webhooks/get-webhook-configuration.md): Returns your organisation's current webhook configuration — the endpoint URL and the list of subscribed event types. The signing secret is not returned; it is only shown once at registration. - [Update event subscriptions](https://docs.pcxpay.com/api-reference/webhooks/update-event-subscriptions.md): Replaces the list of event types your webhook is subscribed to. Send an empty array (or omit `events`) to subscribe to all event types. Use `GET /public/webhooks/events/catalogue` for the list of valid types. - [List subscribable event types](https://docs.pcxpay.com/api-reference/webhooks/list-subscribable-event-types.md): Returns every event type you can subscribe a webhook to. - [Send test event](https://docs.pcxpay.com/api-reference/webhooks/send-test-event.md): Fires a synthetic event at your registered endpoint so you can verify signature validation and processing end to end. The test delivery is signed with your real webhook secret. - [Notify transaction update](https://docs.pcxpay.com/api-reference/webhooks/notify-transaction-update.md): Manually dispatches a transaction update notification to all registered webhook endpoints for the specified organisation. - [Create a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/create-a-beneficiary.md): Creates a new payment beneficiary. The `beneficiary_of` field is resolved automatically from the authenticated user's credentials. For loan-client beneficiaries on behalf of an organisation, pass `org_id` in the body. - [List beneficiaries](https://docs.pcxpay.com/api-reference/beneficiaries/list-beneficiaries.md): Returns a paginated list of beneficiaries for the authenticated user. - [Get a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/get-a-beneficiary.md) - [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. `account_type` and `beneficiary_of` cannot be changed after creation. - [Delete a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/delete-a-beneficiary.md) - [List my payments](https://docs.pcxpay.com/api-reference/payments/list-my-payments.md): Returns a paginated list of payments for the authenticated user. - [Create a payment](https://docs.pcxpay.com/api-reference/payments/create-a-payment.md): Initiates a new payment. - [Get a payment](https://docs.pcxpay.com/api-reference/payments/get-a-payment.md) - [Update a payment](https://docs.pcxpay.com/api-reference/payments/update-a-payment.md) - [Get payments by transaction ID](https://docs.pcxpay.com/api-reference/payments/get-payments-by-transaction-id.md): Returns all payments associated with a given transaction ID. - [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. - [List supported Nigerian banks](https://docs.pcxpay.com/api-reference/bank-validation/list-supported-nigerian-banks.md): Returns the list of Nigerian banks with their bank codes. - [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. - [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. - [Verify UK account holder name](https://docs.pcxpay.com/api-reference/bank-validation/verify-uk-account-holder-name.md): Verifies a name matches the account holder on record via TrueLayer. Requires an `accessToken` from 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. - [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 for identity verification. - [Exchange TrueLayer auth code](https://docs.pcxpay.com/api-reference/bank-validation/exchange-truelayer-auth-code.md): Called after the TrueLayer OAuth redirect. Exchanges the authorization code for access and refresh tokens. Use the returned `access_token` for account holder verification. - [List my transactions](https://docs.pcxpay.com/api-reference/transactions/list-my-transactions.md): Returns a paginated list of transactions for the authenticated user. - [Get a transaction](https://docs.pcxpay.com/api-reference/transactions/get-a-transaction.md) - [Get transaction by payment ID](https://docs.pcxpay.com/api-reference/transactions/get-transaction-by-payment-id.md) - [Filter transactions](https://docs.pcxpay.com/api-reference/transactions/filter-transactions.md): Returns transactions matching the supplied criteria. - [Submit customer KYC](https://docs.pcxpay.com/api-reference/virtual-accounts/submit-customer-kyc.md): First step of customer onboarding. Provide the customer's email and type to receive a `customer_id` and a Terms of Service link they must accept before their account is created. - [Onboard a customer](https://docs.pcxpay.com/api-reference/virtual-accounts/onboard-a-customer.md): Second step of customer onboarding. Submit the full customer profile once the customer has accepted the Terms of Service. - [Create fiat currency account](https://docs.pcxpay.com/api-reference/virtual-accounts/create-fiat-currency-account.md): Creates a fiat virtual account in any supported currency for an organisation. - [List accounts by organisation](https://docs.pcxpay.com/api-reference/virtual-accounts/list-accounts-by-organisation.md) - [List accounts by user](https://docs.pcxpay.com/api-reference/virtual-accounts/list-accounts-by-user.md) - [Withdraw funds](https://docs.pcxpay.com/api-reference/virtual-accounts/withdraw-funds.md): Initiates a withdrawal from a virtual account. NGN withdrawals are placed in `pending` status and require an admin approval step before the bank transfer fires. - [Internal transfer](https://docs.pcxpay.com/api-reference/virtual-accounts/internal-transfer.md): Moves funds between two virtual accounts on the platform. - [NGN bank account lookup](https://docs.pcxpay.com/api-reference/virtual-accounts/ngn-bank-account-lookup.md): Verifies a destination NGN bank account before initiating a withdrawal. Returns the verified `account_name` for user confirmation. - [Crypto deposit](https://docs.pcxpay.com/api-reference/virtual-accounts/crypto-deposit.md): Credits crypto funds to a virtual account. - [Crypto withdrawal](https://docs.pcxpay.com/api-reference/virtual-accounts/crypto-withdrawal.md): Withdraws crypto funds from a virtual account to an external wallet address. - [List account transactions](https://docs.pcxpay.com/api-reference/virtual-accounts/list-account-transactions.md) - [Get a VA transaction](https://docs.pcxpay.com/api-reference/virtual-accounts/get-a-va-transaction.md) - [Link external bank account](https://docs.pcxpay.com/api-reference/virtual-accounts/link-external-bank-account.md): Links an external bank account as a withdrawal destination. - [List linked external accounts](https://docs.pcxpay.com/api-reference/virtual-accounts/list-linked-external-accounts.md) - [Unlink external bank account](https://docs.pcxpay.com/api-reference/virtual-accounts/unlink-external-bank-account.md) - [Org account registry](https://docs.pcxpay.com/api-reference/virtual-accounts/org-account-registry.md): Full registry of all virtual accounts for the organisation, with balances and status. - [Org dashboard metrics](https://docs.pcxpay.com/api-reference/virtual-accounts/org-dashboard-metrics.md) - [List org VA transactions](https://docs.pcxpay.com/api-reference/virtual-accounts/list-org-va-transactions.md): Paginated list of all virtual account transactions across the organisation. - [Org transaction summary](https://docs.pcxpay.com/api-reference/virtual-accounts/org-transaction-summary.md): Aggregated transaction totals by status and currency for the organisation. - [Preview transaction fee](https://docs.pcxpay.com/api-reference/virtual-accounts/preview-transaction-fee.md): Calculates the fee for a specific transaction type before executing it. Useful for showing users their total cost in pre-confirmation UIs. - [List account activity logs](https://docs.pcxpay.com/api-reference/virtual-accounts/list-account-activity-logs.md): Immutable activity log. Filter by org, account, event type, and date range. - [List escrow projects](https://docs.pcxpay.com/api-reference/escrow/list-escrow-projects.md): Paginated list of escrow entities belonging to the caller's organisation. Requires the `escrow` feature to be enabled for the organisation. - [Create an escrow project](https://docs.pcxpay.com/api-reference/escrow/create-an-escrow-project.md): Creates a new escrow entity (project) for the caller's organisation, optionally with milestones and parties inline. Requires the `escrow` feature to be enabled for the organisation. - [Get an escrow project](https://docs.pcxpay.com/api-reference/escrow/get-an-escrow-project.md): Fetches the full escrow entity, including its milestones, parties, contracts, and payment links. Org-scoped — the escrow must belong to the caller's organisation. Requires the `escrow` feature. - [Update an escrow project](https://docs.pcxpay.com/api-reference/escrow/update-an-escrow-project.md): Updates the entity's metadata — `label`, `org_ref`, or `total_amount`. Requires `org-admin` OrgMember role and the `escrow` feature. - [Cancel an escrow project](https://docs.pcxpay.com/api-reference/escrow/cancel-an-escrow-project.md): Cancels the escrow entity. Only permitted while the escrow is unfunded — returns a conflict once funds have been deposited. Requires `org-admin` OrgMember role and the `escrow` feature. - [Add a milestone](https://docs.pcxpay.com/api-reference/escrow/add-a-milestone.md): Adds a milestone to an existing escrow project. Requires `org-admin` OrgMember role and the `escrow` feature. - [Update a milestone](https://docs.pcxpay.com/api-reference/escrow/update-a-milestone.md): Updates a milestone's `label` or `expected_disbursement`. Requires `org-admin` OrgMember role and the `escrow` feature. - [Register parties](https://docs.pcxpay.com/api-reference/escrow/register-parties.md): Registers one or more parties (contractor, agency commission, or expense) on an escrow project. A party's payout participation and split are assigned per milestone via the milestone-parties endpoint. The body also accepts a single party object or a bare array instead of the `parties` wrapper. Requir… - [Update parties](https://docs.pcxpay.com/api-reference/escrow/update-parties.md): Updates one or more registered parties at once — each item carries the `party_id` to change plus the fields to update. The body also accepts a single update object or a bare array instead of the `parties` wrapper. Requires `org-admin` OrgMember role and the `escrow` feature. - [Update a party](https://docs.pcxpay.com/api-reference/escrow/update-a-party.md): Updates a single registered party — the `party_id` comes from the URL and the body carries the fields to change. Requires `org-admin` OrgMember role and the `escrow` feature. - [Remove a party](https://docs.pcxpay.com/api-reference/escrow/remove-a-party.md): Removes a party from the escrow project. Requires `org-admin` OrgMember role and the `escrow` feature. - [Assign parties to a milestone](https://docs.pcxpay.com/api-reference/escrow/assign-parties-to-a-milestone.md): Assigns one or more registered parties to this milestone with a payout split. Each `party_id` must already be registered on the escrow project via `POST /virtual-accounts/escrow/{escrow_id}/parties`. The body also accepts a single assignment object or a bare array instead of the `parties` wrapper. R… - [Update milestone party splits](https://docs.pcxpay.com/api-reference/escrow/update-milestone-party-splits.md): Updates one or more party splits on this milestone at once. The body also accepts a single update object or a bare array instead of the `parties` wrapper. Requires `org-admin` OrgMember role and the `escrow` feature. - [Remove a party from a milestone](https://docs.pcxpay.com/api-reference/escrow/remove-a-party-from-a-milestone.md): Removes a party's assignment (participation and split) from this milestone. The party's entity-level identity is kept — use `DELETE /virtual-accounts/escrow/{escrow_id}/parties/{party_id}` to remove it from the project entirely. Requires `org-admin` OrgMember role and the `escrow` feature. - [Submit a contract confirmation](https://docs.pcxpay.com/api-reference/escrow/submit-a-contract-confirmation.md): Records a contract event for the milestone — exactly one action per call. Send `party_id` to record a contractor's completion confirmation (the contract record is created implicitly on the first event). Send `client_confirmed` to relay the client's final decision: `true` checks that every contractor… - [Get a milestone's contract](https://docs.pcxpay.com/api-reference/escrow/get-a-milestones-contract.md): Returns the current contract record for the milestone. Exactly one contract exists per milestone, created implicitly on the first confirmation event. Requires the `escrow` feature. - [Create an escrow payment link](https://docs.pcxpay.com/api-reference/escrow/create-an-escrow-payment-link.md): Mints a hosted payment link for the escrow project — e.g. an agency sends it to their client to deposit a milestone payment. Returns the `link_ref` (deposit-match key) and the hosted URL to share. Incoming deposits are matched to the escrow on `link_ref`. Requires the `escrow` feature. - [List escrow disbursements](https://docs.pcxpay.com/api-reference/escrow/list-escrow-disbursements.md): Returns the escrow's disbursement history — the transaction records of type `escrow_disbursement` (one per party payout), newest first. Requires the `escrow` feature. - [Create a payment link](https://docs.pcxpay.com/api-reference/payment-links/create-a-payment-link.md): Creates a new payment link. Requires the `org-admin` or `staff` role. - [Get a payment link](https://docs.pcxpay.com/api-reference/payment-links/get-a-payment-link.md) - [Revoke a payment link](https://docs.pcxpay.com/api-reference/payment-links/revoke-a-payment-link.md): Revokes a payment link. Optionally pass `email` in the body to revoke all active links for that recipient at once. - [Verify a payment link](https://docs.pcxpay.com/api-reference/payment-links/verify-a-payment-link.md): Checks whether a link is valid (not expired or revoked). No authentication required. - [List org payment links](https://docs.pcxpay.com/api-reference/payment-links/list-org-payment-links.md): Returns all payment links for an organisation. Requires `org-admin` or `staff`. - [Send OTP](https://docs.pcxpay.com/api-reference/payment-links/send-otp.md): Sends a one-time password to the customer's email. No authentication required. - [Verify OTP](https://docs.pcxpay.com/api-reference/payment-links/verify-otp.md): Verifies the OTP and returns a short-lived JWT (`type: payment_link`, 24-hour expiry) for accessing the protected payment link. - [Create a VA payment link](https://docs.pcxpay.com/api-reference/payment-links/create-a-va-payment-link.md): Creates a virtual account payment link for accepting deposits. - [Initiate VA payment](https://docs.pcxpay.com/api-reference/payment-links/initiate-va-payment.md): Payer provides their currency and amount. PCX returns a payment quote with the calculated exchange rate. - [Confirm VA payment](https://docs.pcxpay.com/api-reference/payment-links/confirm-va-payment.md): Payer confirms the payment. PCX processes the transfer into the virtual account. - [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. - [Create API key](https://docs.pcxpay.com/api-reference/api-keys/create-api-key.md): Creates a new API key. The full key value is returned once at creation and cannot be retrieved again — store it securely. - [Validate API key](https://docs.pcxpay.com/api-reference/api-keys/validate-api-key.md): Checks whether a given API key is valid and active. Returns the associated `user_id`, `org_id`, and key status. No authentication is required on this endpoint — pass `NONE` for both headers. - [Delete API key](https://docs.pcxpay.com/api-reference/api-keys/delete-api-key.md): Permanently deletes an API key. Any integration using this key will immediately lose access. - [Revoke API key](https://docs.pcxpay.com/api-reference/api-keys/revoke-api-key.md): Disables an API key without deleting it. The key is preserved for audit purposes but rejected on all subsequent requests. - [Get webhook configuration](https://docs.pcxpay.com/api-reference/webhooks/get-webhook-configuration.md): Returns your organisation's current webhook configuration — the endpoint URL and the list of subscribed event types. The signing secret is not returned; it is only shown once at registration. - [Register webhook](https://docs.pcxpay.com/api-reference/webhooks/register-webhook.md): Registers an HTTPS endpoint to receive event notifications. PCX will POST events to this URL as they occur. The organisation identity is derived from your API key. The response includes the `secret_key` used to sign every delivery — it is returned only once, so store it securely. - [Update event subscriptions](https://docs.pcxpay.com/api-reference/webhooks/update-event-subscriptions.md): Replaces the list of event types your webhook is subscribed to. Send an empty array (or omit `events`) to subscribe to all event types. Use `GET /public/webhooks/events/catalogue` for the list of valid types. - [List subscribable event types](https://docs.pcxpay.com/api-reference/webhooks/list-subscribable-event-types.md): Returns every event type you can subscribe a webhook to. - [Send test event](https://docs.pcxpay.com/api-reference/webhooks/send-test-event.md): Fires a synthetic event at your registered endpoint so you can verify signature validation and processing end to end. The test delivery is signed with your real webhook secret. - [Notify transaction update](https://docs.pcxpay.com/api-reference/webhooks/notify-transaction-update.md): Manually dispatches a transaction update notification to all registered webhook endpoints for the specified organisation. - [Initiate a payment](https://docs.pcxpay.com/api-reference/payment-initiation/initiate-a-payment.md): Initiate a payin or payout. `org_id` and `user_id` are injected automatically from the authenticated API key, so you do not need to include them in the request body. Same-currency and cross-currency flows are both supported — for cross-currency flows, lock a rate first and pass its `org_rate_id`. - [Submit a payment action](https://docs.pcxpay.com/api-reference/payment-initiation/submit-a-payment-action.md): Continue a pending payment that is awaiting a customer action — for example when the initiation response returned `next_action: collect_otp`. Supported actions are `submit_otp`, `verify`, and `cancel`. The payment must be in `pending` status. - [Browser callback after hosted checkout](https://docs.pcxpay.com/api-reference/payment-initiation/browser-callback-after-hosted-checkout.md): Browser redirect endpoint that payment providers send the customer to after hosted checkout finishes. You do not call this endpoint yourself — PCX registers it with the provider during redirect checkout flows (`next_action: redirect`). It requires no authentication. - [Initiate a payment (deprecated)](https://docs.pcxpay.com/api-reference/payment-initiation/initiate-a-payment-deprecated.md): **Deprecated.** This endpoint has been consolidated into `POST /payments-init/initiate`, which accepts the same API-key authentication and also supports cross-currency flows. Use `/payments-init/initiate` instead. - [Initiate a crypto ramp](https://docs.pcxpay.com/api-reference/payment-initiation/initiate-a-crypto-ramp.md): Initiate an on-ramp (fiat → crypto) or off-ramp (crypto → fiat) conversion. PCX acts as the orchestrator — your users send or receive fiat, and PCX handles the crypto settlement automatically. - [List available payment networks](https://docs.pcxpay.com/api-reference/payment-initiation/list-available-payment-networks.md): Returns the available payment networks (banks and mobile money operators) for a given country. The upstream provider is selected automatically based on the country code. - [List beneficiaries](https://docs.pcxpay.com/api-reference/beneficiaries/list-beneficiaries.md): Returns a paginated list of beneficiaries for the authenticated user. - [Create a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/create-a-beneficiary.md): Creates a new payment beneficiary. The `beneficiary_of` field is resolved automatically from the authenticated user's credentials. For loan-client beneficiaries on behalf of an organisation, pass `org_id` in the body. - [Get a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/get-a-beneficiary.md) - [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. `account_type` and `beneficiary_of` cannot be changed after creation. - [Delete a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/delete-a-beneficiary.md) - [List my payments](https://docs.pcxpay.com/api-reference/payments/list-my-payments.md): Returns a paginated list of payments for the authenticated user. - [Create a payment](https://docs.pcxpay.com/api-reference/payments/create-a-payment.md): Initiates a new payment. - [Get a payment](https://docs.pcxpay.com/api-reference/payments/get-a-payment.md) - [Update a payment](https://docs.pcxpay.com/api-reference/payments/update-a-payment.md) - [Get payments by transaction ID](https://docs.pcxpay.com/api-reference/payments/get-payments-by-transaction-id.md): Returns all payments associated with a given transaction ID. - [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. - [List supported Nigerian banks](https://docs.pcxpay.com/api-reference/bank-validation/list-supported-nigerian-banks.md): Returns the list of Nigerian banks with their bank codes. - [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. - [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. - [Verify UK account holder name](https://docs.pcxpay.com/api-reference/bank-validation/verify-uk-account-holder-name.md): Verifies a name matches the account holder on record via TrueLayer. Requires an `accessToken` from 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. - [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 for identity verification. - [Exchange TrueLayer auth code](https://docs.pcxpay.com/api-reference/bank-validation/exchange-truelayer-auth-code.md): Called after the TrueLayer OAuth redirect. Exchanges the authorization code for access and refresh tokens. Use the returned `access_token` for account holder verification. - [List my transactions](https://docs.pcxpay.com/api-reference/transactions/list-my-transactions.md): Returns a paginated list of transactions for the authenticated user. - [Get a transaction](https://docs.pcxpay.com/api-reference/transactions/get-a-transaction.md) - [Get transaction by payment ID](https://docs.pcxpay.com/api-reference/transactions/get-transaction-by-payment-id.md) - [Filter transactions](https://docs.pcxpay.com/api-reference/transactions/filter-transactions.md): Returns transactions matching the supplied criteria. - [Submit customer KYC](https://docs.pcxpay.com/api-reference/virtual-accounts/submit-customer-kyc.md): First step of customer onboarding. Provide the customer's email and type to receive a `customer_id` and a Terms of Service link they must accept before their account is created. - [Onboard a customer](https://docs.pcxpay.com/api-reference/virtual-accounts/onboard-a-customer.md): Second step of customer onboarding. Submit the full customer profile once the customer has accepted the Terms of Service. - [Create fiat currency account](https://docs.pcxpay.com/api-reference/virtual-accounts/create-fiat-currency-account.md): Creates a fiat virtual account in any supported currency for an organisation. - [List accounts by organisation](https://docs.pcxpay.com/api-reference/virtual-accounts/list-accounts-by-organisation.md) - [List accounts by user](https://docs.pcxpay.com/api-reference/virtual-accounts/list-accounts-by-user.md) - [Withdraw funds](https://docs.pcxpay.com/api-reference/virtual-accounts/withdraw-funds.md): Initiates a withdrawal from a virtual account. NGN withdrawals are placed in `pending` status and require an admin approval step before the bank transfer fires. - [Internal transfer](https://docs.pcxpay.com/api-reference/virtual-accounts/internal-transfer.md): Moves funds between two virtual accounts on the platform. - [NGN bank account lookup](https://docs.pcxpay.com/api-reference/virtual-accounts/ngn-bank-account-lookup.md): Verifies a destination NGN bank account before initiating a withdrawal. Returns the verified `account_name` for user confirmation. - [Crypto deposit](https://docs.pcxpay.com/api-reference/virtual-accounts/crypto-deposit.md): Credits crypto funds to a virtual account. - [Crypto withdrawal](https://docs.pcxpay.com/api-reference/virtual-accounts/crypto-withdrawal.md): Withdraws crypto funds from a virtual account to an external wallet address. - [List account transactions](https://docs.pcxpay.com/api-reference/virtual-accounts/list-account-transactions.md) - [Get a VA transaction](https://docs.pcxpay.com/api-reference/virtual-accounts/get-a-va-transaction.md) - [List linked external accounts](https://docs.pcxpay.com/api-reference/virtual-accounts/list-linked-external-accounts.md) - [Link external bank account](https://docs.pcxpay.com/api-reference/virtual-accounts/link-external-bank-account.md): Links an external bank account as a withdrawal destination. - [Unlink external bank account](https://docs.pcxpay.com/api-reference/virtual-accounts/unlink-external-bank-account.md) - [Preview transaction fee](https://docs.pcxpay.com/api-reference/virtual-accounts/preview-transaction-fee.md): Calculates the fee for a specific transaction type before executing it. Useful for showing users their total cost in pre-confirmation UIs. - [List account activity logs](https://docs.pcxpay.com/api-reference/virtual-accounts/list-account-activity-logs.md): Immutable activity log. Filter by org, account, event type, and date range. - [Org account registry](https://docs.pcxpay.com/api-reference/virtual-accounts/org-account-registry.md): Full registry of all virtual accounts for the organisation, with balances and status. - [Org dashboard metrics](https://docs.pcxpay.com/api-reference/virtual-accounts/org-dashboard-metrics.md) - [List org VA transactions](https://docs.pcxpay.com/api-reference/virtual-accounts/list-org-va-transactions.md): Paginated list of all virtual account transactions across the organisation. - [Org transaction summary](https://docs.pcxpay.com/api-reference/virtual-accounts/org-transaction-summary.md): Aggregated transaction totals by status and currency for the organisation. - [Create a payment link](https://docs.pcxpay.com/api-reference/payment-links/create-a-payment-link.md): Creates a new payment link. Requires the `org-admin` or `staff` role. - [Get a payment link](https://docs.pcxpay.com/api-reference/payment-links/get-a-payment-link.md) - [Revoke a payment link](https://docs.pcxpay.com/api-reference/payment-links/revoke-a-payment-link.md): Revokes a payment link. Optionally pass `email` in the body to revoke all active links for that recipient at once. - [Verify a payment link](https://docs.pcxpay.com/api-reference/payment-links/verify-a-payment-link.md): Checks whether a link is valid (not expired or revoked). No authentication required. - [List org payment links](https://docs.pcxpay.com/api-reference/payment-links/list-org-payment-links.md): Returns all payment links for an organisation. Requires `org-admin` or `staff`. - [Verify OTP](https://docs.pcxpay.com/api-reference/payment-links/verify-otp.md): Verifies the OTP and returns a short-lived JWT (`type: payment_link`, 24-hour expiry) for accessing the protected payment link. - [Send OTP](https://docs.pcxpay.com/api-reference/payment-links/send-otp.md): Sends a one-time password to the customer's email. No authentication required. - [Create a VA payment link](https://docs.pcxpay.com/api-reference/payment-links/create-a-va-payment-link.md): Creates a virtual account payment link for accepting deposits. - [Initiate VA payment](https://docs.pcxpay.com/api-reference/payment-links/initiate-va-payment.md): Payer provides their currency and amount. PCX returns a payment quote with the calculated exchange rate. - [Confirm VA payment](https://docs.pcxpay.com/api-reference/payment-links/confirm-va-payment.md): Payer confirms the payment. PCX processes the transfer into the virtual account. - [List escrow projects](https://docs.pcxpay.com/api-reference/escrow/list-escrow-projects.md): Paginated list of escrow entities belonging to the caller's organisation. Requires the `escrow` feature to be enabled for the organisation. - [Create an escrow project](https://docs.pcxpay.com/api-reference/escrow/create-an-escrow-project.md): Creates a new escrow entity (project) for the caller's organisation, optionally with milestones and parties inline. Requires the `escrow` feature to be enabled for the organisation. - [Get an escrow project](https://docs.pcxpay.com/api-reference/escrow/get-an-escrow-project.md): Fetches the full escrow entity, including its milestones, parties, contracts, and payment links. Org-scoped — the escrow must belong to the caller's organisation. Requires the `escrow` feature. - [Update an escrow project](https://docs.pcxpay.com/api-reference/escrow/update-an-escrow-project.md): Updates the entity's metadata — `label`, `org_ref`, or `total_amount`. Requires `org-admin` OrgMember role and the `escrow` feature. - [Cancel an escrow project](https://docs.pcxpay.com/api-reference/escrow/cancel-an-escrow-project.md): Cancels the escrow entity. Only permitted while the escrow is unfunded — returns a conflict once funds have been deposited. Requires `org-admin` OrgMember role and the `escrow` feature. - [Add a milestone](https://docs.pcxpay.com/api-reference/escrow/add-a-milestone.md): Adds a milestone to an existing escrow project. Requires `org-admin` OrgMember role and the `escrow` feature. - [Update a milestone](https://docs.pcxpay.com/api-reference/escrow/update-a-milestone.md): Updates a milestone's `label` or `expected_disbursement`. Requires `org-admin` OrgMember role and the `escrow` feature. - [Update milestone party splits](https://docs.pcxpay.com/api-reference/escrow/update-milestone-party-splits.md): Updates one or more party splits on this milestone at once. The body also accepts a single update object or a bare array instead of the `parties` wrapper. Requires `org-admin` OrgMember role and the `escrow` feature. - [Assign parties to a milestone](https://docs.pcxpay.com/api-reference/escrow/assign-parties-to-a-milestone.md): Assigns one or more registered parties to this milestone with a payout split. Each `party_id` must already be registered on the escrow project via `POST /virtual-accounts/escrow/{escrow_id}/parties`. The body also accepts a single assignment object or a bare array instead of the `parties` wrapper. R… - [Remove a party from a milestone](https://docs.pcxpay.com/api-reference/escrow/remove-a-party-from-a-milestone.md): Removes a party's assignment (participation and split) from this milestone. The party's entity-level identity is kept — use `DELETE /virtual-accounts/escrow/{escrow_id}/parties/{party_id}` to remove it from the project entirely. Requires `org-admin` OrgMember role and the `escrow` feature. - [Update parties](https://docs.pcxpay.com/api-reference/escrow/update-parties.md): Updates one or more registered parties at once — each item carries the `party_id` to change plus the fields to update. The body also accepts a single update object or a bare array instead of the `parties` wrapper. Requires `org-admin` OrgMember role and the `escrow` feature. - [Register parties](https://docs.pcxpay.com/api-reference/escrow/register-parties.md): Registers one or more parties (contractor, agency commission, or expense) on an escrow project. A party's payout participation and split are assigned per milestone via the milestone-parties endpoint. The body also accepts a single party object or a bare array instead of the `parties` wrapper. Requir… - [Update a party](https://docs.pcxpay.com/api-reference/escrow/update-a-party.md): Updates a single registered party — the `party_id` comes from the URL and the body carries the fields to change. Requires `org-admin` OrgMember role and the `escrow` feature. - [Remove a party](https://docs.pcxpay.com/api-reference/escrow/remove-a-party.md): Removes a party from the escrow project. Requires `org-admin` OrgMember role and the `escrow` feature. - [Get a milestone's contract](https://docs.pcxpay.com/api-reference/escrow/get-a-milestones-contract.md): Returns the current contract record for the milestone. Exactly one contract exists per milestone, created implicitly on the first confirmation event. Requires the `escrow` feature. - [Submit a contract confirmation](https://docs.pcxpay.com/api-reference/escrow/submit-a-contract-confirmation.md): Records a contract event for the milestone — exactly one action per call. Send `party_id` to record a contractor's completion confirmation (the contract record is created implicitly on the first event). Send `client_confirmed` to relay the client's final decision: `true` checks that every contractor… - [List escrow disbursements](https://docs.pcxpay.com/api-reference/escrow/list-escrow-disbursements.md): Returns the escrow's disbursement history — the transaction records of type `escrow_disbursement` (one per party payout), newest first. Requires the `escrow` feature. - [Create an escrow payment link](https://docs.pcxpay.com/api-reference/escrow/create-an-escrow-payment-link.md): Mints a hosted payment link for the escrow project — e.g. an agency sends it to their client to deposit a milestone payment. Returns the `link_ref` (deposit-match key) and the hosted URL to share. Incoming deposits are matched to the escrow on `link_ref`. Requires the `escrow` feature. - [Create a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/create-a-beneficiary.md): Creates a new payment beneficiary. The `beneficiary_of` field is resolved automatically from the authenticated user's credentials. For loan-client beneficiaries on behalf of an organisation, pass `org_id` in the body. - [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. `account_type` and `beneficiary_of` cannot be changed after creation. - [Delete a beneficiary](https://docs.pcxpay.com/api-reference/beneficiaries/delete-a-beneficiary.md) - [List my payments](https://docs.pcxpay.com/api-reference/payments/list-my-payments.md): Returns a paginated list of payments for the authenticated user. - [Create a payment](https://docs.pcxpay.com/api-reference/payments/create-a-payment.md): Initiates a new payment. - [Get a payment](https://docs.pcxpay.com/api-reference/payments/get-a-payment.md) - [Update a payment](https://docs.pcxpay.com/api-reference/payments/update-a-payment.md) - [Get payments by transaction ID](https://docs.pcxpay.com/api-reference/payments/get-payments-by-transaction-id.md): Returns all payments associated with a given transaction ID. - [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. - [List supported Nigerian banks](https://docs.pcxpay.com/api-reference/bank-validation/list-supported-nigerian-banks.md): Returns the list of Nigerian banks with their bank codes. - [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. - [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. - [Verify UK account holder name](https://docs.pcxpay.com/api-reference/bank-validation/verify-uk-account-holder-name.md): Verifies a name matches the account holder on record via TrueLayer. Requires an `accessToken` from 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. - [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 for identity verification. - [List escrow projects](https://docs.pcxpay.com/api-reference/escrow/list-escrow-projects.md): Paginated list of escrow entities belonging to the caller's organisation. Requires the `escrow` feature to be enabled for the organisation. - [Create an escrow project](https://docs.pcxpay.com/api-reference/escrow/create-an-escrow-project.md): Creates a new escrow entity (project) for the caller's organisation, optionally with milestones and parties inline. Requires the `escrow` feature to be enabled for the organisation. - [Get an escrow project](https://docs.pcxpay.com/api-reference/escrow/get-an-escrow-project.md): Fetches the full escrow entity, including its milestones, parties, contracts, and payment links. Org-scoped — the escrow must belong to the caller's organisation. Requires the `escrow` feature. - [Update an escrow project](https://docs.pcxpay.com/api-reference/escrow/update-an-escrow-project.md): Updates the entity's metadata — `label`, `org_ref`, or `total_amount`. Requires `org-admin` OrgMember role and the `escrow` feature. - [Cancel an escrow project](https://docs.pcxpay.com/api-reference/escrow/cancel-an-escrow-project.md): Cancels the escrow entity. Only permitted while the escrow is unfunded — returns a conflict once funds have been deposited. Requires `org-admin` OrgMember role and the `escrow` feature. - [Add a milestone](https://docs.pcxpay.com/api-reference/escrow/add-a-milestone.md): Adds a milestone to an existing escrow project. Requires `org-admin` OrgMember role and the `escrow` feature. - [Update a milestone](https://docs.pcxpay.com/api-reference/escrow/update-a-milestone.md): Updates a milestone's `label` or `expected_disbursement`. Requires `org-admin` OrgMember role and the `escrow` feature. - [Register parties](https://docs.pcxpay.com/api-reference/escrow/register-parties.md): Registers one or more parties (contractor, agency commission, or expense) on an escrow project. A party's payout participation and split are assigned per milestone via the milestone-parties endpoint. The body also accepts a single party object or a bare array instead of the `parties` wrapper. Requir… - [Update parties](https://docs.pcxpay.com/api-reference/escrow/update-parties.md): Updates one or more registered parties at once — each item carries the `party_id` to change plus the fields to update. The body also accepts a single update object or a bare array instead of the `parties` wrapper. Requires `org-admin` OrgMember role and the `escrow` feature. - [Update a party](https://docs.pcxpay.com/api-reference/escrow/update-a-party.md): Updates a single registered party — the `party_id` comes from the URL and the body carries the fields to change. Requires `org-admin` OrgMember role and the `escrow` feature. - [Remove a party](https://docs.pcxpay.com/api-reference/escrow/remove-a-party.md): Removes a party from the escrow project. Requires `org-admin` OrgMember role and the `escrow` feature. - [Assign parties to a milestone](https://docs.pcxpay.com/api-reference/escrow/assign-parties-to-a-milestone.md): Assigns one or more registered parties to this milestone with a payout split. Each `party_id` must already be registered on the escrow project via `POST /virtual-accounts/escrow/{escrow_id}/parties`. The body also accepts a single assignment object or a bare array instead of the `parties` wrapper. R… - [Update milestone party splits](https://docs.pcxpay.com/api-reference/escrow/update-milestone-party-splits.md): Updates one or more party splits on this milestone at once. The body also accepts a single update object or a bare array instead of the `parties` wrapper. Requires `org-admin` OrgMember role and the `escrow` feature. - [Remove a party from a milestone](https://docs.pcxpay.com/api-reference/escrow/remove-a-party-from-a-milestone.md): Removes a party's assignment (participation and split) from this milestone. The party's entity-level identity is kept — use `DELETE /virtual-accounts/escrow/{escrow_id}/parties/{party_id}` to remove it from the project entirely. Requires `org-admin` OrgMember role and the `escrow` feature. - [Submit a contract confirmation](https://docs.pcxpay.com/api-reference/escrow/submit-a-contract-confirmation.md): Records a contract event for the milestone — exactly one action per call. Send `party_id` to record a contractor's completion confirmation (the contract record is created implicitly on the first event). Send `client_confirmed` to relay the client's final decision: `true` checks that every contractor… - [Get a milestone's contract](https://docs.pcxpay.com/api-reference/escrow/get-a-milestones-contract.md): Returns the current contract record for the milestone. Exactly one contract exists per milestone, created implicitly on the first confirmation event. Requires the `escrow` feature. - [Create an escrow payment link](https://docs.pcxpay.com/api-reference/escrow/create-an-escrow-payment-link.md): Mints a hosted payment link for the escrow project — e.g. an agency sends it to their client to deposit a milestone payment. Returns the `link_ref` (deposit-match key) and the hosted URL to share. Incoming deposits are matched to the escrow on `link_ref`. Requires the `escrow` feature. - [List escrow disbursements](https://docs.pcxpay.com/api-reference/escrow/list-escrow-disbursements.md): Returns the escrow's disbursement history — the transaction records of type `escrow_disbursement` (one per party payout), newest first. Requires the `escrow` feature. - [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. - [Create API key](https://docs.pcxpay.com/api-reference/api-keys/create-api-key.md): Creates a new API key. The full key value is returned once at creation and cannot be retrieved again — store it securely. - [Validate API key](https://docs.pcxpay.com/api-reference/api-keys/validate-api-key.md): Checks whether a given API key is valid and active. Returns the associated `user_id`, `org_id`, and key status. No authentication is required on this endpoint — pass `NONE` for both headers. - [Delete API key](https://docs.pcxpay.com/api-reference/api-keys/delete-api-key.md): Permanently deletes an API key. Any integration using this key will immediately lose access. - [Revoke API key](https://docs.pcxpay.com/api-reference/api-keys/revoke-api-key.md): Disables an API key without deleting it. The key is preserved for audit purposes but rejected on all subsequent requests. - [Register webhook](https://docs.pcxpay.com/api-reference/webhooks/register-webhook.md): Registers an HTTPS endpoint to receive event notifications. PCX will POST events to this URL as they occur. The organisation identity is derived from your API key. The response includes the `secret_key` used to sign every delivery — it is returned only once, so store it securely. - [Get webhook configuration](https://docs.pcxpay.com/api-reference/webhooks/get-webhook-configuration.md): Returns your organisation's current webhook configuration — the endpoint URL and the list of subscribed event types. The signing secret is not returned; it is only shown once at registration. - [Update event subscriptions](https://docs.pcxpay.com/api-reference/webhooks/update-event-subscriptions.md): Replaces the list of event types your webhook is subscribed to. Send an empty array (or omit `events`) to subscribe to all event types. Use `GET /public/webhooks/events/catalogue` for the list of valid types. - [List subscribable event types](https://docs.pcxpay.com/api-reference/webhooks/list-subscribable-event-types.md): Returns every event type you can subscribe a webhook to. - [Send test event](https://docs.pcxpay.com/api-reference/webhooks/send-test-event.md): Fires a synthetic event at your registered endpoint so you can verify signature validation and processing end to end. The test delivery is signed with your real webhook secret. - [Notify transaction update](https://docs.pcxpay.com/api-reference/webhooks/notify-transaction-update.md): Manually dispatches a transaction update notification to all registered webhook endpoints for the specified organisation. - [Create a payment link](https://docs.pcxpay.com/api-reference/payment-links/create-a-payment-link.md): Creates a new payment link. Requires the `org-admin` or `staff` role. - [Get a payment link](https://docs.pcxpay.com/api-reference/payment-links/get-a-payment-link.md) - [Verify a payment link](https://docs.pcxpay.com/api-reference/payment-links/verify-a-payment-link.md): Checks whether a link is valid (not expired or revoked). No authentication required. - [List my transactions](https://docs.pcxpay.com/api-reference/transactions/list-my-transactions.md): Returns a paginated list of transactions for the authenticated user. - [Get a transaction](https://docs.pcxpay.com/api-reference/transactions/get-a-transaction.md) - [Filter transactions](https://docs.pcxpay.com/api-reference/transactions/filter-transactions.md): Returns transactions matching the supplied criteria. - [Get transaction by payment ID](https://docs.pcxpay.com/api-reference/transactions/get-transaction-by-payment-id.md) ## OpenAPI Specs - [openapi](/api-reference/external/openapi.yaml) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.