Creazione di un beneficiario di bonifico globale con l'APIAnteprima pubblica

Crea un flusso di raccolta delle informazioni affinché i beneficiari ottengano i dati relativi al beneficiario e alla modalità del bonifico, quindi invia le informazioni a Stripe attraverso le nostre API.

Considerazioni

La tua attività è responsabile di tutte le interazioni con i beneficiari e della raccolta di tutte le informazioni necessarie per verificarli. Stripe aggiorna i requisiti di verifica dei beneficiari seguendo i cambiamenti delle leggi e dei regolamenti di tutto il mondo.

Quando crei un’integrazione per i bonifici, valuta come gestire:

• L’esame regolare dei cambiamenti dei requisiti legali e normativi.
• L’aggiornamento della logica dell’applicazione in risposta ai cambiamenti.

Prevedi di rivedere e aggiornare regolarmente i requisiti di attivazione per evitare che i bonifici non vadano a buon fine.

Creazione di un beneficiario

Quando utilizzi un modulo per acquisire le informazioni sul beneficiario del bonifico, utilizza l’API Accounts v2 per creare il beneficiario. Per creare l’ID dell’account devi specificare i seguenti parametri:

Devi specificare le modalità di bonifico che prevedi con l’API Accounts v2, in quanto alcune modalità richiedono ulteriori informazioni sul beneficiario prima che si possiamo abilitare. 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 degli Stati Uniti richiede l’invio di un conto e di un numero di routing.

Un beneficiario può avere abilitate più modalità di bonifico. Non tutte le modalità di bonifico sono disponibili per destinatari in 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 dell’API che devi inviare per preparare il beneficiario a ricevere i bonifici. Per ricevere questi requisiti, includi requirements, configuration.recipient e identity nell’array include. In caso contrario, Stripe restituirà una risposta nulla, indipendentemente dal loro valore effettivo.

Quando crei, recuperi o aggiorni un account, alcuni campi vengono compilati nella risposta solo se sono specificati nel parametro include. Per tutti i campi non specificati, la risposta li include come nulli, indipendentemente dal loro valore effettivo.

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": [
        "identity",
        "configuration.recipient",
        "requirements"
    ]
  }'

Determina i campi obbligatori per l’attivazione di un beneficiario

Utilizza la risposta dell’API Accounts v2 per ispezionare il campo requirements.entries e determinare i campi specifici da inviare a Stripe. Tutte le voci con il campo restricts_capabilities sono necessarie affinché il beneficiario accetti i bonifici.

{
 "id": "{{CONNECTED_ACCOUNT_ID}}",
 "object": "v2.core.account",
 "applied_configurations": [
   "recipient"
 ],
 "configuration": {
   "customer": null,
   "merchant": null,
   "recipient": {

Invia a Stripe le informazioni sul beneficiario

Dopo aver determinato i campi aggiuntivi da inviare, utilizza l’API Accounts v2 per inviare le informazioni richieste. Utilizza nell’URI l’ID della risposta precedente.

curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -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",
        "individual": {
            "given_name": "Jenny",
            "surname": "Rosen",
            "address": {
                "city": "Brothers",
                "country": "US",
                "line1": "27 Fredrick Ave",
                "postal_code": "97712",
                "state": "OR"
            }
        }
    },
    "include": [
        "identity"
    ]
  }'

Conferma che il beneficiario è abilitato

Utilizza l’API Accounts v2 per recuperare un account e controllare lo stato delle funzionalità richieste. Affinché un beneficiario possa ricevere i bonifici con la modalità specificata, lo stato deve essere attivo.

curl -G https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  -d "include[0]"="configuration.recipient"

Crea le modalità di bonifico per i beneficiari

Utilizza l’API OutboundSetupIntents v2 per inviare a Stripe i dettagli della modalità di bonifico e consentire l’invio di un bonifico a un beneficiario.

In questa richiesta, l’intestazione StripeContext deve essere l’ID dell’account del beneficiario.

curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
" \
  --json '{
    "payout_method_data": {
        "type": "bank_account",
        "bank_account": {
            "country": "FR",
            "account_number": "FR76300060000112345678901234"
        }
    }
  }'

Per inviare i pagamenti mediante trasferimento elettronico, utilizza l’API USBankAccount v2 per aggiungere il fedwire_routing_number alla modalità di bonifico. Si applicano commissioni aggiuntive. Per ulteriori informazioni, consulta le tariffe.

Puoi anche utilizzare le carte di debito come modalità di bonifico. Tuttavia, i destinatari devono inviare i dati della carta di debito direttamente a Stripe. Se vuoi abilitare i bonifici mediante carte di debito, utilizza l’API account Links v2 per creare un modulo condivisibile che consenta all’utente di inviare le credenziali della carta di debito.

Visualizza tutte le modalità di bonifico per un beneficiario

Visualizza tutte le modalità di bonifico create per un beneficiario. Chiama l’API Bonifici v2 e specifica l’ID del beneficiario.

In questa richiesta, l’intestazione StripeContext deve essere l’ID dell’account del beneficiario.

curl https://api.stripe.com/v2/money_management/payout_methods \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

La risposta contiene un elenco di oggetti PayoutMethod di proprietà del beneficiario. Utilizza gli ID PayoutMethod per effettuare un bonifico utilizzando l’API OutboundPayments. Per ulteriori informazioni, consulta Invio di denaro.