> ## 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 Link > Create new Payment Link. To avoid duplicate payments, you must provide a `unique_reference_id` which uniquely identifies the bill/invoice being paid. This allows you to safely create/retry Payment Links multiple times using the same `unique_reference_id`, for example if a user restarts the payment flow on a different device. Finverse will only allow a single payment per `unique_reference_id`. See "Implementation guidance" section below for additional details on how to generate a `unique_reference_id`. **Authorization**: `customer_token` ### integration_metadata (object, optional) Use the following optional parameters to pass custom values for Finverse-supported integrations (e.g. ERP/CRM/accounting integrations). ### link_customizations (object, optional) You can use the following optional parameters to customize the behaviour of Finverse Link's UI to fit your implementation requirements. ### payment_details (object, conditionally required) Details describing the Payment transaction. Required if `mode` = `PAYMENT`. ### payment_setup_options (object, conditionally required) Additional parameters to configure payment methods and future payments. Required if `mode` = `SETUP`. #### **Impact of** **`future_payments`** **on payment methods displayed** When enabling `future_payments`: - In `mode` = `SETUP`: the Finverse Link UI will only display payment methods which support recurring "pull" payments (e.g direct debit & cards). - In `mode` = `PAYMENT`, the Finverse Link UI will continue to show all available payment methods, including one-time payment methods (in order to encourage payment completion). - The future payments setting will only apply if the user selects a payment method which supports recurring payments (e.g. direct debit or cards). - To enable future payments and display only recurring payment methods, use the (optional) `payment_method_types` filter to explicitly limit the payment methods displayed. ### autopay_enrollment_configurations **(object, optional)** Configures the FInverse Link UI to enroll users into autopay (i.e. collects consent for future payments). This controls whether the Finverse UI will prompt users to opt-in to autopay, when autopay is not already enforced (i.e. when `future_payments` ≠ `AUTOPAY`). When a user consents to autopay, the payment user property `autopay_consent` is set to `true`, which allows: - User can be charged for payments (using `POST /payments`) without obtaining additional user consent for each charge; - Finverse can automatically initiate charges on bill/invoice due dates (for customer apps where Finverse ingests bill/invoices via ERP integrations or API). Note: `autopay_enrollment_configurations` cannot be set when `future_payments` = `AUTOPAY` (since this already enforces autopay for all users; no autopay enrollment screen is shown). ### mandate_details (object, optional) Optional configurations for any direct debit mandate setup by the user. ### receipient_account_filters (object, optional) Optional filter to narrow the list of accounts receiving money (also called "settlement accounts"). This is typically used for more complex payment scenarios, for example when a Customer App needs multiple settlement accounts: - For different business units, or - With different collection fee rules (e.g. with or without transaction fee surcharges paid by senders) In these cases the Customer App can use `recipient_account_filters` to explicitly filter the receiving accounts matching its business requirements. Note: settlement accounts are configured by Finverse during initial onboarding of each Customer App. By default, Finverse creates 1 recipient account per payment method. Contact [support@finverse.com](mailto:support@finverse.com) if you have complex payment flows, use cases or business units which may benefit from setting up multiple settlement accounts. ### sender (object, required) Details on the sender of the payment. View More ## Response fields The response is a Payment Link object. Refer to Payment Link object data model in `GET /payments_links/{payment_link_id}`. ## Implementation guidance #### **Handling retries/revisit and avoiding duplicate payments: using** **`unique_reference_id as idempotency key`** - To enable retries/revisit, Finverse allows creating payment links using a previously-used `unique_reference_id`, if all payment link details are identical (amount, etc). This returns the same payment link ID and URL as originally created. This allows using `unique_reference_id` similarly to an idempotency key. - To avoid duplicate payments, Finverse will only allow 1 executed payment per `unique_reference_id`. - When a user revisits a payment link, the Finverse Link UI will show end-users a “Payment in progress” screen if a payment is already pending for the same `unique_reference_id`. - Example: if a user revisits a payment link after previously using the payment link to setup a direct debit mandate => the user will see "Payment in progress" if the direct debit mandate is still being processed; a payment will automatically be executed when the direct debit mandate becomes successful. - `unique_reference_id` generation: we recommend generating `unique_reference_id` based on a composite/hash of the key payment details. The composite/hash should include any payment link details that could change between 2 user sessions, for example: - Bill/invoice/purchase reference (`external_transaction_reference`) - Payment `amount` - Sender details (`sender.name`, `sender.email`) - Metadata (`metadata`, `payment_metadata`). - This ensures that a new `unique_reference_id` is generated if any payment link details are modified (for example if the amount is updated or if the user changes their name/email between 2 user sessions). - If a payment link creation request is sent using an existing `unique_reference_id` but different payment link details, the following API error will be returned: ``` json // HTTP 400 Bad Request { "error": { "details": "Trying to update existing paymentLink. Not supported.", "error_code": "INVALID_PARAMETER", "message": "The parameters provided are invalid. See details.", "request_id": "1689652320", "type": "API_ERROR" } } ``` ## OpenAPI ````yaml /api-reference/openapi.json post /payment_links 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_links: post: tags: - payment_links summary: Create Payment Link description: >- Create new Payment Link. To avoid duplicate payments, you must provide a `unique_reference_id` which uniquely identifies the bill/invoice being paid. This allows you to safely create/retry Payment Links multiple times using the same `unique_reference_id`, for example if a user restarts the payment flow on a different device. Finverse will only allow a single payment per `unique_reference_id`. See "Implementation guidance" section below for additional details on how to generate a `unique_reference_id`. **Authorization**: `customer_token` ### integration_metadata (object, optional) Use the following optional parameters to pass custom values for Finverse-supported integrations (e.g. ERP/CRM/accounting integrations). ### link_customizations (object, optional) You can use the following optional parameters to customize the behaviour of Finverse Link's UI to fit your implementation requirements. ### payment_details (object, conditionally required) Details describing the Payment transaction. Required if `mode` = `PAYMENT`. ### payment_setup_options (object, conditionally required) Additional parameters to configure payment methods and future payments. Required if `mode` = `SETUP`. #### **Impact of** **`future_payments`** **on payment methods displayed** When enabling `future_payments`: - In `mode` = `SETUP`: the Finverse Link UI will only display payment methods which support recurring "pull" payments (e.g direct debit & cards). - In `mode` = `PAYMENT`, the Finverse Link UI will continue to show all available payment methods, including one-time payment methods (in order to encourage payment completion). - The future payments setting will only apply if the user selects a payment method which supports recurring payments (e.g. direct debit or cards). - To enable future payments and display only recurring payment methods, use the (optional) `payment_method_types` filter to explicitly limit the payment methods displayed. ### autopay_enrollment_configurations **(object, optional)** Configures the FInverse Link UI to enroll users into autopay (i.e. collects consent for future payments). This controls whether the Finverse UI will prompt users to opt-in to autopay, when autopay is not already enforced (i.e. when `future_payments` ≠ `AUTOPAY`). When a user consents to autopay, the payment user property `autopay_consent` is set to `true`, which allows: - User can be charged for payments (using `POST /payments`) without obtaining additional user consent for each charge; - Finverse can automatically initiate charges on bill/invoice due dates (for customer apps where Finverse ingests bill/invoices via ERP integrations or API). Note: `autopay_enrollment_configurations` cannot be set when `future_payments` = `AUTOPAY` (since this already enforces autopay for all users; no autopay enrollment screen is shown). ### mandate_details (object, optional) Optional configurations for any direct debit mandate setup by the user. ### receipient_account_filters (object, optional) Optional filter to narrow the list of accounts receiving money (also called "settlement accounts"). This is typically used for more complex payment scenarios, for example when a Customer App needs multiple settlement accounts: - For different business units, or - With different collection fee rules (e.g. with or without transaction fee surcharges paid by senders) In these cases the Customer App can use `recipient_account_filters` to explicitly filter the receiving accounts matching its business requirements. Note: settlement accounts are configured by Finverse during initial onboarding of each Customer App. By default, Finverse creates 1 recipient account per payment method. Contact [support@finverse.com](mailto:support@finverse.com) if you have complex payment flows, use cases or business units which may benefit from setting up multiple settlement accounts. ### sender (object, required) Details on the sender of the payment. View More ## Response fields The response is a Payment Link object. Refer to Payment Link object data model in `GET /payments_links/{payment_link_id}`. ## Implementation guidance #### **Handling retries/revisit and avoiding duplicate payments: using** **`unique_reference_id as idempotency key`** - To enable retries/revisit, Finverse allows creating payment links using a previously-used `unique_reference_id`, if all payment link details are identical (amount, etc). This returns the same payment link ID and URL as originally created. This allows using `unique_reference_id` similarly to an idempotency key. - To avoid duplicate payments, Finverse will only allow 1 executed payment per `unique_reference_id`. - When a user revisits a payment link, the Finverse Link UI will show end-users a “Payment in progress” screen if a payment is already pending for the same `unique_reference_id`. - Example: if a user revisits a payment link after previously using the payment link to setup a direct debit mandate => the user will see "Payment in progress" if the direct debit mandate is still being processed; a payment will automatically be executed when the direct debit mandate becomes successful. - `unique_reference_id` generation: we recommend generating `unique_reference_id` based on a composite/hash of the key payment details. The composite/hash should include any payment link details that could change between 2 user sessions, for example: - Bill/invoice/purchase reference (`external_transaction_reference`) - Payment `amount` - Sender details (`sender.name`, `sender.email`) - Metadata (`metadata`, `payment_metadata`). - This ensures that a new `unique_reference_id` is generated if any payment link details are modified (for example if the amount is updated or if the user changes their name/email between 2 user sessions). - If a payment link creation request is sent using an existing `unique_reference_id` but different payment link details, the following API error will be returned: ``` json // HTTP 400 Bad Request { "error": { "details": "Trying to update existing paymentLink. Not supported.", "error_code": "INVALID_PARAMETER", "message": "The parameters provided are invalid. See details.", "request_id": "1689652320", "type": "API_ERROR" } } ``` operationId: CreatePaymentLink requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentLinkRequest' examples: create_payment_link: summary: Create Payment Link value: amount: 100 currency: HKD link_customizations: countries: [] institution_status: '' language: en link_mode: '' redirect_uri: '' ui_mode: '' mode: PAYMENT payment_details: description: TEST Payment external_transaction_reference: INV12345 sender: email: info+test@finverse.com external_user_id: user_id_1||{{$timestamp}} name: John Doe unique_reference_id: Inv12345|{{$timestamp}} create_payment_link_in_setup_mode: summary: Create Payment Link in Setup Mode value: currency: HKD link_customizations: countries: [] institution_status: '' language: en link_mode: '' redirect_uri: '' ui_mode: '' mode: SETUP payment_setup_options: future_payments: AUTOPAY sender: email: info+test@finverse.com external_user_id: user_id_1||{{$timestamp}} name: John Doe unique_reference_id: User12345|{{$timestamp}} description: Parameters required to create a payment link required: true responses: '200': description: Success (payment mode, future payments disabled) content: application/json: schema: $ref: '#/components/schemas/PaymentLinkResponse' examples: payment_mode_future_payments_disabled: summary: Success (payment mode, future payments disabled) value: amount: 10000 created_at: '2024-11-08T04:10:33.481Z' currency: HKD link_customizations: language: en metadata: key: value tracking_flow: webapp-checkout mode: PAYMENT payment_details: description: TEST Payment external_transaction_reference: INV12345 payment_link_id: 01JC4ZEY49TPX2TQXXXTWB37AT payment_metadata: contract_id: '1234' key: value storeganise_invoice_ids: ABCD user_address: 1 Admiralty Drive user_city: Hong Kong user_country: HK user_first_name: John user_last_name: Doe sender: email: info+test@finverse.com external_user_id: user_id_1||1731039033 name: John Doe user_id: 01JC4ZEY4Q7TGG1MGAYQZC6P4B session_status: OPEN status: CREATED unique_reference_id: Inv12345|1731039033 updated_at: '2024-11-08T04:10:33.481Z' url: >- https://pay.prod.finverse.net/link/01JC4ZEY49TPX2TQXXXTWB37AT payment_mode_future_payments_enabled: summary: Success (payment mode, future payments enabled) value: amount: 10000 created_at: '2024-11-08T04:12:19.103Z' currency: HKD link_customizations: language: en metadata: key: value tracking_flow: webapp-checkout mode: PAYMENT payment_details: description: TEST Payment external_transaction_reference: INV12345 payment_link_id: 01JC4ZJ58ZKXPVDSPDKCP27FKM payment_metadata: contract_id: '1234' key: value storeganise_invoice_ids: ABCD user_address: 1 Admiralty Drive user_city: Hong Kong user_country: HK user_first_name: John user_last_name: Doe payment_setup_options: future_payments: CLICK_TO_PAY payment_method_types: - CARD - MANDATE - MANUAL sender: email: info+test@finverse.com external_user_id: user_id_1||1731039139 name: John Doe user_id: 01JC4ZJ5998NHNZ0CV6KNSYECF session_status: OPEN status: CREATED unique_reference_id: Inv12345|1731039139 updated_at: '2024-11-08T04:12:19.103Z' url: >- https://pay.prod.finverse.net/link/01JC4ZJ58ZKXPVDSPDKCP27FKM setup_mode: summary: Success (setup mode) value: created_at: '2024-11-08T04:08:42.719Z' currency: HKD link_customizations: language: en metadata: key: value tracking_flow: webapp-checkout mode: SETUP payment_details: description: '' external_transaction_reference: '' payment_link_id: 01JC4ZBHYZMJ470WSVFSM7JRRA payment_metadata: user_address: 1 Admiralty Drive user_city: Hong Kong user_country: HK user_first_name: John user_last_name: Doe payment_setup_options: future_payments: AUTOPAY payment_method_types: - CARD - MANDATE - MANUAL sender: email: info+test@finverse.com external_user_id: user_id_1||1731038922 name: John Doe user_id: 01JC4ZBHZC3476P3482CCC7D85 session_status: OPEN status: CREATED unique_reference_id: User12345|1731038922 updated_at: '2024-11-08T04:08:42.719Z' url: >- https://pay.prod.finverse.net/link/01JC4ZBHYZMJ470WSVFSM7JRRA '400': description: Error (reused unique_reference_id with different request body) content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' examples: reused_unique_reference_id_with_different_request_body: summary: >- Error (reused unique_reference_id with different request body) value: error: details: Trying to update existing paymentLink. Not supported. error_code: INVALID_PARAMETER message: The parameters provided are invalid. See details. request_id: '1689652320' type: API_ERROR mismatch_between_existing_sender_name_and_external_user_id: summary: >- Error (mismatch between existing sender name and external_user_id) value: error: details: >- Sender external_user_id already exists, but matches a different sender name. Please check your sender inputs or provide a new sender external_user_id. error_code: INVALID_PARAMETER message: The parameters provided are invalid. See details. request_id: '1689652320' type: API_ERROR reused_unique_reference_id_with_different_request_body_2: summary: >- Error (reused unique_reference_id with different request body) value: error: details: Trying to update existing paymentLink. Not supported. error_code: INVALID_PARAMETER message: The parameters provided are invalid. See details. request_id: '1689652320' type: API_ERROR '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' security: - Oauth2: - paymentlink:create components: schemas: CreatePaymentLinkRequest: required: - currency - mode - sender - unique_reference_id properties: amount: description: >- Amount of the payment (in minor currency unit). Required if `mode` = `PAYMENT`. type: integer minimum: 1 example: 100 currency: type: string maxLength: 3 minLength: 3 example: HKD description: Currency of the payment (e.g. HKD) integration_metadata: $ref: '#/components/schemas/IntegrationMetadataRequest' description: >- Optional parameters to pass custom values for Finverse-supported integrations (e.g. ERP/CRM/accounting integrations) link_customizations: $ref: '#/components/schemas/PaymentLinkCustomizations' description: >- Optional parameters to customize the behaviour of Finverse Link's UI to fit your implementation requirements metadata: $ref: '#/components/schemas/CreateMetadata' description: >- Customer-supplied attributes in key:value format. E.g. `contract_id: 1234` mode: description: >- Specified payment link mode. **Accepted values:** \- `PAYMENT`: payment link is used to collect the specified payment amount now; \- `SETUP`: payment link is used to register a payment method to be charged later (using `POST /payments`). type: string enum: - PAYMENT - SETUP example: PAYMENT payment_details: $ref: '#/components/schemas/PaymentLinkDetails' description: Details on the payment Only used if `mode` = `PAYMENT`. payment_metadata: $ref: '#/components/schemas/CreateMetadata' description: >- Customer-supplied attributes associated with the payment, in key:value format. Use this to pass any information you later need to tie a successful payment back to its original context (e.g. user, bill, invoice, checkout). E.g. `contract_id: 1234`. These attributes will be added as `metadata` on any payment object directly created by the Payment Link, and will be included in: (i) any API response with a payment object; (ii) Payments webhooks; and (iii) Finverse's reporting (e.g. statements issued to customer apps). Only used if `mode` = `PAYMENT`. Will be ignored if `mode` = `SETUP`. payment_setup_options: $ref: '#/components/schemas/PaymentSetupOptionsRequest' description: >- Additional parameters to configure payment methods and future payments Required if `mode` = `SETUP`. sender: $ref: '#/components/schemas/PaymentLinkSender' description: Details on the sender of the payment unique_reference_id: description: >- Customer-supplied string, uniquely identifying the payment to be collected. See “_Handling retries and avoiding duplicate payments_” below. type: string minLength: 1 PaymentLinkResponse: properties: amount: description: >- Amount of the payment (in minor currency unit). Only returned if `mode` = `PAYMENT`. type: integer example: 100 created_at: description: Timestamp when the payment link was first created type: string format: date-time currency: type: string example: HKD description: Currency of the payment (e.g. HKD) integration_metadata: $ref: '#/components/schemas/IntegrationMetadataResponse' link_customizations: $ref: '#/components/schemas/PaymentLinkCustomizations' description: >- Optional parameters to customize the behaviour of Finverse Link's UI to fit your implementation requirements. See `POST /payment_links`. metadata: description: >- Customer-supplied attributes in key:value format. E.g. `contract_id: 1234`. type: object additionalProperties: type: string mode: description: >- Specified payment link mode. **Possible values:** \- `PAYMENT`: payment link is used to collect the specified payment amount now; \- `SETUP`: payment link is used to register a payment method to be charged later (using `POST /payments`). type: string enum: - PAYMENT example: PAYMENT payment: $ref: '#/components/schemas/PaymentResponse' description: >- Latest Payment object (if any) associated with the payment link Only returned if `mode` = `PAYMENT`. payment_details: $ref: '#/components/schemas/PaymentLinkDetails' description: Details on the payment Only returned if `mode` = `PAYMENT`. payment_link_id: description: >- Finverse Payment Link ID for this payment link. Always unique. Creating a payment link with different `unique_reference_id` values will result in two payment links with different IDs. type: string payment_metadata: description: >- Customer-supplied attributes in key:value format, to facilitate payment reconciliation. E.g. `contract_id: 1234`. These will be added as `metadata` on any Payment object directly created by the Payment Link, and will be included in Finverse's reporting (e.g. statements issued to customer apps). Only used if `mode` = `PAYMENT`. Will be ignored if `mode` = `SETUP`. type: object additionalProperties: type: string payment_method: $ref: '#/components/schemas/PaymentMethodResponse' description: Details on the payment method authorized by the end-user payment_setup_options: $ref: '#/components/schemas/PaymentSetupOptions' description: >- Additional parameters recording how payment methods and future payments have been configured sender: $ref: '#/components/schemas/PaymentLinkSenderResponse' description: Details on the sender of the payment session_status: description: >- Current session status of the payment link. Possible values: `OPEN`, `PROCESSING`, `COMPLETE`, `FAILED`. Session status returns interim status details on a payment link in `status` = `CREATED`: \- Session status starts as `OPEN`, then may progress to `PROCESSING` (indicating an async payment method or payment is currently processing), `COMPLETE` (for successful payment links), or `FAILED` (for failed payment method setup or payments). \- Session status is computed at read-time based on the status of any payment method setup or payment initiated by the payment link, until the payment link is successful. \- Session status may reset if a user retries a payment method setup or payment using the same payment link until it is successful (e.g. session_status may go from `FAILED` > `PROCESSING`, `FAILED` > `COMPLETE`, etc). \- The final `session_status` is `COMPLETE`, which corresponds to payment link `status` = `PAID` or `SETUP_SUCCEEDED`. We recommend using the payment link `status` as the primary indicator of payment link success (e.g. `status` = `PAID` or `SETUP_CREATED`). However, if your user flow or UI needs interim session details while the payment link `status` is still `CREATED`, then you should use `session_status` (for example to display to the user a "Your payment is processing" or "Your payment failed" message). type: string enum: - OPEN - PROCESSING - COMPLETE - FAILED status: description: >- Status of the payment link. Possible values: `CREATED`, `PAID`, `SETUP_SUCCEEDED`, `CANCELLED`. The status for a successful payment link varies based on the payment link `mode`: \- `mode` = `PAYMENT` => success `status` = `PAID` \- `mode` = `SETUP` => success `status` = `SETUP_SUCCEEDED`. type: string enum: - CREATED - PAID - EXPIRED unique_reference_id: description: >- Customer-supplied string, uniquely identifying the payment to be collected. See “_Handling retries and avoiding duplicate payments_” under `POST /payment_links`. type: string minLength: 1 updated_at: description: Timestamp of the last update to the payment link's record type: string format: date-time url: description: >- URL to launch the Finverse Link UI flow, for the end-user to select a payment method & authorize the payment. type: string ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' IntegrationMetadataRequest: required: - integration_id properties: integration_id: type: string enum: - RAPIDSTOR description: >- ID of the specified integration. **Accepted values:** \- RAPIDSTOR: SiteLink/Rapidstor property management integration (managed by R6 Digital). rapidstor_metadata: $ref: '#/components/schemas/RapidstorMetadataRequest' description: >- Location and tenant parameters for Rapidstor integration. Contact `support@finverse.com` for details. Required if `integration_id` = `RAPIDSTOR`. PaymentLinkCustomizations: properties: language: description: >- Desired language selection for Finverse Link UI. If empty or if an unsupported language is specified, Finverse Link will display the default language. Users can manually override the language selection on the 1st Finverse Link screen. Supported languages: `en` (default), `vi`, `zh` type: string enum: - en - vi - zh - ko example: en redirect_uri: description: >- Required when `ui_mode` = `redirect`. When `ui_mode` = `redirect`, the Finverse Link UI will redirect to this uri after success, failure or when user exits the UI. Uri must be one of the redirect_uri values registered by customer under "API settings" in Finverse developer dashboard (dashboard.finverse.com). type: string ui_mode: description: >- Specifies the behaviour of the Finverse Link UI upon completion of the authorization flow (in both success or error cases). If left empty, Finverse Link will default to `standalone` behaviour for both the Payment Links and Mandates UI. **Accepted values**: \- `redirect`: for when Finverse Link UI is launched as a window/webview embedded within the customer's application. Finverse will display an Exit ("X") button on each screen and a "Continue" button on final success/error screens, each redirecting to the specified `redirect_uri`, allowing the user to return to the customer's application. \- `standalone`: for when Finverse Link UI is launched in a new window/webview without the need to navigate back to the customer's application. Finverse will display a "You may close this window now" message on final success/error screens, guiding the user to manually close the window/webview. \- `iframe`: for when Finverse Link UI is launched as an iframe/webview embedded within the customer's application. Finverse will display an Exit ("X") button on each screen and a "Continue" button on final success/error screens, allowing the user to close the iframe/webview and return to the customer's application (requires customer's application to handle iframe/webview messages). Limitations: `iframe` cannot be used for Payment Links which accept credit card payment methods (e.g. Stripe). **Recommended value**: `redirect` or `standalone` type: string enum: - iframe - redirect - auto_redirect - standalone example: redirect CreateMetadata: type: object additionalProperties: type: string maxLength: 1000 PaymentLinkDetails: required: - description - external_transaction_reference properties: description: type: string maxLength: 100 description: >- User-facing description for the payment transaction. SWIFT character set includes the following characters: alphanumeric, space, and symbols `/ - ? : ( ) . , ' +` Required if `mode` = `PAYMENT`. external_transaction_reference: description: >- User-facing transaction reference for the payment transaction (e.g. bill/invoice number). Some payment methods may display this on the user's statement. Required if `mode` = `PAYMENT`. SWIFT character set includes the following characters: alphanumeric, space, and symbols `/ - ? : ( ) . , ' +` We recommend including at least 1 latin letter in the reference, as some payment methods (e.g. Cards) cannot process payments where statement references have zero letters. type: string maxLength: 35 PaymentSetupOptionsRequest: properties: autopay_enrollment_configuration: $ref: '#/components/schemas/AutopayEnrollmentConfiguration' future_payments: description: >- Configures user consent for future payments, which will be displayed in the Finverse Link UI. Required if `mode` = `SETUP`, optional if mode = `PAYMENT`. **Accepted values**: \- Not set (default): Future payments behaviour depends on payment method selected. (i) If user selects direct debit, the flow behaves like CLICK_TO_PAY; (ii) for all other payment methods, no payment method is saved. _Recommended for: 1-time payments._ \- `AUTOPAY`: Saves user's payment method and allows future payments to be initiated off-session, without user input (see `POST /payments`). The Finverse Link UI flow will disclose to the user that autopay is enabled, and set `autopay_consent` = `true` for the user (sender). _Recommended for: automated recurring payments (fixed or variable timing/amount)._ \- `CLICK_TO_PAY` (BETA): Saves user's payment method, but future payments require user confirmation for each payment. This keeps `autopay_consent` = `false` for the user (sender). The Finverse Link UI will still suggest to the user to enable `AUTOPAY`, but not require it. Returning Payment Link users (identified by `external_user_id`) will be asked to confirm their payment, without having to re-enter payment method details. _Recommended for: recurring payments where users want to control when to pay._ **Impact on payment methods displayed**: type: string enum: - AUTOPAY - CLICK_TO_PAY mandate_details: $ref: '#/components/schemas/MandateDetailsForPaymentLinkRequest' description: >- Optional configurations for any direct debit mandate setup by the user If not used, the Payment Link will set default transaction limits for mandate payments, which may be too low for certain use-cases. Please review the default transaction limits documented in `POST /mandates` to ensure they are approproriate for your use case. payment_method_types: type: array items: type: string enum: - MANDATE - SINGLE - CARD - MANUAL - WALLET x-omitempty: true description: >- Optional parameter to explicitly specify the list of payment methods displayed to users in the Finverse Link UI. This parameter selects payment methods from the Customer App's list of available payment methods (contact Finverse to modify the available list). Other filters will be applied simultaneously (e.g. filtering payment methods for the desired payment currency and amount). Note: if the user has an existing stored payment method (mapped to its `external_user_id`), the Finverse Link UI will default to the stored payment method and not ask the user to select a new payment method. **Accepted ENUM values:** "CARD", "MANDATE", "MANUAL" recipient_account_filters: $ref: '#/components/schemas/RecipientAccountFilters' description: >- Optional filter to narrow the list of settlement accounts receiving money. This is typically used for more complex payment scenarios, for example where a company has multiple receiving accounts (e.g. for different business units, or with different collection fee rules) recurring_payment_mode: description: >- Optional flag indicating whether the payment link is to be used for recurring payment(s). See also: Payment object (`payment_details.recurring_payment_mode`) Recurring payments may be eligible for discounted fees (contact [sales@finverse.com](mailto:sales@finverse.com) for details). Finverse may require a customer app to use this flag to qualify for agreed rates. **Possible ENUM values:** \- `FIXED_SCHEDULE`: recurring payment collected on a fixed, regular schedule up to 1 year between payments (e.g. weekly, monthly, quarterly, annually), agreed to by the end-user. Payment amounts can be variable. Examples: subscriptions, monthly contract invoices, monthly rent, bills autopay. \- `VARIABLE_RECURRING`: recurring payment collected on an adhoc/variable schedule. Payment amounts can be variable. Examples: usage-based contracts/tolls collected on a variable schedule, on-demand services (e.g. Uber, Deliveroo), wallet top-ups. \- `NON_RECURRING`: non-recurring payments initiated by the end-user. Example: ecommerce purchase using a one-time or stored card. \- `UNKNOWN`: value not defined. type: string PaymentLinkSender: required: - external_user_id - name properties: email: type: string format: email description: >- Sender'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: description: >- Customer App's unique ID for the sender. 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. type: string minLength: 1 name: 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). type: string minLength: 1 example: Chan Li Pak IntegrationMetadataResponse: properties: integration_id: type: string enum: - RAPIDSTOR rapidstor_metadata: $ref: '#/components/schemas/RapidstorMetadataResponse' PaymentResponse: required: - amount - surcharge_amount - amount_total_with_surcharge properties: amount: description: Amount of the payment (in minor currency unit) type: integer example: 100 amount_total_with_surcharge: description: >- Total amount of the payment including any transaction fee `surcharge_amount` paid by the sender (in minor currency unit). See `surcharge_amount` on transaction fee surcharges. type: integer example: 100 created_at: description: Timestamp when the payment was first created type: string format: date-time currency: type: string example: HKD description: Currency of the payment (e.g. HKD) error: $ref: '#/components/schemas/FvEmbeddedErrorModel' description: >- Details on why the payment failed (returned when `status` = `FAILED`). Note: this is used to detail any asynchronous e errors occuring after payment creation; any synchronous errors (e.g. API validation errors, real-time payment errors) will instead be returned directly during `POST /payments`. fees: type: array items: $ref: '#/components/schemas/Fee' description: Details on the fee(s) to be charged metadata: description: >- Customer-supplied attributes in key:value format. E.g. `employer_name`: `Apple Inc` type: object additionalProperties: type: string payment_details: $ref: '#/components/schemas/PaymentDetails2' description: Details on the payment payment_id: description: >- Finverse Payment ID for this payment. Always unique. Creating a payment with different idempotency keys will result in two payments with different IDs. type: string payment_method: $ref: '#/components/schemas/PaymentSnapshotPaymentMethod' description: Details on the payment method payment_method_id: description: (TO BE DEPRECATED) Finverse unique ID for the payment method type: string recipient: $ref: '#/components/schemas/MandateRecipient' description: Details on the recipient of the payment recipient_account: $ref: '#/components/schemas/MandateRecipientAccount' description: >- Details on the recipient's account for the payment (i.e. the Customer App's settlement account at Finverse) sender: $ref: '#/components/schemas/GetMandateSender' description: Details on the sender of the payment sender_account: $ref: '#/components/schemas/MandateSenderAccount' description: >- (IN DEVELOPMENT) Details on the Sender's source institution and account, which is funding the payment status: description: >- Current status of the payment. Possible values: `CREATED`, `AUTHORIZATION_REQUIRED`, `PROCESSING`, `SUBMITTED, EXECUTED`, `CANCELLED`, `FAILED` type: string enum: - AUTHORIZATION_REQUIRED - AUTHORIZING - PROCESSING - SUBMITTED - EXECUTED - FAILED - REVOKED - CANCELLED - CREATED surcharge_amount: description: >- Transaction fee surcharge_amount paid by the sender, if any surcharge has been configured (in minor currency unit). Transaction fee surcharges are off by default, but can be set for specific payment methods, or for custom scenarios (e.g. based on transaction amount, payment flow, etc). Contact [support@Finverse.com](mailto:support@Finverse.com) to configure surcharges. type: integer example: 100 type: description: >- Specified payment type. Possible values: - `CARD`: payment via card gateway (e.g. Stripe) \- `MANDATE`: direct debit bank payment \- `MANUAL`: manual bank transfer (e.g. FPS, PayNow) \- `SINGLE`: not used (reserved for future use) type: string enum: - MANDATE - SINGLE - CARD - MANUAL - WALLET updated_at: description: Timestamp of the last update to the payment's record type: string format: date-time PaymentMethodResponse: properties: card: $ref: '#/components/schemas/FVCard' description: Card object Included only if payment_method_type = `CARD`. integration_metadata: $ref: '#/components/schemas/PaymentMethodIntegrationMetadataResponse' mandate: $ref: '#/components/schemas/GetMandateResponse' description: >- Mandate object. Refer to Mandate object data model in `GET /mandates/{mandate_id}`. Included only if payment_method_type = `MANDATE`. payment_method_id: type: string description: >- Finverse unique ID for this payment method. If the `Sender` has `autopay_consent` = `true` , this ID can be used to trigger additional payments on-demand (see `POST /`payments). payment_method_type: type: string description: 'Type of payment method. **Possible values**: `CARD`, `MANDATE`.' PaymentSetupOptions: properties: autopay_enrollment_configuration: $ref: '#/components/schemas/AutopayEnrollmentConfiguration' future_payments: description: See `POST /payment_links` for details. type: string enum: - AUTOPAY - CLICK_TO_PAY mandate_details: $ref: '#/components/schemas/MandateDetailsForPaymentLink' description: See `POST /payment_links` for details. payment_method_types: type: array items: type: string enum: - MANDATE - SINGLE - CARD - MANUAL - WALLET x-omitempty: true description: See `POST /payment_links` for details. recipient_account_filters: $ref: '#/components/schemas/RecipientAccountFilters' description: See `POST /payment_links` for details. recurring_payment_mode: description: The recurring payment mode type: string PaymentLinkSenderResponse: properties: email: type: string format: email external_user_id: description: >- Customer App's user ID, representing the end-user making the payment. type: string minLength: 1 name: description: Accountholder name of the sender's account type: string minLength: 1 example: Chan Li Pak user_id: description: A unique identifier generated after creating sender type: string 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 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 AutopayEnrollmentConfiguration: required: - display_enrollment_screen properties: display_enrollment_screen: description: >- Toggles the autopay enrollment screen on/off in Finverse Link. Default behaviour: `true` If `true`: autopay enrollment screen will be shown to users to ask users whether they consent to autopay. type: boolean enrollment_prefill_value: description: >- Prefills the default user selection on the autopay enrollment screen. **Default behaviour:** `YES` **Accepted values**: \- `YES`: autopay enrollment screen will prefill the "YES" option (to encourage opt-in). User will have to manually select "NO" to opt-out of autopay. \- `NO`: autopay enrollment screen will prefill the "NO" option. User will have to manually select "YES" to opt-in to autopay. type: string enum: - 'YES' - 'NO' MandateDetailsForPaymentLinkRequest: properties: 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 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. See `POST /mandates`. RecipientAccountFilters: required: - business_unit properties: business_unit: type: string minLength: 1 description: >- Business unit identifier/name the recipient account is associated with. Contact [support@finverse.com](mailto:support@finverse.com) to configure your recipient accounts and business unit names. Note: required if no other recipient_account_filter is passed. 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 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 PaymentDetails2: 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 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 payments collected through Finverse (e.g. HK eDDA payments), `collection_entity_name` will be the same as `processor_entity_name` description: description: >- User-facing description for the payment transaction. SWIFT character set includes the following characters: alphanumeric, space, and symbols `/ - ? : ( ) . , ' +` type: string maxLength: 100 external_transaction_reference: description: >- User-facing transaction reference for the payment transaction. SWIFT character set includes the following characters: alphanumeric, space, and symbols / - ? : ( ) . , ' + type: string maxLength: 35 mandate_id: description: >- `mandate_id` from Mandates object. Only returned if `type` = `MANDATE`. type: string processor_details: $ref: '#/components/schemas/PaymentProcessorDetails' description: Additional details on how the payment was processed processor_entity_name: type: string description: >- Name of the payment processor (if any) through which payments are collected. This name may be displayed to users in the Finverse UI, in email notifications and in the sender's bank/card statements. For payments directly collected by the merchant (e.g. SG eGIRO payments, most card payments), no `processor_entity_name` is returned. For payments collected through Finverse (e.g. HK eDDA payments), `processor_entity_name` will be Finverse's legal entity name. recurring_payment_mode: description: >- Flag used to identify recurring payment use cases (for which some payment methods can be eligible for discounted pricing). Possible values: - `FIXED_SCHEDULE`: used for subscriptions (fixed schedule, fixed or variable amount) \- `NON_RECURRING`: used for one-off, user-initiated payments (like an Uber ride or Amazon shopping order) \- `VARIABLE_RECURRING`: used for variable schedule + amount recurring contracts (e.g. usage based contracts like Cloud / SaaS services, or property rentals with additional adhoc charges for value-added services) type: string references: $ref: '#/components/schemas/PaymentDetailsReferences' description: >- Additional references for the Payment (e.g. transaction IDs generated by Finverse or the payment gateway) transaction_reference_id: description: >- (DEPRECATED - replaced by `external_transaction_reference`) User-facing transaction reference ID for the payment transaction. SWIFT character set includes the following characters: alphanumeric, space, and symbols `/ - ? : ( ) . , ' +` type: string PaymentSnapshotPaymentMethod: properties: bank_transfer: properties: bank_transfer_details: $ref: '#/components/schemas/BankTransferDetails' risk_data: $ref: '#/components/schemas/RiskData' card: properties: card_details: $ref: '#/components/schemas/FVCardDetails' wallet: properties: risk_data: $ref: '#/components/schemas/RiskData' wallet_details: $ref: '#/components/schemas/FVWalletDetails' 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 FVCard: properties: card_details: $ref: '#/components/schemas/FVCardDetails' description: Additional details on the card created_at: description: Time when the card object was first created type: string format: date-time error: $ref: '#/components/schemas/FvEmbeddedErrorModel' recipient_account: $ref: '#/components/schemas/MandateRecipientAccount' description: Finverse ID for the account receiving the card payment. risk_data: $ref: '#/components/schemas/RiskData' status: description: >- Current status of the card. Possible values: PROCESSING, SUCCEEDED, CANCELLED, FAILED type: string enum: - UNKNOWN - CREATED - SUCCEEDED - CANCELLED - FAILED updated_at: description: Timestamp of the last update to the card object type: string format: date-time PaymentMethodIntegrationMetadataResponse: properties: adyen_metadata: type: object properties: auth_code: type: string network_transaction_reference: type: string payment_method_id: type: string psp_reference: type: string recurring_processing_model: type: string nullable: true cybersource_metadata: type: object properties: payment_token: type: string nullable: true gocardless_metadata: type: object properties: authorization_source: description: The source of the mandate authorization type: string funds_settlement: description: How GoCardless handles funds settlement type: string last_action: description: The last action taken on the mandate type: string mandate_id: description: The GoCardless mandate ID type: string next_possible_charge_date: description: The next possible charge date, in ISO format (YYYY-MM-DD) type: string format: date nullable: true payments_require_approval: description: Whether payments require approval type: boolean nullable: true reference: description: The GoCardless reference type: string scheme: description: The bank payment scheme type: string status: description: The GoCardless mandate status type: string verified_at: description: >- The timestamp when the mandate was verified, in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ) type: string format: date-time nullable: true nullable: true integration_id: type: string stripe_metadata: type: object properties: customer: type: object properties: id: type: string payment_method: type: object properties: id: type: string nullable: true GetMandateResponse: required: - updated_at - mandate_id - status - recipient - sender - mandate_details properties: created_at: description: Timestamp when the mandate was first created type: string format: date-time error: $ref: '#/components/schemas/FvEmbeddedErrorModel' description: >- Details on why the mandate failed (returned when `status` = `FAILED`). Note: this is used to detail any asynchronous e errors occuring after mandate creation; any synchronous errors (e.g. API validation errors) will instead be returned directly during `POST /mandates`. fees: type: array items: $ref: '#/components/schemas/Fee' description: Details on the fee(s) to be charged mandate_details: $ref: '#/components/schemas/MandateDetailsResponse' description: Details on the mandate mandate_id: description: >- Finverse Mandate ID for this mandate. Always unique. Creating a mandate with different idempotency keys will result in two mandates with different IDs. type: string metadata: description: >- Customer-supplied attributes in key:value format. E.g. `employer_name`: `Apple Inc` type: object additionalProperties: type: string payment_method_id: description: >- Finverse Payment Method ID for this mandate, used to create payments using the mandate (see `POST /`payments). Always unique. Creating a mandate with different idempotency keys will result in two mandates with different IDs. type: string recipient: $ref: '#/components/schemas/MandateRecipient' description: Details on the recipient of the payment recipient_account: $ref: '#/components/schemas/MandateRecipientAccount' description: >- Details on the recipient's account for the payment (i.e. the Customer App's settlement account at Finverse) sender: $ref: '#/components/schemas/GetMandateSender' description: Details on the sender of the payment sender_account: $ref: '#/components/schemas/MandateSenderAccount' description: >- Details on the sender's source institution and account, which is funding the payment status: description: >- Current status of the mandate. Possible values: `AUTHORIZATION_REQUIRED`, `PROCESSING`, `READY_TO_SUBMIT`, `SUBMITTED`, `SUCCEEDED`, `CANCELLED`, `CLOSED`, `FAILED` Note: `CLOSED` occurs when a draft Mandate is created by a Finverse Payment Link (with status `AUTHORIZATION_REQUIRED`), and the user then drops-off or creates a new Payment Method or Mandate. In these cases, Finverse closes the draft Mandate in order to associate a new Payment Method / Mandate with the same Payment Link. type: string enum: - AUTHORIZATION_REQUIRED - AUTHORIZING - PROCESSING - SUBMITTED - SUCCEEDED - FAILED - REVOKED updated_at: description: Timestamp of the last update to the mandate's record type: string format: date-time MandateDetailsForPaymentLink: properties: description: description: >- End-user facing description of the mandate (used in notifications, and in payments if no description is provided) type: string end_date: description: YYYY-MM-DD, must be later than the date of creation. type: string format: date nullable: true start_date: description: >- YYYY-MM-DD, must be later than or the same as the date of creation. If unspecified, default to the date of creation. type: string format: date nullable: true transaction_limits: $ref: '#/components/schemas/TransactionLimitsResponse' 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 PaymentProcessorDetails: properties: auth_code: type: string description: Authorization code returned by the payment gateway processor_id: type: string description: >- ID of the payment gateway which processed the payment. Possible values: - `ADYEN` processor_reference: type: string description: Transaction reference returned by the payment gateway result: $ref: '#/components/schemas/PaymentProcessorResult' description: Additional details on the payment processing result scheme: description: Scheme like becs, bacs, ach, etc. (applicable to Gocardless for now) type: string virtual_account_bank_code: description: >- Bank code for the virtual account without a BK prefix (e.g. KCP manual virtual account payments). type: string virtual_account_number: description: >- Virtual account number issued by the processor (e.g. KCP manual virtual account payments). type: string PaymentDetailsReferences: properties: bank_transaction_reference: type: string description: Unique bank reference ID for the payment. dda_reference: type: string description: >- (Direct debit mandate payments only) Unique reference ID for the Direct Debit Authorization registered with the user's bank, used to authorized the payment. The user's bank may quote this reference in notifications to the user, and in the user's bank statements. finverse_transaction_reference: type: string description: >- Finverse-generated unique transaction ID for the payment. This value may be generated and passed to 3rd party payment gateways when using the Finverse `payment_id` is not possible or desirable (e.g. when the transaction reference is user-facing, making a more user-friendly transaction reference preferable). BankTransferDetails: properties: transfer_type: description: The transfer type type: string example: PayNow RiskData: properties: processor_risk_data: $ref: '#/components/schemas/ProcessorRiskData' FVCardDetails: properties: acquirer_authorization_reference: description: The acquirer authorization reference type: string example: '524506894419' brand: description: >- Card brand. Common values: American Express, Diners Club, JCB, Mastercard, UnionPay, Visa. type: string example: VISA brand_product_name: description: The brand product name type: string example: visacommercialpremiumcredit card_number_alias: description: >- Unique fingerprint for the card number, if provided by the card payment gateway. The card number alias can be used to check whether the card number is the same (for example across multiple users). Unlike the card `fingerprint`, the card number alias will change if the card is reissued with a new number (e.g. upon card expiry). See also: `fingerprint` field. type: string example: F046886807590403 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 card statements. For card 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. country: description: Card country of issuance (e.g. "SG") type: string example: HK expiry_month: description: Card expiry month (e.g. 3 = March) type: integer example: 7 expiry_year: description: 4-digit card expiry year (e.g. 2025) type: integer example: 2028 fingerprint: type: string example: V0010013822052427221044754993 description: >- Unique fingerprint for the card account, if provided by the card payment gateway. The card fingerprint remains the same even when a card expires and a new card is issued with a new card number. The fingerprint can be used to check whether the card is the same (for example across multiple users). See also: `card_number_alias` field. finverse_authorization_reference: type: string description: >- Finverse-generated unique ID for the payment method authorization setup. This value may be generated and passed to 3rd party payment gateways when using the Finverse `payment_id` is not possible or desirable (e.g. when the reference is user-facing, making a more user-friendly reference preferable). funding: description: >- Card funding type. Possible values: `CREDIT`, `DEBIT`, `PREPAID`, `UNKNOWN` type: string enum: - UNKNOWN - CREDIT - DEBIT - PREPAID is_commercial: description: Whether the card is a commercial card type: boolean example: true nullable: true last4: description: Last 4 digits of the card number type: string example: '1234' processor_details: $ref: '#/components/schemas/FVCardProcessorDetails' description: >- Additional details on how the payment method authorization was processed processor_entity_name: type: string description: >- Name of the payment processor (if any) through which payments are collected. This name may be displayed to users in the Finverse UI, in email notifications and in the sender's bank/card statements. For payments directly collected by the merchant (e.g. SG eGIRO payments, most card payments), no `processor_entity_name` is returned. For payments collected through Finverse (e.g. HK eDDA payments), `processor_entity_name` will be Finverse's legal entity name. recurring_payment_mode: description: >- Flag used to identify whether the payment method specifically has been setup for recurring payment use cases (for which some payment methods can be eligible for discounted pricing). Possible values: - `FIXED_SCHEDULE`: used for subscriptions (fixed schedule, fixed or variable amount) \- `NON_RECURRING`: used for one-off, user-initiated payments (like an Uber ride or Amazon shopping order) \- `VARIABLE_RECURRING`: used for variable schedule + amount recurring contracts (e.g. usage based contracts like Cloud / SaaS services, or property rentals with additional adhoc charges for value-added services) type: string FVWalletDetails: properties: brand: description: The wallet brand type: string example: Alipay brand_product_name: description: The brand product name type: string example: alipay_hk country: description: The issuer country type: string example: HK 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 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 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 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 PaymentProcessorResult: properties: decline_code: description: Payment processor's decline code (e.g. "2") type: string decline_reason: description: >- Decline reason returned by the payment gateway (if payment was declined) type: string last_action: description: >- Last action taken by the payment processor (e.g. "created", "captured", "failed", etc.) type: string result_code: description: Payment result code returned by the payment gateway type: string status: description: >- Status of the payment reported by processor (e.g. "authorized", "captured", "failed", etc.) type: string ProcessorRiskData: properties: browser_type: description: The browser type type: string example: Chrome device_type: description: The device type type: string example: Desktop shopper_country: description: The shopper country type: string example: HK shopper_ip: description: The shopper IP address type: string example: 127.0.0.1 shopper_locale: description: The shopper locale type: string example: en-HK FVCardProcessorDetails: properties: auth_code: type: string description: Authorization code returned by the payment gateway network_transaction_reference: description: The network transaction reference type: string processor_id: type: string description: >- ID of the payment gateway which processed the payment method authorization. Possible values: - `ADYEN` processor_reference: type: string description: Transaction reference returned by the payment gateway token_id: type: string description: >- Token ID returned by the payment gateway (for tokenized payment methods) 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 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 ````