Schemas

Os endpoints de Schema retornam definições de JSON Schema (draft-07) específicas por país para pessoas, contas e payouts. Consulte-os antes de construir um recipient para que seu formulário renderize exatamente os campos — e as regras de validação — que aquele corredor exige.

Como os campos obrigatórios, os formatos de código postal, os tipos de documento e os métodos de payout variam por país, um formulário codificado de forma fixa para um corredor falhará em outro. Em vez disso, construa o formulário a partir do schema:

Construa formulários dinâmicos que se adaptam a cada país de destino
Valide entradas no lado do cliente usando pattern, enum, minLength e required do schema
Exiba os campos corretos para cada método de payout (depósito bancário, PIX, carteira)

Formato do código de país: o parâmetro de query countryCode é ISO 3166-1 alpha-3 (ex.: BRA, MEX, PHL, USA). Dentro do schema retornado, o campo address.countryCode é alpha-2 (ex.: BR, MX, PH). Não os confunda.

Todas as respostas são documentos JSON Schema draft-07: um objeto com type, required e properties, onde objetos aninhados (address, payoutMethod) e arrays (documents) carregam seus próprios required/properties.

Person Schema

Retorna o schema de identidade e endereço do destinatário para um país de destino — os campos necessários para construir a seção de beneficiário do formulário.

Endpoint

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

Cabeçalhos:

Cabeçalho	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
`countryCode`	string	Sim	Código de país ISO 3166-1 alpha-3 (ex.: `"PHL"`, `"BRA"`, `"ESP"`)

Exemplo de Requisição

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

Resposta (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}$" }
      }
    }
  }
}

Alguns corredores adicionam um array documents para captura de documento nacional de identidade (veja Diferenças por País — o Brasil exige um CPF):

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

Account Schema

Retorna o schema de conta e método de payout do destinatário para um país de destino. A resposta agrupa duas coisas:

asset — a moeda de liquidação do payout
payoutMethod — um objeto aninhado descrevendo como os fundos chegam (depósito bancário, PIX, carteira), com os campos específicos do método

Nota: os campos do método de payout estão incorporados no account schema como payoutMethod. Você não precisa buscar o Payout Schema separadamente para renderizar o formulário do destinatário — ele existe para quem quer o sub-schema do método de payout isoladamente.

Endpoint

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

Cabeçalhos:

Cabeçalho	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
`countryCode`	string	Sim	Código de país ISO 3166-1 alpha-3 (ex.: `"BRA"`, `"MEX"`, `"USA"`)

Exemplo de Requisição

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

Resposta (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"] }
      }
    }
  }
}

O enum payoutMethod.type indica quais campos se aplicam:

`type`	Campos relevantes
`BANK_DEPOSIT`	`bankCode`, `routingNumber`, `accountNumber` (varia por corredor)
`PIX`	`keyType`, `key`
`WALLET`	`walletId`, `walletType`, `walletOperator`

Payout Schema

Retorna o sub-schema do método de payout isoladamente — o mesmo formato do objeto payoutMethod incorporado no Account Schema. Use-o quando você só precisar dos campos do método de payout (ex.: revalidar um método de payout sem o contexto completo da conta). Para construir o formulário do destinatário, o account schema já inclui tudo.

Endpoint

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

Cabeçalhos:

Cabeçalho	Valor
`Authorization`	`Bearer {accessToken}`

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
`countryCode`	string	Sim	Código de país ISO 3166-1 alpha-3 (ex.: `"PHL"`, `"BRA"`, `"MEX"`)

Exemplo de Requisição

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

Resposta (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." }
  }
}

Diferenças por País

Os schemas são a fonte da verdade, mas alguns corredores têm particularidades que merecem destaque. Sempre renderize a partir do schema ao vivo em vez de codificar estas informações de forma fixa — elas podem mudar.

País	Diferença
Brasil (`BRA`)	Somente depósito bancário em alguns fluxos — `payoutMethod.type` reduzido a `["BANK_DEPOSIT"]`, `key`/`keyType` do PIX removidos. O destinatário exige um CPF via `documents[].document` (11 dígitos, numérico, com validação de dígito verificador). `bankCode` (3 dígitos), `routingNumber` = agência.
México (`MEX`)	A CLABE (`accountNumber`) já codifica o banco, então `routingNumber` não é usado — está ausente do schema e da lista de obrigatórios. `bankCode` normalmente vem de um seletor de bancos.
Filipinas (`PHL`)	`address.stateCode` é um enum de ~70 códigos de província (`ABR`, `AGN`, … `ZSI`). Endereço completo obrigatório; `zipcode` corresponde a `^[0-9]{4}$`.
UE (`AUT`, `BEL`, `FRA`, `IRL`, `ITA`, `PRT`, `ESP`)	`address` é opcional — apenas `firstName` e `lastName` são obrigatórios. O `pattern` de código postal difere por país (ex.: `^\d{5}$` para ES/FR/IT, `^\d{4}$` para AT/BE, `^\d{4}-\d{3}$` para PT).

Como Consumir um Schema

Interpretando as palavras-chave draft-07 ao renderizar um campo:

Palavra-chave	Uso
`type`	Tipo de dado: `"string"`, `"object"`, `"array"`, `"number"`, `"boolean"`
`required`	Array de nomes de propriedades obrigatórias (no nível daquele objeto)
`properties`	Definições de campos de um objeto
`items`	Schema dos elementos de um array (ex.: `documents`)
`enum`	Valores permitidos — renderize um enum de valor único como somente leitura e um enum de múltiplos valores como um select
`pattern`	Regex que o valor deve satisfazer (códigos postais, CPF, números de conta)
`minLength`	Comprimento mínimo da string
`description`	Dica legível por humanos — bom padrão para placeholder ou rótulo

Fluxo recomendado:

Leia o país de destino da etapa 1 do seu formulário e converta-o para ISO-3.
Faça GET /schema/person e GET /schema/account para esse código ISO-3.
Renderize o formulário do destinatário a partir de personSchema.properties e accountSchema.properties (este último inclui payoutMethod).
Valide os valores contra o pattern/enum/required de cada campo.
Envie o recipient coletado (identidade + address + documents opcional) e o paymentMethod no payload da Push Transaction.

Próximos Passos

Push Transaction — Construa o recipient e o paymentMethod a partir desses schemas
Payment Person — Crie e valide pessoas usando os campos do schema
Bancos — Consulte códigos de banco para popular os campos bankCode
Check Account — Valide os dados da conta antes de transacionar