Cuentas Externas

Las cuentas externas son cuentas bancarias pre-registradas y verificadas que los socios referencian por ID en Órdenes FX y Transferencias.

La superficie hacia el socio está dividida entre dos APIs por propósito:

Registro y listado viven bajo /customers/me/external-accounts/* porque están con alcance al cliente autenticado. El endpoint independiente /externalAccounts/validate no tiene alcance — responde "este IBAN es parseable + checksum válido" sin comprometer ningún estado.

Inicio rápido

# Paso 1: Validar un formato de IBAN (sin mutación de estado)
curl -fsS -X POST "https://sandbox-api.ariari.xyz/api/v1/externalAccounts/validate" \
  -H "Ocp-Apim-Subscription-Key: $SU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "iban": "CR07058919882707497149" }'
# { "valid": true, "country_code": "CR", "bank_code": "0589", ... }

# Paso 2: Registrar el IBAN validado bajo el cliente autenticado
curl -fsS -X POST "https://sandbox-api.ariari.xyz/api/v1/customers/me/external-accounts" \
  -H "Ocp-Apim-Subscription-Key: $SU_CLAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "CR07058919882707497149",
    "iban_holder": "Mario Herrera",
    "currency": "CRC"
  }'
# { "external_account_id": "880e8400-e29b-41d4-a716-446655440000",
#   "verification_status": "pending", ... }

Una vez que verification_status avanza a verified (típicamente en segundos para IBANs de Costa Rica; más para transfronterizos), el external_account_id es utilizable en createOrder y flujos de transferencia.

Ejemplo multi-lenguaje — `getMyExternalAccounts`

Generado desde el spec OpenAPI vivo. Elija su lenguaje; su elección persiste a través de otras páginas.

curl -fsS -X GET "https://sandbox-api.ariari.xyz/api/v1/customers/me/external-accounts" \
  -H "Ocp-Apim-Subscription-Key: $YOUR_KEY"

const response = await fetch('https://sandbox-api.ariari.xyz/api/v1/customers/me/external-accounts', {
  method: 'GET',
  headers: {
    'Ocp-Apim-Subscription-Key': process.env.ARI_SANDBOX_KEY!,
  },
});

if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.error_code}: ${problem.detail}`);
}

const result = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key",
    Environment.GetEnvironmentVariable("ARI_SANDBOX_KEY"));

var response = await client.GetAsync("https://sandbox-api.ariari.xyz/api/v1/customers/me/external-accounts");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadAsStringAsync();

val client = HttpClient(CIO) {
    install(ContentNegotiation) { json() }
}

val response: HttpResponse = client.get("https://sandbox-api.ariari.xyz/api/v1/customers/me/external-accounts") {
    header("Ocp-Apim-Subscription-Key", System.getenv("ARI_SANDBOX_KEY"))
}

val result: String = response.bodyAsText()

Vea también

• Referencia del objeto `ExternalAccount` — esquema en el cable y ciclo de verificación
• Autenticación — modelo de clave de suscripción APIM, scope accounts.manage
• Clientes — las operaciones de registro y listado viven bajo /customers/me/external-accounts/*
• Idempotencia — el registro es idempotente sobre el IBAN
• Errores — códigos DB-CUS-* y GW-STC-* alrededor de verificación
• Órdenes FX y Transferencias — consumidores principales de cuentas registradas
• Sandbox — sufijos de IBAN determinísticos para escenarios de verificación