Alias Directory

El acceso a la API de Alias Directory no está ampliamente disponible. Este endpoint está sujeto a límites de cuota y restringido a casos de uso específicos. Contacte a su gerente de cuenta de Inyo para obtener más información.

La API de Alias Directory le permite resolver el alias de un destinatario (como un documento nacional de identidad, número de teléfono, correo electrónico o identificación fiscal) en su cuenta bancaria vinculada y los datos del titular antes de iniciar una transacción push. Esto es útil para validar destinos de payout y mostrar los datos de confirmación al remitente.

¿Qué es un directorio de alias?

Los rieles de pago instantáneo — como PIX en Brasil, UPI en India o PayNow en Singapur — mantienen directorios centralizados que asocian alias (claves) con cuentas bancarias. Cuando un usuario se registra en uno de estos sistemas, vincula un alias (p. ej., su número de CPF, número de teléfono o correo electrónico) a una cuenta bancaria específica. La API de Alias Directory consulta estos registros específicos de cada riel y devuelve la información de la cuenta y del titular encontrados.

Casos de uso comunes:

• Validación previa — Verificar que un alias se resuelve en una cuenta válida antes de enviar una transacción push
• Confirmación del destinatario — Mostrar el nombre del titular y el número de cuenta enmascarado para que el remitente pueda confirmar el destino del payout
• Prevención de errores — Detectar errores de tipeo o claves inválidas de forma temprana, evitando transacciones fallidas y ciclos de reembolso

Endpoint

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

Encabezados:

Solicitud

Rieles y tipos de clave soportados

El sistema de pagos instantáneos de cada país soporta diferentes tipos de alias. Use la tabla a continuación para determinar qué valores de keyType son válidos para cada riel.

Respuesta — Alias encontrado (HTTP 200)

Cuando el alias se encuentra en el directorio, la API devuelve los datos de la cuenta vinculada y del titular.

Respuesta — Alias no encontrado (HTTP 400)

Cuando el alias no puede resolverse en el directorio, la API devuelve un estado 400.

Ejemplos

PIX — Brasil (consulta por CPF)

Solicitud:

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

Respuesta (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 — Singapur (consulta por NRIC/FIN)

Solicitud:

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

Respuesta (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 no encontrado — InstaPay (Filipinas)

Solicitud:

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

Respuesta (400):

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

Alias no encontrado — PromptPay (Tailandia)

Solicitud:

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

Respuesta (400):

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

Alias no encontrado — PayNow (Singapur)

Solicitud:

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

Respuesta (400):

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