Pagamenti

Intenzioni di pagamento e idempotenza

Un'intento di pagamento stabilisce immutabilmente i termini economici della transazione prima che l'utente interagisca con il widget. Questo impedisce a un cliente malintenzionato di manipolare l'importo, il conto di destinazione o la causale di trasferimento sul frontend.

Parametri per creare un'intento di pagamento (`POST /payments/?action=create`)

1. Modello standard per i commercianti (beneficiario proprio)

In questo modello, il commerciante definisce tutti i dati di riscossione:

Campo	Tipo	Richiesto	Descrizione e regole
`amount_minor`	Numero intero	Sì	Quantità in unità minori (centesimi). Ad esempio, `1500` rappresenta `15,00 EUR`.
`currency`	Stringa di testo	Sì	Codice valutario ISO 4217 a 3 lettere. Attualmente `EUR`.
`beneficiary`	Oggetto dati JSON	Sì	Dati di destinazione dell'account: `name` (proprietario, da 1 a 140 caratteri di testo) e `iban` (validoIBAN senza spazi, con cifra di controllo controllata). Supporta solo queste due chiavi.
`reference`	Stringa di testo	Sì	Il concetto è visibile sull'estratto conto bancario (massimo 140 caratteri di testo).
`customer_reference`	Stringa di testo	Sì	Identificatore interno del tuo ordine o cliente (da 1 a 128 caratteri di testo: lettere, numeri, `.`, `_`, `:`, `-`; deve iniziare con una lettera o un numero).
`allowed_origin`	Stringa di testo	Sì	Esatta HTTPS sorgente che incorporerà il widget (ad esempio `https://tienda.example.com`), senza percorso.
`allowed_institution_codes`	Array di dati	No	Elenco dei codici di entità consentiti (ad es. `["santander-es", "bbva-es"]`). Se omesso, qualsiasi entità nel catalogo è consentita.
`locale`	Stringa di testo	No	Il linguaggio dell'interfaccia widget. Solo `es`sono accettate in questa versione; qualsiasi altro valore restituisce `422 invalid_locale`.
`expected_mode`	Stringa di testo	No	`mock` o `live`. Controlla che tu chiami l'ambiente atteso; non cambia ambiente. Se non corrisponde, `409 payment_mode_mismatch`.

Il corpo è una whitelist rigorosa: inviare un campo che non è in questa tabella restituisce 422 invalid_request, così come omettere un campo obbligatorio. L'intestazione Content-Type: application/json è obbligatoria (415 json_required) e il corpo è limitato a 32 KB.

2. Modello con profilo gestito (Donazioni/Demo)

Per casi regolamentati o dimostrazioni pubbliche come cruz_roja_demo, il server impone le regole finanziarie e stabilisce i conti target ufficiali:

Campo	Tipo	Richiesto	Descrizione e regole
`profile`	Stringa di testo	Sì	Identificatore del profilo (ad esempio `cruz_roja_demo`).
`institution_code`	Stringa di testo	Sì	Codice entità selezionato dall'utente (da `profile-institutions`).
`amount_minor`	Numero intero	Sì	Importo limitato dalle polizze del profilo (ad esempio da 1 a 100 centesimi).
`customer_reference`	Stringa di testo	Sì	Il riferimento di audit del tuo sistema.
`allowed_origin`	Stringa di testo	Sì	Widget HTTPS fonte.
`locale`	Stringa di testo	No	Linguaggio dei widget (`es`).
`expected_mode`	Stringa di testo	No	Modalità attesa (`mock` o `live`).

Quando profileviene specificato, il server assegna automaticamente il beneficiario ufficiale e il relativo concetto. Non inviare beneficiary o reference su richieste con un profilo gestito.

Regola del `Idempotency-Key`

L'intestazione Idempotency-Key è richiesta in qualsiasi richiesta per creare un'intenzione di pagamento. Deve contenere tra 16 e 128 caratteri di testo ASCII visibili, senza spazi (ad esempio, una UUID v4). Il suo ambito è unico per l'azienda autenticata:

Stessa chiave di idempotenza e stesso corpo: restituisce l'intento originale precedentemente creato insieme a idempotent_replay: true. Non viene generato alcun nuovo addebito e l'ordine bancario non viene duplicato.
Stessa chiave di idempotenza e corpo diverso: rispondi immediatamente con HTTP 409 Conflict.
Stessa chiave di idempotenza in un'altra azienda: appartiene a un altro spazio di idempotenza completamente isolato.

Se una richiesta per creare un'intento di pagamento subisce un'interruzione o un timeout di rete, riprova con esattamente la stessa intestazione Idempotency-Key e lo stesso corpo. Non generare una nuova chiave in caso di guasto temporaneo.

Persistenza e ciclo di vita

Persistenza precedente: L'intento viene registrato nel database prima di restituire la risposta o interagire con qualsiasi connettore bancario.
Token widget effimero: Il token di risposta (payment.widget.token) ha una validità temporale breve (di solito 15-30 minuti) e può essere utilizzato solo dal allowed_origin dichiarato.
Blocco di Concorrenza: Il sistema implementa un controllo ottimista e leases per impedire che due chiamate simultanee autorizzino o modifichino la stessa intentità.

Codici di errore comuni

HTTP	Codice	Causa	Azione consigliata
`400`	`idempotency_key_required`	L'intestazione `Idempotency-Key` manca o è formattata in modo errato.	Genera una chiave valida di testo ASCII visibile tra 16 e 128 caratteri, senza spazi.
`409`	`idempotency_conflict`	La chiave è stata riutilizzata con dettagli di pagamento diversi.	Genera una nuova chiave per pagamenti diversi o riutilizza esattamente lo stesso corpo della richiesta.
`409`	`payment_mode_mismatch`	`expected_mode` non corrisponde alla modalità dell'ambiente che stai chiamando.	Controlla se stai puntando al sandbox o alla produzione; la modalità è impostata dal deployment, non dalla chiamata.
`401`	`invalid_api_key`	L'intestazione `X-API-Key`manca, il formato è invalido oppure la chiave di passaggio non esiste o è inattiva.	Rivedi il codice di accesso. Non includerlo mai nel frontend.
`403`	`payments_not_allowed`	La chiave API non ha abilitato il prodotto `PAYMENTS` .	Contatta Wealth Reader supporto per attivare i pagamenti sul tuo conto.
`403`	`payment_profile_not_allowed`	Il profilo gestito non è abilitato per la tua azienda.	Richiedi la registrazione dell'account profilo da Wealth Reader.
`429`	`api_limit_reached`	Il tuo codice ha esaurito il contatore chiamate cumulativo.	Non si risolve riprovando o aspettando: non c'è finestra né reset automatico. Richiesta di estendere il limite.
`415`	`json_required`	La testa `Content-Type: application/json`manca.	Mandate il corpo come JSON.
`422`	`invalid_request`	Manca un campo obbligatorio o è stato inviato un campo non riconosciuto.	Controlla la tabella dei parametri: il corpo è una whitelist rigorosa.
`422`	`invalid_institution`	L'entità selezionata è non disponibile o non valida.	Vedi `GET /payments/entities/` per codici validi.
`422`	`invalid_amount`	L'importo è inferiore al minimo (€0,01) o non è un intero.	Verifica di inviare un intero in centesimi (`amount_minor`).

Passo successivo

Continua con Stati, consultazioni periodiche sullo status e riconciliazione.

Ultimo aggiornamento 2026-09-10

Parametri per creare un'intento di pagamento (POST /payments/?action=create)