FAQs

Authentication is a two-step JWT-based flow:

1. Generate a signed JWT (HS256) using your ClientID and ClientSecret.
2. Send that JWT in the X-AUTH-TOKEN header to GET /v2/auth — you'll receive a SessionToken.
3. Use the SessionToken as Authorization: Bearer <SessionToken> on all subsequent secured API calls.

The SessionToken is typically valid for about 15 minutes. Reuse the same token until it expires rather than generating a new one per request.

If an API returns 401 Unauthorized, regenerate the SessionToken via /v2/auth. Additionally, a refreshed token may be returned in the x-refresh-token response header on regular calls — if present, replace your stored token with it and continue without re-authenticating.

API requests must originate from the same IP address used during authentication. If your traffic comes from a different IP than the one that generated the SessionToken, requests will be rejected. Regenerate the token from the correct IP, and check that the token hasn't expired.

Yes. The sandbox base URL is https://sandbox.merchant.fvbank.us/v2. Use it for all development and testing before moving to production.

Yes — the documentation site includes a Run in Postman link that lets you fork the full collection with all endpoints pre-configured.

First call POST /v2/beneficiary/get-required-fields, then POST /v2/beneficiary/create with only the fields returned there (type, name, email, address, etc.). The response returns a BeneficiaryID.

Allow up to 10 minutes after creation for the beneficiary status to turn Active. Payment instruments can only be created once the beneficiary is Active.

A payment instrument holds the banking (or wallet) details used to pay a beneficiary — for example, an ACH bank account with routing and account numbers. Create it via POST /v2/payment-instrument/create after the beneficiary is Active, and reference the returned PaymentInstrumentID when initiating payments.

Exception: FVNet payments do not require a beneficiary or payment instrument — you identify the recipient by FV Bank user email.

Yes. The flow (Create Beneficiary → Add Payment Instrument → Initiate Payment → Track Transaction) is identical for all fiat payment types. Only the Payment_Type value and the associated banking details change.

Always call the matching get-required-fields endpoint first and send only the field names returned there. Do not guess from examples.

Create Beneficiary → Add Payment Instrument → (optionally) Upload Supporting Document → Preview via POST /v2/payment/bank/preview → Submit via POST /v2/payment/bank → Track the transaction using the returned TransactionNumber.

Use availableBalance, not total balance. Reserved amounts are pending authorization and are not spendable.

Upload the file first using POST /v2/files/upload with customField and fileName query parameters. The response returns a File ID, which you pass as SupportingDocument when initiating the payment. Some payment types require a supporting document depending on amount thresholds.

Files must be under 5 MB, use a supported file type (png, jpg, jpeg, pdf), and be submitted with the correct customField mapping (e.g. Payment_Invoice for payment supporting documents).

Use GET /v2/transactions/details/{TransactionNumber}. The TransactionNumber is returned when you create the payment, and also appears in transaction listing APIs and webhook payloads. Prefer webhooks for real-time updates; poll this endpoint for on-demand refresh and reconciliation.

Missing or invalid SessionToken, incorrect BeneficiaryID or PaymentInstrumentID, beneficiary/instrument not Active, missing SupportingDocument when required, invalid bank details (routing/account number), insufficient availableBalance, or an expired session without refresh handling.

An optional header on POST /v2/payment/bank and POST /v2/cross-border (also accepted on their preview endpoints). When provided (max 255 characters), the key is stored on the payment and 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, so no second payment is created. Reuse the same key only when retrying the same logical payment; use a new key for a new payment.

Virtual accounts are unique account numbers assigned to individual beneficiaries. They let you receive deposits and automatically map incoming funds to the correct beneficiary, enabling automated reconciliation.

Virtual accounts can be created along with the beneficiary by including the additional virtual-account fields in POST /v2/beneficiary/create, or added later via POST /v2/beneficiary/add-virtual-account/{beneficiaryId} after calling get-required-fields-for-virtual-account. FV Bank then generates a virtual account number and deposit instructions.

Fetch beneficiary details via GET /v2/beneficiary/{beneficiaryId} after creation, then share the deposit instructions with your beneficiary.

When funds arrive, FV Bank creates a deposit transaction that includes a Virtual Account identifier (in webhooks, under AdditionalData). Store your Beneficiary ID ↔ Virtual Account mapping and use the identifier to reconcile deposits automatically.

Webhooks are real-time HTTP POST notifications sent to your server when events occur — such as payment status updates or deposit confirmations — eliminating the need to continuously poll the APIs.

It must be a publicly accessible HTTPS endpoint that accepts POST requests and returns a 200 OK response to acknowledge receipt.

Each webhook includes a signature header. Compute an HMAC SHA256 of the request payload using your webhook secret and compare it to the signature (use a timing-safe comparison). Reject any request whose signature doesn't match.

Any non-200 response triggers automatic retries with increasing intervals. Because retries can cause duplicate deliveries, make your endpoint idempotent — for example, by storing processed event IDs.

Verify signatures before processing, store processed event IDs to prevent duplicates, return 200 OK quickly and process asynchronously, and use webhooks for real-time updates while using the APIs for reconciliation.

Yes — use the Re-Send Webhook endpoint in the API Reference to trigger redelivery of a webhook event.

All errors share a consistent structure: ResponseCode (HTTP status), ResponseMessage (high-level error type), RequestID (unique trace identifier), and ResponseErrors (a list of detailed messages). Always log the RequestID — it's what support uses to trace your request.

• 200 — success
• 400 — bad request / validation error
• 401 — unauthorized (invalid or expired token)
• 403 — forbidden (insufficient permissions)
• 404 — resource not found
• 500 — internal server error

Validation errors mean the request input is missing or malformed (e.g. "Mandatory Fields are Missing", "Invalid Data") — fix the request body.

Business logic errors mean the request was valid but violates system rules (e.g. duplicate account, insufficient balance, compliance rejection) — verify the underlying data and eligibility before retrying.

Only after fixing the underlying issue. Implement retry logic solely for safe operations, and never blindly retry failed payments without validating the cause first.

Reach out to your FV Bank integration contact with the RequestID from the error response, the endpoint called, and the approximate timestamp — this allows the request to be traced directly.