> ## 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 Payouts > Retrieve a Payout object (using a specific `payout_id`). **Authorization**: `customer_token` ## Response fields Single `Payout` object, containing information on the Payout. ### fees (array) Details on the fee(s) to be charged. Returns an empty array if no fees will be charged. ### payment_details (object) Details describing the Payout. ### processor_details (object) ### recipient (object), sender (object) The recipient and sender objects include a Payment User object for each of the counterparties of a payout. 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`). ### recipient_account (object), sender_account (object) The recipient_account and sender_account objects include a Payment Account object for each of the counterparties of a payout. Refer to the Payment Account object data model in `GET /payment_users/{user_id}/payment_accounts` for details on the Payment Account object. Note: Some Payment Account metadata fields are omitted for clarity (e.g. `created_at`, `metadata`, `updated_at`). ## OpenAPI ````yaml /api-reference/openapi.json get /payouts 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: /payouts: get: tags: - payouts summary: List Payouts description: >- Retrieve a Payout object (using a specific `payout_id`). **Authorization**: `customer_token` ## Response fields Single `Payout` object, containing information on the Payout. ### fees (array) Details on the fee(s) to be charged. Returns an empty array if no fees will be charged. ### payment_details (object) Details describing the Payout. ### processor_details (object) ### recipient (object), sender (object) The recipient and sender objects include a Payment User object for each of the counterparties of a payout. 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`). ### recipient_account (object), sender_account (object) The recipient_account and sender_account objects include a Payment Account object for each of the counterparties of a payout. Refer to the Payment Account object data model in `GET /payment_users/{user_id}/payment_accounts` for details on the Payment Account object. Note: Some Payment Account metadata fields are omitted for clarity (e.g. `created_at`, `metadata`, `updated_at`). operationId: listPayouts parameters: - description: ISO format (YYYY-MM-DD) name: date_from in: query schema: type: string format: date - description: ISO format (YYYY-MM-DD) name: date_to in: query schema: type: string format: date - description: The payout statuses to filter for, comma separated name: statuses in: query style: form explode: false schema: type: array items: enum: - EXECUTED - CREATED - PROCESSING - PROCESSING_FUNDS - CANCELLED - FAILED - FUNDED - SUBMITTED type: string - name: currencies in: query style: form explode: false schema: type: array items: type: string - name: payout_types in: query style: form explode: false schema: type: array items: enum: - MANUAL - SCHEDULED - SETTLEMENT type: string - name: mandate_id in: query schema: type: string - name: sender_account_id in: query schema: type: string - name: recipient_account_id in: query schema: type: string - name: recipient_user_id in: query schema: type: string - name: recipient_external_user_id in: query schema: type: string - description: Default is 0 name: offset in: query schema: type: integer default: 0 - description: default is 500, max is 1000 name: limit in: query schema: type: integer minimum: 1 maximum: 1000 default: 500 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListPayoutsResponse' examples: success: summary: Success value: payouts: - amount: 14986 created_at: '2025-09-01T05:01:04.459Z' currency: HKD fees: [] live: false metadata: adyen_balance_account_id: BA32CQQ223229D5N25FX22T3S adyen_transaction_id: EVJN42CQW225223W5N42QDKDBP4X3THKD adyen_transfer_id: 6JH0IB6866J194ZR adyen_transfer_instrument_id: SE32CSP223226Q5N25HX4BVQ8 payment_details: description: Monthly clearing payout estimated_arrival_time: '2025-09-01T19:05:00.000Z' processor_details: processor_id: ADYEN processor_reference: SWPE42CPH22337HK5N25K2M3RD4RFH references: recipient_reference: FinverseCardPayout scheduled_date: '2025-09-01T05:00:21.000Z' transaction_reference_id: FinverseCardPayout SWPE42CPH22337HK5N25K2M3RD4RFH payout_id: 01K41TC01K3MATGN9K05B5YC2M sender: name: Demo Company (Global) sender_account: account_id: 01K2Z4517P0CG4TPS1E7YJ1G8R account_type: SETTLEMENT_ACCOUNT status: EXECUTED transaction_time: '2025-09-01T05:00:27.000Z' type: SETTLEMENT updated_at: '2025-09-01T05:01:04.459Z' - amount: 4000 created_at: '2023-12-15T10:53:05.274Z' currency: HKD fees: [] live: false payment_details: description: Finverse payout FV231215TEST6 scheduled_date: '0001-01-01T00:00:00.000Z' transaction_reference_id: FV231215TEST6 payout_id: 01HHPHQFE15WTHSR2VP67412FP recipient: external_user_id: XERO_CUSTOMER-01HH0YNP5RZQYPC20RG71H9QYH name: Demo Company (Global) user_details: [] user_id: 01HH0YNP779S2DD3WFWKF6TEPX user_type: BUSINESS recipient_account: account_id: 01HH0YNP91WV8CT9F34C484ZTE account_number: number: 01HH0YNPED8F69EFTBMWBP8T37 type: LOCAL account_number_masked: 012XXXXXX7890 account_type: EXTERNAL_ACCOUNT accountholder_name: 01HH0YNPDA5XXWZC75G0HH4A8M bank_code: '012' institution_id: bochk-business user_id: 01HH0YNP779S2DD3WFWKF6TEPX sender: name: Demo Company (Global) sender_account: account_id: 01H5GXS3S6SGY7N4WBDZ2VYB2A account_type: SETTLEMENT_ACCOUNT status: EXECUTED transaction_date: '2023-12-15' type: MANUAL updated_at: '2023-12-15T10:53:05.274Z' total_payouts: 2 '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' security: - Oauth2: - payout:list components: schemas: ListPayoutsResponse: required: - payouts - total_payouts properties: payouts: type: array items: $ref: '#/components/schemas/PayoutSnapshotResponse' total_payouts: type: integer ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' PayoutSnapshotResponse: required: - live properties: amount: type: integer description: Amount of the payout (in minor currency unit) created_at: type: string format: date-time description: Timestamp when the payout was first created currency: type: string description: Currency of the payout (e.g. HKD) error: $ref: '#/components/schemas/FvEmbeddedErrorModel' description: >- Details on why the payout failed (returned when `status` = `FAILED`). Note: this is used to detail any asynchronous e errors occuring after payout creation; any synchronous errors (e.g. API validation errors, real-time payout errors) will instead be returned directly during `POST /payouts`. fees: type: array items: $ref: '#/components/schemas/Fee' description: Details on the fee(s) to be charged live: description: >- Flag to indicate whether the payment is a test transaction (i.e. from/to a test bank, `live=false`) or a live transaction (i.e. from/to a real bank, `live=true`). type: boolean 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/PayoutSnapshotDetails' description: Details on the payout payout_id: type: string description: >- Finverse Payout ID for this payout. Always unique. Creating a payout with different idempotency keys will result in two payouts with different IDs. recipient: $ref: '#/components/schemas/GetMandateSender' description: >- Details on the recipient of the payout Note: In some cases when the payout has been executed by a 3rd party payment gateway, the recipient may not be known. recipient_account: $ref: '#/components/schemas/MandateSenderAccount' description: >- Details on the account receiving the payout Note: In some cases when the payout has been executed by a 3rd party payment gateway, the recipient account may not be known. sender: $ref: '#/components/schemas/MandateRecipient' description: Details on the sender of the payout sender_account: $ref: '#/components/schemas/MandateRecipientAccount' description: >- Details on the Sender's account at Finverse (i.e. the Customer App's settlement account at Finverse) status: type: string enum: - EXECUTED - CREATED - PROCESSING - PROCESSING_FUNDS - CANCELLED - FAILED - FUNDED - SUBMITTED description: >- Current status of the payout. Possible values: `CREATED`, `FUNDED`, `PROCESSING`, `SUBMITTED, EXECUTED`, `CANCELLED`, `FAILED` transaction_date: type: string description: \[DEPRECATED\] Transaction date transaction_time: type: string format: date-time example: '2025-08-22T12:00:00Z' nullable: true description: >- Date/time at which the payout was confirmed as executed. The actual settlement date/time of the payout may be different. In addition, a payout may be recorded at different times on the bank accounts of the sender vs. the recipient. Note: in some cases, the transaction date will be known, but the specific transaction time may not be known. In these cases, the transaction time will be listed as `YYYY-MM-DDT00:00:00Z` (or another fixed time value). type: type: string enum: - MANUAL - SCHEDULED - SETTLEMENT description: >- Specified payout type. Possible values: `MANUAL`, `SCHEDULED`, `SETTLEMENT` updated_at: type: string format: date-time description: Timestamp of the last update to the payout's record 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 PayoutSnapshotDetails: properties: description: type: string description: >- User-facing description for the payout transaction. SWIFT character set includes the following characters: alphanumeric, space, and symbols `/ - ? : ( ) . , ' +` estimated_arrival_time: type: string format: date-time example: '2025-08-22T12:00:00Z' nullable: true description: >- Estimated date/time the payout funds will land in the recipient's account (when available). mandate_id: type: string description: >- `mandate_id` from mandates object. Indicates which direct debit mandate should be used to fund the payout. processor_details: $ref: '#/components/schemas/PayoutProcessorDetails' description: Details on the payment processor for the payout references: $ref: '#/components/schemas/PayoutReferences' scheduled_date: type: string format: date-time nullable: true description: >- Scheduled date when the payout should be executed. Required when payout `type` = `SCHEDULED`. transaction_reference_id: type: string description: >- User-facing transaction reference ID for the payout transaction, generated by Finverse. This value will typically be provided to banks executing the payout and may be displayed on the recipient's bank statement. 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 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 PayoutProcessorDetails: properties: processor_id: type: string description: 'ID of the payment processor for the payout. Possible values: ADYEN' processor_reference: type: string description: Payment processor's internal reference for the payout PayoutReferences: properties: recipient_reference: type: string 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 ````