Class VirtualAccountAdminService

constructor

• new VirtualAccountAdminService(
      args: {
          db: B2bDatabase;
          entityService: EntityService;
          eventPublisher: CustomerEventPublisher;
          internalEventPublisher: InternalEventPublisher | null;
          ledgerAccountQueryService: LedgerAccountQueryService;
          paymentInstrumentVendorBackfillStarter: PaymentInstrumentVendorBackfillStarter;
          productQuoteService: ProductQuoteService;
          virtualAccountQueryService: VirtualAccountQueryService;
      },
  ): VirtualAccountAdminService

  Parameters

  • args: {
        db: B2bDatabase;
        entityService: EntityService;
        eventPublisher: CustomerEventPublisher;
        internalEventPublisher: InternalEventPublisher | null;
        ledgerAccountQueryService: LedgerAccountQueryService;
        paymentInstrumentVendorBackfillStarter: PaymentInstrumentVendorBackfillStarter;
        productQuoteService: ProductQuoteService;
        virtualAccountQueryService: VirtualAccountQueryService;
    }

    • db: B2bDatabase

    • entityService: EntityService

    • eventPublisher: CustomerEventPublisher

    • internalEventPublisher: InternalEventPublisher | null

      Publishes account.virtualAccount.hidden / .unhidden; null publishes nothing (tests).

    • ledgerAccountQueryService: LedgerAccountQueryService

    • paymentInstrumentVendorBackfillStarter: PaymentInstrumentVendorBackfillStarter

    • productQuoteService: ProductQuoteService

    • virtualAccountQueryService: VirtualAccountQueryService

  Returns VirtualAccountAdminService

Staticinstance

create

• create(
      args: {
          accountNumber: string;
          bankId: string;
          customerId: string;
          ledgerAccountId: string;
          name?: string;
          providerId: string;
          referenceId?: string | null;
          type: "US_DEPOSIT" | "US_DDA";
      },
  ): Promise<
      | {
          ok: true;
          value: {
              accountNumber: string;
              achDepositInstructions: AchDepositInstructions
              | null;
              createdAt: Date;
              data:
                  | {
                      provider: "VICTOR";
                      victorId: string;
                      victorLedgerProgramId: string;
                  }
                  | {
                      entityId: string;
                      entityInput?: {
                          businessAddress1: string;
                          businessAddress2?: string;
                          businessCity: string;
                          businessCountry: string;
                          businessName: string;
                          businessPostalCode: string;
                          businessStateProvinceRegion?: string;
                          businessType?: | "b_corporation"
                          | "c_corporation"
                          | "close_corporation"
                          | "cooperative"
                          | "general_partnership"
                          | "limited_liability_company"
                          | "limited_partnership"
                          | "nonprofit_corporation"
                          | "s_corporation"
                          | "sole_proprietorship"
                          | "non_us";
                          contactFirstName: string;
                          contactLastName: string;
                          email: string;
                          incorporationDate?: string;
                          phone?: string;
                          phoneCountry?: string;
                          taxNumber?: string;
                          websiteUrl?: string;
                      };
                      fundingInstructions: | {
                          accountHolderAddress1?: string
                          | null;
                          accountHolderAddress2?: string | null;
                          accountHolderCity?: string | null;
                          accountHolderCountry?: string | null;
                          accountHolderName: string | null;
                          accountHolderPostalCode?: string | null;
                          accountHolderStateProvinceRegion?: string | null;
                          accountNumber: string | null;
                          bankAddress1?: string | null;
                          bankAddress2?: string | null;
                          bankCity?: string | null;
                          bankCountry: string | null;
                          bankName: string | null;
                          bankPostalCode?: string | null;
                          bankStateProvinceRegion?: string | null;
                          currency: string | null;
                          message?: string | null;
                          qr?: { base64Image: ...; expirationDate: ...; qrDecoded: ... } | null;
                          reference: string | null;
                          routingCode: string | null;
                          routingCodeAlternate?: string | null;
                          swiftBic: string | null;
                          taxNumber?: string | null;
                          type: string | null;
                      }
                      | null;
                      programId: string;
                      provider: "ROUTE_FUSION";
                      walletId: string;
                  }
                  | { accountId?: string; masterAccountId: string; provider: "ZENUS" }
                  | null;
              deletedAt: Date | null;
              id: string;
              name: string | null;
              providerId: string;
              providerName: string;
              providerType: "VICTOR" | "BIVO" | "ROUTE_FUSION" | "ZENUS" | "MANUAL";
              providerTypeDescription: string;
              referenceId: string | null;
              routingNumber: string;
              rtpDepositInstructions: RtpDepositInstructions | null;
              status: "PENDING" | "ACTIVE" | "FAILED" | "INACTIVE";
              statusDescription: string;
              swiftDepositInstructions:
                  | (
                      | Omit<UsdSwiftWireInstructionData, "swiftField70Prefix"> & {
                          receivingEntityName: string;
                          swiftField70: SwiftField70Prefix;
                      }
                      | Omit<ForeignSwiftWireInstructionData, "swiftField70Prefix"> & {
                          receivingEntityName: string;
                          swiftField70: SwiftField70Prefix;
                      }
                  )[]
                  | null;
              type: "US_DEPOSIT"
              | "US_DDA";
              typeDescription: string;
              updatedAt: Date;
              walletAddress: Address;
              wireDepositInstructions: UsWireDepositInstructions | null;
          } & { customerId: string; entityId: string; ledgerAccountId: string };
      }
      | { error: ServiceError; ok: false },
  >

  Admin-creates an ACTIVE virtual account on an existing ledger account for a MANUAL-type provider — a bank we hold an out-of-band deposit account at but have no onboarding integration for. Unlike the Victor flow there's no partner API to call and nothing to poll: the row lands ACTIVE in one transaction, stamped with an audit product_quote.

  The provider must resolve to a MANUAL-type virtual_account_provider row (integrated victor/bivo/route_fusion providers are rejected — those mint through their own dispatcher). The bank supplies the customer-facing deposit instructions via the linked bank row.

  Parameters

  • args: {
        accountNumber: string;
        bankId: string;
        customerId: string;
        ledgerAccountId: string;
        name?: string;
        providerId: string;
        referenceId?: string | null;
        type: "US_DEPOSIT" | "US_DDA";
    }

    • accountNumber: string

    • bankId: string

    • customerId: string

    • ledgerAccountId: string

    • Optionalname?: string

    • providerId: string

      A virtual_account_provider externalId; must resolve to type MANUAL.

    • OptionalreferenceId?: string | null

    • type: "US_DEPOSIT" | "US_DDA"

  Returns Promise<
      | {
          ok: true;
          value: {
              accountNumber: string;
              achDepositInstructions: AchDepositInstructions
              | null;
              createdAt: Date;
              data:
                  | {
                      provider: "VICTOR";
                      victorId: string;
                      victorLedgerProgramId: string;
                  }
                  | {
                      entityId: string;
                      entityInput?: {
                          businessAddress1: string;
                          businessAddress2?: string;
                          businessCity: string;
                          businessCountry: string;
                          businessName: string;
                          businessPostalCode: string;
                          businessStateProvinceRegion?: string;
                          businessType?: | "b_corporation"
                          | "c_corporation"
                          | "close_corporation"
                          | "cooperative"
                          | "general_partnership"
                          | "limited_liability_company"
                          | "limited_partnership"
                          | "nonprofit_corporation"
                          | "s_corporation"
                          | "sole_proprietorship"
                          | "non_us";
                          contactFirstName: string;
                          contactLastName: string;
                          email: string;
                          incorporationDate?: string;
                          phone?: string;
                          phoneCountry?: string;
                          taxNumber?: string;
                          websiteUrl?: string;
                      };
                      fundingInstructions: | {
                          accountHolderAddress1?: string
                          | null;
                          accountHolderAddress2?: string | null;
                          accountHolderCity?: string | null;
                          accountHolderCountry?: string | null;
                          accountHolderName: string | null;
                          accountHolderPostalCode?: string | null;
                          accountHolderStateProvinceRegion?: string | null;
                          accountNumber: string | null;
                          bankAddress1?: string | null;
                          bankAddress2?: string | null;
                          bankCity?: string | null;
                          bankCountry: string | null;
                          bankName: string | null;
                          bankPostalCode?: string | null;
                          bankStateProvinceRegion?: string | null;
                          currency: string | null;
                          message?: string | null;
                          qr?: { base64Image: ...; expirationDate: ...; qrDecoded: ... } | null;
                          reference: string | null;
                          routingCode: string | null;
                          routingCodeAlternate?: string | null;
                          swiftBic: string | null;
                          taxNumber?: string | null;
                          type: string | null;
                      }
                      | null;
                      programId: string;
                      provider: "ROUTE_FUSION";
                      walletId: string;
                  }
                  | { accountId?: string; masterAccountId: string; provider: "ZENUS" }
                  | null;
              deletedAt: Date | null;
              id: string;
              name: string | null;
              providerId: string;
              providerName: string;
              providerType: "VICTOR" | "BIVO" | "ROUTE_FUSION" | "ZENUS" | "MANUAL";
              providerTypeDescription: string;
              referenceId: string | null;
              routingNumber: string;
              rtpDepositInstructions: RtpDepositInstructions | null;
              status: "PENDING" | "ACTIVE" | "FAILED" | "INACTIVE";
              statusDescription: string;
              swiftDepositInstructions:
                  | (
                      | Omit<UsdSwiftWireInstructionData, "swiftField70Prefix"> & {
                          receivingEntityName: string;
                          swiftField70: SwiftField70Prefix;
                      }
                      | Omit<ForeignSwiftWireInstructionData, "swiftField70Prefix"> & {
                          receivingEntityName: string;
                          swiftField70: SwiftField70Prefix;
                      }
                  )[]
                  | null;
              type: "US_DEPOSIT"
              | "US_DDA";
              typeDescription: string;
              updatedAt: Date;
              walletAddress: Address;
              wireDepositInstructions: UsWireDepositInstructions | null;
          } & { customerId: string; entityId: string; ledgerAccountId: string };
      }
      | { error: ServiceError; ok: false },
  >

delete

• delete(
      args: { deleted: boolean; id: string },
  ): Promise<
      { ok: true; value: { id: string } }
      | { error: ServiceError; ok: false },
  >

  Toggle whether a virtual account is soft-deleted (hidden from customer-facing reads). When deleted is true the consumer VirtualAccountService read paths filter the row out entirely.

  Parameters

  • args: { deleted: boolean; id: string }

  Returns Promise<
      { ok: true; value: { id: string } }
      | { error: ServiceError; ok: false },
  >

update

• update(
      args: {
          accountNumber?: string;
          bankId?: string;
          beneficiaryAddress?: Address | null;
          beneficiaryName?: string | null;
          depositReference?: string | null;
          id: string;
          routeFusion?: Partial<
              Pick<
                  {
                      entityId: string;
                      entityInput?: {
                          businessAddress1: string;
                          businessAddress2?: string;
                          businessCity: string;
                          businessCountry: string;
                          businessName: string;
                          businessPostalCode: string;
                          businessStateProvinceRegion?: string;
                          businessType?: | "b_corporation"
                          | "c_corporation"
                          | "close_corporation"
                          | "cooperative"
                          | "general_partnership"
                          | "limited_liability_company"
                          | "limited_partnership"
                          | "nonprofit_corporation"
                          | "s_corporation"
                          | "sole_proprietorship"
                          | "non_us";
                          contactFirstName: string;
                          contactLastName: string;
                          email: string;
                          incorporationDate?: string;
                          phone?: string;
                          phoneCountry?: string;
                          taxNumber?: string;
                          websiteUrl?: string;
                      };
                      fundingInstructions: | {
                          accountHolderAddress1?: string
                          | null;
                          accountHolderAddress2?: string | null;
                          accountHolderCity?: string | null;
                          accountHolderCountry?: string | null;
                          accountHolderName: string | null;
                          accountHolderPostalCode?: string | null;
                          accountHolderStateProvinceRegion?: string | null;
                          accountNumber: string | null;
                          bankAddress1?: string | null;
                          bankAddress2?: string | null;
                          bankCity?: string | null;
                          bankCountry: string | null;
                          bankName: string | null;
                          bankPostalCode?: string | null;
                          bankStateProvinceRegion?: string | null;
                          currency: string | null;
                          message?: string | null;
                          qr?:
                              | {
                                  base64Image: string
                                  | null;
                                  expirationDate: string | null;
                                  qrDecoded: string | null;
                              }
                              | null;
                          reference: string
                          | null;
                          routingCode: string | null;
                          routingCodeAlternate?: string | null;
                          swiftBic: string | null;
                          taxNumber?: string | null;
                          type: string | null;
                      }
                      | null;
                      programId: string;
                      provider: "ROUTE_FUSION";
                      walletId: string;
                  },
                  "walletId"
                  | "fundingInstructions",
              >,
          >;
          routingNumber?: string;
          status?: "PENDING" | "ACTIVE" | "FAILED" | "INACTIVE";
      },
  ): Promise<
      { ok: true; value: { id: string } }
      | { error: ServiceError; ok: false },
  >

  Writes the given fields on id. RouteFusion fields merge into data with jsonb ||, keeping every other key. Publishes no event and busts no cache; a status transition's caller owns both.

  Parameters

  • args: {
        accountNumber?: string;
        bankId?: string;
        beneficiaryAddress?: Address | null;
        beneficiaryName?: string | null;
        depositReference?: string | null;
        id: string;
        routeFusion?: Partial<
            Pick<
                {
                    entityId: string;
                    entityInput?: {
                        businessAddress1: string;
                        businessAddress2?: string;
                        businessCity: string;
                        businessCountry: string;
                        businessName: string;
                        businessPostalCode: string;
                        businessStateProvinceRegion?: string;
                        businessType?: | "b_corporation"
                        | "c_corporation"
                        | "close_corporation"
                        | "cooperative"
                        | "general_partnership"
                        | "limited_liability_company"
                        | "limited_partnership"
                        | "nonprofit_corporation"
                        | "s_corporation"
                        | "sole_proprietorship"
                        | "non_us";
                        contactFirstName: string;
                        contactLastName: string;
                        email: string;
                        incorporationDate?: string;
                        phone?: string;
                        phoneCountry?: string;
                        taxNumber?: string;
                        websiteUrl?: string;
                    };
                    fundingInstructions: | {
                        accountHolderAddress1?: string
                        | null;
                        accountHolderAddress2?: string | null;
                        accountHolderCity?: string | null;
                        accountHolderCountry?: string | null;
                        accountHolderName: string | null;
                        accountHolderPostalCode?: string | null;
                        accountHolderStateProvinceRegion?: string | null;
                        accountNumber: string | null;
                        bankAddress1?: string | null;
                        bankAddress2?: string | null;
                        bankCity?: string | null;
                        bankCountry: string | null;
                        bankName: string | null;
                        bankPostalCode?: string | null;
                        bankStateProvinceRegion?: string | null;
                        currency: string | null;
                        message?: string | null;
                        qr?:
                            | {
                                base64Image: string
                                | null;
                                expirationDate: string | null;
                                qrDecoded: string | null;
                            }
                            | null;
                        reference: string
                        | null;
                        routingCode: string | null;
                        routingCodeAlternate?: string | null;
                        swiftBic: string | null;
                        taxNumber?: string | null;
                        type: string | null;
                    }
                    | null;
                    programId: string;
                    provider: "ROUTE_FUSION";
                    walletId: string;
                },
                "walletId"
                | "fundingInstructions",
            >,
        >;
        routingNumber?: string;
        status?: "PENDING" | "ACTIVE" | "FAILED" | "INACTIVE";
    }

    • OptionalaccountNumber?: string

    • OptionalbankId?: string

      The bank the account receives deposits at, by slug.

    • OptionalbeneficiaryAddress?: Address | null

    • OptionalbeneficiaryName?: string | null

    • OptionaldepositReference?: string | null

    • id: string

    • OptionalrouteFusion?: Partial<
          Pick<
              {
                  entityId: string;
                  entityInput?: {
                      businessAddress1: string;
                      businessAddress2?: string;
                      businessCity: string;
                      businessCountry: string;
                      businessName: string;
                      businessPostalCode: string;
                      businessStateProvinceRegion?: string;
                      businessType?: | "b_corporation"
                      | "c_corporation"
                      | "close_corporation"
                      | "cooperative"
                      | "general_partnership"
                      | "limited_liability_company"
                      | "limited_partnership"
                      | "nonprofit_corporation"
                      | "s_corporation"
                      | "sole_proprietorship"
                      | "non_us";
                      contactFirstName: string;
                      contactLastName: string;
                      email: string;
                      incorporationDate?: string;
                      phone?: string;
                      phoneCountry?: string;
                      taxNumber?: string;
                      websiteUrl?: string;
                  };
                  fundingInstructions: | {
                      accountHolderAddress1?: string
                      | null;
                      accountHolderAddress2?: string | null;
                      accountHolderCity?: string | null;
                      accountHolderCountry?: string | null;
                      accountHolderName: string | null;
                      accountHolderPostalCode?: string | null;
                      accountHolderStateProvinceRegion?: string | null;
                      accountNumber: string | null;
                      bankAddress1?: string | null;
                      bankAddress2?: string | null;
                      bankCity?: string | null;
                      bankCountry: string | null;
                      bankName: string | null;
                      bankPostalCode?: string | null;
                      bankStateProvinceRegion?: string | null;
                      currency: string | null;
                      message?: string | null;
                      qr?:
                          | {
                              base64Image: string
                              | null;
                              expirationDate: string | null;
                              qrDecoded: string | null;
                          }
                          | null;
                      reference: string
                      | null;
                      routingCode: string | null;
                      routingCodeAlternate?: string | null;
                      swiftBic: string | null;
                      taxNumber?: string | null;
                      type: string | null;
                  }
                  | null;
                  programId: string;
                  provider: "ROUTE_FUSION";
                  walletId: string;
              },
              "walletId"
              | "fundingInstructions",
          >,
      >

    • OptionalroutingNumber?: string

    • Optionalstatus?: "PENDING" | "ACTIVE" | "FAILED" | "INACTIVE"

  Returns Promise<
      { ok: true; value: { id: string } }
      | { error: ServiceError; ok: false },
  >