> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Preview a payout > Price a payout from a virtual account before you make it. Nothing is sent and nothing is held, unless you ask for a quote with `create_quote` — then the price comes back with a `quote_id` you can redeem when you execute. ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json post /v1/virtual-accounts/{virtual_account_id}/payout/preview openapi: 3.1.0 info: title: Kira API version: '2026-04-14' description: >- REST API for users, KYC/KYB verification, virtual accounts, payouts, recipients, and webhooks. Every request requires an `x-api-key` header and a bearer access token (see Authentication). Pin your account to version `2026-04-14` before integrating. contact: name: Kira API Support email: support@kirafin.ai servers: - url: https://api.balampay.com description: Production - url: https://api.balampay.com/sandbox description: Sandbox security: - bearerAuth: [] apiKeyAuth: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Recipients - name: Quotations - name: Payouts - name: Reference paths: /v1/virtual-accounts/{virtual_account_id}/payout/preview: post: tags: - Payouts summary: Preview a payout description: >- Price a payout from a virtual account before you make it. Nothing is sent and nothing is held, unless you ask for a quote with `create_quote` — then the price comes back with a `quote_id` you can redeem when you execute. operationId: post_v1-virtual-accounts-virtual-account-id-payout-preview parameters: - in: path name: virtual_account_id required: true schema: type: string format: uuid description: The account the money leaves from. - in: header name: X-Api-Version required: false description: >- Version applied to this request. It wins over your account's pinned version — see [Versioning](/using-the-api/versioning). schema: type: string example: '2026-04-14' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PayoutPreviewRequest' examples: bank: summary: To a saved recipient value: amount: '1000.00' recipient_id: cccccccc-dddd-eeee-ffff-000000000000 hold-the-price: summary: Hold the price to redeem it value: amount: '1000.00' recipient_id: cccccccc-dddd-eeee-ffff-000000000000 create_quote: true responses: '200': description: The priced payout. content: application/json: schema: $ref: '#/components/schemas/PayoutPreviewResult' example: amount: '1000.00' currency: USD fees: base_fees: bank_account_fee: '10.00' bank_account_fee_percentage: '0.00' fixed_fee: '0.00' percentage_fee: '2.50' total: '12.50' client_markup: fixed_fee: '1.00' percentage_fee: '0.00' total: '1.00' network_fee: '0.00' total_fees: '13.50' total: '13.50' recipient_amount: '986.50' recipient_currency: USD '400': description: >- A field is missing, malformed, or the amount cannot carry the fees. `details` names each field that was rejected. content: application/json: schema: type: object properties: code: type: string description: Always `validation_error`. error: type: string description: Always `Invalid data`. details: type: array description: One entry per problem. items: type: object properties: message: type: string description: The field and what is wrong with it. example: code: validation_error error: Invalid data details: - message: amount is Amount must be greater than zero '401': description: >- Your credentials could not be read. The message talks about routing, but the cause is one of these: - The `Authorization` header is missing. - The token is not a token, or was not issued for your account. - The `x-api-key` header is missing or wrong. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: invalid_request message: >- The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem. '404': description: >- No account of yours has that `virtual_account_id`, or the `recipient_id` you sent does not belong to you. content: application/json: schema: type: object properties: statusCode: type: integer description: Repeats the HTTP status. error: type: string description: Always `Not Found`. message: type: string description: Which one was not found. timestamp: type: string description: When the call was rejected, as an ISO 8601 timestamp. path: type: string description: The path you called. example: statusCode: 404 error: Not Found message: Virtual account 11111111-2222-3333-4444-555555555555 not found timestamp: '2026-09-01T12:00:00.000Z' path: >- /v1/virtual-accounts/11111111-2222-3333-4444-555555555555/payout/preview security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production components: schemas: PayoutPreviewRequest: type: object description: Send `recipient_id` or `account_type` — at least one is required. properties: amount: type: string description: >- How much to send, as a positive decimal string with up to 8 decimals. With `inverse_calculation` this is what the recipient should end up with instead. recipient_id: type: string format: uuid description: >- A recipient you saved earlier. Its rail and details are used for the pricing. account_type: type: string enum: - WIRE - ACH - WALLET description: >- Price a rail without saving a recipient first. Ignored when you also send `recipient_id`, which carries its own rail. With `WALLET` and no `recipient_id`, `wallet_network` and `wallet_token` are required too. See [Recipient values](/reference/recipients/values#account_type). wallet_network: type: string enum: - solana - polygon - tron description: >- Chain the recipient's wallet is on. Only used with `account_type: WALLET` and no `recipient_id`. wallet_token: type: string enum: - USDC - USDT description: >- Token the recipient receives. Not every token works on every chain, and a pair that does not is rejected with a `400`. inverse_calculation: type: boolean description: >- Work backwards: treat `amount` as what the recipient receives and return what has to leave the account. `false` when you omit it. client_markup: type: object description: >- Your own fees for this one payout, replacing whatever is configured on your account. `fixed_fee` and `percentage_fee` are both required once you send the object. properties: fixed_fee: type: string description: A flat charge, as a decimal string with up to 2 decimals. percentage_fee: type: string description: >- A share of the amount, as a decimal between `0` and `1` with up to 4 decimals — `0.01` is 1%. fx_markup: type: string description: >- Your cut of the currency conversion, as a decimal with up to 4 decimals. required: - fixed_fee - percentage_fee payment_instructions: type: object description: >- The token and chain you will deposit to fund the payout. Sending this makes it a crypto-funded payout. properties: network: type: string enum: - solana - polygon - tron description: Chain you will deposit on. currency: type: string enum: - USDC - USDT description: Token you will deposit. required: - network - currency extra_info: type: object description: Your own notes on the payout. They come back on a read. properties: memo: type: string description: >- Short note that travels with the payment where the rail allows it. invoice_number: type: string description: Your invoice number. Up to 100 characters. internal_notes: type: string description: A note for your own records. Up to 1000 characters. create_quote: type: boolean description: >- Save the price and return a `quote_id` you can redeem on the payout. Without it the preview prices without holding anything. required: - amount PayoutPreviewResult: type: object description: The priced payout. Every amount is a decimal string. properties: amount: type: string description: What leaves the account. currency: type: string description: Currency of `amount`. Always `USD`. fees: type: object description: What comes off the amount before the recipient is paid. properties: base_fees: type: object description: What Kira charged, each a decimal string. properties: bank_account_fee: type: string description: The rail's own flat charge. bank_account_fee_percentage: type: string description: The rail's own percentage charge. fixed_fee: type: string description: A flat charge. percentage_fee: type: string description: A charge worked out from the amount. conversion_on_ramp_fee: type: string description: >- Charge for turning USD into a token. Only on a payout that converts. total: type: string description: This group added up. client_markup: type: object description: What you charged, each a decimal string. properties: fixed_fee: type: string description: A flat charge. percentage_fee: type: string description: A charge worked out from the amount. conversion_on_ramp_fee: type: string description: >- Charge for turning USD into a token. Only on a payout that converts. total: type: string description: This group added up. network_fee: type: string description: >- The chain's transfer cost. `0` when the payout does not touch a chain. fx: type: object description: >- How the conversion was priced. Only on a payout that converts between USD and a token. properties: commercial_rate: type: string description: >- Reference market rate, in USD per unit of the token. Shown for display. mid_market_rate: type: string description: The same value as `commercial_rate`, under a clearer name. applied_rate: type: string description: The reference rate less the markup. Shown for display only. base_markup_rate: type: string description: Kira's share of the spread, as a rate. client_markup_rate: type: string description: Your share of the spread, as a rate. markup_cost: type: string description: What the spread comes to in USD. depeg_loss: type: string description: >- USD given up because the token was trading below parity. Kept separate so it is not read as revenue. total_fees: type: string description: >- `base_fees.total` and `client_markup.total` added up. `network_fee` is not in it — add that separately on a payout delivered as digital currency. total: type: string description: The same value as `total_fees`. recipient_amount: type: string description: What the recipient ends up with. recipient_currency: type: string description: >- Currency of `recipient_amount` — `USD` on a bank payout, `USDC` or `USDT` on a wallet payout. payment_instructions: type: object additionalProperties: true description: >- The funding token and chain, echoed back. Only on a crypto-funded payout. quote_id: type: string format: uuid description: >- Send this on the payout to settle at this price. Only when you asked for a quote with `create_quote`. quote_expires_at: type: string description: When that price stops holding, as an ISO 8601 timestamp. ErrorResponse: type: object properties: message: type: string code: type: string statusCode: type: number error: type: string timestamp: type: string path: type: string details: {} required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `data.access_token` value from [Get access token](/api-reference/authentication/get-access-token). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. ````