Merchant

Create Virtual Bank Account

Creates a new virtual bank account for a merchant within an organization. This endpoint initiates the creation process through the Payment Service Provider (PSP) and stores the account details locally.

Supported Countries & Currencies:

  • Argentina (AR) → ARS (Argentine Peso) — returns CVU + alias
  • Mexico (MX) → MXN (Mexican Peso) — returns CLABE
  • United States (US) → USD (US Dollar) — returns account number + routing number

Business Rules:

  • Each merchant can have only one virtual account per country/currency combination
  • For US/USD accounts, the merchant must have a KYC_APPROVED status Roles with Access:
  • Platform Admin
  • Wallet & Bank Admin
post/api/v1/organizations/{organizationId}/merchants/{merchantId}/virtual-accounts

Request

  • Base URL: https://api-sandbox.koywe.com
  • URL: https://api-sandbox.koywe.com/api/v1/organizations/{organizationId}/merchants/{merchantId}/virtual-accounts
  • Auth: HTTP bearer

Path parameters

organizationIdstring required
Example:org_abc123

Organization identifier

merchantIdstring required
Example:merchant_123

Merchant identifier

Request body

country'AR' | 'MX' | 'US' required

Two-letter country code (AR, MX, or US)

currency'ARS' | 'MXN' | 'USD' required

Currency code (ARS, MXN, or USD)

Example request

{
  "country": "AR",
  "currency": "ARS"
}

Response

Virtual bank account created successfully

idstring required

Virtual bank account ID

merchantIdstring required

Merchant ID

country'AR' | 'MX' | 'US' required

Country code

currency'ARS' | 'MXN' | 'USD' required

Currency code

isActiveboolean required

Active status of the account

virtualBankAccountNumberstring

Virtual bank account number

aliasstring

Custom alias for the virtual bank account. Contains only letters, numbers, and dots.

routingNumberstring

Routing number (USA/ACH). Optional.

bankNamestring

Bank name. Optional.

createdAtstring date-time required

Creation date

updatedAtstring date-time required

Last update date

Example response

{
  "id": "pivba_123456",
  "merchantId": "merchant-456",
  "country": "AR",
  "currency": "ARS",
  "isActive": true,
  "virtualBankAccountNumber": "0000000000000000000000",
  "alias": "john.doe.koywe",
  "routingNumber": "021000021",
  "bankName": "Chase Bank",
  "createdAt": "2025-10-25T12:00:00Z",
  "updatedAt": "2025-10-25T12:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.