Create Virtual Bank Account

1 import requests 2 3 url = "https://api-test.koywe.com/api/v1/organizations/org_abc123/merchants/merchant_123/virtual-accounts" 4 5 payload = { 6 "country": "AR", 7 "currency": "ARS" 8 } 9 headers = { 10 "Authorization": "Bearer <token>", 11 "Content-Type": "application/json" 12 } 13 14 response = requests.post(url, json=payload, headers=headers) 15 16 print(response.json())

1 { 2 "id": "pivba_123456", 3 "merchantId": "merchant-456", 4 "country": "AR", 5 "currency": "ARS", 6 "isActive": true, 7 "createdAt": "2025-10-25T12:00:00Z", 8 "updatedAt": "2025-10-25T12:00:00Z", 9 "virtualBankAccountNumber": "0000000000000000000000", 10 "alias": "john.doe.koywe" 11 }

Supported Countries & Currencies:

🇦🇷 Argentina (AR) → ARS (Argentine Peso)
🇲🇽 Mexico (MX) → MXN (Mexican Peso)

Business Rules:

Each merchant can have only one virtual account per country/currency combination
Account creation is processed asynchronously Roles with Access:
Platform Admin
Wallet & Bank Admin

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) - 🇲🇽 Mexico (MX) → MXN (Mexican Peso) **Business Rules:** - Each merchant can have only one virtual account per country/currency combination - Account creation is processed asynchronously **Roles with Access:** - Platform Admin - Wallet & Bank Admin

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path Parameters

organizationIdstringRequired

Organization identifier

merchantIdstringRequired

Merchant identifier

Request

This endpoint expects an object.

countryenumRequired

Two-letter country code (AR or MX)

Allowed values:

currencyenumRequired

Currency code (ARS or MXN)

Allowed values:

Response

Virtual bank account created successfully

idstring

Virtual bank account ID

merchantIdstring

Merchant ID

countryenum

Country code

Allowed values:

currencyenum

Currency code

Allowed values:

isActiveboolean

Active status of the account

createdAtdatetime

Creation date

updatedAtdatetime

Last update date

virtualBankAccountNumberstring or null

Virtual bank account number

aliasstring or null

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

Create Virtual Bank Account

Authentication

Path Parameters

Headers

Request

Response

Errors