Guides/Send Bank Payments

Send Bank Payments

This use case demonstrates how to send a bank payment from your FV account to a beneficiary using Domestic ACH (USD).

The same flow can be used for other fiat payment types (e.g., Wire). Only the Payment_Type and related banking details need to be adjusted based on the payment method.

🔄 Flow Overview

code


Create Beneficiary → Add Payment Instrument → Upload File → Initiate Payment → Track Transaction

📊 Data Flow (IDs Across Steps)

code


BeneficiaryID → PaymentInstrumentID → FileId → TransactionID

✅ Prerequisites

A valid SessionToken
Include the following header in all requests:

code


X-AUTH-TOKEN: {{session_token}}

(Optional but required for some payments) Upload a supporting document using the Files API to obtain a FileId

Create Beneficiary

code


async function createBeneficiary() {
  try {
    const response = await axios.post(
      `${baseUrl}/beneficiary/create`,
      [
        { "field": "Beneficiary_Type", "value": "individual" },
        { "field": "Beneficiary_Email", "value": "john.doe@example.com" },
        { "field": "Beneficiary_Address", "value": "123 Main Street" },
        { "field": "Beneficiary_City", "value": "New York" },
        { "field": "Beneficiary_Postal_Code", "value": "10001" },
        { "field": "Beneficiary_Country", "value": "US" },
  …

Response:

code


{
  "ResponseData": {
    "BeneficiaryId": "4650983997967871956",
    "message": "Please allow 10 minutes for the beneficiary to turn Active. Once the beneficiary status is Active, You can create payment instruments."
  }
}

Add Payment Instrument (ACH Bank Account)

code


async function createACHInstrument() {
  try {
    const response = await axios.post(
      `${baseUrl}/payment-instrument/create`,
      [
        {
          "field": "Payment_Type",
          "value": "BUS_USD_Account.Business_ACH"
        },
        {
          "field": "BeneficiaryId",
  …

Response:

code


{
  ResponseCode: 200,
  ResponseMessage: 'Success',
  ResponseData: { PaymentInstrumentID: '-6477410681264623860' }
}

Upload Supporting Document

Use this endpoint to upload supporting documents (e.g., invoices) that can be attached to payments or other workflows.

code


const axios = require('axios');
const fs = require('fs');
const baseUrl = "https://sandbox.merchant.fvbank.us/v2";
const sessionToken = "your_session_token_here";
// 🔁 Update file path accordingly
const filePath = "/Users/rishav/Documents/Sample/Form_6_English.pdf";
async function uploadFile() {
  try {
    const response = await axios.post(
      `${baseUrl}/files/upload?customField=Payment_Invoice&fileName=Ducket.pdf`,
      fs.createReadStream(filePath),
  …

📌 Note

Refer to the Files Upload endpoint in the API Reference section to better understand:

Supported file types
Required query parameters (customField, fileName)
How uploaded files are used across flows (e.g., attaching documents to payments)

code


{
    "ResponseCode": 200,
    "ResponseMessage": "Success",
    "ResponseData": {
        "ID": "-4004934485838221358"
    }
}

Initiate Payment

💳 Create Bank Payment (Node.js)

Use this endpoint to initiate a bank payment (e.g., ACH/Wire) using a previously created payment instrument.

code


const axios = require('axios');
const baseUrl = "https://sandbox.merchant.fvbank.us/v2";
const sessionToken = "your_session_token_here";
async function createBankPayment() {
  try {
    const response = await axios.post(
      `${baseUrl}/payment/bank`,
      {
        "BeneficiaryPaymentInstrumentID": "-6391842288344584436",
        "Purpose": "Loan_Payments",
        "Currency": "USD",
  …

📌 Note

BeneficiaryPaymentInstrumentID is obtained from the Create Payment Instrument step
SupportingDocument is the File ID received after uploading a file via the Files Upload endpoint
Ensure all required compliance fields (e.g., Purpose, Description) are provided correctly

Response:

code


{
    "ResponseCode": 200,
    "ResponseMessage": "Success",
    "ResponseData": {
        "TransactionNumber": "FV000007938"
    }
}

Track Transaction Status

Use this endpoint to fetch detailed information about a specific transaction using the TransactionNumber.

code


const axios = require('axios');
const baseUrl = "https://sandbox.merchant.fvbank.us/v2";
const sessionToken = "your_session_token_here";
// 🔁 Replace with your actual Transaction Number
const transactionNumber = "FV000462103";
async function getTransactionDetails() {
  try {
    const response = await axios.get(
      `${baseUrl}/transactions/details/${transactionNumber}`,
      {
        headers: {
  …

📌 Note

TransactionNumber is obtained from:
- Payment creation response
- Transaction listing APIs
- Webhook payloads
Use this endpoint to:
- Track transaction status
- View complete transaction details
- Reconcile payments in your system

⚠️ Common Errors

Missing or invalid SessionToken
Incorrect BeneficiaryID or PaymentInstrumentID
Missing SupportingDocument when required
Invalid bank details (routing/account number)
Expired session without refresh handling

📌 Summary

code


BeneficiaryID → PaymentInstrumentID → FileId → TransactionID

This flow can be reused for all fiat payment types by adjusting the Payment_Type and required banking details.

Related endpoints