> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verificar un alias de pago

Comprueba si hay un alias de pago activo y consulta los datos del propietario enmascarado antes de enviar un pago. Actualmente disponible solo para Colombia.

Utiliza este endpoint para consultar un alias de pago antes de enviar un payout. Devuelve el estado del alias y una vista enmascarada del propietario registrado, de modo que puedas confirmar que el alias está activo y corresponde al destinatario esperado. Se trata de una consulta de solo lectura. No crea una transacción ni reserva fondos.

Llamar a este endpoint es opcional. Puedes enviar un payout directamente mediante [Enviar fondos mediante transferencia bancaria](https://docs.localpayment.com/es/docs/send-funds-via-bank-transfer.md) sin verificar primero el alias. Comprobarlo de antemano reduce los payouts fallidos causados por un alias inactivo o no registrado.

> [!NOTE]
>
> **Actualmente disponible solo para Colombia.** `countryISOCode` solo acepta `CO` y `aliasClassification` solo acepta `Breb` (el sistema de pago instantáneo Bre-B de Colombia). En el futuro podría añadirse compatibilidad con otros países y clasificaciones de alias.

## Antes de comenzar

Asegúrate de tener:

* [Credenciales API válidas](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) (token de acceso).
* El alias que deseas verificar, junto con su clasificación.

## Endpoint

```
POST https://api.stage.localpayment.com/api/payment/alias-detail
```

Los detalles completos de parámetros y esquemas también están disponibles en la referencia de la API **[Get Alias Detail](https://docs.localpayment.com/es/reference/get-alias-detail.md)**.

### Encabezados obligatorios

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Content-Type: application/json
Authorization: Bearer <your_access_token>
```

### Cuerpo de la solicitud

| Campo | Descripción | Requerido |
| - | - | - |
| `countryISOCode` | País del alias, en formato ISO 3166-1 alfa-2. Actualmente solo se admite `CO` (Colombia). | Sí |
| `aliasClassification` | Clasificación del alias. Actualmente solo se admite `Breb` (una llave Bre-B de Colombia). | Sí |
| `aliasValue` | El alias a verificar (número de teléfono, documento, correo electrónico, código de comerciante o clave alfanumérica). | Sí |

> [!NOTE]
>
> `countryISOCode` toma el código de 2 letras (`CO`), no el código de 3 letras (`COL`) que utilizan la mayoría de los demás endpoints de Localpayment. Esto coincide con la API en producción y no debe "corregirse" en tu integración.

### Ejemplo de solicitud

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url 'https://api.stage.localpayment.com/api/payment/alias-detail' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --data '{
    "countryISOCode": "CO",
    "aliasClassification": "Breb",
    "aliasValue": "3668933567"
  }'
```

## Gestionar la respuesta

### Respuesta exitosa

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "aliasType": "PHONE",
  "aliasValue": "3668933567",
  "bankName": "KAMIN S.A",
  "firstName": "John",
  "idType": "CC",
  "idValue": "******0695",
  "lastName": "Do**",
  "status": "ACTIVE"
}
```

### Campos de la respuesta y enmascaramiento

Localpayment enmascara los datos personales en la respuesta. Solo se devuelven los campos que se indican a continuación, y únicamente en esta forma enmascarada.

| Campo | Descripción | Enmascaramiento aplicado |
| - | - | - |
| `firstName` | Nombre de pila registrado del propietario del alias. | Ninguno. |
| `lastName` | Apellido registrado del propietario del alias. | Se muestran las 2 primeras letras y el resto se enmascara (`Doe` se convierte en `Do**`). |
| `status` | Estado actual del alias (por ejemplo, `ACTIVE`). | Ninguno. |
| `idType` | Tipo de documento de identidad del propietario (consulte [Tipos de documentos admitidos](https://docs.localpayment.com/es/docs/colombia.md#supported-document-types)). | Ninguno. |
| `idValue` | Número del documento de identidad del propietario. | Solo se muestran los últimos 4 dígitos y el resto se enmascara (`20304050` se convierte en `****4050`). |
| `aliasType` | Clasificación del alias que se resolvió. Para las llaves Bre-B de Colombia: documento de identidad, código de comerciante, número de celular, dirección de correo electrónico o clave alfanumérica. | Ninguno. |
| `aliasValue` | El alias que consultó, devuelto tal cual. | Ninguno. |
| `bankName` | Nombre del banco donde está registrado el alias. | Ninguno. |

### Manejo de errores

| Escenario | Estado HTTP | Mensaje |
| - | - | - |
| El alias no corresponde a un propietario registrado o está inactivo. | `400 Bad Request` | `{"error": "DICE error: Keys not found or inactive", "errorCode": "408"}` |
| La combinación de país o clasificación no es compatible. | `422 Unprocessable Entity` | `{"error": "Service not available for Breb in COL"}` |
| Falta el token de acceso, o este no es válido o ha caducado. | `401 Unauthorized` | Error de autenticación estándar. |

Gestiona siempre estos casos en tu integración en lugar de suponer que todas las consultas se realizan correctamente. Para obtener orientación general sobre cómo interpretar los códigos de estado HTTP y la estructura de las respuestas de error en la API de Localpayment, consulta [Manejo de errores](https://docs.localpayment.com/es/docs/error-handling.md).

## Demo

Prueba la consulta con un alias de ejemplo para ver cómo aparece el resultado enmascarado. La demo refleja el alcance actual: solo Colombia.

Verificar un alias de payout
![Localpayment](https://docs.localpayment.com/images/brand/logo-localpayment-white.png)

POST /api/payment/alias-detail

Solo Colombia

Alias (aliasValue)

Datos de muestra con fines ilustrativos. No llama a la API real de Localpayment.

***

## Próximos pasos

> [card] [Enviar fondos mediante transferencia bancaria](https://docs.localpayment.com/es/docs/send-funds-via-bank-transfer.md)
>
> Envía un payout utilizando el alias que verificó.

> [card] [Colombia](https://docs.localpayment.com/es/docs/colombia.md)
>
> Consulta los bancos admitidos, los tipos de documento y los métodos de payout para Colombia.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.