Skip to main content

Bridge - Cuentas Virtuales

Endpoints para gestión de cuentas virtuales e IBAN en Bridge.

1. Crear Cuenta Virtual​

POST /bridge/virtual-accounts

Crea una nueva cuenta virtual en Bridge.

Headers:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

Body:

{
  "sourceCurrency": "usd"
}

Respuesta Exitosa (201):

{
  "success": true,
  "data": {
    "id": "va_123456",
    "account_number": "1234567890",
    "routing_number": "123456789",
    "source": {
      "currency": "usd"
    },
    "destination": {
      "currency": "usdc",
      "payment_rail": "base",
      "address": "0x26818c85192ddf841e98d6d7f5ac64e4f50a2f44"
    },
    "status": "active"
  },
  "message": "Cuenta virtual USD creada exitosamente"
}

Respuesta de Error (404):

{
  "message": "El usuario no tiene un customer activo en Bridge",
  "error": "Not Found",
  "statusCode": 404
}

2. Crear Cuenta IBAN​

POST /bridge/iban-account

Crea una cuenta IBAN (EUR) en Bridge.

Headers:

Authorization: Bearer <JWT_TOKEN>

Respuesta Exitosa (201):

{
  "success": true,
  "data": {
    "id": "iban_123456",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "source": {
      "currency": "eur"
    },
    "destination": {
      "currency": "eurc",
      "payment_rail": "base",
      "address": "0x26818c85192ddf841e98d6d7f5ac64e4f50a2f44"
    },
    "status": "active"
  },
  "message": "Cuenta IBAN (EUR) creada exitosamente"
}

3. Obtener Cuentas Virtuales​

GET /bridge/virtual-accounts

Obtiene todas las cuentas virtuales del usuario.

Headers:

Authorization: Bearer <JWT_TOKEN>

Respuesta Exitosa (200):

{
  "success": true,
  "data": {
    "virtual_accounts": [
      {
        "id": "va_123456",
        "account_number": "1234567890",
        "routing_number": "123456789",
        "source": {
          "currency": "usd"
        },
        "destination": {
          "currency": "usdc",
          "payment_rail": "base"
        },
        "status": "active"
      }
    ]
  },
  "message": "Cuentas virtuales obtenidas exitosamente"
}

💳 Tipos de Cuentas​

Cuenta Virtual USD​

  • Moneda: USD (Dólares)
  • Account Number: 10 dígitos
  • Routing Number: 9 dígitos
  • Destino: USDC en Base
  • Uso: Recibir transferencias bancarias USD

Cuenta IBAN EUR​

  • Moneda: EUR (Euros)
  • IBAN: Formato estándar europeo
  • BIC/SWIFT: Código bancario
  • Destino: EURC en Base
  • Uso: Recibir transferencias SEPA

🔄 Flujo de Conversión​

USD → USDC​

  1. Transferencia: Cliente envía USD a cuenta virtual
  2. Detección: Bridge detecta la transferencia
  3. Conversión: USD se convierte automáticamente a USDC
  4. Depósito: USDC se deposita en wallet del usuario

EUR → EURC​

  1. Transferencia: Cliente envía EUR via SEPA
  2. Detección: Bridge detecta la transferencia
  3. Conversión: EUR se convierte automáticamente a EURC
  4. Depósito: EURC se deposita en wallet del usuario

🏦 Detalles Bancarios​

Cuenta Virtual USD​

{
  "account_number": "1234567890",
  "routing_number": "123456789",
  "bank_name": "Bridge Financial",
  "account_type": "Checking"
}

Cuenta IBAN EUR​

{
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "bank_name": "Bridge Europe",
  "account_holder": "Bridge Financial Services"
}

📍 Payment Rails​

Base Network​

  • USDC: USD Coin en Base
  • EURC: Euro Coin en Base
  • Red: Ethereum Layer 2
  • Confirmaciones: ~2-5 minutos

Otras Redes (Futuro)​

  • Ethereum Mainnet
  • Polygon
  • Arbitrum

📊 Estados de Cuenta​

Estados Principales​

  • active - Cuenta activa y funcional
  • pending - En proceso de activación
  • suspended - Suspendida temporalmente
  • closed - Cerrada permanentemente

Validaciones​

  • Customer verificado requerido
  • Límites diarios y mensuales
  • Compliance KYC/AML

💰 Límites y Comisiones​

Límites Estándar​

  • Diario: $10,000 USD / €10,000 EUR
  • Mensual: $50,000 USD / €50,000 EUR
  • Por transferencia: $500 - $25,000

Comisiones​

  • Transferencias entrantes: Gratis
  • Conversión: 0.1% - 0.5%
  • Fees de red: Variables según red

⚠️ Errores Comunes​

  • 404 Not Found: Customer no activo en Bridge
  • 400 Bad Request: Moneda no soportada
  • 409 Conflict: Cuenta ya existe para esa moneda
  • 403 Forbidden: Límites excedidos

📝 Notas Importantes​

  • Se requiere customer verificado antes de crear cuentas
  • Cada usuario puede tener una cuenta por moneda
  • Las cuentas se crean instantáneamente pero pueden tardar en activarse
  • Los depósitos se procesan automáticamente 24/7
  • Los fondos se convierten automáticamente a crypto al recibirse