> ## 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 um alias de pagamento

Verifique se um alias de pagamento está ativo e confira os detalhes do proprietário mascarado antes de enviar um pagamento. Disponível atualmente apenas para a Colômbia.

Use este endpoint para consultar um alias de pagamento antes de enviar um payout. Ele retorna o status do alias e uma visão mascarada do proprietário registrado, para que você possa confirmar que o alias está ativo e corresponde ao destinatário esperado. Esta é uma consulta somente leitura. Ela não cria uma transação e não reserva fundos.

Chamar este endpoint é opcional. Você ainda pode enviar um payout diretamente por meio de [Enviar fundos por transferência bancária](https://docs.localpayment.com/pt-br/docs/send-funds-via-bank-transfer.md) sem verificar o alias antes. Verificá-lo previamente reduz payouts com falha causados por um alias inativo ou não registrado.

> [!NOTE]
>
> **Disponível atualmente apenas para a Colômbia.** `countryISOCode` aceita somente `CO`, e `aliasClassification` aceita somente `Breb` (o sistema de pagamento instantâneo Bre-B da Colômbia). O suporte a outros países e classificações de alias poderá ser adicionado no futuro.

## Antes de começar

Certifique-se de ter:

* [Credenciais de API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) válidas (token de acesso).
* O alias que você deseja verificar, junto com sua classificação.

## Endpoint

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

Os detalhes completos de parâmetros e schemas também estão disponíveis na referência de API **[Get Alias Detail](https://docs.localpayment.com/pt-br/reference/get-alias-detail.md)**.

### Cabeçalhos obrigatórios

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

### Corpo da requisição

| Campo | Descrição | Obrigatório |
| - | - | - |
| `countryISOCode` | País do alias, no formato ISO 3166-1 alpha-2. Atualmente, apenas `CO` (Colômbia) é suportado. | Sim |
| `aliasClassification` | Classificação do alias. Atualmente, apenas `Breb` (uma chave Bre-B da Colômbia) é suportado. | Sim |
| `aliasValue` | O alias para verificação (número de telefone, documento, e-mail, código do comerciante ou chave alfanumérica). | Sim |

> [!NOTE]
>
> `countryISOCode` recebe o código de 2 letras (`CO`), e não o código de 3 letras (`COL`) usado pela maioria dos outros endpoints da Localpayment. Isso corresponde à API em produção e não deve ser "corrigido" na sua integração.

### Exemplo de solicitação

```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"
  }'
```

## Trate a resposta

### Resposta bem-sucedida

```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 da resposta e mascaramento

A Localpayment mascara dados pessoais na resposta. Somente os campos abaixo são retornados, e apenas nesta forma mascarada.

| Campo | Descrição | Máscara aplicada |
| - | - | - |
| `firstName` | Nome próprio registrado do proprietário do pseudônimo. | Nenhum. |
| `lastName` | Sobrenome registrado do proprietário do alias. | As 2 primeiras letras são exibidas e o restante é mascarado (`Doe` vira `Do**`). |
| `status` | Status atual do alias (por exemplo, `ACTIVE`). | Nenhum. |
| `idType` | Tipo de documento de identidade do titular (consulte [Tipos de documentos suportados](https://docs.localpayment.com/pt-br/docs/colombia.md#supported-document-types)). | Nenhum. |
| `idValue` | O número do documento de identidade do proprietário. | Apenas os últimos 4 dígitos são exibidos e o restante é mascarado (`20304050` vira `****4050`). |
| `aliasType` | Classificação do alias que foi resolvido. Para chaves Bre-B da Colômbia: documento de identidade, código do comerciante, número de celular, endereço de e-mail ou chave alfanumérica. | Nenhum. |
| `aliasValue` | O alias que você consultou, retornado na resposta. | Nenhum. |
| `bankName` | Nome do banco onde o pseudônimo está registrado. | Nenhum. |

### Tratamento de erros

| Cenário | Status HTTP | Mensagem |
| - | - | - |
| O alias não corresponde a um proprietário registrado ou está inativo. | `400 Bad Request` | `{"error": "DICE error: Keys not found or inactive", "errorCode": "408"}` |
| A combinação de país ou classificação não é suportada. | `422 Unprocessable Entity` | `{"error": "Service not available for Breb in COL"}` |
| O token de acesso está ausente, é inválido ou expirou. | `401 Unauthorized` | Erro de autenticação padrão. |

Sempre trate esses casos na sua integração, em vez de presumir que toda consulta será bem-sucedida. Para orientações gerais sobre como interpretar os códigos de status HTTP e a estrutura das respostas de erro na API da Localpayment, consulte [Tratamento de erros](https://docs.localpayment.com/pt-br/docs/error-handling.md).

## Demonstração

Experimente a consulta com um alias de exemplo para ver como o resultado mascarado é exibido. A demonstração reflete o escopo atual: apenas Colômbia.

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

POST /api/payment/alias-detail

Somente Colômbia

Alias (aliasValue)

Dados de exemplo para ilustração. Não chama a API real da Localpayment.

***

## Próximos passos

> [card] [Enviar fundos por transferência bancária](https://docs.localpayment.com/pt-br/docs/send-funds-via-bank-transfer.md)
>
> Envie um payout usando o alias que você verificou.

> [card] [Colômbia](https://docs.localpayment.com/pt-br/docs/colombia.md)
>
> Consulte os bancos, os tipos de documento e os métodos de payout compatíveis com a Colômbia.


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