--- title: "Preview internal transfer" method: POST path: "/payment/v3/transfers/dry-run" tags: ["Internal Transfers"] --- # Preview internal transfer `POST /payment/v3/transfers/dry-run` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/payment/v3/transfers/dry-run` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Previews an internal transfer without creating it. BVNK calculates and returns conversion details, including exchange rate, spread, fees, and converted amounts, but does not initiate a transfer or move funds. Use this feature to show your customer the exact rate and amounts before confirming a transfer. It supports both `QUOTE` and `AUTO_CONVERSION` types. Same-asset transfers, where the originator and beneficiary currencies match, are not supported. The request and response formats are identical to [`POST /payment/v3/transfers`](/bvnk/api-explorer/endpoints/transfer-create-v-3/). When you are ready to proceed, send the same request to that endpoint. ## Request body - TransferRequestV3 - `reference` string, required: Partner-supplied reference for the transfer tracking. - `originator` object, required: Originator participant. Must include `amount` if the beneficiary does not (exactly one side must specify the amount). - `amount` number, float: Amount to debit from the originator wallet. Required if beneficiary amount is not specified. - `currency` string, required: Currency code of the originator wallet (ISO-4217 for fiat, or crypto currency code). - `walletId` string, required: Identifier of the originator wallet to debit. - `beneficiary` object, required: Beneficiary participant. Must include `amount` if the originator does not (exactly one side must specify the amount). - `amount` number, float: Amount to credit to the beneficiary wallet. Required if originator amount is not specified. - `currency` string, required: Currency code of the beneficiary wallet (ISO-4217 for fiat, or crypto currency code). - `walletId` string, required: Identifier of the beneficiary wallet to credit. - `conversion` object: Conversion configuration. Required when originator and beneficiary currencies differ. - `type` 'QUOTE' | 'AUTO_CONVERSION', required: Conversion type. `QUOTE` provides a firm rate requiring acceptance. `AUTO_CONVERSION` executes at market rate automatically. - `validityDuration` 'PT20S' | 'PT60M': Duration for which the quote remains valid. Only applicable for `QUOTE` type. Accepts ISO-8601 duration format. - `metadata` Metadata: Custom metadata key-value pairs. Structure: key: value. Restrictions: - Maximum five keys. - Each key maximum length 50 characters. - Each value maximum length 100 characters. - Keys and values must be simple strings. ## Response `200` Preview generated successfully. The response has the same shape as a created transfer, but nothing is persisted: don't use its `id` or `conversion.digest` with other endpoints. - TransferResponseV3 - `id` string, uuid, required: Unique transfer identifier. - `reference` string, required: Transfer reference provided in the request. - `type` 'payment:transfer', required: Payment type constant for transfers. - `status` 'PROCESSING' | 'PENDING_QUOTE_ACCEPTANCE' | 'EXPIRED' | 'COMPLETED' | 'FAILED', required: Current transfer status. - `metadata` Metadata: Custom metadata key-value pairs. Structure: key: value. Restrictions: - Maximum five keys. - Each key maximum length 50 characters. - Each value maximum length 100 characters. - Keys and values must be simple strings. - `fees` object, required - `processingFee` MoneyFeeV2 - `amount` number, required: Fee amount in fiat or crypto currency units. - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and cryptocurrencies. - `originator` object, required: Originator details including settled amount. - `amount` number, float, required: Amount debited from the originator wallet. - `currency` string, required: Currency code of the originator wallet. - `walletId` string, required: Identifier of the originator wallet. - `entity` union - TransferIndividual - `type` 'INDIVIDUAL', required: Entity type - `firstName` string, required: First name - `lastName` string, required: Last name - TransferCompany - `type` 'COMPANY': Entity type - `legalName` string, required: Legal company name - `beneficiary` object, required: Beneficiary details including credited amount. - `amount` number, float: Amount credited to the beneficiary wallet. For `AUTO_CONVERSION` transfers it is returned once the conversion executes, so it can be absent while the transfer is `PROCESSING`. - `currency` string, required: Currency code of the beneficiary wallet. - `walletId` string, required: Identifier of the beneficiary wallet. - `entity` union - TransferIndividual - `type` 'INDIVIDUAL', required: Entity type - `firstName` string, required: First name - `lastName` string, required: Last name - TransferCompany - `type` 'COMPANY': Entity type - `legalName` string, required: Legal company name - `conversion` object: Conversion details. Present only for cross-currency transfers. - `type` 'QUOTE' | 'AUTO_CONVERSION': Conversion type used for this transfer. - `spread` object: Commercial spread applied to the conversion. - `percentage` number, float: Spread as a decimal percentage (e.g. 0.01 = 1%). - `amount` number, float: Spread amount in the specified currency. - `currency` string: Currency of the spread amount. - `allInRate` number, float: All-in conversion rate including spread. - `baseRate` number, float: Base market rate before spread. - `validityDuration` string: Duration for which the quote is valid. Only present for QUOTE type. - `expiresAt` string, date-time: Quote expiration timestamp. Only present for QUOTE type. - `digest` string: Fingerprint of the quoted price, not a version of the transfer. A new value is issued only when the price changes: when the quote is created and on every `REFRESH_QUOTE`. The value reflects the quote, `originator.amount`, `beneficiary.amount`, `allInRate`, `spread.percentage`, and `expiresAt`. Accepting the quote does not issue a new value. Required for accepting the quote via the actions endpoint, which is the only place the digest is sent back. Returned for `QUOTE` transfers, including after the quote is accepted. - `expiresAt` string, date-time: Transfer expiration timestamp. Unaccepted quote transfers expire 24 hours after creation. - `createdAt` string, date-time, required: Creation timestamp. - `updatedAt` string, date-time, required: Last update timestamp. - `trackingDetails` object[]: External identifiers for the payment transaction, including tracking references for different payment methods. These can be used to trace transactions across global payment networks such as Fedwire and ACH. - `externalTransactionId` string: External identifier for the transaction. - `imad` string: Input Message Accountability Data. Used as the originator's tracking reference for WIRE transfers. - `omad` string: Output Message Accountability Data. Used as beneficiary's tracking reference for WIRE transfers. - `traceNumber` string: Payment reference used for ACH payments. - `uetr` string: Unique End-to-End Transaction Reference. Used in SWIFT payments. - `method` 'BOOK': Transfer method. ## Other responses - `400`: Bad request - `403`: Forbidden ## Changes - **2026-11-06** `c386d436bf2c`: 1 info - endpoint added [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/payment/v3/transfers/dry-run/post.md) --- [API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)