SEPA · Adesione bancaria · Risposte API

Verificare l’adesione SEPA di una banca con l’API IBAN-Test

Utilizza una risposta di convalida IBAN per verificare la partecipazione di una banca all'addebito diretto principale SEPA, all'addebito diretto aziendale, al bonifico bancario e al bonifico bancario in tempo reale. Considerare ciascuna procedura separatamente e distinguere tra partecipazione confermata e sconosciuta.

Questa guida spiega i campi di risposta e include un esempio Python per valutare una risposta in tempo reale o un file JSON salvato. Ciò che viene controllato è la partecipazione della banca, non la capacità di un conto specifico di effettuare un pagamento.

Stato dei test: La valutazione ha superato sette test locali su procedure indipendenti, dati mancanti, IBAN non validi, errori tecnici e campi errati. È stato eseguito anche il comando offline. I dati del test non provengono da una vera interrogazione bancaria; per questo esempio non è stato eseguito un controllo API live autenticato.

Cosa significano i quattro campi

L'API IBAN-Test confronta la partecipazione con i registri dei partecipanti dell'European Payments Council. Le procedure descrivono diversi servizi di pagamento; La conferma di uno non conferma la partecipazione agli altri. Gli elenchi sottostanti possono essere trovati nello I partecipanti all'EPC si registrano.

1. Controlla l'IBAN

Utilizza il normale endpoint di verifica IBAN. Per questo processo non è necessaria alcuna chiamata SEPA aggiuntiva:

POST https://www.iban-test.eu/api/v2/iban/validate
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{"iban":"DE89 3704 0044 0532 0130 00"}

L'IBAN riportato sopra è un esempio, non un'istruzione di pagamento. Innanzitutto controlla lo stato HTTP e il risultato della convalida. Una risposta utilizzabile per un IBAN valido include code: 2100 e error: false. I campi SEPA saranno quindi disponibili in details.sepa se l'API li fornisce. Gli endpoint separati per la verifica BIC e la verifica del conto tedesco non forniscono questi campi SEPA.

2. Distinguere tra “confermato” e “sconosciuto”.

Ciascuna procedura include status e reason:

• confirmed: L’API ha trovato una corrispondenza attuale e univoca nel registro di questo schema.
• unknown: L’API non ha potuto confermare l’adesione. Questo non significa che la banca non supporti lo schema.

Il seguente estratto è espressamente inteso a scopo illustrativo. Mostra perché quattro colonne separate sono più utili di un singolo indicatore “supportato SEPA”:

{
  "sddCore": {"status": "confirmed", "reason": "matched"},
  "sddB2b":  {"status": "unknown",   "reason": "no_match"},
  "sct":     {"status": "confirmed", "reason": "matched"},
  "sctInst": {"status": "unknown",   "reason": "stale_data"}
}

Core e SCT sono confermati in questi dati di test. Il B2B non è confermato e il risultato per i trasferimenti in tempo reale si basa su dati obsoleti. Nessuno di questi valori sconosciuti modifica il risultato del controllo IBAN originale.

3. Eseguire l'esempio offline

Decomprimere il download ed eseguire:

python3 sepa_check.py --response example-response.json

Non viene inviata alcuna richiesta di rete e non è richiesto alcun token. Il programma genera un riepilogo JSON contenente iban_status, informazioni bancarie e quattro risultati della procedura separati. source: "offline_file" indica la sorgente di ingresso. Il file fornito nomina una banca fittizia e non può essere utilizzato come prova di un istituto reale.

Se i campi SEPA mancano in una risposta salvata, l'assistente restituisce unknown con missing_response_data. Questo motivo è un contrassegno locale dell'esempio, non un codice motivo dell'API IBAN-Test. Valori di stato imprevisti o oggetti procedurali difettosi interrompono il programma invece di essere accettati silenziosamente.

4. Controlla una risposta in tempo reale

python3 sepa_check.py --iban "DE89 3704 0044 0532 0130 00"

Il programma interrogherà il tuo token senza visualizzarlo. In alternativa, distribuisci IBAN_TEST_API_TOKEN tramite la configurazione segreta del tuo ambiente di esecuzione. Un'esecuzione live esegue una richiesta di verifica IBAN e addebita la tua quota API. L'helper utilizza un timeout, controlla TLS, non segue i reindirizzamenti e non ritenta automaticamente le richieste.

Su Windows, usa py -3 al posto di python3 se necessario. Il comando termina con 0 per un IBAN valido, anche quando uno o più schemi sono sconosciuti; con 2 se l’IBAN non supera la validazione e con 1 per un errore operativo o di input. Esamina gli schemi separatamente: il codice 0 non significa che siano tutti confermati.

Comprendere un risultato sconosciuto

Salva lo stato e il motivo insieme. Per risultati sconosciuti, visualizza "La partecipazione non può essere confermata" e gestisci questi casi in base al processo di revisione della tua domanda. Non contrassegnare automaticamente l'IBAN come non valido né affermare che la banca non può elaborare questo metodo di pagamento.

Separa gli errori API dai risultati della partecipazione

Un errore di autenticazione HTTP, una quota esaurita o un errore del server non sono un risultato della partecipazione della banca unknown. L'esempio si ferma prima della valutazione della procedura se la richiesta già fallisce. Allo stesso modo, un IBAN con una somma di controllo non valida non porta ad una decisione procedurale. Ciò significa che un servizio non disponibile non diventa un'affermazione fuorviante sulle capacità di una banca.

Esegui i test offline inclusi utilizzando python3 -m unittest -v. Per elenchi di input più grandi, iniziare con Istruzioni CSV e Python e mantenere una coppia stato-motivo separata per ciascuna procedura man mano che si espande l'output.

Riferimento tecnico: documentazione dell’API IBAN-Test e codici motivo SEPA. L'controllo IBAN e la partecipazione bancaria confermata non dimostrano la titolarità del conto, l'esistenza del conto, il mandato, la disponibilità dei fondi o il successo del pagamento.

Crea un account API Confronta le quote API