Developers

Dati di riferimento e paginazione

I cataloghi di circuiti, asset e paesi sono la stessa fonte che alimenta il sito. Contengono limiti, ritardi, commissioni e schemi di campi — abbastanza per generare il modulo di pagamento invece di codificarlo paese per paese.

Frequenza di aggiornamento

Questi dati cambiano raramente, ma cambiano: un limite del circuito, un orario di cut-off, l'apertura di un paese. Aggiornateli almeno quotidianamente e non congelateli nel vostro codice. Ogni voce riporta una data dell'ultima verifica manuale: oltre sei mesi, trattatela come dovuta per un controllo.

Paginazione

Paginazione tramite cursore, non offset numerici. Un offset salta o duplica elementi non appena l'elenco si sposta tra due pagine; un cursore punta a una posizione stabile.

Richiestahttp

GET /api/v1/rails?limit=50&cursor=cJ0xNzg4MzU2OTgx

Rispostajson

{
  "data": [ /* … */ ],
  "next_cursor": "cJ0xNzg4MzU3MTEy"
}

limit è predefinito a 50, massimo 100. Un valore maggiore viene limitato al massimo anziché essere rifiutato.
next_cursor è null nell'ultima pagina. È l'unico segnale di fine: non deducete la fine da una pagina corta.
Un cursore è opaco e senza durata di vita garantita. Non conservatelo come identificatore durevole e non costruitevene uno da soli.
L'ordinamento è stabile all'interno di una singola esecuzione di paginazione. Un elemento aggiunto mentre si scorre le pagine appare nella successiva esecuzione completa, non nel mezzo di quella corrente.

GET/api/v1/railsPublished contract, not open

Elenca i metodi di pagamento

Catalogo dei canali di pagamento con valuta, paesi serviti, ritardi p50 e p95, regole sui giorni lavorativi, cut-off, limiti per operazione in unità secondarie, commissioni e schema dei campi del beneficiario. Questo schema è ciò che ti permette di generare il modulo di pagamento invece di codificarlo paese per paese.

Autenticazione: Authorization: Bearer … Vedi autenticazione

Parametri

Parametri
Campo	Tipo	Descrizione
`country`	string	Filtro ISO 3166-1 alpha-2.
`currency`	string	Filtro ISO 4217.
`phase`	string	live, beta, planned o never.
`limit`	integer	Dimensione della pagina, da 1 a 100, default 50.
`cursor`	string	Cursore opaco restituito dalla chiamata precedente.

Richiestabash

curl -sS 'https://fiatside.com/api/v1/rails?country=BR' \
  -H 'Authorization: Bearer sk_live_...'

Risposta — contratto pubblicatojson

{
  "data": [
    {
      "id": "br_pix",
      "slug": "pix",
      "name": "PIX",
      "kind": "instant_bank",
      "currency": "BRL",
      "countries": ["BR"],
      "phase": "live",
      "settlement": { "p50Minutes": 1, "p95Minutes": 10, "businessDaysOnly": false },
      "limits": { "minMinor": 1000, "maxMinor": 5000000, "decimals": 2 },
      "fees": { "fixedMinor": 0, "bps": 0 },
      "fields": [
        { "name": "pixKeyType", "type": "select", "required": true },
        { "name": "pixKey", "type": "text", "required": true, "maxLength": 77 },
        { "name": "taxId", "type": "text", "required": true, "pattern": "^[0-9]{11}$" }
      ],
      "verifiedAt": "2026-09-02"
    }
  ],
  "next_cursor": null
}

Un canale chiuso viene restituito con la sua fase e il motivo, non rimosso dall'elenco. Un'integrazione che non può vedere perché un canale è scomparso contatta il proprio supporto.

Possibili errori: unauthorized, invalid_request. Catalogo completo

GET/api/v1/assetsPublished contract, not open

Elenca gli asset accettati

Asset accettati per il deposito, con decimali dell'unità di base, reti, deposito minimo, durata del blocco del tasso e, dove rilevante, il motivo per cui un asset non è offerto.

Autenticazione: Authorization: Bearer … Vedi autenticazione

Parametri

Parametri
Campo	Tipo	Descrizione
`network`	string	Restituisce solo gli asset disponibili su quella rete.

Richiestabash

curl -sS 'https://fiatside.com/api/v1/assets?network=tron' \
  -H 'Authorization: Bearer sk_live_...'

Risposta — contratto pubblicatojson

{
  "data": [
    {
      "id": "usdt",
      "ticker": "USDT",
      "name": "Tether",
      "decimals": 6,
      "networks": ["tron", "ethereum", "bsc", "solana", "polygon", "arbitrum"],
      "stablecoin": true,
      "quoteLockSeconds": 1800,
      "minDepositBase": "20000000",
      "phase": "live"
    }
  ],
  "next_cursor": null
}

minDepositBase è espresso in unità BASE (20000000 = 20 USDT con 6 decimali). Sotto quella soglia il costo di rete consuma la maggior parte dell'operazione.

Possibili errori: unauthorized. Catalogo completo

GET/api/v1/countriesPublished contract, not open

Elenca i paesi

Paesi serviti, paesi in preparazione e paesi rifiutati. Un paese rifiutato viene restituito con il suo motivo: sanzioni internazionali, misure restrittive o un rischio inaccettabile di riciclaggio di denaro.

Autenticazione: Authorization: Bearer … Vedi autenticazione

Parametri

Parametri
Campo	Tipo	Descrizione
`status`	string	open, coming o restricted.

Richiestabash

curl -sS 'https://fiatside.com/api/v1/countries?status=open' \
  -H 'Authorization: Bearer sk_live_...'

Risposta — contratto pubblicatojson

{
  "data": [
    { "code": "BR", "name": "Brasil", "currency": "BRL", "status": "open", "rails": ["br_pix", "paypal", "wise", "swift"] },
    { "code": "IR", "name": "Iran",   "currency": null,  "status": "restricted", "reason": "international_sanctions" }
  ],
  "next_cursor": null
}

Possibili errori: unauthorized. Catalogo completo

Lo schema dei campi del beneficiario

Ogni circuito descrive i campi che richiede, con il relativo pattern di validazione, normalizzazione e testo di aiuto. Questo è ciò che consente di generare un modulo corretto per un paese mai integrato.

Un campo dello schemajson

{
  "name": "iban",
  "label": { "fr": "IBAN", "en": "IBAN" },
  "type": "iban",
  "required": true,
  "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$",
  "normalize": "upper",
  "help": {
    "fr": "Sans espaces. Nous verifions la cle de controle avant de valider la commande.",
    "en": "No spaces. We validate the checksum before confirming your order."
  }
}

La validazione del pattern avviene sia dalla vostra parte che dalla nostra: la vostra evita all'utente un viaggio di andata e ritorno, la nostra è autorevole. Il testo di aiuto è fornito in entrambe le lingue e merita di essere visualizzato: previene la maggior parte dei pagamenti rifiutati, che quasi sempre derivano da un formato errato piuttosto che da un'interruzione del servizio.