Skip to main content
POST
/
accounts
/
{accountId}
/
payment-requests
Create payment request for account
curl --request POST \
  --url https://api.venlyfinance.com/v1/accounts/{accountId}/payment-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 25,
  "currency": "USD",
  "externalId": "order-67890",
  "description": "Order #67890",
  "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
'
{
  "success": true,
  "result": {
    "id": "d4e5f6a7-b8c9-4012-8345-6789abcdef01",
    "accountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "amount": {
      "fiat": 25,
      "crypto": "25.000000"
    },
    "originalAmount": {
      "fiat": 25,
      "crypto": "25.000000"
    },
    "currency": "USD",
    "externalId": "order-67890",
    "description": "Order #67890",
    "status": "RESERVED",
    "executions": [
      {
        "id": "e5f6a7b8-c9d0-4123-9456-789abcdef012",
        "walletPairId": "f6a7b8c9-d0e1-4234-a567-89abcdef0123",
        "type": "AUTHORIZATION",
        "chain": "BASE",
        "asset": "USDC",
        "amount": 25,
        "exchangeRate": 1,
        "status": "RESERVED",
        "transactionHash": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
        "createdAt": "2026-01-15T09:30:00Z",
        "updatedAt": "2026-01-15T09:30:02Z"
      }
    ],
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:02Z"
  }
}
Creates a payment request for an account, reserving funds from its wallet for settlement. The response carries the request status (PENDING/RESERVED) and an executions array with the on-chain transactionHash; the amount moves to the wallet’s reserved balance. Send a unique idempotencyKey per request (safe retries). Concept guide: Payment requests
The account must be verified, and (self-custody) its wallet ACTIVE with an allowance, before a payment can be reserved. See Account verification and Approving transfers without gas.
amount and originalAmount are returned as objects — { "fiat": <number>, "crypto": "<string>" } — not scalars. There is no GET endpoint for payment requests: the full object (including executions) is only returned on this create call, so persist the response if you need it later.

Authorizations

​
Authorization
string
header
required

OAuth2 client credentials flow. Token endpoints:

Path Parameters

​
accountId
string<uuid>
required

Unique account identifier

Body

application/json
​
amount
number
required

Payment amount

​
currency
string
required

Currency code (e.g. EUR, USD)

Minimum string length: 1
​
idempotencyKey
string
required

Unique key to prevent duplicate operations on retry

Minimum string length: 1
​
externalId
string

Optional external reference ID

​
description
string

Optional payment description

Response

Payment request created

​
success
boolean

Indicates whether the request was successful

​
result
object