> ## 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 User > Create a new Payment User to setup mandates or collect payments. **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 ### integration_metadata (object, optional) Use the following optional parameters to pass custom values for Finverse-supported integrations (e.g. ERP/CRM/accounting integrations). ### user_details (array of objects, optional) Additional information about the user's identity, used for validating the user's identity & verifying any user-submitted values in the Finverse Link UI. ## Response fields The response is a Payment User object. Refer to Payment User object data model in `GET /payment_users/{user_id}`. ## OpenAPI ````yaml /api-reference/openapi.json post /payment_users 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_users: post: tags: - payment_users summary: Create Payment User description: >- Create a new Payment User to setup mandates or collect payments. **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 ### integration_metadata (object, optional) Use the following optional parameters to pass custom values for Finverse-supported integrations (e.g. ERP/CRM/accounting integrations). ### user_details (array of objects, optional) Additional information about the user's identity, used for validating the user's identity & verifying any user-submitted values in the Finverse Link UI. ## Response fields The response is a Payment User object. Refer to Payment User object data model in `GET /payment_users/{user_id}`. operationId: createPaymentUser requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentUserRequest' description: request body for creating payment user required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PaymentUser' examples: success: summary: Success value: autopay_consent: false created_at: '2024-03-09T02:15:34.075Z' external_user_id: unique_user_id_1709950534 metadata: employer_name: Apple Inc key: value name: John Doe updated_at: '2024-03-09T02:15:34.075Z' user_details: - details_type: HK_ID values: - 01HRGFX0DE17AE13FCTEDTTS0Z user_id: 01HRGFX0C1KDDXZTA71V085MDX user_type: INDIVIDUAL '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' examples: missing_name: summary: Error (missing name) value: error: details: name in body is required error_code: INVALID_PARAMETER message: The parameters provided are invalid. See details. request_id: '{unique_id}' type: API_ERROR '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' examples: duplicate_user_id: summary: Error (duplicate User ID) value: error: details: error when creating paymentUser error_code: INTERNAL_SERVER_ERROR message: >- We encountered an internal error. Please contact Finverse customer support for further assistance. request_id: '1695211687' type: API_ERROR security: - Oauth2: - payment_user:create components: schemas: CreatePaymentUserRequest: required: - name - external_user_id properties: autopay_consent: type: boolean email: type: string maxLength: 256 external_user_id: type: string maxLength: 100 integration_metadata: $ref: '#/components/schemas/IntegrationMetadataPaymentUserRequest' metadata: $ref: '#/components/schemas/CreateMetadata' name: type: string maxLength: 100 user_details: type: array items: $ref: '#/components/schemas/SenderDetail' user_type: type: string enum: - INDIVIDUAL - BUSINESS PaymentUser: required: - autopay_consent properties: autopay_consent: description: >- Flag indicating whether the user has agreed to future (on-demand) payments of bills/invoices owed by the user. This consent is usually collected in the Payment Link flow. Value is `false` by default, unless: (i) the user enrolled into Autopay in the Payment Link UI, (ii) a Payment LInk was created with the configuration `payment_setup_options.future_payments` = `AUTOPAY`, (iii) the Payment User was created with `autopay_consent` = `true` using the Create Payment User API (`POST /payment_users`). type: boolean example: false created_at: type: string format: date-time description: Timestamp when the Payment User object was first created email: type: string description: >- Payment User's contact email, used for Finverse notifications. To ensure a smooth payment experience for end-users and to avoid support tickets or disputes, we strongly recommend enabling Finverse notifications by providing the end-user's email. Finverse sends email notifications for: \- Changes to stored payment methods (e.g. direct debit mandate or card) \- Changes to user autopay consent \- Executed payments (except card payments via Stripe, since Stripe sends its own notifications). Contact [support@finverse.com](mailto:support@finverse.com) for the full list of email notifications sent by Finverse. external_user_id: type: string description: >- Customer App's unique ID for the user. This ID is used to identify returning users across user sessions and load the user's previously stored Payment Method and settings. For example, a returning user can: \- Directly pay a Payment Link (in `mode`\= `payment`) using their stored Payment Method, without re-entering payment details. - Use a Payment Link to edit their stored Payment Method. \- Use a Payment Link to turn Autopay on/off (by editing their Autopay consent), if allowed by the Customer App. integration_metadata: $ref: '#/components/schemas/IntegrationMetadataResponse' metadata: description: >- Customer-supplied attributes in key:value format. E.g. `employer_name`: `Apple Inc` type: object additionalProperties: type: string name: type: string description: >- User's name or nickname (note: this does not need to exactly match the accountholder name of the user's account; however accountholder name inputs may be verified against this value). next_bill_update: type: string format: date-time nullable: true description: >- Timestamp when Finverse is scheduled to attempt to fetch the next bill/invoice for this user. Bill/invoice ingestion is one of the available methods for Finverse to initiate Autopay bill collections on each bill due date, using the user's saved payment method(s). Note: bills will only be fetched if the Customer App has configured a 3rd party ERP/CRM or Accounting integration, enabling Finverse to fetch bill/invoice data from the 3rd party source (e.g. Xero, RapidStor). Contact [support@finverse.com](mailto:support@finverse.com) to discuss 3rd party bill/invoice integrations and Autopay flows. updated_at: type: string format: date-time description: Timestamp when the Payment User object was last updated user_details: type: array items: $ref: '#/components/schemas/SenderDetail' description: Additional information about the user's identity user_id: type: string description: Finverse unique ID for the user. user_type: type: string enum: - INDIVIDUAL - BUSINESS description: >- Type of user (used to determine what user authentication inputs are required, e.g. individual ID vs. company registration details). Possible values: `INDIVIDUAL`, `BUSINESS` ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' IntegrationMetadataPaymentUserRequest: required: - integration_id properties: integration_id: type: string enum: - RAPIDSTOR rapidstor_metadata: $ref: '#/components/schemas/RapidstorPaymentUserMetadataRequest' CreateMetadata: type: object additionalProperties: type: string maxLength: 1000 SenderDetail: properties: details_type: description: >- Type of the user identity information submitted. Possible values: `HK_ID`, `PASSPORT`, `HK_BUSINESS_REGISTRATION`, `HK_CERTIFICATE_OF_INCORPORATION`, `ACCOUNTHOLDER_NAME` type: string enum: - HK_ID - PASSPORT - HK_BUSINESS_REGISTRATION - HK_CERTIFICATE_OF_INCORPORATION values: description: >- Value(s) of the user identity information submitted. Min 1 value required, max 10 values. Values in responses are tokenized by Finverse. type: array maxItems: 10 items: type: string IntegrationMetadataResponse: properties: integration_id: type: string enum: - RAPIDSTOR rapidstor_metadata: $ref: '#/components/schemas/RapidstorMetadataResponse' 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 RapidstorPaymentUserMetadataRequest: allOf: - $ref: '#/components/schemas/RapidstorMetadataRequest' - type: object required: - tenant_default_currency properties: tenant_default_currency: type: string RapidstorMetadataResponse: properties: account_token: type: string corp_code: type: string i_anniv_days: type: number format: int32 s_location_code: type: string tenant_default_currency: type: string tenant_id: type: string unit_type_id: type: string RapidstorMetadataRequest: required: - corp_code - s_location_code - tenant_id - account_token properties: account_token: type: string minimum: 1 corp_code: type: string i_anniv_days: type: number format: int32 maximum: 31 minimum: 1 s_location_code: type: string tenant_id: type: string unit_type_id: type: string 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 ````