Diretório de Alias

O acesso à API do Diretório de Alias não está amplamente disponível. Este endpoint está sujeito a limites de cota e restrito a casos de uso específicos. Entre em contato com seu gerente de conta Inyo para saber mais.

A API do Diretório de Alias permite resolver o alias de um destinatário (como um documento nacional, número de telefone, e-mail ou identificação fiscal) na conta bancária vinculada e nos dados do titular antes de iniciar uma transação push. Isso é útil para validar destinos de payout e exibir os dados de confirmação ao remetente.

O que é um diretório de alias?

Os trilhos de pagamento instantâneo — como o PIX no Brasil, o UPI na Índia ou o PayNow em Singapura — mantêm diretórios centralizados que mapeiam aliases (chaves) para contas bancárias. Quando um usuário se registra em um desses sistemas, ele vincula um alias (por exemplo, seu número de CPF, telefone ou e-mail) a uma conta bancária específica. A API do Diretório de Alias consulta esses registros específicos de cada trilho e retorna as informações da conta e do titular correspondentes.

Casos de uso comuns:

Validação prévia — Verifique se um alias resolve para uma conta válida antes de submeter uma transação push
Confirmação do destinatário — Exiba o nome do titular e o número de conta mascarado para que o remetente possa confirmar o destino do payout
Prevenção de erros — Detecte erros de digitação ou chaves inválidas cedo, evitando transações com falha e ciclos de reembolso

Endpoint

POST https://{FQDN}/v1/alias/directory

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Requisição

Campo	Tipo	Obrigatório	Descrição
`countryCode`	string	Sim	Código de país ISO Alpha-3 (por exemplo, `"BRA"`, `"SGP"`, `"IND"`)
`key`	string	Sim	O valor do alias a consultar (por exemplo, número de CPF, telefone, e-mail, VPA)
`keyType`	string	Sim	O tipo do alias — os valores válidos dependem do trilho de pagamento instantâneo (veja a tabela abaixo)

Trilhos e Tipos de Chave Suportados

O sistema de pagamento instantâneo de cada país suporta diferentes tipos de alias. Use a tabela abaixo para determinar quais valores de keyType são válidos para cada trilho.

País	`countryCode`	Sistema	Valores de `keyType` suportados
Brasil	`BRA`	PIX	`CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
Índia	`IND`	UPI	`VPA`, `MOBILE`, `AADHAAR`
Singapura	`SGP`	PayNow	`NRIC_FIN`, `UEN`, `MOBILE`, `VPA`
Tailândia	`THA`	PromptPay	`CITIZEN_ID`, `PHONE`, `TAX_ID`
Filipinas	`PHL`	InstaPay	`MOBILE`, `EMAIL`, `ACCOUNT_NUMBER`

Resposta — Alias Encontrado (HTTP 200)

Quando o alias é encontrado no diretório, a API retorna a conta vinculada e os dados do titular.

Campo	Tipo	Descrição
`found`	boolean	`true` — o alias foi resolvido
`countryCode`	string	Código de país ISO Alpha-3
`system`	string	Nome do trilho de pagamento instantâneo (por exemplo, `"PIX"`, `"PayNow"`, `"UPI"`)
`keyType`	string	O tipo de chave consultado
`key`	string	O valor do alias consultado
`account`	object	Dados da conta bancária vinculada
`account.bankCode`	string	Código da instituição bancária
`account.bankName`	string	Nome do banco
`account.accountType`	string	Tipo de conta (por exemplo, `"CHECKING"`, `"SAVINGS"`)
`account.accountNumber`	string	Número da conta mascarado
`account.branchCode`	string	Código da agência (quando aplicável, por exemplo, Brasil)
`holder`	object	Dados do titular da conta
`holder.name`	string	Nome completo do titular
`holder.documentType`	string	Tipo de documento usado no registro (por exemplo, `"CPF"`, `"NRIC"`)
`holder.document`	string	Número do documento mascarado
`holder.type`	string	`"INDIVIDUAL"` ou `"BUSINESS"`

Resposta — Alias Não Encontrado (HTTP 400)

Quando o alias não pode ser resolvido no diretório, a API retorna o status 400.

Campo	Tipo	Descrição
`found`	boolean	`false` — o alias não foi resolvido
`countryCode`	string	Código de país ISO Alpha-3
`system`	string	Nome do trilho de pagamento instantâneo
`keyType`	string	O tipo de chave consultado
`key`	string	O valor do alias consultado
`message`	string	Descrição do erro legível por humanos

Exemplos

PIX — Brasil (consulta por CPF)

Requisição:

curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "BRA",
    "key": "11122233344",
    "keyType": "CPF"
  }'

Resposta (200):

{
  "found": true,
  "countryCode": "BRA",
  "system": "PIX",
  "keyType": "CPF",
  "key": "11122233344",
  "account": {
    "bankCode": "341",
    "bankName": "Itaú Unibanco",
    "accountType": "CHECKING",
    "accountNumber": "****-5",
    "branchCode": "1234"
  },
  "holder": {
    "name": "João da Silva",
    "documentType": "CPF",
    "document": "***.222.***-**",
    "type": "INDIVIDUAL"
  }
}

PayNow — Singapura (consulta por NRIC/FIN)

Requisição:

curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "SGP",
    "key": "S1234567A",
    "keyType": "NRIC_FIN"
  }'

Resposta (200):

{
  "found": true,
  "countryCode": "SGP",
  "system": "PayNow",
  "keyType": "NRIC_FIN",
  "key": "S1234567A",
  "account": {
    "bankCode": "7339",
    "bankName": "OCBC Bank",
    "accountType": "SAVINGS",
    "accountNumber": "XXXX-XXXX-5678"
  },
  "holder": {
    "name": "Lee Siew Ling",
    "documentType": "NRIC",
    "document": "S****567A",
    "type": "INDIVIDUAL"
  }
}

Alias Não Encontrado — InstaPay (Filipinas)

Requisição:

curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "PHL",
    "key": "jua2n@gcash",
    "keyType": "EMAIL"
  }'

Resposta (400):

{
  "found": false,
  "countryCode": "PHL",
  "system": "InstaPay",
  "keyType": "EMAIL",
  "key": "jua2n@gcash",
  "message": "Alias not found in InstaPay directory"
}

Alias Não Encontrado — PromptPay (Tailândia)

Requisição:

curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "THA",
    "key": "+668123456S78",
    "keyType": "PHONE"
  }'

Resposta (400):

{
  "found": false,
  "countryCode": "THA",
  "system": "PromptPay",
  "keyType": "PHONE",
  "key": "+668123456S78",
  "message": "Alias not found in PromptPay directory"
}

Alias Não Encontrado — PayNow (Singapura)

Requisição:

curl -X POST https://{FQDN}/v1/alias/directory \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "SGP",
    "key": "S1234S567A",
    "keyType": "NRIC_FIN"
  }'

Resposta (400):

{
  "found": false,
  "countryCode": "SGP",
  "system": "PayNow",
  "keyType": "NRIC_FIN",
  "key": "S1234S567A",
  "message": "Alias not found in PayNow directory"
}