Payment requests

A payment request holds money aside from an account’s wallet, then settles it. You create one, the amount is reserved, and later you settle it (the money moves to the company’s settlement wallet), reverse it (the money goes back to the account), or adjust the amount. Every on-chain step is recorded as an execution you can read back. Two wallets are involved: the account’s wallet, where the money starts, and a Venly-held escrow wallet that holds the reserved amount until it settles. Settling moves the money to the company’s settlement wallet — your platform’s wallet for collected payments; reversing returns it to the account wallet.

Payment request vs. transfer

A transfer sends money to another account in one move. A payment request reserves the money first and resolves it later — the pattern card and merchant payments need, where the final amount is known only after authorization.

The flow

Create — money is reserved from the account wallet into escrow. The request is RESERVED.
Adjust (optional) — raise or lower the reserved amount while it’s RESERVED.
Settle or reverse — settle sends the money to the company’s settlement wallet; reverse sends it back to the account. Either way the request reaches a final state.

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": { "fiat": 25.0, "crypto": "25.000000" },
    "originalAmount": { "fiat": 25.0, "crypto": "25.000000" },
    "currency": "USD",
    "status": "RESERVED",
    "executions": [
      {
        "id": "e5f6a7b8-c9d0-4123-9456-789abcdef012",
        "type": "AUTHORIZATION",
        "chain": "BASE",
        "asset": "USDC",
        "amount": 25.0,
        "exchangeRate": 1,
        "status": "RESERVED",
        "transactionHash": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
      }
    ]
  }
}

The reserved amount now appears in the wallet’s reserved balance. There are two ways to create a request:

Endpoint	Use when
For an account — `POST /accounts/{accountId}/payment-requests`	you have the Venly `accountId`.
By card provider — `POST /payment-requests`	you have a card-provider reference; the account is resolved from `cardProviderReference`.

Settle

Settle moves the money from escrow to the company’s settlement wallet. The response is status: SETTLING, and the request becomes SETTLED once the on-chain transfers confirm. The settlement amount doesn’t have to equal the authorized amount:

Settlement `amount`	What happens
Equal to authorized	the reserved amount settles
Below authorized	the difference goes back to the account wallet; the rest settles
Above authorized	the reserved amount settles and the extra is collected from the account wallet

Reverse

Reverse sends the full reserved amount back to the account wallet. The response is status: REVERSING, becoming REVERSED once the transfer confirms. Use it to release a hold you no longer need to charge.

Adjust the amount

Update sets a new authorized amount while the request is RESERVED. A lower amount sends the difference back to the account; a higher amount reserves more from it. After the update, amount shows the new value and originalAmount keeps the amount you started with.

Amounts carry fiat and crypto

Every amount on a payment request is an object that shows both sides of the conversion:

"amount": { "fiat": 25.0, "crypto": "25.000000" }

fiat is the value in the request currency; crypto is the stablecoin amount that actually moves on-chain. This applies to amount, originalAmount, settlementAmount, settledAmount, and shortfallAmount.

Status at a glance

`status`	Meaning
`RESERVED`	money is held — ready to settle, reverse, or adjust
`SETTLING` → `SETTLED`	settlement is processing, then complete
`SETTLED_WITH_SHORTFALL`	settled, but less than the full settlement amount was collected — see `shortfallAmount`
`REVERSING` → `REVERSED`	reversal is processing, then complete

Each execution carries its own type (AUTHORIZATION, INCREMENTAL_AUTHORIZATION, AUTHORIZATION_ADJUSTMENT, SETTLEMENT, SETTLEMENT_OVERAGE, REFUND, REVERSAL), status, and transactionHash.

There’s no GET endpoint for a payment request. The full object — including executions — comes back on create, settle, reverse, and update, so store the response and match on your own externalId.

Safe retries

Send a fresh idempotencyKey for each new request. To retry, reuse the same key with the same body and you’ll get the original result back instead of a second charge. See Idempotency.

Overview

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Wallets

Transfers

Fiat to Crypto Payment Sessions

Permits

Allowances

Reference

Payment requests

Payment request vs. transfer

The flow

Create a payment request

Settle

Reverse

Adjust the amount

Amounts carry fiat and crypto

Status at a glance

Safe retries

Next steps

Settle a payment request

Wallets & balances

​Payment request vs. transfer

​The flow

​Create a payment request

​Settle

​Reverse

​Adjust the amount

​Amounts carry fiat and crypto

​Status at a glance

​Safe retries

​Next steps

Settle a payment request

Wallets & balances

Payment request vs. transfer

The flow

Create a payment request

Settle

Reverse

Adjust the amount

Amounts carry fiat and crypto

Status at a glance

Safe retries

Next steps