> ## Documentation Index > Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt > Use this file to discover all available pages before exploring further. # List pay-ins > List every pay-in settlement record across your company. **Requires scope:** `manage:pay-in-sessions` — see [Required scopes](/getting-started/authentication#required-scopes-finance-api). Lists the pay-in ledger — one record per fiat credit that arrived on a [virtual bank account](/guides/finance/virtual-bank-accounts) or through a [pay-in session](/api-reference/Finance-API/fiat-to-crypto-payment-sessions/create-a-fiat-to-crypto-payment-session), with its settlement status, the gross and net crypto amounts, and the on-chain transaction. See [Pay-ins](/guides/finance/pay-ins). All filters combine with AND. Unknown or foreign `accountId` / `virtualBankAccountId` values match nothing. Records stay readable after the resources they reference are closed. ## OpenAPI ````yaml api-reference/Finance-API-Specs.yaml GET /pay-ins openapi: 3.1.0 info: title: Venly Finance API description: > REST API for the Venly Finance platform: - Party management (Individuals & Organisations) - Identity verification — hosted KYC/KYB links and Sumsub share-token forwarding - Account management with party association - Wallet balances & token allowances on supported chains - Virtual bank accounts for global pay-in (EUR SEPA, USD ACH/WIRE/RTP/SWIFT) - Fiat-to-crypto payment sessions (pay-in) - Bank pay-outs — beneficiary allow-listing, routes, and PULL/PUSH pay-outs - Account-to-account fiat & crypto transfers - EIP-2612 permits and allowances - Webhook registration for asynchronous event delivery ## Authentication All endpoints use OAuth2 client credentials. Obtain a token first, then include it in every request: **Step 1 — Get a token:** ```bash curl -X POST https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}" ``` **Step 2 — Use the token:** ``` Authorization: Bearer {access_token} ``` Tokens expire after **5 minutes**. Implement refresh logic in your client. ## Selecting a tenant A token that grants more than one tenant must say which one each request is for, in the `x-tenant-id` header. With a single-tenant token, omit it. Any value you send must exactly match a tenant the token grants; a missing, malformed or foreign value is answered with a generic `403 forbidden` that reveals nothing about which tenants exist. Send the header at most once. ## Request correlation Every response — including `401` and `403` — carries an `X-Correlation-Id` header identifying the operation in our logs. Quote it in a support request. You may supply your own, as `X-Correlation-Id` or (as a fallback) `X-Request-Id`, matching `^[A-Za-z0-9_.:-]{1,64}$`. A value outside that shape is replaced with a generated one rather than rejected. version: 1.10.0 contact: name: Venly Support email: support@venly.io url: https://docs.venlyfinance.com license: name: Proprietary x-logo: url: https://venlyfinance.com/logo.png x-security-contact: security@venly.io servers: - url: https://api.venlyfinance.com/v1 description: Production - url: https://api-staging.venlyfinance.com/v1 description: Staging security: - OAuth2: [] tags: - name: Parties description: Party management (Individuals & Organisations) - name: Accounts description: Account management, party-role associations - name: Wallets description: Blockchain wallet balances - name: Virtual Bank Accounts description: Virtual bank account payment references for global payments - name: Fiat-to-crypto Payment Sessions description: >- Hosted fiat-to-crypto pay-in sessions. **Coming soon** — not yet enabled; use a virtual bank account to receive fiat today. - name: Payout Bank Accounts description: Allow-listing beneficiary bank accounts as pay-out destinations - name: Payout Routes description: >- Account-scoped routes pairing a beneficiary bank account with a crypto deposit asset - name: Payouts description: Crypto-to-fiat pay-outs over a registered route - name: Transfers description: Fiat and crypto transfer operations between accounts - name: Permits description: EIP-712 permit signature management for token approvals - name: Supported Assets description: >- Discover which chains and assets your tenant can settle in, and whether an account can use them yet. - name: Allowances description: Token allowance management for wallets - name: Webhooks description: Webhook registration, delivery testing and delivery history - name: Pay-Ins description: >- The pay-in ledger — every fiat credit that settled (or failed to settle) into an account wallet - name: Billing description: The invoices Venly has issued to your company - name: API Credentials description: Self-service management of your company's OAuth client credentials - name: Company description: Your own company profile paths: /pay-ins: parameters: - $ref: '#/components/parameters/TenantId' get: tags: - Pay-Ins summary: List pay-ins description: > **Requires scope:** `manage:pay-in-sessions` Lists settlement records from the pay-in ledger across every account in your company. A pay-in is the deposit's own settlement record — the fiat credit that arrived on a virtual bank account or through a pay-in session, its conversion, and the crypto credited to the account wallet. Pay-in sessions track initiation separately. All filters are optional and combined with AND. Unknown or foreign `accountId` / `virtualBankAccountId` filters match nothing. Historical records stay readable whatever the current status of the resources they reference, including records with no account attribution. Reading never triggers a provider call or a settlement action. Ordered by `createdAt` descending by default. Empty datasets and pages beyond the last one return an empty `result` with matching totals. operationId: listPayIns parameters: - name: accountId in: query required: false description: Only pay-ins attributed to this account schema: type: string format: uuid - name: virtualBankAccountId in: query required: false description: Only pay-ins received on this virtual bank account schema: type: string format: uuid - name: from in: query required: false description: Inclusive lower bound on `createdAt` (UTC instant) schema: type: string format: date-time - name: to in: query required: false description: >- Exclusive upper bound on `createdAt`; must be after `from` when both are supplied schema: type: string format: date-time - name: status in: query required: false description: Exact settlement status schema: $ref: '#/components/schemas/PayInStatus' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Size' - name: sortOn in: query required: false description: Field to sort by. Only `createdAt` is accepted. schema: type: string enum: - createdAt default: createdAt - $ref: '#/components/parameters/SortOrder' responses: '200': description: A page of pay-ins content: application/json: schema: $ref: '#/components/schemas/PayInListResponse' example: success: true result: - id: 0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5 accountId: b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f virtualBankAccountId: 4d5e6f70-8192-4a3b-9c4d-5e6f7081920a accountWalletId: 9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f status: SETTLED chain: BASE cryptoAsset: USDC fiatCurrency: EUR grossFiatAmount: '100.00' grossCryptoAmount: '108.42' netCryptoAmount: '108.42' transactionHash: >- 0x4f7a2c9e18b3d05a6c7e94f120d8b3a5e6f1c07d92b4a8e35f6c1d0b7a92e438 settledAt: '2026-08-19T09:14:52Z' failedAt: null createdAt: '2026-08-19T09:02:10Z' updatedAt: '2026-08-19T09:14:52Z' pagination: pageNumber: 1 pageSize: 20 numberOfElements: 1 numberOfPages: 1 hasNextPage: false hasPreviousPage: false '400': description: > Invalid UUID, timestamp, status or pagination/sort value; `invalid-date-range` when `from` is at or after `to`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: TenantId: name: x-tenant-id in: header required: false description: > Which tenant the request is scoped to, among those your token grants. Omit it when the token grants exactly one tenant; it is **required** when the token grants more than one. A supplied value must exactly match a tenant the token grants. Absent when required, blank, malformed, or naming a tenant the token does not grant — each gets the same generic `403 forbidden`, which reveals neither whether a tenant exists nor which ones you may use. Send the header once: a repeated header is rejected the same way. schema: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Page: name: page in: query description: Page number (1-based indexing) required: false schema: type: integer format: int32 default: 1 minimum: 1 example: 1 Size: name: size in: query description: Number of items per page required: false schema: type: integer format: int32 default: 100 minimum: 1 example: 20 SortOrder: name: sortOrder in: query description: > Sort direction. **Applied only together with `sortOn`** — on its own it is ignored and the default ordering (`createdAt` descending) is used, so `?sortOrder=ASC` alone does not reverse a list. required: false schema: type: string default: DESC enum: - ASC - DESC example: DESC schemas: PayInStatus: type: string description: > Settlement lifecycle of a pay-in, independent of the initiating session's status. - `RECEIVED` — the fiat credit was observed - `SETTLING` — conversion and the on-chain credit are in progress - `SETTLED` — the crypto is in the account wallet. `PAY_IN_SETTLED` fires - `FAILED` — the deposit ended without crediting the account. `PAY_IN_FAILED` fires - `RETURNED` — the fiat was sent back to the payer enum: - RECEIVED - SETTLING - SETTLED - FAILED - RETURNED PayInListResponse: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object properties: result: type: array items: $ref: '#/components/schemas/PayIn' pagination: $ref: '#/components/schemas/Pagination' ErrorResponse: type: object description: Error response wrapper properties: success: type: boolean description: Always false for error responses example: false errors: type: array description: List of errors that occurred items: $ref: '#/components/schemas/ErrorBody' result: type: object nullable: true description: Null or omitted when success is false BaseResponse: type: object properties: success: type: boolean description: Indicates whether the request was successful PayIn: type: object description: > A pay-in settlement record — one fiat credit, its conversion, and the crypto credited to the account wallet. Amounts are exact decimal strings. Nullable fields are omitted when absent, never substituted with zero. Provider references, raw failure text, internal transaction identifiers and idempotency keys are not exposed. required: - id - virtualBankAccountId - accountWalletId - status - chain - cryptoAsset - fiatCurrency - grossCryptoAmount - netCryptoAmount - createdAt - updatedAt properties: id: type: string format: uuid description: >- Canonical pay-in id; matches `payInId` on the `PAY_IN_SETTLED` / `PAY_IN_FAILED` webhooks accountId: type: string format: uuid nullable: true description: >- The account the deposit was attributed to. Absent when attribution is still pending. virtualBankAccountId: type: string format: uuid description: The virtual bank account the fiat arrived on accountWalletId: type: string format: uuid description: The account wallet the crypto was credited to status: $ref: '#/components/schemas/PayInStatus' chain: $ref: '#/components/schemas/BlockchainNetwork' cryptoAsset: type: string example: USDC fiatCurrency: type: string example: EUR grossFiatAmount: type: string nullable: true description: >- The fiat amount received. Informational; absent for some deposit types. example: '100.00' grossCryptoAmount: type: string description: >- The deposit as received, denominated in `cryptoAsset`. Today always equal to `netCryptoAmount`. example: '108.42' netCryptoAmount: type: string description: >- What reached the account wallet, denominated in `cryptoAsset`. Reconcile against this. example: '108.42' transactionHash: type: string nullable: true description: On-chain settlement transaction, once available settledAt: type: string format: date-time nullable: true failedAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time Pagination: type: object description: Pagination metadata (top-level sibling of `result`) properties: pageNumber: type: integer format: int32 description: Current page number (1-based) pageSize: type: integer format: int32 description: Number of items per page numberOfElements: type: integer format: int64 description: Total number of items across all pages numberOfPages: type: integer format: int32 description: Total number of pages hasNextPage: type: boolean description: Whether there is a next page hasPreviousPage: type: boolean description: Whether there is a previous page ErrorBody: type: object description: Individual error details properties: code: type: string description: Machine-readable error code example: invalid-request message: type: string description: Human-readable error message example: The request contains invalid parameters. BlockchainNetwork: type: string description: > Supported blockchain network. Availability per chain depends on your company's configured `supportedChains` — see [Supported chains and assets](/guides/finance/supported-chains-and-assets). enum: - AVALANCHE - BASE - ETHEREUM - POLYGON - SOLANA responses: Unauthorized: description: Authentication required or failed (401) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: unauthenticated message: Please authenticate to perform this action. Forbidden: description: Caller lacks the required authority/role (403) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: forbidden message: You do not have permission to access this resource. InternalServerError: description: Unexpected server error (500) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: internal-error message: An unexpected error occurred. Please try again later. securitySchemes: OAuth2: type: oauth2 description: > OAuth2 client credentials flow. Token endpoints: - Staging: https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token - Production: https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token flows: clientCredentials: tokenUrl: >- https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.