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

Creare un destinatario per pagamenti Global Payouts con l'APIAnteprima pubblica

Come aggiungere destinatari per pagamenti Global Payouts utilizzando l'API di Stripe

Crea un flusso di raccolta delle informazioni che consenta di raccogliere i dati relativi al destinatario e al metodo di bonifico, e quindi di inviare tali informazioni a Stripe attraverso le nostre API.

Considerazioni

La tua attività è responsabile di tutte le interazioni con i destinatari e della raccolta di tutte le informazioni necessarie per verificarli. Stripe aggiorna i requisiti di verifica dei destinatari in base alle modifiche a leggi e regolamenti in tutto il mondo.

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

  • Verificare regolarmente le modifiche ai requisiti legali e normativi.
  • Aggiornare la logica dell’applicazione in risposta a tali cambiamenti.

Prevedi di rivedere e aggiornare regolarmente i requisiti di attivazione per evitare che i bonifici vengano rifiutati.

Creare un destinatario

Quando raccogli le informazioni sul destinatario del bonifico tramite un modulo, utilizza l’API Accounts v2 per creare il destinatario. Per creare l’ID Account devi specificare i seguenti parametri:

Informazioni obbligatorieParametro
Paese del destinatarioidentity.country
Tipo di attività del destinatarioidentity.entity_type
Indirizzo email del destinatariocontact_email
Nome visualizzato per Account. Viene visualizzato nella Dashboard di Stripe e su tutte le fatture inviate per Account.display_name
Metodi di bonifico che vuoi abilitareconfiguration.recipient.capabilities

Anteprima pubblica

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

Devi specificare i tipi di metodo di pagamento desiderati richiedendo le funzionalità corrispondenti al momento della creazione dell’account.

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

Per un destinatario è possibile abilitare più tipi di metodi di bonifico. Non tutti i tipi di metodi sono disponibili per tutti i Paesi. Consulta l’elenco completo dei metodi di bonifico disponibili per ciascun Paese.

Alcune funzionalità richiedono informazioni aggiuntive sul destinatario. Ad esempio, configuration.recipient.capabilities.bank_accounts.local per un destinatario statunitense richiede l’invio di un numero di conto e di routing. Dopo aver richiesto le funzionalità relative al metodo di bonifico, Stripe determina le informazioni aggiuntive che è necessario inviare per abilitarle e può identificarle nella risposta API. Per ricevere i requisiti nella risposta, includi requirements, configuration.recipient, e identity nell’array include. In caso contrario, Stripe restituisce una risposta nulla per tali proprietà, indipendentemente dai loro valori effettivi.

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

Determinare i campi obbligatori per l’attivazione di un destinatario

Per identificare i requisiti specifici che devi inviare, controlla l’array requirements.entries nella risposta dell’API Accounts. Affinché il destinatario possa accettare i bonifici, devi fornire tutti i requisiti che hanno la proprietà restricts_capabilities.

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

Inviare a Stripe le informazioni sul destinatario

Dopo aver riscosso le informazioni richieste, utilizza l’API Accounts per inviarle.

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

Confermare che il destinatario è abilitato

Utilizza l’account e controlla state delle funzionalità richieste. Affinché un beneficiario possa ricevere i bonifici con la modalità di bonifico specificata, state deve essere active.

Command Line
cURL
No results
curl -G https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.preview" \
  -d "include[0]"="configuration.recipient"

Crea modalità di bonifico per i destinatari

Dopo aver abilitato una funzionalità del metodo di bonifico, utilizza l’API Setup Intents per creare il PayoutMethod effettivo del beneficiario.

In questa richiesta, l’intestazione StripeContext deve essere l’ID dell’account 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/money_management/outbound_setup_intents \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
" \
  --json '{
    "payout_method_data": {
        "type": "bank_account",
        "bank_account": {
            "country": "FR",
            "account_number": "FR76300060000112345678901234"
        }
    }
  }'

Nota

Nella risposta OutboundSetupIntent è presente il PayoutMethod. Quando effettui un OutboundPayment, utilizza l’ID di PayoutMethod indicato nella risposta (ad esempio, frba_test_...), non l’ID OutboundSetupIntent (osi_test_...).

Per inviare pagamenti tramite bonifico bancario, utilizza l’API Accounts delle banche statunitensi per aggiungere fedwire_routing_number al PayoutMethod. Sono applicabili costi aggiuntivi. Consulta le tariffe per ulteriori dettagli.

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 per creare un modulo condivisibile che consenta all’utente di inviare le credenziali della carta di debito.

Visualizzare tutti i metodi di bonifico abilitati per un destinatario

Utilizza l’API Payout Methods per recuperare i PayoutMethod di un beneficiario.

In questa richiesta l’intestazione Stripe-Context deve essere l’ID Accountdel destinatario.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v2/money_management/payout_methods \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2026-02-25.preview" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

La risposta contiene un elenco di oggetti PayoutMethod associati al beneficiario. Utilizza gli ID PayoutMethod per effettuare un bonifico utilizzando l’API Outbound Payments. Per ulteriori informazioni, consulta Inviare denaro.

In questa pagina