Skip to main content
A payment request reserves funds from an account’s wallet and settles a payment on-chain. It’s the building block behind card and merchant settlement: you create one request, Venly reserves the amount, and each on-chain settlement attempt is recorded as an execution.

​
How it differs from a transfer

A transfer moves funds to another Venly account. A payment request settles a payment out of the account’s balance — reserving the amount first, then executing on-chain — and returns an executions array describing each attempt.

​
Two ways to create one

EndpointUse when
For an account — POST /accounts/{accountId}/payment-requestsyou have the Venly accountId.
By card provider — POST /payment-requestsyou only have a card-provider reference; the account is resolved from cardProviderReference (type + referenceId).

​
Prerequisites

The account must be verified. For self-custody, the wallet must be active with an allowance to the orchestration wallet — see Approving transfers without gas.

​
Create a payment request

curl -X POST https://api.venlyfinance.com/v1/accounts/{accountId}/payment-requests \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.0,
    "currency": "USD",
    "externalId": "order-67890",
    "description": "Order #67890",
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'
Response
{
  "success": true,
  "result": {
    "id": "d4e5f6a7-b8c9-4012-8345-6789abcdef01",
    "accountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "amount": 25.0,
    "currency": "USD",
    "status": "RESERVED",
    "executions": [
      {
        "id": "e5f6a7b8-c9d0-4123-9456-789abcdef012",
        "walletPairId": "f6a7b8c9-d0e1-4234-a567-89abcdef0123",
        "chain": "BASE",
        "asset": "USDC",
        "amount": 25.0,
        "exchangeRate": 1,
        "status": "RESERVED",
        "transactionHash": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
      }
    ]
  }
}
On success the reserved amount moves to the wallet’s reserved balance.

​
Status lifecycle

statusMeaning
PENDINGCreated; not yet reserved.
RESERVEDFunds held against the wallet’s reserved balance.
SETTLEDPayment completed.
REVERSEDA reserved or settled request was unwound.
FAILEDReservation or settlement failed.
Each entry in executions carries its own status (PENDING, RESERVED, or FAILED), transactionHash, and exchangeRate.
There is no GET endpoint for payment requests — the full object (including executions) is only returned on create. Persist the create response and key off your own externalId and idempotencyKey.

​
Idempotency

Send a unique idempotencyKey per request; a retry with the same key returns the original request and reserves only once. See Safe retries with idempotency keys.

​
Next steps

Create a payment request

The endpoint reference and full schema.

Wallets & balances

How reserved funds show up in a wallet balance.