Esquemas

Los endpoints de esquemas devuelven definiciones de JSON Schema (draft-07) específicas por país para personas, cuentas y payouts. Consúltalos antes de construir un recipient para que tu formulario muestre exactamente los campos — y las reglas de validación — que requiere ese corredor.

Dado que los campos requeridos, los formatos de código postal, los tipos de documento y los métodos de payout varían por país, un formulario codificado de forma fija para un corredor fallará en otro. En su lugar, genera el formulario a partir del esquema:

• Construye formularios dinámicos que se adaptan a cada país de destino
• Valida las entradas del lado del cliente usando pattern, enum, minLength y required del esquema
• Muestra los campos correctos para cada método de payout (depósito bancario, PIX, billetera)

Formato del código de país: el parámetro de consulta countryCode es ISO 3166-1 alpha-3 (p. ej. BRA, MEX, PHL, USA). Dentro del esquema devuelto, el campo address.countryCode es alpha-2 (p. ej. BR, MX, PH). No los confundas.

Todas las respuestas son documentos JSON Schema draft-07: un objeto con type, required y properties, donde los objetos anidados (address, payoutMethod) y los arrays (documents) llevan sus propios required/properties.

Person Schema

Devuelve el esquema de identidad y dirección del destinatario para un país de destino — los campos que necesitas para construir la sección del beneficiario del formulario.

Endpoint

GET https://{FQDN}/schema/person

Encabezados:

Parámetros de Consulta

Ejemplo de Solicitud

curl -X GET 'https://{FQDN}/schema/person?countryCode=PHL' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Respuesta (200)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Inyo Global Recipient Data - Philippines",
  "description": "Schema for a PHL person.",
  "version": "1.0.0",
  "type": "object",
  "required": ["firstName", "lastName", "address"],
  "properties": {
    "firstName": { "type": "string", "description": "The first name of the person.", "minLength": 1 },
    "lastName": { "type": "string", "description": "The last name of the person.", "minLength": 1 },
    "address": {
      "type": "object",
      "description": "The physical address of the person.",
      "required": ["countryCode", "stateCode", "city", "line1", "zipcode"],
      "properties": {
        "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "enum": ["PH"] },
        "stateCode": { "type": "string", "description": "State or province code.", "enum": ["ABR", "AGN", "ALB", "CEB", "NCR", "..."] },
        "city": { "type": "string", "minLength": 1 },
        "line1": { "type": "string", "minLength": 1 },
        "line2": { "type": "string", "minLength": 1 },
        "zipcode": { "type": "string", "description": "Postal code.", "pattern": "^[0-9]{4}$" }
      }
    }
  }
}

Algunos corredores agregan un array documents para la captura del documento nacional de identidad (consulta Diferencias por País — Brasil requiere un CPF):

"documents": {
  "type": "array",
  "minItems": 1,
  "items": {
    "type": "object",
    "required": ["document"],
    "properties": {
      "document": { "type": "string", "description": "CPF (11 digits)", "pattern": "^\\d{11}$" }
    }
  }
}

Account Schema

Devuelve el esquema de cuenta y método de payout del destinatario para un país de destino. La respuesta agrupa dos cosas:

• asset — la divisa de liquidación del payout
• payoutMethod — un objeto anidado que describe cómo llegan los fondos (depósito bancario, PIX, billetera), con los campos específicos del método

Nota: Los campos del método de payout están incrustados en el esquema de cuenta como payoutMethod. No necesitas obtener el Payout Schema por separado para renderizar el formulario del destinatario — existe para quienes quieren el sub-esquema del método de payout por sí solo.

Endpoint

GET https://{FQDN}/schema/account

Encabezados:

Parámetros de Consulta

Ejemplo de Solicitud

curl -X GET 'https://{FQDN}/schema/account?countryCode=BRA' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Respuesta (200)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Inyo Global Account Data - Brazil",
  "version": "1.0.0",
  "type": "object",
  "required": ["asset", "payoutMethod"],
  "properties": {
    "asset": { "type": "string", "description": "Settlement currency (ISO 4217).", "enum": ["BRL"] },
    "payoutMethod": {
      "type": "object",
      "required": ["type", "countryCode", "bankCode", "routingNumber", "accountNumber"],
      "properties": {
        "type": { "type": "string", "description": "Payout method.", "enum": ["BANK_DEPOSIT", "PIX"] },
        "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "enum": ["BR"] },
        "bankCode": { "type": "string", "description": "Bank code (3 digits).", "pattern": "^\\d{3}$" },
        "routingNumber": { "type": "string", "description": "Branch / agência.", "pattern": "^\\d{1,5}$" },
        "accountNumber": { "type": "string", "pattern": "^\\d{1,13}$" },
        "key": { "type": "string", "description": "PIX key value." },
        "keyType": { "type": "string", "description": "PIX key type.", "enum": ["EMAIL", "PHONE", "DOCUMENT", "EVP"] }
      }
    }
  }
}

El enum de payoutMethod.type te indica qué campos aplican:

Payout Schema

Devuelve el sub-esquema del método de payout por sí solo — la misma forma que el objeto payoutMethod incrustado en el Account Schema. Úsalo cuando solo necesites los campos del método de payout (p. ej., revalidar un método de payout sin el contexto completo de la cuenta). Para construir el formulario del destinatario, el esquema de cuenta ya incluye todo.

Endpoint

GET https://{FQDN}/schema/payout

Encabezados:

Parámetros de Consulta

Ejemplo de Solicitud

curl -X GET 'https://{FQDN}/schema/payout?countryCode=PHL' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Respuesta (200)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Inyo Global Payout Method - Philippines",
  "version": "1.0.0",
  "type": "object",
  "required": ["type", "countryCode", "accountNumber"],
  "properties": {
    "type": { "type": "string", "description": "Payout method.", "enum": ["BANK_DEPOSIT", "WALLET"] },
    "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "enum": ["PH"] },
    "bankCode": { "type": "string", "description": "Destination bank code." },
    "accountNumber": { "type": "string", "description": "Bank account number." },
    "walletId": { "type": "string", "description": "Wallet identifier." },
    "walletType": { "type": "string", "description": "Wallet identifier type (e.g. PHONENUMBER)." },
    "walletOperator": { "type": "string", "description": "Wallet operator / provider." }
  }
}

Diferencias por País

Los esquemas son la fuente de verdad, pero algunos corredores tienen particularidades que vale la pena destacar. Renderiza siempre a partir del esquema en vivo en lugar de codificar estos valores de forma fija — pueden cambiar.

Cómo Consumir un Esquema

Lectura de las palabras clave de draft-07 al renderizar un campo:

Flujo recomendado:

1. Lee el país de destino del paso 1 de tu formulario y conviértelo a ISO-3.
2. Llama a GET /schema/person y GET /schema/account para ese código ISO-3.
3. Renderiza el formulario del destinatario a partir de personSchema.properties y accountSchema.properties (este último incluye payoutMethod).
4. Valida los valores contra el pattern/enum/required de cada campo.
5. Envía el recipient recopilado (identidad + address + documents opcional) y el paymentMethod en el payload de Push Transaction.

Qué Sigue

• Push Transaction — Construye el recipient y el paymentMethod a partir de estos esquemas
• Payment Person — Crea y valida personas usando los campos del esquema
• Bancos — Busca códigos de banco para poblar los campos bankCode
• Check Account — Valida los datos de la cuenta antes de transaccionar