> ## Documentation Index > Fetch the complete documentation index at: https://docs2.finverse.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Payment Account > Create a new Payment Account for Mandates, Payments or Payouts. **Access:** This flow is available on demand for Finverse customers who want to directly manage Payment Users and Payment Accounts. Contact [support@finverse.com](mailto:support@finverse.com) to request access. **Authorization**: `customer_token` ## Request body ### account_number (object, required) Bank account number details. ## Response fields The response is a Payment Account object. Refer to Payment Account object data model in `GET /payment_users/{user_id}/payment_accounts`. ## OpenAPI ````yaml /api-reference/openapi.json post /payment_accounts openapi: 3.0.0 info: description: Documentation of the early finverse services title: Finverse Public termsOfService: https://example.com contact: name: Maintainers email: info@finverse.com license: name: unknown license version: 0.0.1 servers: - url: https://api.prod.finverse.net security: - Oauth2: - test tags: - name: public description: Publicly accessible endpoints x-group: Public - name: customer description: Customer app and institution endpoints x-group: Customer - name: link description: Finverse Link flows x-group: Link - name: login_identity description: Login identity lifecycle and metadata x-group: Login identity - name: accounts description: Accounts, balances, and account numbers x-group: Accounts - name: statements description: Statements and composite statements x-group: Statements - name: transactions description: Transaction history x-group: Transactions - name: identity_income description: Identity and income insights x-group: Identity & income - name: payment_links description: Payment link creation and checkout x-group: Payment links - name: mandates description: Direct debit mandates x-group: Mandates - name: payments description: Payment initiation and status x-group: Payment operations - name: payouts description: Payouts and scheduled payouts x-group: Payouts - name: payment_users description: Payment user profiles x-group: Payment users - name: payment_accounts description: Payment accounts for users x-group: Payment accounts - name: payment_methods description: Stored payment methods x-group: Payment methods - name: bills description: Bill presentment x-group: Bills - name: disputes description: Payment disputes x-group: Disputes - name: ledger description: Ledger and statements x-group: Ledger paths: /payment_accounts: post: tags: - payment_accounts summary: Create Payment Account description: >- Create a new Payment Account for Mandates, Payments or Payouts. **Access:** This flow is available on demand for Finverse customers who want to directly manage Payment Users and Payment Accounts. Contact [support@finverse.com](mailto:support@finverse.com) to request access. **Authorization**: `customer_token` ## Request body ### account_number (object, required) Bank account number details. ## Response fields The response is a Payment Account object. Refer to Payment Account object data model in `GET /payment_users/{user_id}/payment_accounts`. operationId: createPaymentAccount requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentAccountRequest' description: request body for creating payment account required: true responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/PaymentAccountDetails' examples: success: summary: Success value: account_id: 01GM2X09ZTV5WZVC3TXVZJCCTQ account_number: number: 01GM2X0A1HGECAPWXBMZ8ZZJW2 type: LOCAL account_type: EXTERNAL_ACCOUNT accountholder_name: 01GM2X0A0P8F31PBAS8DFHMW00 bank_code: '004' branch_code: '123' created_at: '2022-12-12T10:10:06.006Z' currencies: - HKD - CNY institution_id: hsbc-hk metadata: key: value employer_name: Apple Inc updated_at: '2022-12-12T10:10:06.006Z' user_id: 01GM2CQ5D7GSHGPA73X8NGXCHB '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' examples: missing_permissions_for_this_endpoint: summary: Error (missing permissions for this endpoint) value: code: 401 error: code: NOT_AUTHORIZED details: Invalid bearer token error_code: NOT_AUTHORIZED message: >- Authorization failed. Please review authorization requirements in API documentation. request_id: '{unique_id}' type: API_ERROR message: Invalid bearer token '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' security: - Oauth2: - payment_account:create components: schemas: CreatePaymentAccountRequest: required: - account_type - accountholder_name - institution_id - user_id properties: account_number: $ref: '#/components/schemas/RecipientAccountNumber' account_number_masked: description: >- Masked account number of the payment account. Optional for EXTERNAL_ACCOUNT type. Can be provided when account_number is not available. Only one of account_number or account_number_masked can be provided. type: string account_type: description: >- Type of payment account. Currently only allow creating external account. type: string enum: - EXTERNAL_ACCOUNT example: EXTERNAL_ACCOUNT accountholder_name: description: Accountholder name of the payment account type: string example: Chan Li Pak currencies: description: List of currencies supported by the payment account type: array items: type: string maxLength: 3 example: - HKD - SGD institution_id: description: Finverse Institution ID for the payment institution. type: string maxLength: 100 example: hsbc-hk metadata: $ref: '#/components/schemas/CreateMetadata' user_id: description: >- A unique identifier generated after creating user (Finverse Payment User ID) type: string maxLength: 100 example: 01GY6H0JA7BS8EVGY56NSHFX2E PaymentAccountDetails: properties: account_id: description: Payment account id type: string account_number: $ref: '#/components/schemas/RecipientAccountNumber' account_number_masked: description: Masked Account number of the payment account type: string account_type: description: Type of payment account. type: string enum: - EXTERNAL_ACCOUNT - SETTLEMENT_ACCOUNT example: EXTERNAL_ACCOUNT accountholder_name: description: Accountholder name of the payment account type: string example: Chan Li Pak bank_code: description: 3-digit code associated with bank type: string example: '004' branch_code: description: 3-digit code used to identify specific bank branch type: string example: '123' business_units: description: The business units the payment account belongs to type: array items: type: string x-omitempty: true created_at: description: >- Timestamp of when the payment link was created in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ) type: string format: date-time currencies: description: List of currencies supported by the payment account type: array items: type: string x-omitempty: true example: - HKD - SGD customer_app_id: description: The customer app ID type: string example: 01ARZ3NDEKTSV4RRFFQ69G5FAV institution_id: description: Finverse Institution ID for the payment institution. type: string example: hsbc-hk institution_name: description: Institution Name for the sender’s institution. type: string example: HSBC legal_entity_name: description: This field is only applicable to settlement account type: string metadata: description: >- Additional attributes of the sender account in key:value format (e.g. sender_id: 1234). It supports up to 10 key:value pairs, whereas the key and value supports up to 50 and 1000 characters respectively. type: object additionalProperties: type: string updated_at: description: >- Timestamp of when the payment link was last updated in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ) type: string format: date-time user_id: description: >- A unique identifier generated after creating user (Finverse Payment User ID) type: string example: 01GY6H0JA7BS8EVGY56NSHFX2E ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' RecipientAccountNumber: type: object required: - type - number properties: number: description: >- Account number. Account numbers in responses are tokenized by Finverse. type: string maxLength: 100 minLength: 1 number_plaintext: description: Account number in plaintext type: string maxLength: 100 minLength: 1 nullable: true type: description: 'Type of account number format. Possible values: `IBAN`, `LOCAL`' type: string enum: - LOCAL - IBAN CreateMetadata: type: object additionalProperties: type: string maxLength: 1000 FvErrorModelV2: required: - type - error_code - message - details - request_id properties: details: type: string error_code: type: string example: CREDENTIALS_INVALID message: type: string request_id: description: The request_id provided in the request header type: string type: description: The error type type: string enum: - LINK_ERROR - API_ERROR example: LINKING_ERROR securitySchemes: Oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://finverse-dev.us.auth0.com/oauth/token scopes: account: Account balance: Balance credit: Credit institution: Institution investment: Investment link: Link test: Test transaction: Transaction ````