Guides/Send Stablecoin Payments

Send Stablecoin Payments

This use case demonstrates how to send stablecoin payments (e.g., PYUSD, USDC) from your FV account to a blockchain address.

Stablecoin payments allow you to transfer digital dollars over blockchain networks while funding the transaction from your USD account.

💡 How Stablecoin Payments Work

You initiate a payment in USD
The equivalent value is converted and sent as a stablecoin (PYUSD / USDC)
Funds are primarily deducted from your Account USD balance

🧠 Smart Sweep (Optional Feature)

If enabled on your account:

If the USD account balance is insufficient
The remaining amount is automatically deducted from your Custody USD balance

⚠️ This feature is enabled on-demand for specific merchants

🔄 Flow Overview

code


Create Beneficiary → Add Wallet Address (Payment Instrument) → Initiate Payment → Track Transaction

📊 Data Flow

code


BeneficiaryID → PaymentInstrumentID → TransactionID

✅ Prerequisites

A valid SessionToken
Include the following header in all requests:

code


X-AUTH-TOKEN: {{session_token}}

Beneficiary must be created
Wallet address must be added as a payment instrument

Create Beneficiary

(Same as bank payments)

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" },
  …

Add Wallet Address (Payment Instrument)

🪙 Create Stablecoin Payment Instrument (Node.js)

Use this endpoint to create a crypto wallet payment instrument (e.g., USDC) for a beneficiary.

code


const axios = require('axios');
const baseUrl = "https://sandbox.merchant.fvbank.us/v2";
const sessionToken = "your_session_token_here";
async function createStablecoinInstrument() {
  try {
    const response = await axios.post(
      `${baseUrl}/payment-instruments/create`,
      [
        { "field": "Payment_Type", "value": "CRYPTO_WALLET.USDC" },
        { "field": "BeneficiaryId", "value": "ben_12345" },
        { "field": "Nickname", "value": "Mark USDC Wallet" },
  …

Response:

code


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

📌 Note

BeneficiaryId must be created beforehand using the Create Beneficiary API
Address should be a valid blockchain wallet address
Ensure Blockchain and Asset match (e.g., ETH + USDC)
The response will include a PaymentInstrumentID used for initiating stablecoin payments

Initiate Stablecoin Payment

🪙 Create Stablecoin Payment (Node.js)

Use this endpoint to initiate a stablecoin withdrawal (e.g., USDC, PYUSD) to a beneficiary’s crypto wallet.

code


const axios = require('axios');
const baseUrl = "https://sandbox.merchant.fvbank.us/v2";
const sessionToken = "your_session_token_here";
async function createStablecoinPayment() {
  try {
    const response = await axios.post(
      `${baseUrl}/stablecoin/withdraw`,
      {
        "BeneficiaryPaymentInstrumentID": "pi_crypto_123",
        "Amount": "100",
        "Description": "Stablecoin payout"
  …

📌 Note

BeneficiaryPaymentInstrumentID must refer to a crypto wallet instrument
The equivalent USD amount will be deducted from your account
If Smart Sweep is enabled, insufficient balance may be covered from custody funds
Use this endpoint to send stablecoins like USDC or PYUSD to external wallets

Response:

code


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

Track Transaction Status

📊 Track Transaction Status

Once a payment is created, you can track its progress using the Transaction Details API. This helps you monitor both compliance status and execution status of the transaction.

🔍 Fetch Transaction Details (Node.js)

Use the TransactionNumber received during payment creation to fetch the latest status:

code


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

📦 Example Response

code


{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ResponseData": {
    "TransactionNumber": "FV000694629",
    "CreatedAt": "2026-04-10T05:45:45.516-04:00",
    "Amount": "0.01",
    "From": "Rishav LLC",
    "To": "USDC Wallet",
    "Currency": "USD",
    "Description": "lorem ipsum",
  …

🧠 Understanding Transaction Status

The Status field represents the current stage of the transaction:

PENDING_AUTHORIZATION → Awaiting compliance approval
AUTHORIZED → Approved and ready for processing
IN_PROCESS → Payment is being processed
COMPLETED → Funds successfully transferred
FAILED → Payment failed
CANCELLED → Cancelled by compliance

🔗 Additional Details

The response also includes an AdditionalData array with extended information such as:

Destination currency (e.g., USDC)
Blockchain network
Beneficiary details
Processing gateway (e.g., Circle)

📌 Summary

code


Create Payment → Get TransactionNumber → Track via API / Webhooks

This ensures complete visibility into the transaction lifecycle.

🪙 Stablecoin Deposits

FV Bank also supports receiving stablecoins.

Each merchant is assigned a unique blockchain deposit address
Funds sent to this address are credited to the merchant account

How it works:

code


External Wallet → FV Deposit Address → Custody Balance → Account Balance (if applicable)

Deposit addresses are provided by FV Bank
Supported assets include USDC, PYUSD
Deposits are processed after blockchain confirmations

⚠️ Common Errors

Invalid wallet address
Unsupported network
Insufficient USD balance
Smart sweep not enabled (if relying on custody funds)
Expired SessionToken

📌 Summary

code


BeneficiaryID → PaymentInstrumentID → TransactionID

Stablecoin payments enable fast, global transfers using blockchain rails while maintaining USD-based accounting.

Related endpoints