/v2/payment/bankSend Bank Payment
Sends a bank payment to a beneficiary using a payment instrument. The beneficiary must be enabled. Note: 1. A successful response means the payment was **accepted, not sent**. The payment is created in `PENDING_AUTHORIZATION` and authorization is resolved asynchronously (automated rules, and manual compliance review where required). Track it to a terminal status via Get Transaction Details or webhooks. 2. Some payments require bank authorization; status changes are sent to your webhook URL. 3. The SWIFT code from the payment instrument is verified during submission. 4. Optional header `x-idempotency-key` (max 255 chars): when provided, must be unique. A retry with an already used key is detected *before* SupportingDocument validation and returns HTTP 200 with only `ResponseData.TransactionNumber` of the original payment, without creating a second payment. The replayed request body is ignored, so reusing a key for a genuinely different payment returns the original transaction instead of creating the new one. 5. There is no API endpoint to cancel a payment in production; contact FV Bank support if a submitted payment must be stopped.
Headers
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
Authorization | string | Required | Bearer {SessionToken} | Session token from Get Session Token, sent as `Authorization: Bearer {SessionToken}`. Replace with the value from the `x-refresh-token` response header when present (typically within 2 minutes of expiry). Secured calls must use the same IP as the auth request. |
x-idempotency-key | string | Optional | 7b2c8f1a-4e3d-4a1b-9c0e-123456789abc | Optional client-supplied idempotency key (max 255 characters). When provided, it is stored on the payment and must be unique. Reusing the same key on payment create does not create a second payment: the request short-circuits before SupportingDocument validation and returns HTTP 200 with only `ResponseData.TransactionNumber` of the original payment. Use a new key for each distinct payment; reuse the same key only when retrying the same logical request. Two caveats: (1) the replayed request body is **ignored**, so reusing a key for a genuinely different payment silently returns the original transaction rather than creating the new one; (2) the duplicate check is **not atomic**, so two identical requests sent concurrently with the same key can both pass it — serialize retries instead of firing them in parallel. The header has no effect on `preview` endpoints, which never create a payment. |
Request body
| Field | Type | Required | Possible values | Description |
|---|---|---|---|---|
BeneficiaryPaymentInstrumentID | string | Required | {paymentInstrumentID} | Payment instrument ID linked to the beneficiary (from List or Create Payment Instrument). |
Purpose | string | Required | Asset_Purchase | Contract_Payment | Other | Education_Payment | Payroll | dividends | Mortgage_Payments | Materials_Purchase | Loan_Payments | Professional_Service_Payments | Invoice_Payment | Investment_Purchase | Savings | Rent_Utility_Payments | reimbursements | Tax_Payments | Personal_Family_Payment | settlement_trade | treasury_movement | gift_donation | remittance | Regulatory purpose code for the payment. Must be one of the allowed values. |
Currency | string | Required | USD | BTC | ETH | USDC | USDT | BNB | MATIC | DOGE | ADA | DOT | Transaction currency (e.g. USD, BTC, ETH, USDC, USDT, BNB, MATIC, DOGE, ADA, DOT). |
Amount | string | Required | 1.00 | 2.00 | 3.00 | 4.00 | 5.00 | ... N | Payment amount in the specified currency, as a decimal string (e.g. `1.00`). |
CryptoBuySellActivity | string | Required | Yes | No | Whether the transaction involves buying or selling cryptocurrency: `Yes` or `No`. |
Intermediary_ABA | string | Required | 026001591 | Intermediary bank ABA routing number, when required for the payment route. |
SupportingDocument | string | Required | {fileID} | File ID from Upload File (`customField`: Payment_Invoice) for invoice or supporting documentation. |
Description | string | Required | Test API Payment | Short memo or narrative for the transaction (shown in history and details). |
Additional_Info | object | Optional | — | Optional extra payment metadata. When used, send inside the Fields array as field name `Additional_info` with an object value. |
IsRemittanceTransaction | string | Optional | Yes | No | Marks the payment as a remittance submitted on behalf of your own end customer. Only available when the remittance feature is enabled on your account; sending it otherwise is rejected. Defaults to `No`. |
UltimateDebtorId | string | Optional | {beneficiaryID} | Beneficiary ID of the Ultimate Debtor, i.e. your end customer who is the actual originator of the funds. Required when `IsRemittanceTransaction` is `Yes` and must be an active beneficiary belonging to your account. Must be omitted otherwise. |
Example request
{
"BeneficiaryPaymentInstrumentID": "{paymentInstrumentID}",
"Purpose": "Loan_Payments",
"Currency": "USD",
"Amount": "40",
"CryptoBuySellActivity": "No",
"Intermediary_ABA": "026001591",
"SupportingDocument": "{fileID}",
"Description": "Test API Payment"
}Response
| Field | Type | Possible values | Description |
|---|---|---|---|
ResponseCode | integer | 200 | 201 | 204 | 400 | 401 | 403 | 404 | 410 | 422 | 500 | 301 | 503 | 422 | API result code in the response envelope. Indicates success or the error category (e.g. 200 success, 400 bad request, 401 unauthorized). |
ResponseMessage | string | Success | Created | NoContent | BadRequest | Unauthorized | Forbidden | NotFound | Gone | UnprocessableContent | ServerError | ResourceMoved | ServiceUnAvailable | UnProcessableEntity | Human-readable label paired with ResponseCode (e.g. Success, BadRequest, Unauthorized). Use with ResponseCode to interpret the outcome. |
ResponseData | object | Please refer to below example for response body | Contains TransactionNumber for use with Get Transaction Details. |
Example response
{
"ResponseCode": 200,
"ResponseMessage": "Success",
"ResponseData": {
"TransactionNumber": "FV000007938"
}
}Requires `Authorization: Bearer {SessionToken}` from Get Session Token. Refresh via `x-refresh-token` when supplied; use the same client IP as authentication.