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

Creare destinatari in hosting su StripeAnteprima pubblica

Come aggiungere destinatari utilizzando un modulo in hosting su Stripe

Utilizzando il modulo web in hosting su Stripe puoi acquisire le informazioni sui destinatari, che vengono visualizzate in modo dinamico in base alle funzionalità, al Paese e ai metodi di pagamento di ciascun destinatario.

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

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

Browser supportati

L’acquisizione in hosting 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

Personalizzare il modulo di raccolta dati

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

Creare un destinatario

Anteprima pubblica

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

Usa l’API Accounts v2 per creare il destinatario. Devi specificare i metodi di bonifico previsti, perché l’abilitazione di alcuni di essi richiede informazioni aggiuntive. I metodi abilitati con il parametro capabilities determinano le informazioni che devi acquisire sul destinatario (ad esempio, configuration.recipient.capabilities.bank_accounts.local per un destinatario 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: 2026-02-25.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 i metodi di bonifico richiesti, Stripe determina nella risposta API le informazioni aggiuntive necessarie, che devi inviare per preparare il destinatario 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 destinatario è possibile abilitare più metodi di bonifico. Non tutti i metodi sono disponibili per tutti i Paesi. Consulta l’elenco completo dei metodi di bonifico disponibili per ciascun Paese.

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

Creare un link condivisibile

Crea un link condivisibile utilizzando l’API Account Link. Questo link potrà essere inviato al destinatario, che potrà così accedere al modulo di raccolta dati e inviare le sue informazioni direttamente a Stripe. Ogni URL AccountLink scade 10 minuti dopo la generazione e può essere utilizzato una sola volta. Se il destinatario fa clic su AccountLink dopo 10 minuti, viene reindirizzato per motivi di sicurezza all’URL refresh.url. Una volta che il destinatario ha fornito le proprie informazioni, l’URL AccountLink lo reindirizza all’URL return.url.

Anteprima privata

Vuoi verificare i destinatari? Dopo che questi avranno condiviso i dati dei metodi di bonifico nei moduli in hosting su Stripe, utilizza l’API Financial Connections per visualizzare e confermare i dati associati al conto bancario collegato. Se vuoi accedere, fornisci la tua email.

Per creare un link condivisibile, includi i seguenti parametri:

  • account: ID del conto destinatario, che puoi ottenere utilizzando l’API Accounts v2
  • use_case.type: se acquisisci i dati del destinatario 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 destinatario quando l’AccountLink è già stato visitato, è scaduto o non è valido.
  • use_case.account_onboarding.refresh_url: pagina a cui Stripe reindirizza il destinatario quando compila o lascia il modulo di raccolta delle informazioni.

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

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: 2026-02-25.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 destinatario 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 destinatario inviando un codice di autenticazione alla sua email e reindirizzandolo a un nuovo AccountLink. Se vuoi accedere, fornisci la tua email.

Confermare la verifica del beneficiario Solo Regno Unito

Prima di pagare i beneficiari nel Regno Unito, richiediamo un controllo di conferma del destinatario. 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 è necessario verificare o meno il conto bancario del destinatario.

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

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: 2026-02-25.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: 2026-02-25.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.

Confermare che il destinatario è abilitato

Affinché un destinatario accetti i bonifici, devi acquisire le informazioni su di lui e sui metodi di bonifico previsti.

Una volta che un destinatario accede al modulo di raccolta dati 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 destinatario è pronto ad accettare i bonifici. Scopri di più sui webhook e sui modi per gestirli.

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

  1. Vai a Destinatari e seleziona il destinatario.
  2. Verifica che non sono necessarie ulteriori informazioni. Un banner sulla pagina mostra se richiediamo ulteriori informazioni al destinatario (ad esempio, “Informazioni necessarie” o “Account bancario predefinito non impostato”). In caso contrario, l’acquisizione delle informazioni del destinatario è completa.
  3. Verifica che almeno un metodo di bonifico sia abilitato nella sezione apposita. In caso contrario, devi acquisire un metodo di bonifico condividendo un altro link o utilizzando l’API. Per creare un altro link condivisibile, utilizza di nuovo l’API Account Links.

Aggiornare un destinatario esistente

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

Per creare un nuovo link condivisibile, includi:

  • account: ID del conto destinatario, che puoi ottenere utilizzando l’API Accounts v2
  • use_case.type: specifica account_update.
  • use_case.account_update.configurations: impostato su recipient.
  • use_case.account_update.return_url: la pagina a cui Stripe reindirizza il destinatario dopo che l’AccountLink è già stato visitato, è scaduto o non è valido.
  • use_case.account_update.refresh_url: pagina a cui Stripe reindirizza il destinatario 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: 2026-02-25.preview" \
  --json '{
    "account": "{{ACCOUNT_ID}}",
    "use_case": {
        "type": "account_update",
        "account_update": {
            "configurations": [
                "recipient"
            ],
            "return_url": "https://example.com/return",
            "refresh_url": "https://example.com/reauth"
        }
    }
  }'

Analogamente all’AccountLink utilizzato per creare il destinatario, l’URL scade dopo 10 minuti e può essere utilizzato solo una volta. Se il destinatario apre l’URL più di una volta o dopo che i 10 minuti sono scaduti, verrà reindirizzato a refresh.url.

In questa pagina