Schemas

El GET /schema/{countryCode} devuelve un JSON Schema (draft-07) específico por país que describe todo lo que un payout a ese país debe contener. Consúltalo antes de construir un recipient para que tu formulario renderice exactamente los campos — y las reglas de validación — que ese corredor exige.

Como 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 fijado para un corredor fallará en otro. En su lugar, construye el formulario a partir del esquema:

• Construye formularios dinámicos que se adaptan a cada país de destino
• Valida 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)

La respuesta es un documento JSON Schema draft-07: un objeto con type, required y properties, donde los objetos anidados (address, paymentMethod) y los arrays (documents) llevan sus propios required/properties.

Los códigos de país son ISO 3166-1 alpha-3 en todas partes — en el path (BRA, MEX, PHL) y en el campo address.countryCode, que el esquema valida con "pattern": "^[A-Z]{3}$" tanto en recipient.address como en sender.address.

Country Schema

Devuelve el contrato completo de push para un país de destino: el recipient (identidad, dirección, documentos, método de payout), la moneda que el recipientAmount debe llevar, el additionalData que ese corredor exige y — en los corredores que lo restringen — un bloque sender. Este es el esquema contra el que el propio gateway valida el POST /v2/payment, así que es la respuesta autoritativa a "¿qué exige este país?"

No todos los esquemas de país llevan todos los bloques de nivel superior. El sender en particular está presente en algunos corredores y ausente en otros; donde está ausente, solo aplican las reglas de remitente del esquema genérico de push. Lee los bloques que estén ahí en vez de asumir una forma fija — el conjunto se está extendiendo.

Endpoint

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

Headers:

Parámetros de Path

Ejemplo de Solicitud

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

Respuesta (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" }
      }
    }
  }
}

Leyendo los condicionales

Los corredores más ricos expresan sus reglas como condicionales de JSON Schema, no como una lista required plana. Aparecen dos formas:

• allOf con if/then sobre paymentMethod.type — el corredor ofrece más de un método de payout y cada uno exige campos distintos. Brasil exige accountNumber, accountType, bankCode y routingNumber cuando el type es BANK_DEPOSIT, pero key y keyType cuando es PIX.
• if/then/else sobre accountNumberType — el corredor ofrece un riel de alias junto a las cuentas convencionales. India exige solo accountNumber (un VPA UPI) cuando el accountNumberType es UPI, y accountNumber + bankCode + accountType en caso contrario.

Un validador que lea solo el required de nivel superior aceptará payloads que el gateway rechaza con VE_001. Evalúa el documento completo.

recipientAmount.currency es un enum, no una sugerencia. Cada país fija su moneda de destino — BRA solo acepta BRL. Guinea (GIN) es el único corredor que acepta dos (GNF, XOF).

Errores

Diferencias por País

Los esquemas son la fuente de verdad, pero algunos corredores tienen particularidades que vale la pena destacar. Renderiza siempre desde el esquema en vivo en vez de fijar esto — puede cambiar.

Cómo Consumir un Esquema

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

Nota las dos palabras clave condicionales de arriba: un validador que lea solo el required de nivel superior aceptará payloads que el gateway rechaza con VE_001.

Flujo recomendado:

1. Lee el país de destino de tu formulario y conviértelo a ISO-3.
2. GET /schema/{countryCode} para ese código.
3. Renderiza el formulario de destinatario a partir de recipient.properties — incluido paymentMethod, cuyos campos dependen del type y, en algunos corredores, del accountNumberType.
4. Aplica el bloque sender si el esquema trae uno, y ofrece solo los valores de recipientAmount.currency que el enum permite.
5. Valida cada valor contra su pattern/enum/required, evaluando allOf/if/then/else.
6. Envía el sender, el recipient y el additionalData recolectados en el payload de Push Transaction.

Qué Sigue

• Push Transaction — Construye el recipient y el paymentMethod a partir de este esquema
• Bancos — Busca códigos de banco para poblar los campos bankCode
• Check Account — Valida los datos de la cuenta antes de transaccionar