Transfert de fonds avec Treasury à l'aide d'objets OutboundTransfer

Comment transférer des fonds depuis des comptes financiers Treasury vers des comptes externes.

Un objet OutboundTransfer permet de faciliter les transferts de fonds depuis un compte financier. Utilisez un OutboundTransfer pour envoyer des fonds via le réseau ACH ou via un virement bancaire national vers un compte bancaire externe détenu par un de compte connecté.

En règle générale, les transferts sortants arrivent à la banque destinataire dans un délai maximal de 2 jours ouvrables, qu’il s’agisse d’un virement bancaire ou ACH.

Remarque

Multi FA beta Si vous participez à la version bêta de la fonctionnalité Comptes financiers multiples, vous pouvez utiliser un OutboundTransfer pour envoyer des fonds vers un autre compte financier associé au même compte connecté via le réseau stripe. Les fonds sont disponibles sur le compte financier de destination en quelques minutes.

Pour en savoir plus, consultez le guide consacré aux délais de transfert de fonds.

Les OutboundTransfers prennent en charge les moyens de paiement de type us_bank_account. Vous pouvez également utiliser un BankAccount existant qui appartient au marchand en tant qu’ExternalAccount.

Créer un OutboundTransfer

Utilisez POST /v1/treasury/outbound_transfers pour créer un OutboundTransfer pour le compte financier avec l’ID associé. Sur l’ensemble des paramètres disponibles, quatre sont obligatoires :

amount : montant du transfert en centimes.
currency : code de devise ISO à trois lettres.
financial_account : l’ID du compte financier source d’où proviennent les fonds.
destination_payment_method : l’ID du PaymentMethod de destination ou du BankAccount qui va recevoir les fonds.
destination_payment_method_data : compte financier utilisé pour la réception des fonds.

{
  // The source financial account to pull funds from.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to send. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // The destination PaymentMethod or BankAccount.
  // This should be nil if destination_payment_method is set.
  destination_payment_method_data: {
  type: "financial_account", // us_bank_account is not supported
  financial_account: "{{FINANCIAL_ACCOUNT_ID}}",
  },

  // This should be nil if destination_payment_method_data is set.
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}"  | "{{BANK_ACCOUNT_ID}}",
  // Optionally, to explicitly specify a network, override the `network` value
  // This should be nil if destination_payment_method_data is set.
  "destination_payment_method_options": {
    "us_bank_account": {
      "network": "ach" | "us_domestic_wire"
    }
  },
  // A description visible on the external bank statement.
  "statement_descriptor": "Bank xfer",
  // An optional internal description to identify this OutboundTransfer
  "description": "Transfer to my external account",
  // Stripe does not support updating originated transfers after creation.
  // You can only set metadata at creation.
  "metadata": nil | Hash,
}

La requête suivante permet de créer un OutboundTransfer sur un PaymentMethod associé à un compte et dont les fonds proviennent du compte financier identifié.

Sauf échec de l’opération, la réponse renvoie le nouvel objet OutboundTransfer.

{
    "id": "{{OUTBOUND_TRANSFER_ID}}",
    "object": "outbound_transfer",
    "amount": 1000,
    "cancelable": true,
    "created": 1648479987,
    "currency": "usd",
    "description": null,
    "destination_payment_method": "{{PAYMENT_METHOD_ID}}" | null,
    "destination_payment_method_details": {

ACH le jour même

Version bêta privée

ACH le jour même existe actuellement en version bêta avec une disponibilité limitée, sous réserve de l’examen et de l’approbation de Stripe. Pour demander un accès, envoyez un e-mail à treasury-support@stripe.com.

Si vous n’y avez pas accès, les appels à l’API qui incluent des fonctionnalités ou des paramètres ACH le jour même renvoient une erreur.

Using same-day ACH enables sending funds that arrive the same business day if the OutboundTransfer call successfully completes before the cutoff time. To use same-day ACH, set the destination_payment_method_options.us_bank_account.network parameter to ach and the destination_payment_method_options.us_bank_account.ach.submission parameter to same_day.

Virement bancaire : numéros de routage

Pour les virements bancaires, certaines banques peuvent utiliser un numéro de routage distinct des virements ACH. Par conséquent, vous pourriez recevoir une erreur lors de la création du virement si le numéro de routage du moyen de paiement ne prend pas en charge les virements bancaires. Le cas échéant, vous devez ajouter un nouveau moyen de paiement avec le numéro de routage de votre banque.

Virement bancaire : adresse du bénéficiaire

Les virements bancaires nécessitent des métadonnées ACH ainsi que le nom du bénéficiaire et son adresse de facturation. L’adresse est celle du titulaire du compte recevant le virement et non l’adresse de sa banque.

Lorsque vous saisissez l’adresse billing_details.address pour un moyen de paiement, tous les champs d’adresse doivent être renseignés. Si vous tentez d’effectuer un virement et que les champs de l’adresse billing_details.address sont incomplets, une erreur se produit.

Remarque

Lors de l’envoi d’un virement à l’aide d’un OutboundTransfer, si vous ne remplissez pas les champs d’adresse, Stripe définit par défaut l’entité juridique du titulaire principal du compte Stripe.

Récupérer un OutboundTransfer

Utilisez GET /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}} pour récupérer les informations de l’OutboundTransfer avec l’ID associé.

La requête suivante permet de récupérer l’OutboundTransfer avec l’ID associé en développant les informations de la Transaction.

Sauf échec de l’opération, la réponse renvoie l’objet OutboundTransfer et l’ID associé. Certains des paramètres de la réponse comportent des informations supplémentaires qui ne sont renvoyées que si vous les ajoutez comme valeurs au paramètre expand[]. Les champs que vous pouvez développer affichent le commentaire “Expandable”, comme illustré dans l’exemple de réponse suivant. Pour en savoir plus sur le développement des objets renvoyés, consultez la section consacrée à ce sujet.

JSON (commenté)
{
  "id": "{{OUTBOUND_TRANSFER_ID}}",
  "object": "outbound_transfer",
  "livemode": Boolean,
  "created": Timestamp,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}",
  "description": "Transfer to my external account",

Annuler un OutboundTransfer

Utilisez POST /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/cancel pour annuler l’OutboundTransfer avec l’ID associé. L’objet OutboundTransfer inclut un paramètre cancelable dont la valeur booléenne indique si vous pouvez ou non annuler le transfert. Une fois que vous avez soumis un OutboundTransfer au réseau, la valeur cancelable bascule sur false et cet endpoint envoie une erreur pour le transfert.

Sauf échec de l’opération, la réponse renvoie l’objet OutboundTransfer avec l’état canceled.

{
    "id": "{{OUTBOUND_TRANSFER_ID}} ",
    "object": "outbound_transfer",
    "amount": 1000,
    "cancelable": false,
    "created": 1648487177,
    "currency": "usd",
    ...
    "status": "canceled",
    "status_transitions": {
        "canceled_at": 1648487198,
        "failed_at": null,
        "posted_at": null,
        "returned_at": null
    },
    "transaction": "{{TRANSACTION_ID}}"
}

Répertorier les OutboundTransfers

Utilisez GET /v1/treasury/outbound_transfers pour répertorier les OutboundTransfers envoyés depuis le compte financier avec l’ID du paramètre financial_account. Vous pouvez filtrer la liste en utilisant les paramètres de liste standard ou par status.

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "posted" | "failed" | "returned" | "canceled",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
}

La requête suivante permet de récupérer les OutboundTransfers provenant du compte financier identifié. Les paramètres inclus limitent la réponse aux trois premiers transferts suivant l’OutboundTransfer dont vous avez fourni l’ID.

Sauf échec de l’opération, la réponse renvoie la liste des objets OutboundTransfer qui respectent les critères de filtre.

États OutboundTransfer

Le tableau suivant détaille chaque status ainsi que les éventuels états de transition des OutboundTransfers.

ÉTAT	DESCRIPTION	PASSE À L’ÉTAT
`processing`	L’état initial de l’`OutboundTransfer`. Les fonds sont attribués à une transaction en attente (mais sont toujours conservés sur le solde actuel). L’utilisateur peut annuler l’`OutboundTransfer` tant que le paramètre `cancelable` est défini sur `true`.	`posted`, `canceled`, `failed`
`canceled` (définitif)	Un utilisateur a annulé l’`OutboundTransfer` avant sa comptabilisation. Stripe annule la transaction en cours et restitue les fonds à l’utilisateur.	S.O.
`posted`	Stripe has adjusted the Financial Account balance and determined the `OutboundTransfer` is unlikely to be returned.	`returned`
`returned` (définitif)	L’`OutboundTransfer` n’a pas pu arriver à destination (en raison de coordonnées bancaires erronées par exemple). Stripe restitue les fonds à l’utilisateur avec `returned_details[transaction]`.	S.O.
`failed` (définitif)	L’`OutboundTransfer` n’a pas pu être envoyé sur le réseau. Stripe annule la transaction en cours et restitue les fonds à l’utilisateur. Stripe peut utiliser cet état pour signaler des erreurs internes.	S.O.

Tester les OutboundTransfers

En mode test, vous pouvez indiquer le destination_payment_method comme moyen de paiement de test. Lorsque vous testez votre intégration, vous pouvez créer vos propres PaymentMethods en mode test ou utiliser nos ID de test.

TYPE	RÉSULTAT	MOYEN DE PAIEMENT
`us_bank_account`	Par défaut, passe à `posted`.	`pm_usBankAccount`
`us_bank_account`	Passe à `posted`, ajoute une journée à la date `expected_arrival_date`.	`pm_usBankAccount_expectedArrivalDateUpdated`
`us_bank_account`	Reste sur `processing`.	`pm_usBankAccount_processing`
`us_bank_account`	Passe à `canceled`.	`pm_usBankAccount_canceledByUser`
`us_bank_account`	Passe à `failed`.	`pm_usBankAccount_internalFailure`
`us_bank_account`	Passe à `returned` avec `returned_details.code="no_account"`.	`pm_usBankAccount_noAccount`
`us_bank_account`	Passe à `returned` avec `returned_details.code="account_closed"`.	`pm_usBankAccount_accountClosed`
`us_bank_account`	Passe à `returned` avec `returned_details.code="invalid_account_number"`.	`pm_usBankAccount_invalidAccountNumber`

Dans tous les cas, la réponse de l’objet OutboundTransfer présente l’état processing. Stripe déclenche des webhooks pour les changements d’état pertinents, et la récupération de l’objet OutboundTransfer après sa création renvoie l’état attendu.

Endpoints d’aide au test des objets OutboundTransfer

Stripe fournit des endpoints qui vous aident à tester des OutboundTransfers dans différents états. Après avoir créé un OutboundTransfer, utilisez ces endpoints pour le faire directement passer à l’état posted, failed, canceled ou returned.

Utilisez l’endpoint de publication de test pour faire passer l’état de l’objet OutboundTransfer identifié de processing (en cours de traitement) à posted (publié).
POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/post
Utilisez l’endpoint d’échec de test pour faire passer l’état de l’objet OutboundTransfer identifié de processing (en cours de traitement) à failed (en échec).
POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/fail
Utilisez l’endpoint de renvoi de test pour faire passer l’état de l’objet OutboundTransfer identifié de posted (publié) à returned (renvoyé).
POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/return

Ces endpoints sont particulièrement utiles pour tester des scénarios d’erreur, tels que des restitutions, qui nécessiteraient autrement une action extérieure.

Pour l’endpoint return, incluez le paramètre facultatif returned_details.code dans le corps de la requête pour indiquer le motif de la restitution du transfert. Si vous ne fournissez pas ce paramètre, le transfert affiche par défaut le code de retour declined.

{
  "returned_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" |
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account" |
          "declined"
  }
}

Nous fournissons également un endpoint de modification de test pour simuler la publication des informations de suivi d’un Outbound Transfer de test. Le champ tracking_details peut uniquement être défini pour les objets de test.

Dans tous les cas, Stripe déclenche des webhooks pour chaque changement d’état pertinent. La récupération de l’objet OutboundTransfer après le changement d’état renvoie l’état attendu.

Webhooks OutboundTransfer

Stripe émet les événements OutboundTransfer suivants à votre endpoint de webhook :

treasury.outbound_transfer.created à la création d’un OutboundTransfer.
treasury.outbound_transfer.{{new_status}} lorsqu’un OutboundTransfer change d’état. Il peut prendre les états suivants :
- treasury.outbound_transfer.posted
- treasury.outbound_transfer.failed
- treasury.outbound_transfer.returned
- treasury.outbound_transfer.canceled
treasury.outbound_transfer.expected_arrival_date_updated en cas de modification de la date expected_arrival_date d’un OutboundTransfer.
treasury.outbound_transfer.tracking_details_updated lorsque les informations de suivi d’un OutboundTransfer sont mis à jour.