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

Comment créer des paiements sortants pour transférer des fonds depuis des comptes financiers Treasury vers des comptes tiers.

Les objets OutboundPayment représentent des transferts de type « push » depuis votre compte financier Treasury vers un compte externe tiers par virement ACH ou bancaire, ou vers un autre compte financier associé à la même plateforme au moyen du réseau stripe. Par exemple, si vous voulez envoyer de l’argent depuis votre compte financier vers le compte bancaire américain externe de votre fournisseur, vous devez créer un OutboundPayment pour transférer les fonds. Le bénéficiaire d’un OutboundPayment est un compte bancaire externe ou un autre compte financier.

Le délai de transfert standard pour les paiements sortants peut varier de quelques minutes (lorsque vous utilisez le réseau Stripe), à une livraison le jour même ou à une livraison en 1 ou 2 jours ouvrés (lorsque vous utilisez le réseau ACH). Pour en savoir plus, consultez le guide sur les délais de transfert de fonds.

Créer un OutboundPayment

Utilisez POST /v1/treasury/outbound_payments pour créer un OutboundPayment. Sur l’ensemble des paramètres disponibles, les suivants sont obligatoires :

amount : montant en centimes à payer.
currency : le code de devise ISO à trois lettres (seule la devise usd est prise en charge).
financial_account : le compte financier source depuis lequel les fonds sont transférés.
destination_payment_method ou destination_payment_method_data : informations relatives au bénéficiaire des fonds du paiement.
- Avec destination_payment_method, vous devez d’abord définir le PaymentMethod pour les flux sortants à l’aide d’un SetupIntent. Vous devez également indiquer l’ID client qui correspond à l’objet Customer auquel est associé le PaymentMethod. Vous pouvez aussi utiliser un BankAccount existant associé au Customer au lieu du PaymentMethod.
- Avec destination_payment_method_data, vous pouvez indiquer les informations de moyen de paiement en ligne. Vous pouvez utiliser ce paramètre pour spécifier des coordonnées bancaires ou envoyer des fonds vers un autre compte financier via le réseau Stripe.

Créer un OutboundPayment vers un compte bancaire externe

Utilisez POST /v1/treasury/outbound_payments pour créer un OutboundPayment provenant du compte financier identifié par l’ID du paramètre financial_account du corps. La requête suivante ajoute les informations statement_descriptor et destination_payment_method_data.

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

JSON (commenté)
{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  // The source FinancialAccount. Funds are pulled from this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to send. 10.00 USD in this case.
  "amount": 1000,
  "cancelable": true | false,
  "currency": "usd",
  // The destination payment method. Either this or `destination_payment_method_data`

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 OutboundPayment 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.

Créer un OutboundPayment vers un compte financier

Pour transférer des fonds d’un compte financier à un autre, appelez POST /v1/treasury/outbound_payments sur le compte d’origine et indiquez le compte de destination dans le paramètre destination_payment_method_data. Les deux comptes financiers doivent être associés à la même plateforme, mais ne peuvent pas être associés au même compte connecté. Pour transférer des fonds entre des comptes financiers associés au même compte connecté, utilisez un objet OutboundTransfer.

Le corps de votre requête doit être x-www-form-urlencoded, mais le JSON suivant définit les données que vous pouvez envoyer.

JSON (commenté)
{
  // The source FinancialAccount. Funds are pulled from this account.
  "financial_account": "{{SOURCE_FINANCIAL_ACCOUNT_ID}}",
  // The amount to send.
  "amount": 1000,
  "currency": "usd",
  // The destination payment method. This parameter is the only way to
  // send an OutboundPayment through the `stripe` network.
  "destination_payment_method_data": {
    "type": "financial_account",

Récupérer un OutboundPayment

Utilisez GET /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} pour récupérer les informations de l’OutboundPayment avec l’ID associé.

Sauf échec de l’opération, la réponse renvoie l’objet OutboundPayment 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_PAYMENT_ID}}",
  "object": "outbound_payment",
  "livemode": true | false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // Will only be set if `destination_payment_method` was used during the creation of
  // the OutboundPayment

Annuler un OutboundPayment

Utilisez POST /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel pour annuler l’OutboundPayment avec l’ID associé. L’objet OutboundPayment 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 OutboundPayment 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 OutboundPayment dont le status est défini sur canceled.

{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  "livemode": false,
  "created": 123456,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "amount": 1000,
  "currency": "usd",
  ...
  "status": "canceled",

Répertorier les OutboundPayments

Utilisez GET /v1/treasury/outbound_payments pour obtenir la liste des OutboundPayments du compte financier avec l’ID associé. Vous pouvez filtrer la liste en utilisant les paramètres de liste standard, par status ou customer.

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

La requête suivante permet de récupérer les cinq derniers objets OutboundPayment du compte financier associé à la plateforme et payés à l’objet Customer identifié.

États OutboundPayment

Le tableau suivant détaille chaque état ainsi que les éventuels états de transition.

ÉTAT	DESCRIPTION	PEUT PASSER À L’ÉTAT
`processing`	L’état initial de l’`OutboundPayment`. Les fonds sont attribués à une transaction en attente (mais sont toujours conservés sur le solde actuel). L’utilisateur peut annuler l’`OutboundPayment` tant que le paramètre `cancelable` est défini sur `true`.	`posted`, `canceled`, `failed`
`failed` (définitif)	La confirmation de l’`OutboundPayment` a échoué. Stripe annule la transaction en cours et restitue les fonds à l’utilisateur.	S.O.
`canceled` (définitif)	Un utilisateur a annulé l’`OutboundPayment` avant sa comptabilisation. Stripe annule la transaction en cours et restitue les fonds à l’utilisateur.	S.O.
`posted`	L’`OutboundPayment` a été comptabilisé et les fonds ont été débités du compte. La transaction sous-jacente est comptabilisée.	`returned`
`returned` (définitif)	L’`OutboundPayment` n’est pas parvenu à destination. Les fonds sont restitués à l’utilisateur au moyen d’une transaction (`returned_details[transaction]`).	S.O.

Tester les OutboundPayments

Pour tester votre intégration de bout en bout, nous vous recommandons d’utiliser les requêtes SetupIntent en mode test pour créer un PaymentMethod. Transmettez ensuite ce PaymentMethod dans une requête de création d’OutboundPayment en utilisant le paramètre destination_payment_method.

Stripe met également à votre disposition des numéros et des tokens PaymentMethod de test afin de déclencher des fonctionnalités spécifiques :

En transmettant un token PaymentMethod de test à destination_payment_method (pour les réseaux ach et us_domestic_wire)
- Si vous transmettez un token PaymentMethod de test directement dans destination_payment_method, vous devez quand même transmettre un ID de client au paramètre customer. Pour des raisons pratiques, Stripe vous permet de transmettre n’importe quel client existant en mode test. Cela n’est pas possible en mode production : dans ce dernier, le PaymentMethod existant doit être associé à un Customer, et ce même ID de client doit être transmis au paramètre customer.
En transmettant les numéros de routage et de compte de test à destination_payment_method_data[us_bank_account] (pour les réseaux ach et us_domestic_wire).
En transmettant l’ID d’un compte financier de test appartenant à un compte de la plateforme à destination_payment_method_data[financial_account] (pour le réseau Stripe).

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

CRÉE	DESTINATION_PAYMENT_METHOD (AVEC UN OBJET CUSTOMER DE TEST EXISTANT)	DESTINATION_PAYMENT_METHOD_DATA[US_BANK_ACCOUNT]
Un `OutboundPayment` à l’état initial processing	`pm_usBankAccount_processing`	`routing_number` : 110000000 `account_number` : 000000000009
Un `OutboundPayment` qui passe à `posted` (de `processing`)	`pm_usBankAccount`	`routing_number` : 110000000 `account_number` : 000123456789
Un `OutboundPayment` qui passe à `posted` (de `processing`), en ajoutant un jour à la date `expected_arrival_date` d’origine	`pm_usBankAccount_expectedArrivalDateUpdated`	`routing_number` : 110000000 `account_number` : 000123457890
Un `OutboundPayment` qui passe à l’état `canceled` (de `processing`)	`pm_usBankAccount_canceledByUser`	`routing_number` : 110000000 `account_number` : 000000000123
Un `OutboundPayment` qui passe à `failed` (de `processing`)	`pm_usBankAccount_internalFailure`	`routing_number` : 110000000 `account_number` : 000000000234
Un `OutboundPayment` qui passe à `returned` en raison de la clôture du compte (de processing, après posted)	`pm_usBankAccount_accountClosed`	`routing_number` : 110000000 `account_number` : 000111111113
Un `OutboundPayment` qui passe à l’état returned en raison d’un compte inexistant (de processing, après posted)	`pm_usBankAccount_noAccount`	`routing_number` : 110000000 `account_number` : 000111111116
Un `OutboundPayment` qui passe à `returned` en raison d’un numéro de compte non valide (de processing, après posted)	`pm_usBankAccount_invalidAccountNumber`	`routing_number` : 110000000 `account_number` : 000111111119

Endpoints d’aide au test des objets OutboundPayment

Stripe fournit des endpoints qui vous aident à tester des OutboundPayments dans différents états. Utilisez les endpoints de test pour faire passer un OutboundPayment que vous avez créé directement à l’état posted, failed ou returned.

Utilisez l’endpoint de publication de test pour faire passer l’état de l’objet OutboundPayment identifié de processing (en cours de traitement) à posted (publié).
POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/post
Utilisez l’endpoint d’échec de test pour faire passer l’état de l’objet OutboundPayment identifié de processing (en cours de traitement) à failed (en échec).
POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/fail
Utilisez l’endpoint de renvoi de test pour faire passer l’état de l’objet OutboundPayment identifié de processing (en cours de traitement) à returned (renvoyé).
POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_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 retour 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 Payment 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 OutboundPayment après le changement d’état renvoie l’état attendu.

Webhooks OutboundPayment

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

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