Passa al contenuto
Crea account o Accedi
Il logo della documentazione Stripe
/
Crea un accountAccedi

Creazione di beneficiari ospitati su StripeAnteprima pubblica

Scopri come aggiungere beneficiari utilizzando un modulo ospitato su Stripe

Utilizza il modulo web ospitato su Stripe per acquisire le informazioni sui beneficiari, che vengono visualizzate in modo dinamico in base alle funzionalità, al Paese e ai metodi di pagamento di ciascun beneficiario.

Utilizza l’API Account Links per generare tramite codice un link per acquisire le informazioni con i moduli ospitati su Stripe, che sono visualizzati in modo dinamico in base alle funzionalità, al Paese e ai metodi di pagamento di ciascun beneficiario, e che puoi personalizzare con la ragione sociale, i colori e l’icona del tuo brand. I beneficiari compilano il modulo ospitato e inviano direttamente a Stripe i dati richiesti, incluse le credenziali per i bonifici (ad esempio, conto bancario e numero di routing).

Il beneficiario inserisce i propri dati nel modulo
Il beneficiario accetta di connettere a Stripe le credenziali del bonifico
Una schermata di conferma mostra al beneficiario che è pronto a ricevere i bonifici

Browser supportati

L’acquisizione ospitata su Stripe supporta i browser per desktop e dispositivi mobili, che sono:

  • Le ultime 20 versioni principali di Chrome e Firefox
  • Le ultime 2 versioni principali di Safari ed Edge
  • Le ultime 2 versioni principali di Safari per i dispositivi mobili iOS
  • Ambienti non iframe

Personalizzazione del modulo di acquisizione

Per personalizzare i moduli ospitati su Stripe, vai alla pagina Impostazioni brand dell’attività nella Dashboard per includere ragione sociale, colore e icona.

Creazione di un beneficiario

Anteprima pubblica

I bonifici transfrontalieri per gli ordinanti degli Stati Uniti sono disponibili in anteprima pubblica.

Usa l’API Accounts v2 per creare il beneficiario. Devi specificare le modalità di bonifico previste perché l’abilitazione di alcune modalità richiede informazioni aggiuntive sul beneficiario. Le modalità abilitate utilizzando il parametro capabilities determinano le informazioni che devi acquisire sul beneficiario (ad esempio, configuration.recipient.capabilities.bank_accounts.local per un beneficiario negli Stati Uniti richiede l’invio di un conto e di un numero di routing).

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "identity": {
        "country": "us",
        "entity_type": "individual"
    },
    "configuration": {
        "recipient": {
            "capabilities": {
                "bank_accounts": {
                    "local": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "requirements",
        "configuration.recipient",
        "identity"
    ]
  }'

Dopo aver aggiunto questi campi e le modalità di bonifico richieste, Stripe determina le informazioni aggiuntive necessarie nella risposta API che devi inviare per preparare il beneficiario a ricevere i bonifici.

Metodo di bonificoParametro APIDescrizione
Banca localeconfiguration.recipient.capabilities.bank_accounts.localConsente al conto di ricevere OutboundPayments tramite i circuiti bancari locali, come ACH o FPS.
Bonifico bancarioconfiguration.recipient.capabilities.bank_accounts.wireConsente al conto di ricevere OutboundPayments tramite reti bancarie, come Fedwire o SWIFT.
Carteconfiguration.recipient.capabilities.cardsConsente al conto di ricevere OutboundPayments attraverso i circuiti di carte di debito, come Visa Direct o Mastercard Send.

Per un beneficiario possono essere abilitate più modalità di bonifico. Non tutte le modalità di bonifico sono disponibili per i beneficiari di tutti i Paesi. Consulta l’elenco completo delle modalità di bonifico disponibili per ciascun Paese.

Dopo aver aggiunto questi campi e le modalità di bonifico richieste, Stripe determina le informazioni aggiuntive necessarie nella risposta API che devi inviare per preparare il beneficiario a ricevere i bonifici.

Creazione di un link condivisibile

Crea un link condivisibile utilizzando l’API Account Link. Lo invii al beneficiario, che ha quindi accesso al modulo di acquisizione per inviare le informazioni richieste direttamente a Stripe. Ogni URL AccountLink scade 10 minuti dopo la generazione e può essere utilizzato una sola volta. Se il beneficiario fa clic su AccountLink dopo il periodo di 10 minuti, viene reindirizzato per motivi di sicurezza all’URL aggiornato. Una volta che il beneficiario ha fornito le proprie informazioni, l’URL AccountLink lo reindirizza all’URL return.url.

Anteprima privata

Vuoi verificare i beneficiari? Dopo che i beneficiari avranno condiviso i dati delle modalità di bonifico nei moduli ospitati su Stripe, utilizza l’API Financial Connections per visualizzare e confermare i dati di proprietà associati al conto bancario collegato. Se vuoi accedere, immetti la tua email.

Per creare un link condivisibile, includi i seguenti parametri:

  • account: ID del conto beneficiario, che puoi ottenere utilizzando l’API Accounts v2
  • use_case.type: se acquisisci i dati del beneficiario per la prima volta, specifica account_onboarding.
  • use_case.account_onboarding.configurations: impostato su recipient.
  • use_case.account_onboarding.return_url: la pagina a cui Stripe reindirizza il beneficiario quando l’AccountLink è già stato visitato, è scaduto o non è valido.
  • use_case.account_onboarding.refresh_url: pagina a cui Stripe reindirizza il beneficiario quando compila o lascia il modulo di acquisizione delle informazioni.

La seguente richiesta crea un AccountLink per acquisire per la prima volta le informazioni su un beneficiario:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "account": "{{ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "return_url": "https://example.com/return",
            "refresh_url": "https://example.com/reauth"
        }
    }
  }'

Autentica il beneficiario nella tua applicazione prima di reindirizzarlo a questo URL.

Anteprima privata

Ti interessano altri strumenti di autenticazione? Stripe offre anche una funzione passcode monouso per riautenticare il beneficiario inviando un codice di autenticazione alla sua email e reindirizzandolo a un nuovo AccountLink. Se vuoi accedere, immetti la tua email.

Conferma del controllo del beneficiario Solo Regno Unito

Prima di pagare I beneficiari nel Regno Unito, richiediamo un controllo di conferma del beneficiario. Esegui questo controllo quando crei il conto bancario o utilizzi una chiamata API separata.

Fornisci i seguenti parametri nella tua richiesta a /v2/payment_methods/gb_bank_accounts:

Parametro APIObbligatorioDescrizione
account_numberSìNumero del conto bancario.
sort_codeSìCodice di avviamento (solo numerico) del conto bancario.
confirmation_of_payeeNoDetermina se controllare il conto bancario del beneficiario.

L’intestazione StripeContext in queste richieste deve essere l’ID del conto beneficiario.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/vault/gb_bank_accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
" \
  --json '{
    "sort_code": "108800",
    "account_number": "00012345",
    "confirmation_of_payee": {
        "initiate": true
    }
  }'

Di seguito è riportato un esempio di risposta:

{
  "id": "gbba_123",
  "object": "payment_methods.gb_bank_account",
  "bank_account_type": "checking",
  "bank_name": "Test Bank",
  "created": "2023-05-15T16:29:15.738Z",
  "deactivated": false,
  "last4": "2345",
  "sort_code": "108800",
  "confirmation_of_payee": {
    "result": {
      "created": "2024-10-18T19:19:31.000Z",
      "match_result": "mismatch",
      "matched": {
        "business_type": null,
        "name": ""
      },
      "message": "The provided information does not match the information the bank has on file for this account.",
      "provided": {
        "business_type": "business",
        "name": "John Smith"
      }
    },
    "status": "awaiting_acknowledgement"
  },
}

Se il risultato della conferma del beneficiario corrisponde, puoi inviare immediatamente i fondi a questa destinazione. Se il risultato corrisponde parzialmente, non corrisponde o il servizio non è disponibile, devi prima accettare il risultato:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/vault/gb_bank_accounts/gbba_1234/acknowledge_confirmation_of_payee \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

Riesamina questi conti bancari per assicurarti che siano corretti prima di confermarli. Puoi anche rivedere i conti bancari non corrispondenti nella Dashboard.

Conferma che il beneficiario è abilitato

Affinché un beneficiario accetti i bonifici, devi acquisire le informazioni sul beneficiario e sulle modalità di bonifico previste.

Una volta che un beneficiario accede al modulo di acquisizione dal link condivisibile, e invia le informazioni richieste, viene attivato il webhook v2.core.account_link.returned. Ascoltando questo evento webhook, puoi sapere quando l’AccountLink è stato elaborato correttamente e il beneficiario è pronto ad accettare i bonifici. Scopri di più sui webhook e sui modi per gestirli.

In alternativa, puoi anche determinare se un beneficiario è pronto ad accettare i bonifici utilizzando la Dashboard o l’API Accounts v2.

  1. Vai a Beneficiari e seleziona il beneficiario.
  2. Conferma che non sono necessarie ulteriori informazioni. Un banner sulla pagina mostra se richiediamo ulteriori informazioni al beneficiario (ad esempio, “Informazioni necessarie” o “Account bancario predefinito non impostato”). In caso contrario, l’acquisizione delle informazioni del beneficiario è completa.
  3. Verifica che almeno una modalità di bonifico è abilitata in Modalità di bonifico. In caso contrario, devi acquisire una modalità di bonifico condividendo un altro link o utilizzando l’API. Per creare un altro link condivisibile, utilizza di nuovo l’API Account Links.

Aggiornamento di un beneficiario esistente

Puoi consentire ai beneficiari di aggiornare le proprie informazioni nel modulo ospitato su Stripe, creando un altro link condivisibile con l’API Account Links.

Per creare un nuovo link condivisibile, includi:

  • account: ID del conto beneficiario, che puoi ottenere utilizzando l’API Accounts v2
  • use_case.type: Specifica account_update.
  • use_case.account_onboarding.configurations: impostato su recipient.
  • use_case.account_onboarding.return_url: la pagina a cui Stripe reindirizza il beneficiario dopo che l’AccountLink è già stato visitato, è scaduto o non è valido.
  • use_case.account_onboarding.refresh_url: pagina a cui Stripe reindirizza il beneficiario quando ha compilato o lasciato il modulo di acquisizione delle informazioni.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "account": "{{ACCOUNT_ID}}",
    "use_case": {
        "type": "account_update",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "return_url": "https://example.com/return",
            "refresh_url": "https://example.com/reauth"
        }
    }
  }'

Analogamente all’AccountLink utilizzato per creare il beneficiario, l’URL scade dopo 10 minuti e può essere utilizzato solo una volta. Se il beneficiario apre l’URL oltre la finestra di 10 minuti o più di una volta, lo reindirizziamo a refresh.url.