> ## 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. # List Payments > List Payments associated with a Customer App. **Authorization**: `customer_token` ## OpenAPI ````yaml /api-reference/openapi.json get /payments 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: /payments: get: tags: - payments summary: List Payments description: |- List Payments associated with a Customer App. **Authorization**: `customer_token` operationId: listPayments parameters: - description: Start date for filtering (applied to Payment `updated_at` field) name: date_from in: query schema: type: string format: date - description: End date for filtering (applied to Payment `updated_at` field) name: date_to in: query schema: type: string format: date - description: >- Comma-separated filter for specific Payment statuses. Example: `statuses=SUCCEEDED FAILED`. Refer to Payment statuses in `GET /payments/{payment_id}` name: statuses in: query style: form explode: false schema: type: array items: enum: - AUTHORIZATION_REQUIRED - AUTHORIZING - PROCESSING - SUBMITTED - EXECUTED - FAILED - REVOKED - CANCELLED - CREATED type: string - description: >- Filter for a specific sender type. Refer to Payment sender_type in `GET /payments/{payment_id}` name: sender_type in: query schema: type: string enum: - INDIVIDUAL - BUSINESS - description: '**\[Coming soon\]** Finverse unique ID for the user.' name: user_id in: query schema: type: string - description: Filter for a specific Institution ID name: institution_id in: query schema: type: string - description: Deprecated - The type of payment name: payment_type in: query schema: type: string enum: - MANDATE - SINGLE - CARD - MANUAL - WALLET - name: payment_types in: query style: form explode: false schema: type: array items: type: string enum: - MANDATE - SINGLE - CARD - MANUAL - WALLET description: >- Comma-separated filter for specific Payment types. Refer to payment_type in `GET /payments/{payment_id}` - description: Filter for Payments under a specific Mandate name: mandate_id in: query schema: type: string - description: Deprecated - The currency the payment is made in name: currency in: query schema: type: string - name: currencies in: query style: form explode: false schema: type: array items: type: string description: Comma-separated filter for a specific of currencies - description: 'Pagination offset (default: 0)' name: offset in: query schema: type: integer default: 0 - description: 'Maximum number of records per page (default: 500, max: 1000)' name: limit in: query schema: type: integer minimum: 1 maximum: 1000 default: 500 responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/ListPaymentsResponse' examples: card_payments: summary: Success (Card payments) value: payments: - amount: 500 amount_total_with_surcharge: 752 created_at: '2025-06-21T06:11:19.848Z' currency: HKD fees: - amount: 252 currency: HKD paid_by: SENDER paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 - amount: 261 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 metadata: branch: branch1 key: value stripe_charge_id: ch_3RcKe4JXxo5qMAzS1Ue37Jxk stripe_payment_intent_id: pi_3RcKe4JXxo5qMAzS1nVrP2kt payment_details: collection_entity_name: Finverse Test description: Test payment external_transaction_reference: '1750486279' references: finverse_transaction_reference: FV250101GGBB payment_id: 01JY8HSSGS0GA6VJXYWQ32RYNR payment_method: card: card_details: brand: Visa funding: UNKNOWN last4: '4242' payment_method_id: 01JY8H414WA2G39Y18G6E62DFY recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPF2CBDBQ6F66N78NA47 account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750485561 name: John Doe user_details: [] user_id: 01JY8H3WCKB99VSEVZ2P3ZRG35 user_type: UNKNOWN status: EXECUTED surcharge_amount: 252 type: CARD updated_at: '2025-06-21T06:11:21.603Z' - amount: 10000 amount_total_with_surcharge: 10575 created_at: '2025-06-21T05:54:42.800Z' currency: HKD fees: - amount: 575 currency: HKD paid_by: SENDER paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 - amount: 595 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 metadata: contract_id: '1234' key: value storeganise_invoice_ids: ABCD stripe_charge_id: ch_3RcKOIJXxo5qMAzS1O7zX6Jn stripe_payment_intent_id: pi_3RcKOIJXxo5qMAzS1hKaqKIj user_address: 1 Admiralty Drive user_city: Hong Kong user_country: HK user_first_name: John user_last_name: Doe payment_details: collection_entity_name: Finverse Test description: TEST Payment external_transaction_reference: INV12345 references: finverse_transaction_reference: FV250101FFBB payment_id: 01JY8GVBWG929X02BEDBGPJGPS payment_method: card: card_details: brand: Visa last4: '4242' recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPF2CBDBQ6F66N78NA47 account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750485272 name: John Doe user_details: [] user_id: 01JY8GV2MA6X5QRMY2Q8HABFQJ user_type: UNKNOWN status: EXECUTED surcharge_amount: 575 type: CARD updated_at: '2025-06-21T05:55:05.215Z' - amount: 10000 amount_total_with_surcharge: 10575 created_at: '2025-06-21T05:39:28.452Z' currency: HKD fees: - amount: 575 currency: HKD paid_by: SENDER paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 - amount: 595 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 metadata: contract_id: '1234' key: value storeganise_invoice_ids: ABCD stripe_charge_id: ch_3RcK9dJXxo5qMAzS0mk3bRL9 stripe_payment_intent_id: pi_3RcK9dJXxo5qMAzS0WsG04wW user_address: 1 Admiralty Drive user_city: Hong Kong user_country: HK user_first_name: John user_last_name: Doe payment_details: collection_entity_name: Finverse Test description: TEST Payment external_transaction_reference: INV12345 references: finverse_transaction_reference: FV250621EEBB payment_id: 01JY8FZEZXR3RG0Z8XZQ5CCZB3 payment_method: card: card_details: brand: Visa last4: '4242' payment_method_id: 01JY8FZF0TTC86M1WWGH3G98SG recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPF2CBDBQ6F66N78NA47 account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750484358 name: John Doe user_details: [] user_id: 01JY8FZ5XEAQFW3GZZRYK72M1G user_type: UNKNOWN status: EXECUTED surcharge_amount: 575 type: CARD updated_at: '2025-06-21T05:39:57.257Z' - amount: 500 amount_total_with_surcharge: 752 created_at: '2025-06-21T05:26:27.104Z' currency: HKD fees: - amount: 252 currency: HKD paid_by: SENDER paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 - amount: 261 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 metadata: branch: branch1 key: updated_value new_key: new_value stripe_charge_id: ch_3RcJwdJXxo5qMAzS1mMWGQUe stripe_payment_intent_id: pi_3RcJwdJXxo5qMAzS1ktHHSbS payment_details: collection_entity_name: Finverse Test description: Test payment external_transaction_reference: '1750483586' references: finverse_transaction_reference: FV250621DDBB payment_id: 01JY8F7KVAW66HAVWTNRGF6RSV payment_method: card: card_details: brand: Visa funding: UNKNOWN last4: '4242' payment_method_id: 01JY8DW4DAQY5STF25AE22W5C7 recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPF2CBDBQ6F66N78NA47 account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750482147 name: John Doe user_details: [] user_id: 01JY8DVPA28N4TB11N9H57J5CX user_type: UNKNOWN status: EXECUTED surcharge_amount: 252 type: CARD updated_at: '2025-06-21T05:27:12.719Z' - amount: 500 amount_total_with_surcharge: 752 created_at: '2025-06-21T05:24:50.021Z' currency: HKD fees: - amount: 252 currency: HKD paid_by: SENDER paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 - amount: 261 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 metadata: branch: branch1 key: value stripe_charge_id: ch_3RcJv4JXxo5qMAzS1lyWmNJY stripe_payment_intent_id: pi_3RcJv4JXxo5qMAzS189b3VkG payment_details: collection_entity_name: Finverse Test description: Test payment external_transaction_reference: '1750483489' references: finverse_transaction_reference: FV250621BBCC payment_id: 01JY8F4N0WSJMW9P2T73XDF0NX payment_method: card: card_details: brand: Visa funding: UNKNOWN last4: '4242' payment_method_id: 01JY8DW4DAQY5STF25AE22W5C7 recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPF2CBDBQ6F66N78NA47 account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750482147 name: John Doe user_details: [] user_id: 01JY8DVPA28N4TB11N9H57J5CX user_type: UNKNOWN status: EXECUTED surcharge_amount: 252 type: CARD updated_at: '2025-06-21T05:24:52.179Z' - amount: 10000 amount_total_with_surcharge: 10575 created_at: '2025-06-21T05:02:42.165Z' currency: HKD fees: - amount: 575 currency: HKD paid_by: SENDER paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 - amount: 595 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPF2CBDBQ6F66N78NA47 metadata: contract_id: '1234' key: value storeganise_invoice_ids: ABCD stripe_charge_id: ch_3RcJa1JXxo5qMAzS1JQLl4Nl stripe_payment_intent_id: pi_3RcJa1JXxo5qMAzS1T13AcoE user_address: 1 Admiralty Drive user_city: Hong Kong user_country: HK user_first_name: John user_last_name: Doe payment_details: collection_entity_name: Finverse Test description: TEST Payment external_transaction_reference: INV12345 references: finverse_transaction_reference: FV250621AABB payment_id: 01JY8DW4CGB3Z0WTBHZFSZTJZ4 payment_method: card: card_details: brand: Visa last4: '4242' payment_method_id: 01JY8DW4DAQY5STF25AE22W5C7 recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPF2CBDBQ6F66N78NA47 account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750482147 name: John Doe user_details: [] user_id: 01JY8DVPA28N4TB11N9H57J5CX user_type: UNKNOWN status: EXECUTED surcharge_amount: 575 type: CARD updated_at: '2025-06-21T05:03:09.340Z' total_payments: 6 mandate_payments: summary: Success (Mandate payments) value: payments: - amount: 500 amount_total_with_surcharge: 500 created_at: '2025-06-21T06:30:26.839Z' currency: HKD fees: - amount: 500 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPBC32AZ5TPD99R27JZP metadata: branch: branch1 key: updated_value new_key: new_value payment_details: collection_entity_name: Finverse Technologies Limited description: Test payment external_transaction_reference: '1750487427' mandate_id: 01JY8JWDY51SYHP006XZBAMVGN processor_entity_name: Finverse Technologies Limited references: bank_transaction_reference: DBS_BANK_REF_01JY8JWTJ92E3RX2TF5F1RA2KK dda_reference: FINVERSE T-62F2-FINV finverse_transaction_reference: FV250621JJBB transaction_reference_id: '1750487427' payment_id: 01JY8JWSHVR9SNZWYFYX2C9CTV payment_method_id: 01JY8JWE50618D9RGH44AR884F recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPBC32AZ5TPD99R27JZP account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1_1750487415 name: John Doe user_details: [] user_id: 01JY8JWE3NG8CJ7DVJZJC3HMJT user_type: INDIVIDUAL sender_account: account_id: 01JY8JWKX2HSZJ500DNEJ3JGHQ account_number: number: 01JY8JWM06NV1VNCPM6D5JJ9Y9 type: LOCAL account_number_masked: XXX45 account_type: EXTERNAL_ACCOUNT accountholder_name: 01JY8JWKZRZ32FFE4G0FPM19H1 bank_code: '420' institution_id: testbank-dbs-hk institution_name: Testbank (HK) Payments - Personal user_id: 01JY8JWE3NG8CJ7DVJZJC3HMJT status: EXECUTED surcharge_amount: 0 type: MANDATE updated_at: '2025-06-21T06:30:28.482Z' - amount: 10000 amount_total_with_surcharge: 10000 created_at: '2025-06-21T05:35:28.612Z' currency: HKD fees: - amount: 500 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPBC32AZ5TPD99R27JZP 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_details: collection_entity_name: Finverse Technologies Limited description: TEST Payment external_transaction_reference: INV12345 mandate_id: 01JY8FQHTEX7FAJMM4SGK4GRSZ processor_entity_name: Finverse Technologies Limited references: bank_transaction_reference: DBS_BANK_REF_01JY8FR55T92FBYARB2SDH1EPH dda_reference: FINVERSE T-8F52-FINV finverse_transaction_reference: FV250621IIBB transaction_reference_id: INV12345 payment_id: 01JY8FR4M8JN3RYWJNNK7AE3HK payment_method_id: 01JY8FQHXCZXWYN2EG383YAGR2 recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPBC32AZ5TPD99R27JZP account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750484076 name: John Doe user_details: [] user_id: 01JY8FPJ0XFTEBPH5VHF379XF3 user_type: INDIVIDUAL sender_account: account_id: 01JY8FQWS1D4ZX8PJJS9ZY6B58 account_number: number: 01JY8FQWYTG44WF6RECHN6M09F type: LOCAL account_number_masked: 300XXXX03 account_type: EXTERNAL_ACCOUNT accountholder_name: 01JY8FQWXZN9CFXFKPPKEHTE2M bank_code: '420' institution_id: testbank-dbs-hk institution_name: Testbank (HK) Payments - Personal user_id: 01JY8FPJ0XFTEBPH5VHF379XF3 status: EXECUTED surcharge_amount: 0 type: MANDATE updated_at: '2025-06-21T05:35:29.664Z' - amount: 500 amount_total_with_surcharge: 500 created_at: '2025-06-21T04:31:28.952Z' currency: HKD fees: - amount: 500 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPBC32AZ5TPD99R27JZP metadata: branch: branch1 key: updated_value new_key: new_value payment_details: collection_entity_name: Finverse Technologies Limited description: Test payment external_transaction_reference: '1750480288' mandate_id: 01JY8C0V23FPKZXH1YAHC9JBD5 processor_entity_name: Finverse Technologies Limited references: bank_transaction_reference: DBS_BANK_REF_01JY8C2ZE4NK0NGAQMCETTSPMM dda_reference: FINVERSE T-2X6K-FINV finverse_transaction_reference: FV250621KKBB transaction_reference_id: '1750480288' payment_id: 01JY8C2YY2AE7NGZHNFPFP99NR payment_method_id: 01JY8C0V652P775DQG7DXH9HNR recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPBC32AZ5TPD99R27JZP account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1_1750480219 name: John Doe user_details: [] user_id: 01JY8C0V4VMZRC8YM399JF84BP user_type: INDIVIDUAL sender_account: account_id: 01JY8C2MR456G4EXKVZHB45WPR account_number: number: 01JY8C2MWT0M5NXR1V7FW8ZJEG type: LOCAL account_number_masked: XXX45 account_type: EXTERNAL_ACCOUNT accountholder_name: 01JY8C2MW9WT09SK3AA0928518 bank_code: '420' institution_id: testbank-dbs-hk institution_name: Testbank (HK) Payments - Personal user_id: 01JY8C0V4VMZRC8YM399JF84BP status: EXECUTED surcharge_amount: 0 type: MANDATE updated_at: '2025-06-21T04:31:39.777Z' - amount: 10000 amount_total_with_surcharge: 10000 created_at: '2025-06-21T04:20:41.367Z' currency: HKD fees: - amount: 500 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPBC32AZ5TPD99R27JZP 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_details: collection_entity_name: Finverse Technologies Limited description: TEST Payment external_transaction_reference: INV12345 mandate_id: 01JY8BEMF3AGBQ7C9CJWTV2W4X processor_entity_name: Finverse Technologies Limited references: bank_transaction_reference: DBS_BANK_REF_01JY8BF7M1ZTGQ8NXZ1F1VJYVH dda_reference: FINVERSE T-8M2Z-FINV finverse_transaction_reference: FV250621LLBB transaction_reference_id: INV12345 payment_id: 01JY8BF6JMXS7WS48YM2995GK4 payment_method_id: 01JY8BEMJZQQWGFTCKNSJGB0BD recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPBC32AZ5TPD99R27JZP account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750479613 name: John Doe user_details: [] user_id: 01JY8BECD0ARSWMA0YX0DRY57A user_type: INDIVIDUAL sender_account: account_id: 01JY8BF0GD7H9WWSD892FP5FJT account_number: number: 01JY8BF0Q7VGR0H60M00ZG4HXZ type: LOCAL account_number_masked: 030XXXXX4004 account_type: EXTERNAL_ACCOUNT accountholder_name: 01JY8BF0MPCWYC25B4AFJNGGSQ bank_code: '420' institution_id: testbank-dbs-hk institution_name: Testbank (HK) Payments - Personal user_id: 01JY8BECD0ARSWMA0YX0DRY57A status: EXECUTED surcharge_amount: 0 type: MANDATE updated_at: '2025-06-21T04:20:42.953Z' - amount: 10000 amount_total_with_surcharge: 10000 created_at: '2025-06-21T04:15:12.624Z' currency: HKD fees: - amount: 500 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPBC32AZ5TPD99R27JZP 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_details: collection_entity_name: Finverse Technologies Limited description: TEST Payment external_transaction_reference: INV12345 mandate_id: 01JY8B4MK6T0KFYPV028FRW1YS processor_entity_name: Finverse Technologies Limited references: bank_transaction_reference: DBS_BANK_REF_01JY8B560ATZXDTYP9YRC5VTYE dda_reference: FINVERSE T-0KMR-FINV finverse_transaction_reference: FV250621MMBB transaction_reference_id: INV12345 payment_id: 01JY8B55H1TYX6XDF89Z40D0W6 payment_method_id: 01JY8B4MPYMWNJ7XT603HV2SZ8 recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPBC32AZ5TPD99R27JZP account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750479256 name: John Doe user_details: [] user_id: 01JY8B3FK244XNJCZV2J2PBRMN user_type: INDIVIDUAL sender_account: account_id: 01JY8B4XY0N1AVRR88WWHC7NK2 account_number: number: 01JY8B4Y2W8GJGVV1G6ZZNAPE9 type: LOCAL account_number_masked: 404XXXXX4040 account_type: EXTERNAL_ACCOUNT accountholder_name: 01JY8B4Y1HQFKHXKG2RGA0CZZ3 bank_code: '420' institution_id: testbank-dbs-hk institution_name: Testbank (HK) Payments - Personal user_id: 01JY8B3FK244XNJCZV2J2PBRMN status: EXECUTED surcharge_amount: 0 type: MANDATE updated_at: '2025-06-21T04:15:14.224Z' total_payments: 5 manual_bank_payments: summary: Success (Manual bank payments) value: payments: - amount: 10000 amount_total_with_surcharge: 10000 created_at: '2025-06-21T05:33:41.957Z' currency: HKD fees: - amount: 50 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPD7J0GDJGX99VWJSMXN 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_details: collection_entity_name: Finverse Technologies Limited description: TEST Payment external_transaction_reference: INV12345 processor_entity_name: Finverse Technologies Limited references: finverse_transaction_reference: FV250621OOCC payment_id: 01JY8FMWGS1NV7T9QGFBA84A52 recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPD7J0GDJGX99VWJSMXN account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750484015 name: John Doe user_details: [] user_id: 01JY8FMP77D0S5KSB7CXSA4MTJ user_type: UNKNOWN status: SUBMITTED surcharge_amount: 0 type: MANUAL updated_at: '2025-06-21T05:33:44.767Z' - amount: 10000 amount_total_with_surcharge: 10000 created_at: '2025-06-21T05:33:16.934Z' currency: HKD fees: - amount: 50 currency: HKD paid_by: RECIPIENT paid_by_account_id: 01JY8AKPD7J0GDJGX99VWJSMXN 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_details: collection_entity_name: Finverse Technologies Limited description: TEST Payment external_transaction_reference: INV12345 processor_entity_name: Finverse Technologies Limited references: finverse_transaction_reference: FV250621NNCC payment_id: 01JY8FM45XCZCC7F258DA2532H recipient: name: Finverse Test recipient_account: account_id: 01JY8AKPD7J0GDJGX99VWJSMXN account_type: SETTLEMENT_ACCOUNT sender: external_user_id: user_id_1||1750483990 name: John Doe user_details: [] user_id: 01JY8FKYV1ZJJXC6JHM7FKRCSG user_type: UNKNOWN status: CREATED surcharge_amount: 0 type: MANUAL updated_at: '2025-06-21T05:33:16.934Z' total_payments: 2 '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: - payment:list components: schemas: ListPaymentsResponse: required: - total_payments properties: payments: type: array items: $ref: '#/components/schemas/PaymentResponse' description: >- List of Payment objects that satisfy the filters in the request. Refer to Payment object data model in `GET /payments/{payment_id}` total_payments: type: integer description: >- Total number of Payment records available for the selected filtering criteria (can be used to inform pagination requests) ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' 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 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 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 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 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) 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 ````