> ## 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 Method: direct debit mandate > _Note: this endpoint is primarily intended for migrating payment methods from other payment gateways into Finverse._ Manually register a Payment Method, referencing a valid card or direct debit mandate (already setup on a 3rd party payment gateway). The fields required depend on whether the payment method to be registered is a card or direct debit mandate. This request example creates a **direct debit mandate**. See the next requests for examples of creating a **card payment method.** **Access:** This flow is available on demand for Finverse customers who want to directly create or migrate Payment Methods. Contact [support@finverse.com](mailto:support@finverse.com) to request access. **Authorization**: `customer_token` ## Request fields Pass details of the card or mandate to be created. ### card (object, conditionally required) Details on the card authorized by the end-user. ### mandate (object, conditionally required) Details on the direct debit mandate authorized by the end-user. ### mandate_details (object, required) Details describing the Mandate. ### recipient_account (object, required) Details on the recipient account of the payment (i.e. the Customer App's receiving account). ### sender_account (object, required) Details on the sender account of the payment (i.e. the payer's originating account). ## Response fields Single Payment Method object containg details on the payment method authorized by the end-used (Card or Mandate). ### card (object, conditional) Details on the card authorized by the end-user. ### card_details (object) Additional details on the card. ### sender (object) The sender object includes a Payment User object for the sender of the payment. Refer to the Payment User data model in `GET /payment_users/{payment_user_id}` for details on the Payment User object. Note: Some Payment User metadata fields are omitted for clarity (e.g. `created_at`, `metadata`, `updated_at`). ## OpenAPI ````yaml /api-reference/openapi.json post /payment_users/{paymentUserId}/payment_methods openapi: 3.0.0 info: description: Documentation of the early finverse services title: Finverse Public termsOfService: https://example.com contact: name: Maintainers email: info@finverse.com license: name: unknown license version: 0.0.1 servers: - url: https://api.prod.finverse.net security: - Oauth2: - test tags: - name: public description: Publicly accessible endpoints x-group: Public - name: customer description: Customer app and institution endpoints x-group: Customer - name: link description: Finverse Link flows x-group: Link - name: login_identity description: Login identity lifecycle and metadata x-group: Login identity - name: accounts description: Accounts, balances, and account numbers x-group: Accounts - name: statements description: Statements and composite statements x-group: Statements - name: transactions description: Transaction history x-group: Transactions - name: identity_income description: Identity and income insights x-group: Identity & income - name: payment_links description: Payment link creation and checkout x-group: Payment links - name: mandates description: Direct debit mandates x-group: Mandates - name: payments description: Payment initiation and status x-group: Payment operations - name: payouts description: Payouts and scheduled payouts x-group: Payouts - name: payment_users description: Payment user profiles x-group: Payment users - name: payment_accounts description: Payment accounts for users x-group: Payment accounts - name: payment_methods description: Stored payment methods x-group: Payment methods - name: bills description: Bill presentment x-group: Bills - name: disputes description: Payment disputes x-group: Disputes - name: ledger description: Ledger and statements x-group: Ledger paths: /payment_users/{paymentUserId}/payment_methods: post: tags: - payment_users summary: 'Create Payment Method: direct debit mandate' description: >- _Note: this endpoint is primarily intended for migrating payment methods from other payment gateways into Finverse._ Manually register a Payment Method, referencing a valid card or direct debit mandate (already setup on a 3rd party payment gateway). The fields required depend on whether the payment method to be registered is a card or direct debit mandate. This request example creates a **direct debit mandate**. See the next requests for examples of creating a **card payment method.** **Access:** This flow is available on demand for Finverse customers who want to directly create or migrate Payment Methods. Contact [support@finverse.com](mailto:support@finverse.com) to request access. **Authorization**: `customer_token` ## Request fields Pass details of the card or mandate to be created. ### card (object, conditionally required) Details on the card authorized by the end-user. ### mandate (object, conditionally required) Details on the direct debit mandate authorized by the end-user. ### mandate_details (object, required) Details describing the Mandate. ### recipient_account (object, required) Details on the recipient account of the payment (i.e. the Customer App's receiving account). ### sender_account (object, required) Details on the sender account of the payment (i.e. the payer's originating account). ## Response fields Single Payment Method object containg details on the payment method authorized by the end-used (Card or Mandate). ### card (object, conditional) Details on the card authorized by the end-user. ### card_details (object) Additional details on the card. ### sender (object) The sender object includes a Payment User object for the sender of the payment. Refer to the Payment User data model in `GET /payment_users/{payment_user_id}` for details on the Payment User object. Note: Some Payment User metadata fields are omitted for clarity (e.g. `created_at`, `metadata`, `updated_at`). operationId: createPaymentMethod parameters: - description: Payment User ID name: paymentUserId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentMethodRequest' examples: create_payment_method_direct_debit_mandate: summary: 'Create Payment Method: direct debit mandate' value: mandate: mandate_details: dda_reference: '{{dda_reference}}' currency: SGD description: Paper eGIRO Mandate transaction_limits: max_period_amount: 100000000 max_period_count: 100000 max_transaction_amount: 100000000 period: MONTHLY metadata: key: value recipient_account: account_id: '{{recipient_account_id}}' sender_account: account_id: '{{existing_sender_account_id2}}' status: SUCCEEDED payment_method_type: MANDATE create_payment_method_adyen_card: summary: 'Create Payment Method: Adyen card' value: card: card_details: brand: Mastercard brand_product_name: Mastercard card_number_alias: F495225511395777 collection_entity_name: Demo Company Limited country: HK currency: HKD expiry_month: 3 expiry_year: 2030 fingerprint: 5ePOmfH7G5irogopQi8b1XfF4G3CF finverse_authorization_reference: FC260415XP40 last4: '1111' processor_details: auth_code: '070240' processor_id: ADYEN processor_reference: PTQK3MZ7F9SRCTV5 token_id: WV947F3N9PJ3JWV5 recurring_payment_mode: FIXED_SCHEDULE recipient_account: account_id: '{{recipient_account_id}}' status: SUCCEEDED integration_metadata: adyen_metadata: auth_code: '070240' payment_method_id: WV947F3N9PJ3JWV5 psp_reference: PTQK3MZ7F9SRCTV5 recurring_processing_model: Subscription integration_id: ADYEN payment_method_type: CARD create_payment_method_cybersource_card: summary: 'Create Payment Method: Cybersource card' value: card: card_details: brand: Visa expiry_month: 3 expiry_year: 2026 last4: '1234' currency: SGD recipient_account: account_id: '{{recipient_account_id}}' status: SUCCEEDED integration_metadata: integration_id: CYBERSOURCE cybersource_metadata: payment_token: 23DACC841CCE235CE063AF598E0A779B payment_method_type: CARD create_payment_method_gocardless_mandate: summary: 'Create Payment Method: GoCardless Mandate' value: integration_metadata: gocardless_metadata: funds_settlement: managed mandate_id: MD01K8F72JABC1 reference: TESTMANDATE-1234 scheme: becs status: active integration_id: GOCARDLESS mandate: mandate_details: currency: AUD description: GoCardless Mandate - TESTMANDATE-1234 recipient_account: account_id: 01KFF2KAXWF93DSR0X1ABCDAB1 sender_account: account_id: 01KFE2S3WWQBAA8MJK12ABCD1A status: SUCCEEDED payment_method_type: MANDATE required: true responses: '200': description: Success (Mandate) content: application/json: schema: $ref: '#/components/schemas/PaymentMethodResponse' examples: mandate: summary: Success (Mandate) value: payment_methods: - mandate: created_at: '2024-03-22T05:30:07.606Z' fees: - amount: 0 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01H2QD9W1SR1QN7JAMVNF4A6GC mandate_details: collection_entity_name: Finverse Technologies Limited currency: HKD description: Payment link mandate mandate_bank_reference: 01FHF1MEY9-VWNM-01FH processor_entity_name: Finverse Technologies Limited start_date: '2024-03-22' transaction_limits: max_transaction_amount: 100000000 mandate_id: 01HSJA64F1Q3NGVB3D94XFNHBD payment_method_id: 01HSJA64HAP8KVSXCMP6K7KQY2 recipient: name: REGRESSION recipient_account: account_id: 01H2QD9W1SR1QN7JAMVNF4A6GC account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1711085382 name: John Doe user_details: [] user_id: 01HSJA5TNAQSRZEZGX9KM3WPM8 user_type: INDIVIDUAL sender_account: account_id: 01HSJA6HWKG3ENW4WV678APHHJ account_number: number: 01HSJA6HZW81QPCJXB48AW1FJ9 type: LOCAL account_number_masked: XX34 account_type: EXTERNAL_ACCOUNT accountholder_name: 01HSJA6HZEBEYWHZ56HSBGJWA7 institution_id: testbank-dbs-hk user_id: 01HSJA5TNAQSRZEZGX9KM3WPM8 status: SUCCEEDED updated_at: '2024-03-22T05:30:06.686Z' payment_method_id: 01HSJA64HAP8KVSXCMP6K7KQY2 payment_method_type: MANDATE sender: autopay_consent: true created_at: '2024-03-22T05:29:42.314Z' external_user_id: user_id_1||1711085382 name: John Doe updated_at: '2024-03-22T05:30:11.301Z' user_details: [] user_id: 01HSJA5TNAQSRZEZGX9KM3WPM8 user_type: INDIVIDUAL adyen_card: summary: Success (Adyen card) value: card: card_details: brand: Mastercard brand_product_name: Mastercard card_number_alias: F495225511395777 collection_entity_name: Demo Company Limited country: HK expiry_month: 3 expiry_year: 2030 fingerprint: 5ePOmfH7G5irogopQi8b1XfF4G3CF finverse_authorization_reference: FC260415XP40 last4: '1111' processor_details: auth_code: '070240' processor_id: ADYEN processor_reference: PTQK3MZ7F9SRCTV5 token_id: WV947F3N9PJ3JWV5 created_at: '2025-10-24T06:00:35.712Z' recipient_account: account_id: 01K4YESKNJCPJ52QS9V4GC95KK account_type: SETTLEMENT_ACCOUNT status: SUCCEEDED updated_at: '2025-10-24T06:00:35.712Z' integration_metadata: adyen_metadata: auth_code: '070240' payment_method_id: WV947F3N9PJ3JWV5 psp_reference: PTQK3MZ7F9SRCTV5 recurring_processing_model: UnscheduledCardOnFile integration_id: ADYEN payment_method_id: 01KPQEPCD9EXCSA27WCDP3X0JR payment_method_type: CARD cybersource_card: summary: Success (Cybersource card) value: card: card_details: brand: Visa collection_entity_name: Finverse Technologies Limited expiry_month: 3 expiry_year: 2026 last4: '1234' created_at: '2024-12-03T12:39:49.989Z' recipient_account: account_id: 01JE5MNR43T7Y8CDNH06M1S4FP account_type: SETTLEMENT_ACCOUNT status: SUCCEEDED updated_at: '2024-12-03T12:39:49.989Z' integration_metadata: cybersource_metadata: payment_token: 23DACC841CCE235CE063AF598E0A779B integration_id: CYBERSOURCE payment_method_id: 01JE68HDEWQQ4C6A4JG2DAWBR9 payment_method_type: CARD gocardless_mandate: summary: Success (GoCardless mandate) value: integration_metadata: gocardless_metadata: funds_settlement: managed mandate_id: MD01K8F72JABC1 next_possible_charge_date: '0001-01-01' reference: TESTMANDATE-1234 scheme: becs status: active integration_id: GOCARDLESS mandate: created_at: '2026-01-21T02:15:28.054Z' fees: [] mandate_details: collection_entity_name: Test Entity Ltd currency: AUD description: GoCardless Mandate - TESTMANDATE-1234 mandate_id: 01KFF5BQFMZ4RD9PQ6TJABC02 payment_method_id: 01KFF5BQFMZ4RD9PQ6AB1ABCDE recipient: name: Example Co recipient_account: account_id: 01KFF2KAXWF93DSR0X1ABCDEF1 account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_1 name: John Doe user_details: [] user_id: 01KFDB8MNB3JN7XRJYABCDE1AB user_type: INDIVIDUAL sender_account: account_id: 01KFE2S3WWQBAA8MJA12ABCD1A account_number_masked: '12' account_type: EXTERNAL_ACCOUNT accountholder_name: 01KFE2S3YCCK3ND0Y5ABCDEF1A institution_id: westpac-aus-payments institution_name: Westpac (Australia) user_id: 01KFDB8MNB3JN7XRJYAB1AB0AB status: SUCCEEDED updated_at: '2026-01-21T02:15:28.054Z' payment_method_id: 01KFF5BQFMZ4RD9PQ6AB1ABCDE payment_method_type: MANDATE '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' '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: - paymentMethod:create components: schemas: CreatePaymentMethodRequest: required: - payment_method_type properties: card: $ref: '#/components/schemas/CreateCardRequest' integration_metadata: $ref: '#/components/schemas/PaymentMethodIntegrationMetadata' mandate: $ref: '#/components/schemas/CreateMandateRequestWithDdaReference' payment_method_type: type: string enum: - CARD - MANDATE 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`.' ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' CreateCardRequest: required: - card_details - status - recipient_account properties: card_details: type: object required: - brand - last4 - currency properties: brand: type: string card_bin: description: First 6 digits of the credit card number type: string card_number_alias: description: The card number alias type: string example: F046886807590403 country: description: The issuer country type: string example: HK currency: type: string expiry_month: type: integer expiry_year: type: integer funding: description: The funding source of the card type: string enum: - UNKNOWN - CREDIT - DEBIT - PREPAID last4: type: string recipient_account: $ref: '#/components/schemas/MandateRecipientRequest' status: type: string enum: - SUCCEEDED PaymentMethodIntegrationMetadata: required: - integration_id properties: adyen_metadata: type: object required: - payment_method_id properties: auth_code: type: string network_transaction_reference: type: string payment_method_id: type: string psp_reference: type: string recurring_processing_model: type: string enum: - CardOnFile - UnscheduledCardOnFile - Subscription cybersource_metadata: type: object required: - payment_token properties: payment_token: type: string gocardless_metadata: type: object required: - mandate_id properties: funds_settlement: description: How GoCardless handles funds settlement type: string enum: - managed - direct 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 reference: description: The GoCardless reference type: string scheme: description: The bank payment scheme type: string status: description: The GoCardless mandate status type: string enum: - active 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 integration_id: type: string enum: - STRIPE - CYBERSOURCE - ADYEN - GOCARDLESS stripe_metadata: type: object required: - customer - payment_method properties: customer: type: object required: - id properties: id: type: string payment_method: type: object required: - id properties: id: type: string CreateMandateRequestWithDdaReference: required: - recipient_account - sender_account - mandate_details - status properties: mandate_details: $ref: '#/components/schemas/MandateDetailsRequestWithDdaReference' metadata: $ref: '#/components/schemas/CreateMetadata' recipient_account: $ref: '#/components/schemas/MandateRecipientRequest' sender_account: $ref: '#/components/schemas/MandateSenderAccountRequest' status: description: The mandate status type: string enum: - SUCCEEDED example: SUCCEEDED 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 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 MandateRecipientRequest: required: - account_id properties: account_id: description: Unique ID for the sender account type: string maxLength: 100 MandateDetailsRequestWithDdaReference: required: - currency - description properties: currency: description: ISO currency code type: string dda_reference: description: The direct debit authorization reference type: string 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/TransactionLimitsRequest' CreateMetadata: type: object additionalProperties: type: string maxLength: 1000 MandateSenderAccountRequest: required: - account_id properties: account_id: description: account ID assigned by Finverse type: string maxLength: 100 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 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 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 RiskData: properties: processor_risk_data: $ref: '#/components/schemas/ProcessorRiskData' 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 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 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 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) 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 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 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 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 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 ````