# Creare un destinatario per pagamenti Global Payouts con l'API

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](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview) per creare il destinatario. Per creare l’ID `Account` devi specificare i seguenti parametri:

| Informazioni obbligatorie                                                                                                  | Parametro                              |
| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Paese del destinatario                                                                                                     | `identity.country`                     |
| Tipo di attività del destinatario                                                                                          | `identity.entity_type`                 |
| Indirizzo email del destinatario                                                                                           | `contact_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 abilitare                                                                                      | `configuration.recipient.capabilities` |

> 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](https://docs.stripe.com/connect/account-capabilities.md?accounts-namespace=v2) al momento della [creazione dell’account](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview#v2_create_accounts-configuration-recipient-capabilities).

| Metodo di bonifico | Parametro API                                              | Descrizione                                                                                                                        |
| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Banca locale       | `configuration.recipient.capabilities.bank_accounts.local` | Consente ad `Account` di ricevere `OutboundPayments` tramite i circuiti bancari locali, come ACH o FPS.                            |
| Bonifico bancario  | `configuration.recipient.capabilities.bank_accounts.wire`  | Consente ad `Account` di ricevere `OutboundPayments` tramite circuiti bancari, come Fedwire o SWIFT.                               |
| Carte              | `configuration.recipient.capabilities.cards`               | Consente 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](https://docs.stripe.com/global-payouts/recipient-creation-options.md#requirements-for-supported-recipient-countries).

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.

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.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](https://docs.stripe.com/api/v2/core/accounts/create.md?api-version=preview#v2_create_accounts-response-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`.

```json
{
 "id": "{{CONNECTED_ACCOUNT_ID}}",
 "object": "v2.core.account",
 "applied_configurations": [
   "recipient"
 ],
 "configuration": {
   "customer": null,
   "merchant": null,
   "recipient": {
     "capabilities": {
       "bank_accounts": {
         "local": {
           "requested": true,
           "status": "restricted",
           "status_details": [
             {
               "code": "requirements_past_due",
               "resolution": "provide_info"
             }
           ]
         },
         "wire": null,
         "instant": null
       },
       "cards": null,
       "stripe_balance": null
     },
     "default_outbound_destination": null
   }
 },
 "contact_email": "jenny.rosen@stripe.com",
 "created": "2025-04-02T17:20:00.000Z",
 "dashboard": null,
 "identity": {
   "attestations": {
     "directorship_declaration": null,
     "ownership_declaration": null,
     "persons_provided": {
       "directors": null,
       "executives": null,
       "owners": null,
       "ownership_exemption_reason": null
     },
     "terms_of_service": {
       "account": null
     }
   },
   "business_details": null,
   "country": "US",
   "entity_type": "individual",
   "individual": null
 },
 "defaults": null,
 "display_name": "Jenny Rosen",
 "metadata": {},
 "requirements": {
   "collector": "stripe",
   "entries": [
     {
       "awaiting_action_from": "user",
       "description": "identity.individual.given_name",
       "errors": [],
       "impact": {"restricts_capabilities": [
           {
             "capability": "bank_accounts.local",
             "configuration": "recipient",
             "deadline": {
               "status": "past_due"
             }
           }
         ],
         "restricts_payouts": null
       },
       "minimum_deadline": {
         "status": "past_due"
       },
       "reference": null,
       "requested_reasons": [
         {
           "code": "routine_onboarding"
         }
       ]
     },
     {
       "awaiting_action_from": "user",
       "description": "identity.individual.surname",
       "errors": [],
       "impact": {
         "restricts_capabilities": [
           {
             "capability": "bank_accounts.local",
             "configuration": "recipient",
             "deadline": {
               "status": "past_due"
             }
           }
         ],
         "restricts_payouts": null
       },
       "minimum_deadline": {
         "status": "past_due"
       },
       "reference": null,
       "requested_reasons": [
         {
           "code": "routine_onboarding"
         }
       ]
     }
   ],
   "summary": {
     "minimum_deadline": {
       "status": "past_due",
       "time": null
     }
   }
 }
}
```

## Inviare a Stripe le informazioni sul destinatario

Dopo aver riscosso le informazioni richieste, utilizza l’[API Accounts](https://docs.stripe.com/api/v2/core/accounts/update.md?api-version=preview) per inviarle.

```curl
curl -X POST https://api.stripe.com/v2/core/accounts/{{CONNECTEDACCOUNT_ID}} \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.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](https://docs.stripe.com/api/v2/core/accounts/retrieve.md?api-version=preview) e controlla `state` delle funzionalità richieste. Affinché un beneficiario possa ricevere i bonifici con la modalità di bonifico specificata, `state` deve essere `active`.

```curl
curl -G https://api.stripe.com/v2/core/accounts/{{CONNECTEDACCOUNT_ID}} \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.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](https://docs.stripe.com/api/v2/money-management/outbound-setup-intents/create.md?api-version=preview) per creare il `PayoutMethod` effettivo del beneficiario.

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

```curl
curl -X POST https://api.stripe.com/v2/money_management/outbound_setup_intents \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -H "Stripe-Context: {{CONTEXT_ID}}" \
  --json '{
    "payout_method_data": {
        "type": "bank_account",
        "bank_account": {
            "country": "FR",
            "account_number": "FR76300060000112345678901234"
        }
    }
  }'
```

> Nella risposta `OutboundSetupIntent` è presente [il PayoutMethod](https://docs.stripe.com/api/v2/money-management/outbound-setup-intents/create.md?api-version=preview#v2_create_outbound_setup_intents-response-payout_method). 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](https://docs.stripe.com/api/v2/core/vault/us-bank-accounts/update.md?api-version=preview) per aggiungere `fedwire_routing_number` al `PayoutMethod`. Sono applicabili costi aggiuntivi. Consulta le [tariffe](https://docs.stripe.com/global-payouts/pricing.md) 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](https://docs.stripe.com/api/v2/core/account-links.md) 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](https://docs.stripe.com/api/v2/money-management/payout-methods/list.md?api-version=preview).

In questa richiesta l’intestazione Stripe-Context deve essere l’ID `Account`del destinatario.

```curl
curl https://api.stripe.com/v2/money_management/payout_methods \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -H "Stripe-Context: {{CONTEXT_ID}}"
```

La risposta contiene un elenco di oggetti `PayoutMethod` associati al beneficiario. Utilizza gli ID `PayoutMethod` per effettuare un bonifico utilizzando l’[API Outbound Payments](https://docs.stripe.com/api/v2/money-management/outbound-payments/create.md?api-version=preview). Per ulteriori informazioni, consulta [Inviare denaro](https://docs.stripe.com/global-payouts/send-money.md).