> ## 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 session > Read one fiat-to-crypto pay-in session. **Coming soon — not yet available.** Hosted pay-in sessions are documented ahead of launch. Until they're enabled for your company, creating one is refused with `400 no-suitable-provider`. To receive fiat today, use a [virtual bank account](/guides/finance/virtual-bank-accounts). **Requires scope:** `manage:pay-in-sessions` — see [Required scopes](/getting-started/authentication#required-scopes-finance-api). Returns a single pay-in session from persisted state. It advances only when the payment provider reports back, so polling this endpoint can only ever show you `PAYMENT_RECEIVED` as its happy-path end — settlement is tracked on the [pay-in](/api-reference/Finance-API/pay-ins/get-a-pay-in), signalled by `PAY_IN_SETTLED`. ## OpenAPI ````yaml api-reference/Finance-API-Specs.yaml GET /accounts/{accountId}/fiat-to-crypto/payment-sessions/{sessionId} 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: /accounts/{accountId}/fiat-to-crypto/payment-sessions/{sessionId}: parameters: - $ref: '#/components/parameters/TenantId' get: tags: - Fiat-to-crypto Payment Sessions summary: Get a pay-in session description: > **Requires scope:** `manage:pay-in-sessions` Returns a single fiat-to-crypto pay-in session belonging to the account. The endpoint returns persisted state and never calls the payment provider, so the session advances only when the provider reports back. **A pay-in session is an initiation-only record.** It tracks the fiat payment being initiated, not its settlement: on the happy path it terminates at `PAYMENT_RECEIVED` and never advances further. Conversion and the crypto deposit are tracked separately as a [pay-in](/api-reference/Finance-API/pay-ins/list-pay-ins) — do not poll this endpoint waiting for a "completed" status; there is none. operationId: getPayInSession parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/SessionId' responses: '200': description: The pay-in session content: application/json: schema: $ref: '#/components/schemas/SinglePaymentSessionResponse' example: success: true result: id: 5e6f7081-92a3-4b4c-8d5e-6f708192a3b4 accountId: b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f status: PAYMENT_RECEIVED inAmount: 100 inCurrency: EUR outCryptocurrency: USDC paymentUrl: https://pay.example.com/session/5e6f708192a3b4c8 externalRef: order-67890 walletId: 9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f blockchainTxId: null cancellable: false expiresAt: '2026-01-15T10:30:00Z' metadata: orderId: '67890' idempotencyKey: 3fa85f64-5717-4562-b3fc-2c963f66afa6 createdAt: '2026-01-15T09:30:00Z' updatedAt: '2026-01-15T09:41:12Z' '400': description: '`invalid-parameter` — malformed `accountId` or `sessionId`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- The account was not found or is not yours, or the session does not exist on that account. 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 AccountId: name: accountId in: path required: true description: Unique account identifier schema: type: string format: uuid example: b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f SessionId: name: sessionId in: path required: true description: Unique pay-in session identifier schema: type: string format: uuid example: 5e6f7081-92a3-4b4c-8d5e-6f708192a3b4 schemas: SinglePaymentSessionResponse: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object properties: result: $ref: '#/components/schemas/PaymentSession' 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 PaymentSession: type: object properties: id: type: string format: uuid accountId: type: string format: uuid status: $ref: '#/components/schemas/PaymentSessionStatus' inAmount: type: number description: Fiat amount to be paid in inCurrency: type: string description: Fiat currency of the incoming payment outCryptocurrency: type: string description: Cryptocurrency the incoming fiat is converted to paymentUrl: type: string format: uri description: Hosted URL to redirect the payer to externalRef: type: string walletId: type: string format: uuid blockchainTxId: type: string nullable: true cancellable: type: boolean expiresAt: type: string format: date-time metadata: type: object additionalProperties: type: string idempotencyKey: type: string format: uuid 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. PaymentSessionStatus: type: string description: > Status of a fiat-to-crypto pay-in session. A session is an **initiation-only** record: it tracks the fiat payment being initiated, not its settlement. On the happy path it terminates at `PAYMENT_RECEIVED`; conversion and the crypto credit are tracked as a [pay-in](/api-reference/Finance-API/pay-ins/list-pay-ins). There is deliberately no "completed" value — `CONVERTING`, `MINTING` and `COMPLETED` were removed in 1.8.0. - `CREATED` — persisted, not yet handed to the provider - `PENDING_PAYMENT` — awaiting the payer to complete the fiat payment - `PAYMENT_RECEIVED` — fiat payment confirmed. **Terminal on the happy path** - `FAILED` — the session could not be initiated or the payment failed - `EXPIRED` — the session passed `expiresAt` unpaid - `CANCELLED` — cancelled before payment - `REFUNDING` — a refund of the received fiat is in progress - `REFUNDED` — the received fiat was refunded enum: - CREATED - PENDING_PAYMENT - PAYMENT_RECEIVED - FAILED - EXPIRED - CANCELLED - REFUNDING - REFUNDED 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.