Virtual Bank Accounts

Request a Virtual USD Bank Account

mutation {
  requestVirtualBankAccount(customerId: "customer_id") {
    id
    status
  }
}

Argument	Type	Required	Description
customer	ID!	Yes	The ID of the customer to request the virtual bank account for. (Create a customer).

The mutation returns the new virtual bank account’s global id, which you’ll reference in future calls (e.g., fetching the full account details).

Important Notes

• The virtual bank account is only available for USD ACH payments.

• The issuance fee is free, but the KYC fee is a non-refundable $3 fee. Ensure your balance is sufficient to cover the fee.

• We'll email your customer the KYC form & ToS to complete.

• We recommend that your customer submit their International Passport for KYC to increase the chances of approval and account issuance.

---

Fetch a Virtual Bank Account

query {
  virtualBankAccount(id: "virtual_bank_account_id") {
    id
    accountName
    accountNumber
    bankName
    city
    country
    line1
    postalCode
    state
    routingNumber
    status
    createdAt
  }
}

Argument	Type	Required	Description
id	ID!	Yes	The ID of the virtual bank account to fetch.

The query returns the full details of the virtual bank account.

Virtual Bank Account Statuses

Status	Description
requested	Account has been requested, waiting for KYC verification and ToS acceptance to complete
pending	KYC verified and ToS accepted, account creation is in progress
active	Account successfully created and ready to use
freezing	Account is frozen or suspended

---

Fetch Virtual Bank Account KYC Info

query {
  virtualBankAccountKycInfo(merchantCustomer: "merchant_customer_id") {
    kycLink
    tosLink
    kycStatus
    tosStatus
    kycRejectionReason
    kycRejectionReasons {
      reason
      developerReason
    }
    pendingIssues
  }
}

Argument	Type	Required	Description
merchantCustomer	ID!	Yes	The ID of the merchant customer to fetch KYC info for.

The query returns:

• kycLink - URL to the KYC verification form

• tosLink - URL to the Terms of Service agreement

• kycStatus - Completion status of the KYC verification

• tosStatus - Completion status of the ToS agreement

• kycRejectionReason - Flat string summary of rejection reasons (only present when kycStatus is rejected or incomplete)

• kycRejectionReasons - Structured list of rejection reasons (only present when kycStatus is rejected or incomplete), each containing:

  • reason - Human-readable rejection reason

  • developerReason - Technical reason intended for debugging

• pendingIssues - List of outstanding issues that need to be resolved for KYC approval

KYC Status Values

Status	Description
pending	KYC verification is in progress
verified	KYC has been approved and verified
incomplete	KYC requires additional information — check kycRejectionReasons and pendingIssues for details
rejected	KYC has been rejected — check kycRejectionReasons for details

TOS Status Values

Status	Description
pending	Terms of Service has not been accepted yet
verified	Terms of Service has been accepted