> ## 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. # Payment requests > Reserve money from an account, then settle, reverse, or adjust it — with a per-step breakdown. 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](/guides/finance/transfers) 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 ```bash theme={null} curl -X POST https://api.venlyfinance.com/v1/accounts/{accountId}/payment-requests \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "amount": 25.0, "currency": "USD", "externalId": "order-67890", "description": "Order #67890", "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }' ``` ```json Response theme={null} { "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](/guides/finance/wallets). There are two ways to create a request: | Endpoint | Use when | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | [For an account](/api-reference/Finance-API/payment-requests/create-payment-request-for-account) — `POST /accounts/{accountId}/payment-requests` | you have the Venly `accountId`. | | [By card provider](/api-reference/Finance-API/payment-requests/create-payment-request-by-card-provider) — `POST /payment-requests` | you have a card-provider reference; the account is resolved from `cardProviderReference`. | ## Settle [Settle](/api-reference/Finance-API/payment-requests/settle-a-payment-request) 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](/api-reference/Finance-API/payment-requests/reverse-a-payment-request) 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](/api-reference/Finance-API/payment-requests/update-a-payment-request) 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: ```json theme={null} "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](/guides/finance/idempotency). ## Next steps Finalize a reserved payment, with exact, lower, and higher amounts. How reserved money shows up in a wallet balance.