Skip to main content
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

  1. Create — money is reserved from the account wallet into escrow. The request is RESERVED.
  2. Adjust (optional) — raise or lower the reserved amount while it’s RESERVED.
  3. 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:
EndpointUse when
For an account — POST /accounts/{accountId}/payment-requestsyou have the Venly accountId.
By card provider — POST /payment-requestsyou 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 amountWhat happens
Equal to authorizedthe reserved amount settles
Below authorizedthe difference goes back to the account wallet; the rest settles
Above authorizedthe 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

statusMeaning
RESERVEDmoney is held — ready to settle, reverse, or adjust
SETTLING → SETTLEDsettlement is processing, then complete
SETTLED_WITH_SHORTFALLsettled, but less than the full settlement amount was collected — see shortfallAmount
REVERSING → REVERSEDreversal 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.

​
Next steps

Settle a payment request

Finalize a reserved payment, with exact, lower, and higher amounts.

Wallets & balances

How reserved money shows up in a wallet balance.