> ## Documentation Index > Fetch the complete documentation index at: https://docs.mlm-platform.com/llms.txt > Use this file to discover all available pages before exploring further. # Create member payout account > Creates a payout account and provisions a real Stripe Connect account for the member. The account is created with the `transfers` capability enabled, allowing the platform to send payouts. ## Identity + Country Requirements Identity and country are **not** provided in this request. They are derived from the member's stored profile (typically populated/verified during KYC). Before calling this endpoint: - Ensure the member profile has `countryCode` (ISO alpha-3) and address fields set via `PATCH /api/v1/members/{userId}/profile`. - For Stripe, ensure the profile also has identity fields required for verification. ## Selecting `methodType` and building `bankAccount` 1. Call `GET /api/v1/payout-methods?country=XX`. 2. Choose a method from `methods[]`. 3. Use `methods[].id` as `methodType`. 4. Populate `bankAccount` using the selected method's `fields[]` (each field's `key` becomes a key in `bankAccount`). ## OpenAPI ````yaml api/openapi.yaml post /api/v1/members/{userId}/payout-accounts openapi: 3.1.0 info: title: MLM Platform API version: 1.0.0 description: > The MLM Platform API enables tenant developers to integrate commission tracking, member management, and referral systems into their applications. ## Authentication All API requests require a tenant API key passed in the `x-tenant-api-key` header. ## Environments - **LIVE**: Production environment with real data - **SANDBOX**: Test environment for development and testing API keys are scoped to specific environments. Use sandbox keys for testing. The environment is derived from the API key used for the request. The platform returns the selected environment in the response header `X-Environment`. If you send an `X-Environment` request header, it is treated as optional/debug-only. contact: name: MLM Platform Support email: support@mlm-platform.example.com license: name: Proprietary url: https://mlm-platform.example.com/terms servers: - url: https://app.mlm-platform.com description: Production API - url: http://localhost:3000 description: Local Development security: - TenantApiKey: [] tags: - name: Auth description: Token exchange, validation, refresh, and revocation for OIDC federation - name: Events description: Purchase and commission events - name: Users description: Member management - name: Leads description: Lead capture and tracking - name: Referrals description: Referral links and codes - name: Payout description: Payout methods metadata for dynamic payout setup forms - name: Payout Accounts description: Member payout accounts (create/list/update/delete) - name: KYC description: Member KYC start, status, and document submission - name: Admin KYC description: Admin KYC review queue, details, and actions - name: Widget description: Embeddable widget authentication - name: Webhooks description: Webhook receivers for third-party providers (Sumsub) paths: /api/v1/members/{userId}/payout-accounts: post: tags: - Payout Accounts summary: Create member payout account description: > Creates a payout account and provisions a real Stripe Connect account for the member. The account is created with the `transfers` capability enabled, allowing the platform to send payouts. ## Identity + Country Requirements Identity and country are **not** provided in this request. They are derived from the member's stored profile (typically populated/verified during KYC). Before calling this endpoint: - Ensure the member profile has `countryCode` (ISO alpha-3) and address fields set via `PATCH /api/v1/members/{userId}/profile`. - For Stripe, ensure the profile also has identity fields required for verification. ## Selecting `methodType` and building `bankAccount` 1. Call `GET /api/v1/payout-methods?country=XX`. 2. Choose a method from `methods[]`. 3. Use `methods[].id` as `methodType`. 4. Populate `bankAccount` using the selected method's `fields[]` (each field's `key` becomes a key in `bankAccount`). operationId: createMemberPayoutAccount parameters: - name: userId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayoutAccountRequest' examples: hk_bank: summary: Create a Hong Kong bank payout account value: methodType: bank_hk currency: HKD bankAccount: accountHolderName: Chan Tai Man bankCode: '004' branchCode: '123' accountNumber: '12345678901' isPrimary: true us_bank: summary: Create a US bank payout account value: methodType: bank_us_ach currency: USD bankAccount: accountHolderName: Jane Doe routingNumber: '110000000' accountNumber: '000123456789' isPrimary: false gcash: summary: Create a GCash payout account (e-wallet) value: methodType: gcash currency: PHP bankAccount: accountHolderName: Juan Dela Cruz phoneNumber: '+639123456789' isPrimary: true responses: '201': description: Created payout account content: application/json: schema: $ref: '#/components/schemas/PayoutAccount' headers: X-Environment: $ref: '#/components/headers/X-Environment' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalError' components: schemas: CreatePayoutAccountRequest: type: object required: - methodType - currency properties: methodType: type: string description: > Payout method ID. Must match a value from `GET /api/v1/payout-methods?country=XX` response `methods[].id`. currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code. Must match the selected payout method. bankAccount: $ref: '#/components/schemas/BankAccountDetails' details: type: object additionalProperties: type: string description: > **Deprecated**: Use `bankAccount` instead. Provider-agnostic key/value map of method-specific fields. Keys and validation rules are defined by the selected payout method's `fields[]` from `GET /api/v1/payout-methods`. deprecated: true accountHolderName: type: string description: | **Deprecated**: Use `bankAccount.accountHolderName` instead. Name of the payout account holder as registered with the provider. deprecated: true isPrimary: type: boolean description: If true, marks this account as the member's primary payout account PayoutAccount: type: object properties: id: type: string format: uuid methodType: type: string category: type: string displayName: type: string countryCode: type: string currency: type: string providerType: type: string isPrimary: type: boolean isActive: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message code: type: string description: Machine-readable error code details: type: object additionalProperties: true description: Additional error details BankAccountDetails: type: object required: - accountHolderName properties: accountHolderName: type: string description: Name of the payout account holder as registered with the bank additionalProperties: type: string description: > Bank account details. Required fields depend on the selected `methodType`. Use `GET /api/v1/payout-methods?country=XX` to get field definitions for each method. Common fields by country: - **HK**: `bankCode`, `branchCode`, `accountNumber` - **US**: `routingNumber`, `accountNumber` - **GB**: `sortCode`, `accountNumber` - **EU (SEPA)**: `iban` headers: X-Environment: description: >- Indicates the environment (LIVE or SANDBOX) the request was processed in (derived from API key) schema: type: string enum: - LIVE - SANDBOX responses: BadRequest: description: Bad Request - Invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Invalid request body code: VALIDATION_ERROR details: field: email message: Invalid email format Unauthorized: description: Unauthorized - Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_api_key: summary: Missing API key value: error: Authentication required code: UNAUTHORIZED invalid_api_key: summary: Invalid API key value: error: Invalid API key code: INVALID_API_KEY InternalError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: An unexpected error occurred code: INTERNAL_ERROR securitySchemes: TenantApiKey: type: apiKey in: header name: x-tenant-api-key description: > Tenant API key for authentication. Keys are scoped to specific environments (LIVE or SANDBOX). Obtain keys from the admin dashboard. ````