ARi LogoPortal de Desarrolladores
|
Volver a Documentacion

ExternalAccount

Una ExternalAccount es un destino de pago verificado fuera de la plataforma ARi — típicamente una cuenta bancaria de Costa Rica accesible vía SINPE (rail sinpe) o, para destinos en stablecoins, una dirección accesible vía el rail de stablecoin. Una vez que usted ha creado y verificado una cuenta externa, esta queda direccionable en createTransfer y en el lado destino de createOrder (FX-y-luego-payout).

Las cuentas externas se asocian al cliente que las creó. Una llave de suscripción lista, crea e inspecciona cuentas externas por cliente.
Endpoints que la producen o devuelven POST /api/v1/external-accounts (crear), GET /api/v1/external-accounts (listar), GET /api/v1/external-accounts/{accountId}
Esquema en el cable ExternalAccountDto
Ciclo de vida Se crea en is_verified=false, pasa a true luego de la verificación aguas arriba. Disponible como destino de transferencia únicamente cuando está verificada.

Garantías del objeto

  • account_id se asigna en el servidor — nunca reutilice un identificador del lado del cliente.
  • iban se normaliza: se quitan los espacios y se convierte a mayúsculas; los socios pueden enviar cualquiera de las dos formas al crear.
  • Las cuentas con is_verified=false son visibles pero no se pueden usar como destino de transferencia — createTransfer devuelve DB-XA-409 cuando el destino resuelve a una cuenta no verificada.
  • bank_code y bank_name los completa ARi a partir del prefijo bancario del IBAN; los valores enviados por el socio al crear se ignoran.
  • La moneda se determina al crearla y es inmutable después — para agregar un payout en una moneda distinta al mismo beneficiario, cree una nueva cuenta.

Campos

Campo Tipo Requerido Descripción
account_id string (uuid) sí Identificador asignado por el servidor.
iban string (22 caracteres) sí IBAN de Costa Rica (o dirección de stablecoin para rails stablecoin).
iban_holder string no Nombre del titular mostrado en los recibos.
alias string no Nombre legible que define el socio.
bank_code string (4 dígitos) no Código bancario costarricense derivado del IBAN.
bank_name string no Nombre comercial del banco (solo UI; no lo parsee para enrutar).
currency string (ISO 4217) sí Moneda de liquidación (CRC, USD, etc.).
is_verified boolean sí true una vez que la verificación aguas arriba se completa.

Ejemplo

{
  "account_id": "ext_550e8400-e29b-41d4-a716-446655440000",
  "iban": "CR05015202001026284060",
  "iban_holder": "Comercial La Sabana",
  "alias": "Pagos Sabana",
  "bank_code": "0152",
  "bank_name": "Banco de Costa Rica",
  "currency": "CRC",
  "is_verified": true
}

Véase también