> ## Documentation Index > Fetch the complete documentation index at: https://docs.pcxpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a beneficiary > 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. ## OpenAPI ````yaml /api-reference/external/openapi.yaml post /beneficiaries openapi: 3.0.3 info: title: PCX API description: > The PCX integration API. Every request requires two headers: `Authorization` (Bearer JWT for user-facing flows, or the literal string `NONE`) and `X-Api-Key` (your API key for server-to-server calls, or the literal string `NONE`). Pass `NONE` for whichever header you are not using. version: '1.0' servers: - url: https://prod-api.pcxpay.com/v1 description: Production - url: https://devs.pcxpay.com/v1 description: Development security: [] tags: - name: Payment Initiation description: Initiate payments and poll for status - name: API Keys description: Create and manage API keys for programmatic access - name: Webhooks description: Register endpoints and receive transaction notifications - name: Beneficiaries description: Manage payment recipients - name: Payments description: Initiate and track payments - name: Bank Validation description: Validate bank accounts before initiating a payment - name: Transactions description: Query the financial transaction ledger - name: Virtual Accounts description: Multi-currency virtual account provisioning and fund operations - name: Payment Links description: Generate shareable payment links for customer checkout - name: Escrow description: Milestone-based escrow projects, parties, contracts, and funding paths: /beneficiaries: parameters: - $ref: '#/components/parameters/AuthorizationHeader' - $ref: '#/components/parameters/XApiKeyHeader' post: tags: - Beneficiaries summary: Create a beneficiary description: > 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. operationId: createBeneficiary requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BeneficiaryCreate' responses: '201': description: Beneficiary created content: application/json: schema: $ref: '#/components/schemas/BeneficiaryResponse' '400': $ref: '#/components/responses/BadRequest' '409': description: Beneficiary already exists components: parameters: AuthorizationHeader: name: Authorization in: header required: true description: >- Bearer JWT for user-facing flows (`Bearer eyJraWQ...`), or the literal string `NONE` when authenticating via API key. schema: type: string default: NONE example: Bearer eyJraWQ... XApiKeyHeader: name: X-Api-Key in: header required: true description: >- API key for server-to-server flows, or the literal string `NONE` when authenticating via JWT. schema: type: string default: NONE example: pcx_abc123_xxxx schemas: BeneficiaryCreate: type: object required: - account_type - country - currency - fname - lname properties: account_type: $ref: '#/components/schemas/AccountType' beneficiary_type: $ref: '#/components/schemas/BeneficiaryType' beneficiary_of: type: string description: > ID of the user this beneficiary belongs to. Defaults to the authenticated user when not provided. fname: type: string description: Beneficiary first name. example: John lname: type: string description: Beneficiary last name. example: Doe email: type: string format: email description: Beneficiary email address (optional). example: john@example.com phone_number: type: string description: Beneficiary phone number (optional). example: '+2348012345678' country: type: string description: > ISO 3166-1 alpha-2 country code. Supported: `NG`, `GH`, `GB`, `US`, `KE`, `RW`, `ZA`, `AE`, `DE`, `FR`, `NL`, `ES`, `IT`, `BE`, `AT`, `IE`, `PT`. example: NG currency: type: string description: > ISO 4217 currency code. Must match the expected currency for the given country: `NG → NGN`, `GH → GHS`, `GB → GBP or EUR`, `US → USD`, `KE → KES`, `RW → RWF`, `ZA → ZAR`, `AE → AED`, Euro-zone countries → `EUR`. example: NGN bank_details: type: object description: | Bank account details. Required when `account_type` is `bank`. properties: bank_name: type: string example: Zenith Bank account_number: type: string example: '1234567890' account_name: type: string example: John Doe bank_code: type: string example: '057' momo_details: type: object description: > Mobile money account details. Required when `account_type` is `momo`. Shape is provider-specific. properties: network: type: string description: Mobile money network name (e.g. `MTN`, `Airtel`). example: MTN phone_number: type: string example: '+2348012345678' loan_client_details: type: object description: Additional metadata for `loan_client` beneficiary types. external_account_id: type: string description: ID of the corresponding account in an external system. org_id: type: string description: > Organisation ID. Required when creating a beneficiary on behalf of an organisation (e.g. for a loan-client disbursement flow). BeneficiaryResponse: type: object properties: beneficiary_id: type: string account_type: $ref: '#/components/schemas/AccountType' beneficiary_of: type: string description: User ID of the beneficiary owner. beneficiary_type: $ref: '#/components/schemas/BeneficiaryType' fname: type: string lname: type: string email: type: string nullable: true phone_number: type: string nullable: true country: type: string currency: type: string bank_details: type: object nullable: true properties: bank_name: type: string account_number: type: string account_name: type: string bank_code: type: string momo_details: type: object nullable: true properties: network: type: string phone_number: type: string loan_client_details: type: object nullable: true external_account_id: type: string nullable: true org_id: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time AccountType: type: string enum: - bank - momo description: > `bank` — bank account (details in `bank_details`). `momo` — mobile money account (details in `momo_details`). BeneficiaryType: type: string enum: - loan_client - payout_recipient default: payout_recipient ErrorResponse: type: object properties: message: type: string status: type: string enum: - error responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ````