Disponibilidade
O gerenciamento de aliases de contas virtuais está disponível nos seguintes países:Antes de começar
Certifique-se de ter:- Credenciais de API válidas (token de acesso).
- O
externalIdde uma conta virtual ativa com statusCOMPLETED.
Como os aliases funcionam na Argentina
A Argentina oferece suporte a aliases de CVU para contas virtuais. Principais características:- Formato: Apenas letras (a–z, A–Z), números (0–9) e pontos (
.). Sem espaços, hifens, sublinhados ou caracteres especiais. - Comprimento: Entre 5 e 20 caracteres.
- Unicidade: O alias deve ser único em nível de país. Isso não é uma restrição da plataforma, mas um requisito do sistema bancário argentino. Se outra CVU já usar o mesmo alias, a solicitação será rejeitada.
- Atualização de um alias: Para atualizar um alias, chame o mesmo endpoint com o novo valor depois que o período de espera necessário tiver decorrido.
- Limite de alterações: Depois de definido ou atualizado, um alias não pode ser alterado novamente por 24 horas. O alias pode ser atualizado no máximo 10 vezes no total.
- Ativação assíncrona: O alias é ativado em segundo plano. Uma resposta
INPROGRESSnão significa que o alias já esteja ativo. Verifique a ativação usando Obtenha o status da sua Virtual Account.
alias.example · alias.example2026 · alias.example.test
Exemplos de alias inválidos: alias example (espaço) · alias-example (hífen) · alias_example (sublinhado) · alias@example (arroba)
Definir alias da Virtual Account
Defina um alias personalizado para uma conta virtual ativa existente. Esta operação atribui um novo alias e também atualiza um alias existente. O mesmo endpoint trata ambos os casos.Parâmetros-chave da solicitação
Exemplo de solicitação
Resposta bem-sucedida
O status
INPROGRESS significa que a solicitação foi recebida e está sendo processada de forma assíncrona. O alias ainda não está ativo. Use o endpoint Obtenha o status da sua Virtual Account para confirmar a ativação antes de notificar seus usuários finais.Verificar a ativação do alias
Depois de receber uma respostaINPROGRESS, consulte a conta virtual para confirmar que o alias está ativo. Envie uma solicitação GET ao endpoint de status individual:
beneficiary.bank.account.alias:
INPROGRESS, o erro aparecerá no array errors desta mesma resposta. Consulte o endpoint de status repetidamente até que errors esteja vazio e o alias esteja visível em beneficiary.bank.account.alias.
Campos de resposta principais
Respostas de erro
Os códigos de erro a seguir se aplicam à resposta síncrona. Se a resposta inicial forINPROGRESS, a operação foi aceita, mas ainda podem ocorrer erros durante o processamento assíncrono. Para detectá-los, consulte Obtenha o status da sua Virtual Account e verifique o array errors.
Cenários de erro comuns
Demonstração

Próximos passos
Criar contas virtuais
Gere novas contas virtuais que podem ser aprimoradas com pseudônimos.
Gerenciar o status da conta virtual
Verifique o status das contas virtuais e seus respectivos aliases.
Referência da API
Referência completa de parâmetros do endpoint Definir alias.

