> ## 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 Mandate > Create a Mandate (i.e. pre-authorization) that will be used to make payments, without any existing/known sender account details (the end-user will be requested to input these in the mandate authorization UI). `Idempotency-Key` header is **required**. This makes it safe to retry the request without re-triggering the underlying create Mandate operation. Any retries will return the same Mandate response as the first request using the same key. **Authorization**: `customer_token` ### mandate_details (object, required) Details describing the Mandate. ### payment_schedule (object, optional) RESERVED FOR FUTURE USE - Specifies scheduled auto-payments with the specified amounts and dates. ### transaction_limits (object, optional) Specifies custom limits on payment transactions executed under the Mandate. ### recipient_account (object, required) Details on the recipient account of the payment (i.e. the Customer App's receiving account). ### sender (object, required) Details on the sender of the payment. ### user_details (array of objects, optional) Additional information about the user's identity, used for validating any end-user submitted identity details in the Finverse Link UI. ## Response fields The response is a Mandate object. Refer to Mandate object data model in `GET /mandates/{mandate_id}`. ## OpenAPI ````yaml /api-reference/openapi.json post /mandates 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: /mandates: post: tags: - mandates summary: Create Mandate description: >- Create a Mandate (i.e. pre-authorization) that will be used to make payments, without any existing/known sender account details (the end-user will be requested to input these in the mandate authorization UI). `Idempotency-Key` header is **required**. This makes it safe to retry the request without re-triggering the underlying create Mandate operation. Any retries will return the same Mandate response as the first request using the same key. **Authorization**: `customer_token` ### mandate_details (object, required) Details describing the Mandate. ### payment_schedule (object, optional) RESERVED FOR FUTURE USE - Specifies scheduled auto-payments with the specified amounts and dates. ### transaction_limits (object, optional) Specifies custom limits on payment transactions executed under the Mandate. ### recipient_account (object, required) Details on the recipient account of the payment (i.e. the Customer App's receiving account). ### sender (object, required) Details on the sender of the payment. ### user_details (array of objects, optional) Additional information about the user's identity, used for validating any end-user submitted identity details in the Finverse Link UI. ## Response fields The response is a Mandate object. Refer to Mandate object data model in `GET /mandates/{mandate_id}`. operationId: createMandate parameters: - description: >- A random key provided by the customer, per unique payment. The purpose for the Idempotency key is to allow safe retrying without the operation being performed multiple times. name: Idempotency-Key in: header schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateMandateRequest' description: request body for creating mandate required: true responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/CreateMandateResponse' examples: success: summary: Success value: created_at: '2024-03-28T15:06:10.744Z' fees: [] mandate_details: currency: HKD description: Test Mandate end_date: '2024-12-01' start_date: '2024-03-28' transaction_limits: max_period_amount: 10000 max_period_count: 10 max_transaction_amount: 10000 period: MONTHLY mandate_id: 01HT2SHP6DQJ3A4MTR6V5RVDYR metadata: employer_name: Apple Inc key: value payment_method_id: 01HT2SHPDAFZCHPVCDJ2Z99GX8 recipient: name: Demo App recipient_account: account_id: 01H5VH5YCFDVH80YZ8D0TG3HET account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1 name: John Doe user_details: - details_type: HK_ID values: - 01HT2SHPCXQNGDGEHTHXTKAB90 user_id: 01GWKTK0380NBRCV1B8D6N0SEH user_type: INDIVIDUAL status: AUTHORIZATION_REQUIRED updated_at: '2024-03-28T15:06:10.730Z' '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' examples: invalid_parameter: summary: Error (invalid parameter) value: error: details: sender.user_type required error_code: INVALID_PARAMETER message: The parameters provided are invalid. See details. request_id: '{unique_id}' type: API_ERROR invalid_input: summary: Error (invalid input) value: error: details: EndDate specified is before today (UTC)! error_code: INVALID_INPUT message: >- Invalid parameter value(s). Please review parameter inputs. request_id: '{unique_id}' type: API_ERROR invalid_recipient_account: summary: Error (invalid Recipient Account) value: error: details: >- Invalid recipient_account_id value. Verify your recipient_account_id. error_code: INVALID_INPUT message: >- Invalid parameter value(s). Please review parameter inputs. request_id: '{unique_id}' type: API_ERROR '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' security: - Oauth2: - mandate:create components: schemas: CreateMandateRequest: required: - recipient_account - sender - mandate_details properties: mandate_details: $ref: '#/components/schemas/MandateDetailsRequest' description: Details on the mandate metadata: $ref: '#/components/schemas/CreateMetadata' description: >- Customer-supplied attributes in key:value format. E.g. `employer_name`: `Apple Inc` recipient_account: $ref: '#/components/schemas/MandateRecipientRequest' description: >- Details on the recipient of the payment (i.e. the Customer App's receiving account) sender: $ref: '#/components/schemas/CreateMandateSender' description: Details on the sender of the payment CreateMandateResponse: required: - updated_at - mandate_id - status - recipient - sender - mandate_details properties: created_at: description: Timestamp in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ) type: string format: date-time error: $ref: '#/components/schemas/FvEmbeddedErrorModel' fees: type: array items: $ref: '#/components/schemas/Fee' mandate_details: $ref: '#/components/schemas/MandateDetailsResponse' mandate_id: description: Finverse Mandate ID (ULID) type: string metadata: description: >- Additional attributes of the mandate in key:value format (e.g. mandate_internal_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 payment_method_id: description: Finverse Payment Method ID (ULID) type: string recipient: $ref: '#/components/schemas/MandateRecipient' recipient_account: $ref: '#/components/schemas/MandateRecipientAccount' sender: $ref: '#/components/schemas/GetMandateSender' sender_account: $ref: '#/components/schemas/MandateSenderAccount' status: description: Mandate status type: string enum: - AUTHORIZATION_REQUIRED - AUTHORIZING - PROCESSING - SUBMITTED - SUCCEEDED - FAILED - REVOKED - READY_TO_SUBMIT - CLOSED - CANCELLED updated_at: description: Timestamp in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ) type: string format: date-time ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' MandateDetailsRequest: required: - currency properties: currency: description: Currency of the mandate (e.g. HKD) type: string description: description: User-facing description for the mandate type: string end_date: description: >- Expiration date of the mandate, e.g. `2022-12-31`. Payment requests will be allowed up to this date (inclusive). All date inputs assume UTC times (e.g. if `end_date` = `2022-12-31`, then a payment will be allowed until 2022-12-31 at 23:59:59 UTC). `end_date` must be equal to or greater than `start_date` (in UTC). type: string format: date nullable: true mandate_bank_reference: description: A bank specific reference, what the end user may see type: string payment_schedule: $ref: '#/components/schemas/PaymentSchedule' description: RESERVED FOR FUTURE USE - Specifies scheduled auto-payments start_date: description: >- Start date of the mandate, e.g. `2022-06-01`. Payment requests will be allowed from this date onwards (inclusive). All date inputs assume UTC times (e.g. if `start_date` = `2022-06-01`, then a payment will be allowed starting from 2022-06-01 at 00:00:00 UTC). `start_date` must be equal to or greater than today's date (in UTC). type: string format: date nullable: true transaction_limits: $ref: '#/components/schemas/TransactionLimitsRequest' description: Specifies custom limits per payment transaction CreateMetadata: type: object additionalProperties: type: string maxLength: 1000 MandateRecipientRequest: required: - account_id properties: account_id: description: Unique ID for the sender account type: string maxLength: 100 CreateMandateSender: required: - email properties: email: type: string format: email external_user_id: description: Customer App's unique ID for the sender. type: string name: type: string description: >- Sender's name or nickname (note: this does not need to exactly match the accountholder name of the sender's account; however accountholder name inputs may be verified against this value). user_details: description: Additional information about the user's identity type: array maxItems: 10 items: $ref: '#/components/schemas/SenderDetail' user_type: description: >- Type of sender (used to determine what sender authentication inputs are required, e.g. individual ID vs. company registration details). Possible values: `INDIVIDUAL`, `BUSINESS` type: string enum: - INDIVIDUAL - BUSINESS FvEmbeddedErrorModel: required: - type - error_code - message - details properties: details: type: string error_code: type: string example: CREDENTIALS_INVALID message: type: string type: description: The error type type: string enum: - LINK_ERROR - API_ERROR example: LINKING_ERROR Fee: required: - amount properties: amount: description: Amount of the fee (in minor currency unit) type: integer example: 100 currency: type: string example: HKD description: Currency of the fee (e.g. HKD) paid_by: type: string enum: - RECIPIENT - SENDER example: RECIPIENT description: >- Party who will be charged the fee. Possible values: `RECIPIENT`, `SENDER` paid_by_account_id: description: >- Finverse Payment Account ID of the party who will be charged the fee. This references the `account_id` of either the `recipient_account` or the `sender_account`. type: string example: The payment account ID MandateDetailsResponse: required: - currency properties: collection_entity_name: type: string description: >- Name of the legal entity directly collecting the payment. This name may be displayed to users in the Finverse UI and in email notifications and in the sender's bank statements. For direct debit payments directly collected by the merchant (e.g. SG eGIRO payments), `collection_entity_name` is typically the merchant's legal entity name, configured by Finverse during customer onboarding. Contact [support@finverse.com](mailto:support@finverse.com) to configure your merchant details. For direct debit payments collected through Finverse (e.g. HK eDDA payments), `collection_entity_name` will be the same as `processor_entity_name` currency: description: Currency of the mandate (e.g. HKD) type: string dda_reference: description: >- Unique reference ID for the Direct Debit Authorization registered with the user's bank. The user's bank may quote this reference in notifications to the user, and in direct debit payment records on the user's bank statements. type: string description: description: User-facing description for the mandate type: string end_date: description: >- Expiration date of the mandate, e.g. `2022-12-31`. Payment requests will be allowed up to this date (inclusive). All date inputs assume UTC times (e.g. if `end_date` = `2022-12-31`, then a payment will be allowed until 2022-12-31 at 23:59:59 UTC). `end_date` must be equal to or greater than `start_date` (in UTC). type: string format: date nullable: true mandate_bank_reference: description: >- Bank-generated reference for the mandate, usually shown to senders on their bank notifications or statements. Only returned once mandate has been processed successfully by the sender's bank (i.e. mandate `status`\= `SUCCESSFUL`). type: string payment_schedule: $ref: '#/components/schemas/PaymentSchedule' description: RESERVED FOR FUTURE USE - Specifies scheduled auto-payments processor_entity_name: type: string description: >- Name of the payment processor (if any) through which the payment is collected. This name may be displayed to users in the Finverse UI, in email notifications and in the sender's bank statements. For direct debit payments directly collected by the merchant (e.g. SG eGIRO payments), no `processor_entity_name` is returned. For direct debit payments collected through Finverse (e.g. HK eDDA payments), `processor_entity_name` will be Finverse's legal entity name. start_date: description: >- Start date of the mandate, e.g. `2022-06-01`. Payment requests will be allowed from this date onwards (inclusive). All date inputs assume UTC times (e.g. if `start_date` = `2022-06-01`, then a payment will be allowed starting from 2022-06-01 at 00:00:00 UTC). `start_date` must be equal to or greater than today's date (in UTC). type: string format: date nullable: true transaction_limits: $ref: '#/components/schemas/TransactionLimitsResponse' description: Specifies custom limits per payment transaction MandateRecipient: required: - name properties: name: description: Merchant account name type: string MandateRecipientAccount: required: - account_id - account_type properties: account_id: description: Merchant account ID assigned by Finverse type: string account_type: description: Type of recipient account. type: string enum: - EXTERNAL_ACCOUNT - SETTLEMENT_ACCOUNT example: SETTLEMENT_ACCOUNT GetMandateSender: required: - user_id - external_user_id - user_type properties: external_user_id: description: >- Customer App's user ID, representing the end-user making the payment. type: string name: type: string user_details: description: Sender details which will be used for fraud checking. type: array items: $ref: '#/components/schemas/SenderDetail' user_id: description: A unique identifier generated after creating sender type: string user_type: description: >- Type of account held by the Sender at the Institution. Possible values are INDIVIDUAL, BUSINESS type: string enum: - INDIVIDUAL - BUSINESS MandateSenderAccount: type: object properties: account_id: description: A unique identifier generated after creating sender account type: string example: sender_account_id account_number: $ref: '#/components/schemas/RecipientAccountNumber' description: Bank account number details, including account number in plaintext account_number_masked: description: Masked Account number of the sender’s account type: string account_type: description: Type of sender account. type: string enum: - EXTERNAL_ACCOUNT example: EXTERNAL_ACCOUNT accountholder_name: description: Tokenized accountholder name of the sender's account type: string example: 01EP4A1MZDHKETZFRPF0K62S6S accountholder_name_plaintext: description: Accountholder name in plaintext. type: string example: Chan Li Pak nullable: true bank_code: type: string institution_id: description: Finverse Institution ID for the sender’s institution. type: string example: hsbc-hk institution_name: description: Institution Name for the sender’s institution. type: string example: HSBC 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 user_id: description: >- A unique identifier generated after creating sender (Finverse Payment User ID) type: string example: 01GY6H0JA7BS8EVGY56NSHFX2E 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 PaymentSchedule: required: - amount - frequency properties: amount: description: Amount of the scheduled payment in major currency type: integer example: 100 frequency: description: >- Frequency of the scheduled payment. Possible values: `DAILY`, `WEEKLY`, `MONTHLY` type: string enum: - DAILY - WEEKLY - MONTHLY - QUARTERLY - YEARLY TransactionLimitsRequest: required: - max_transaction_amount properties: max_period_amount: description: >- Maximum cumulative amount (in minor currency unit) of payment transactions (for the specified `period` unit) type: integer minimum: 1 max_period_count: description: >- Maximum number of payment transactions (for the specified `period` unit) type: integer minimum: 1 max_transaction_amount: description: >- Maximum amount per single payment transaction (in minor currency unit). If not specified, the default limits are: (i) Mandates with `sender_type` = `INDIVIDUAL`: CNY 5,000, HKD 5,000, SGD 1,000, USD 1,000 (ii) Mandates with `sender_type` = `BUSINESS`: CNY 20,000, HKD 20,000, SGD 3,000, USD 3,000 type: integer minimum: 1 period: description: Required when providing `max_period_amount` or `max_period_count` type: string enum: - DAILY - WEEKLY - MONTHLY - QUARTERLY - YEARLY nullable: true 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 TransactionLimitsResponse: properties: max_period_amount: description: >- Maximum cumulative amount (in minor currency unit) of payment transactions (for the specified `period` unit) type: integer minimum: 1 max_period_count: description: >- Maximum number of payment transactions (for the specified `period` unit) type: integer minimum: 1 max_transaction_amount: description: >- Maximum amount per single payment transaction, set by your Customer App (in minor currency units). Note: to avoid your Customer App triggering over-limit payments, Finverse will block any `POST /payments` requests exceeding the `max_transaction_amount` Banks may separately apply their own per transaction limit (see `max_transaction_amount_set_by_payer_initial` below) type: integer minimum: 1 max_transaction_amount_set_by_payer_initial: description: >- Maximum amount per single payment transaction, optionally set by the end-user at the time of direct debit mandate creation, e.g. for eGIRO in Singapore (in minor currency units). Note: Finverse will attempt to submit `POST /payments` requests to banks even when the payment amount exceeds this limit, however you should expect the end-user's bank will reject over-limit payemnt requests, unless the user directly updates their limit through their bank (e.g. through their bank's internet banking portal > eGIRO management page). Finverse separately applies its own per transaction limit (see `max_transaction_limit` above) type: integer nullable: true period: description: Returned if `max_period_amount` or `max_period_count` are set. type: string enum: - DAILY - WEEKLY - MONTHLY - QUARTERLY - YEARLY nullable: true 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 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 ````