> ## 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. # Get a pay-in > Read one pay-in by the id carried on the PAY_IN_SETTLED or PAY_IN_FAILED webhook. **Requires scope:** `manage:pay-in-sessions` — see [Required scopes](/getting-started/authentication#required-scopes-finance-api). Reads one settlement record. The `payInId` comes from a `PAY_IN_SETTLED` or `PAY_IN_FAILED` [webhook](/guides/finance/webhooks#event-catalogue). Unknown and foreign ids return the same `404 pay-in-not-found`. Reconcile against `netCryptoAmount` — that is what reached the account wallet. ## OpenAPI ````yaml api-reference/Finance-API-Specs.yaml GET /pay-ins/{payInId} 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/{payInId}: parameters: - $ref: '#/components/parameters/TenantId' get: tags: - Pay-Ins summary: Get a pay-in description: > **Requires scope:** `manage:pay-in-sessions` Reads one settlement record by the `payInId` carried on a `PAY_IN_SETTLED` or `PAY_IN_FAILED` webhook. Unknown and foreign ids both return the same `404 pay-in-not-found`. Deactivation of the resources a pay-in references never hides its history. operationId: getPayIn parameters: - $ref: '#/components/parameters/PayInId' responses: '200': description: The pay-in content: application/json: schema: $ref: '#/components/schemas/SinglePayInResponse' 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' '400': description: Malformed `payInId` (must be a UUID) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: '`pay-in-not-found` — unknown or foreign pay-in id' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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 PayInId: name: payInId in: path required: true description: >- Unique pay-in identifier — the `payInId` from a `PAY_IN_SETTLED` or `PAY_IN_FAILED` event schema: type: string format: uuid example: 0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5 schemas: SinglePayInResponse: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object properties: result: $ref: '#/components/schemas/PayIn' 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 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. 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 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.