Skip to main content

Form Schemas

Overview​

Form schemas define the data required to complete a payment through a specific channel. They are standard JSON Schema definitions that you can use to:

  • Validate payment data before submission
  • Generate forms using libraries like JSON Forms or react-jsonschema-form
  • Build automated integrations that programmatically populate payment details

We publish all form schemas to a public GitHub repository for full transparency and offline access.

tip

View our published schemas at github.com/noah-labs/public-schemas

Understanding Channels and Schemas​

A Channel represents a specific payment route, uniquely identified by:

ParameterDescriptionExample
CountryISO 3166-1 alpha-2 country codeBR, DE, US
PaymentMethodTypeThe payment methodBankSepa, BankAch, IdentifierPix
DirectionTransaction directionIn (deposit), Out (payout)
ProviderThe underlying payment processor(internal)

Multiple Channels per Route​

For a given Country + PaymentMethodType + Direction, there may be multiple channels available — one or more per payment provider. These channels are not always identical and may differ in:

AspectDescription
FeaturesOne provider may support QR codes while another supports identifiers
Required DataSome providers require more customer information than others
CostFee structures vary between providers
Processing TimeSettlement times differ

Each channel has its own form schema, tailored to that provider’s specific data requirements. We normalise field names and structures across providers wherever possible, but each schema is deliberately scoped to the minimum information required for that provider.

That means you’ll never be asked to collect extra data just because another provider (or channel) needs it. If a particular provider requires additional information, those fields will appear only in that provider’s form schema, never as superfluous requirements applied across the board.

Retrieving Form Schemas​

When you query available channels, each channel includes its FormSchema directly in the response:

curl -L 'https://api.sandbox.noah.com/v1/channels/sell?Country=BR&FiatCurrency=BRL&CryptoCurrency=USDC_TEST' \
  -H 'Accept: application/json' \
  -H 'X-Api-Key: <X-Api-Key>'

Response:

{
  "Items": [
    {
      "ID": "channel-uuid-1",
      "Country": "BR",
      "FiatCurrency": "BRL",
      "PaymentMethodType": "IdentifierPix",
      "FormSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "PixKey": {
            "type": "string",
            "title": "PIX Key"
          }
        },
        "required": ["PixKey"]
      },
      "Limits": { "MinLimit": "1" },
      "ProcessingSeconds": 300
    },
    {
      "ID": "channel-uuid-2",
      "Country": "BR",
      "FiatCurrency": "BRL",
      "PaymentMethodType": "IdentifierPix",
      "FormSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "PixKey": { "type": "string", "title": "PIX Key" },
          "TaxId": { "type": "string", "title": "Tax ID" },
          "FullName": { "type": "string", "title": "Full Name" }
        },
        "required": ["PixKey", "TaxId", "FullName"]
      },
      "Limits": { "MinLimit": "10" },
      "ProcessingSeconds": 600
    }
  ]
}

In this example, two PIX channels are available for Brazil — one requires only a PIX key, while the other requires additional customer information. Use the schema from whichever channel you select.

Option 2: Via Published Schema Files​

Important

The published schemas are provided for informational purposes and are subject to change. We strongly recommend integrating dynamically using the Channels API rather than hardcoding against the published schema files. This ensures your integration automatically adapts to any schema updates.

For offline access or pre-integration planning, schemas are published to our public-schemas repository:

public-schemas/
├── prod/
│   ├── README.md          # Lookup table
│   ├── a1b2c3d4.json      # Schema files
│   └── ...
└── sandbox/
    ├── README.md
    └── ...

Each environment folder contains:

  1. README.md — A lookup table mapping channels to schema files:

    CountryPayment MethodDirectionProviderSchema
    BRIdentifierPixOutProvider1./a1b2c3d4.json
    BRIdentifierPixOutProvider2./e5f6g7h8.json

  2. Schema JSON files — Each file includes the schema plus metadata:

    {
      "metadata": {
        "channels": [{
          "country": "BR",
          "direction": "Out",
          "finServiceID": "b9s4g",
          "paymentMethodType": "IdentifierPix"
        }],
        "contentHash": "sha256...",
        "generatedAt": "2025-01-29T12:00:00Z"
      },
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": { ... }
    }

Sandbox vs Production​

The schemas themselves are identical between environments when a channel is available in both. However, different channels may be enabled in sandbox versus production.

This means:

  • A channel available in production might not be enabled in sandbox (or vice versa)
  • Always query the appropriate environment to discover available channels
tip

Recommendation: Use the Channels API to discover available channels at runtime rather than hardcoding assumptions about availability.

Selecting a Channel​

When multiple channels exist for the same route, select based on your requirements:

  • Features needed — Does your use case require QR codes, identifiers, or specific payment flows?
  • Data availability — Do you have the customer data required by each schema?
  • Cost — Compare fee structures between channels
  • Processing time — Consider settlement speed requirements

We support channel prioritization configuration if you need consistent routing behavior.

Using Schemas for Automation​

For automated integrations where you want to pre-fill payment data without user interaction:

  1. Query available channels for the customer's country and payment method
  2. Review the schemas to understand data requirements for each channel
  3. Select the channel that matches your available data and requirements
  4. Validate your data against the schema before submission
import Ajv from 'ajv';

// 1. Get available channels
const { Items: channels } = await api.get('/v1/channels/sell', {
  params: { Country: 'BR', FiatCurrency: 'BRL', CryptoCurrency: 'USDC' },
});

// 2. Find a channel where you have all required data
const selectedChannel = channels.find((channel) => {
  const required = channel.FormSchema?.required || [];
  return required.every((field) => customerData[field] !== undefined);
});

// 3. Validate data against the schema
const ajv = new Ajv();
const validate = ajv.compile(selectedChannel.FormSchema);
const isValid = validate(customerData);

if (!isValid) {
  console.error('Validation errors:', validate.errors);
}