> ## 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-in sessions
> List an account's fiat-to-crypto pay-in sessions, newest first.
**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 the account's pay-in sessions from persisted state — the provider is never called. Use it for a deposits view, or to recover a session whose `callbackUrl` notification was missed.
A session is an **initiation-only** record. It stops at `PAYMENT_RECEIVED`; the conversion and crypto credit are a separate [pay-in](/api-reference/Finance-API/pay-ins/list-pay-ins). Don't wait for a "completed" session status — there is none.
To poll for changes, sort `updatedAt` descending and read only the first page, sized above your expected change volume. `from`/`to` bound `createdAt`, so there is no "changed since" filter.
## OpenAPI
````yaml api-reference/Finance-API-Specs.yaml GET /accounts/{accountId}/fiat-to-crypto/payment-sessions
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:
parameters:
- $ref: '#/components/parameters/TenantId'
get:
tags:
- Fiat-to-crypto Payment Sessions
summary: List pay-in sessions
description: >
**Requires scope:** `manage:pay-in-sessions`
Returns the account's fiat-to-crypto pay-in sessions, newest first. Use
it to render a deposits
view, or to recover the state of a session whose `callbackUrl`
notification was missed — the
endpoint returns persisted state and never calls the payment provider.
**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), so do not
wait for a "completed"
session status — there is none.
**Polling for changes:** sort `updatedAt` descending and read only the
first page. `from`/`to`
bound `createdAt`, not `updatedAt`, so there is no *changed since*
filter — you are re-reading
the head of an ordering whose key mutates underneath you, and a row that
moves between your
page-1 and page-2 requests is never returned. Size the page above your
expected change volume
rather than paging deeper.
Omit `sortOn` and the list is ordered by `createdAt` descending;
`sortOrder` on its own has no
effect. The session `id` is always appended as a final tiebreaker, so
the `sort` block in the
response carries a trailing `id` order that is not itself an accepted
`sortOn` value — replay
`sort.orders[0].property`, not the whole list. `status`, `expiresAt` and
`inAmount` are not
sortable.
operationId: listPayInSessions
parameters:
- $ref: '#/components/parameters/AccountId'
- name: status
in: query
required: false
description: Filter by session status
schema:
$ref: '#/components/schemas/PaymentSessionStatus'
- name: from
in: query
required: false
description: Lower bound on `createdAt`, inclusive (ISO-8601 instant)
schema:
type: string
format: date-time
- name: to
in: query
required: false
description: Upper bound on `createdAt`, exclusive (ISO-8601 instant)
schema:
type: string
format: date-time
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- name: sortOn
in: query
required: false
description: '`createdAt` or `updatedAt`. Omitted means `createdAt` descending.'
schema:
type: string
enum:
- createdAt
- updatedAt
- $ref: '#/components/parameters/SortOrder'
responses:
'200':
description: >-
A page of pay-in sessions. A page beyond the last one is an empty
`result`, not an error.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentSessionListResponse'
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'
pagination:
pageNumber: 1
pageSize: 20
numberOfElements: 1
numberOfPages: 1
hasNextPage: false
hasPreviousPage: false
'400':
description: >
- `invalid-parameter` — malformed `accountId`, an unknown `status`,
or a `from`/`to` that is not
an ISO-8601 instant
- `invalid-date-range` — `from` is after `to`
- `.validation` — `size` > 100, `page` < 1, or a `sortOn`
outside the allowed fields
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 owned by your company.
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
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:
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
PaymentSessionListResponse:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/PaymentSession'
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
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
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.
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.