Transfert de fonds avec Treasury à l'aide d'objets OutboundTransfer
Un objet OutboundTransfer
permet de faciliter les mouvements 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 utilisateur 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.
Note
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 des mouvements 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 duPaymentMethod
de destination ou duBankAccount
qui va recevoir les 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. "destination_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}", // Optionally, to explicitly specify a network, override the `network` value "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é.
Note
Same Day ACH beta Incluez le paramètre facultatif destination_payment_method_options[us_bank_account][ach][submission]=same_day
pour que les fonds soient versés via ACH le même jour ouvrable, si l’appel OutboundTransfer
aboutit avant l’heure limite. Si ce paramètre n’est pas inclus lors de la création d’un OutboundPayment
, la transaction utilise la fréquence de mouvements de fonds par défaut. Incluez destination_payment_method_options[us_bank_account][network]=ach
lorsque vous utilisez cette fonctionnalité. Pour vous inscrire sur la liste d’attente de la version bêta de l’ ACH Same Day, contactez treasury-support@stripe.com.
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}}", "destination_payment_method_details": {
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
Outre les métadonnées ACH, les virements bancaires nécessitent des métadonnées supplémentaires, en particulier le nom du bénéficiaire et son adresse de facturation. L’adresse fournie doit être l’adresse 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.
Note
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 « Développable », 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.
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}}" }
Lister des 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 des OutboundTransfers
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 | L’OutboundTransfer a été envoyé sur le réseau et les fonds ont été prélevés sur le compte (la transaction a été comptabilisée). | 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 des OutboundTransfers
En mode test, vous pouvez indiquer le destination_payment_method
comme moyen de paiement du mode 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’OutboundTransfer
présente l’état processing
. Stripe déclenche des webhooks pour les changements d’état pertinents, et la récupération de l’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’
OutboundTransfer
identifié deprocessing
(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’
OutboundTransfer
identifié deprocessing
(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’
OutboundTransfer
identifié deposted
(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 restitution 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
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’OutboundTransfer
après le changement d’état renvoie l’état attendu.
Webhooks relatifs aux OutboundTransfers
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 dateexpected_arrival_date
d’un OutboundTransfer.treasury.outbound_transfer.tracking_details_updated
lorsque les informations de suivi d’unOutboundTransfer
sont mis à jour.