Transfert de fonds avec Treasury à l'aide d'objets 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.

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.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor=payment_1 \
  -d "destination_payment_method_data[type]"=us_bank_account \
  -d "destination_payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "destination_payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "destination_payment_method_data[us_bank_account][account_number]"=1234567890 \
  --data-urlencode "destination_payment_method_data[billing_details][email]"="jenny@example.com" \
  -d "destination_payment_method_data[billing_details][phone]"=7135551212 \
  -d "destination_payment_method_data[billing_details][address][city]"=Alvin \
  -d "destination_payment_method_data[billing_details][address][state]"=TX \
  -d "destination_payment_method_data[billing_details][address][postal_code]"=77511 \
  -d "destination_payment_method_data[billing_details][address][line1]"="123 Main St." \
  -d "destination_payment_method_data[billing_details][name]"="Jenny Rosen"

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

{
  "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

L’utilisation de l’ACH le jour même permet d’envoyer des fonds qui arrivent le même jour ouvrable si l’appel OutboundPayment est effectué avec succès avant l’heure limite. Pour utiliser l’ACH le jour même, attribuez la valeur ach au paramètre destination_payment_method_options.us_bank_account.network et la valeur same_day au paramètre destination_payment_method_options.us_bank_account.ach.submission.

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.

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 peuvent être liés soit à un compte connecté, soit à la plateforme.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account={{SOURCE_FINANCIAL_ACCOUNT_ID}} \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor="Test outbound payment to FA" \
  -d "destination_payment_method_data[type]"=financial_account \
  -d "destination_payment_method_data[financial_account]"={{DESTINATION_FINANCIAL_ACCOUNT_ID}}

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.

{
  // 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 via the `stripe` network.
  "destination_payment_method_data": {
    "type": "financial_account",

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

curl https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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.

{
  "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

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.

curl -X POST https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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",

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

curl -G https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d limit=5 \
  -d customer=
{{CUSTOMER_ID}}

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

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’objet 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. Notez que 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 en mode 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.

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 en mode test. Le champ tracking_details ne peut être défini que pour les objets du mode 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.

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.