Schemas

O GET /schema/{countryCode} retorna um JSON Schema (draft-07) específico por país descrevendo tudo o que um payout para aquele país deve conter. Consulte-o 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)

A resposta é um documento JSON Schema draft-07: um objeto com type, required e properties, onde objetos aninhados (address, paymentMethod) e arrays (documents) carregam seus próprios required/properties.

Códigos de país são ISO 3166-1 alpha-3 em todo lugar — no path (BRA, MEX, PHL) e no campo address.countryCode, que o schema valida com "pattern": "^[A-Z]{3}$" tanto em recipient.address quanto em sender.address.

Country Schema

Retorna o contrato completo de push para um país de destino: o recipient (identidade, endereço, documentos, método de payout), a moeda que o recipientAmount deve carregar, o additionalData que aquele corredor exige e — nos corredores que o restringem — um bloco sender. Este é o schema contra o qual o próprio gateway valida o POST /v2/payment, então é a resposta autoritativa para "o que este país exige?"

Nem todo schema de país carrega todos os blocos de topo. O sender em particular está presente em alguns corredores e ausente em outros; onde ausente, valem apenas as regras de remetente do schema genérico de push. Leia os blocos que estão lá em vez de assumir um formato fixo — o conjunto está sendo estendido.

Endpoint

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

Headers:

Parâmetros de Path

Exemplo de Requisição

curl -X GET 'https://{FQDN}/schema/DEU' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Resposta (200)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Inyo Global PUSH Country Schema - Germany",
  "version": "1.0.1",
  "description": "Schema for processing a transaction to a DEU recipient",
  "type": "object",
  "properties": {
    "recipient": {
      "type": "object",
      "required": ["firstName", "lastName"],
      "properties": {
        "firstName": { "type": "string", "minLength": 1 },
        "lastName": { "type": "string", "minLength": 1 },
        "address": { "type": "object", "properties": { "…": {} } },
        "paymentMethod": {
          "type": "object",
          "required": ["countryCode"],
          "properties": {
            "type": { "type": "string", "enum": ["BANK_DEPOSIT"] },
            "countryCode": { "type": "string", "enum": ["DEU"] },
            "accountNumber": {
              "type": "string",
              "description": "The International Bank Account Number (IBAN).",
              "pattern": "^DE\\d{20}$"
            }
          }
        }
      }
    },
    "recipientAmount": {
      "type": "object",
      "properties": {
        "total": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "enum": ["EUR"] }
      }
    },
    "additionalData": {
      "type": "object",
      "properties": {
        "statementNarrative": { "type": "string" }
      }
    }
  }
}

Lendo os condicionais

Corredores mais ricos expressam suas regras como condicionais de JSON Schema, e não como uma lista required plana. Dois formatos aparecem:

• allOf com if/then sobre paymentMethod.type — o corredor oferece mais de um método de payout e cada um exige campos diferentes. O Brasil exige accountNumber, accountType, bankCode e routingNumber quando o type é BANK_DEPOSIT, mas key e keyType quando é PIX.
• if/then/else sobre accountNumberType — o corredor oferece um trilho de alias ao lado das contas convencionais. A Índia exige apenas accountNumber (um VPA UPI) quando o accountNumberType é UPI, e accountNumber + bankCode + accountType caso contrário.

Um validador que leia apenas o required de topo vai aceitar payloads que o gateway rejeita com VE_001. Avalie o documento inteiro.

recipientAmount.currency é um enum, não uma sugestão. Cada país trava sua moeda de destino — BRA aceita apenas BRL. A Guiné (GIN) é o único corredor que aceita duas (GNF, XOF).

Erros

Diferenças por País

Os schemas são a fonte de verdade, mas alguns corredores têm particularidades que vale destacar. Sempre renderize a partir do schema ao vivo em vez de fixar isto — pode mudar.

Como Consumir um Schema

Lendo as palavras-chave do draft-07 ao renderizar um campo:

Note as duas palavras-chave condicionais acima: um validador que leia apenas o required de topo vai aceitar payloads que o gateway rejeita com VE_001.

Fluxo recomendado:

1. Leia o país de destino do seu formulário e converta para ISO-3.
2. GET /schema/{countryCode} para esse código.
3. Renderize o formulário de destinatário a partir de recipient.properties — incluindo paymentMethod, cujos campos dependem do type e, em alguns corredores, do accountNumberType.
4. Aplique o bloco sender se o schema trouxer um, e ofereça apenas os valores de recipientAmount.currency que o enum permite.
5. Valide cada valor contra seu pattern/enum/required, avaliando allOf/if/then/else.
6. Envie o sender, o recipient e o additionalData coletados no payload de Push Transaction.

Próximos Passos

• Push Transaction — Construa o recipient e o paymentMethod a partir deste schema
• Bancos — Consulte códigos de banco para popular os campos bankCode
• Check Account — Valide os dados da conta antes de transacionar