Transférer des fonds à l'aide d'objets OutboundPayment

Les objets OutboundPayment représentent des transferts de type « push » depuis votre compte financier 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 ouvrables (lorsque vous utilisez le réseau ACH). Pour en savoir plus, consultez le guide sur la chronologie 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.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 la fonctionnalité ACH le jour même permet d’envoyer des fonds qui arrivent le jour ouvrable même si l’appel OutboundPayment aboutit avant l’heure limite. Pour utiliser l’ACH le jour même, définissez le paramètre destination_payment_method_options.us_bank_account.network sur ach et le paramètre destination_payment_method_options.us_bank_account.ach.submission sur 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.

Créer un OutboundPayment vers un compte financier

Pour transférer des fonds d’un compte financier à un autre, appelez la méthode 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.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 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é.

curl https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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

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.

curl -X POST https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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",

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

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

États OutboundPayment

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

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

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.