Transfert de fonds avec Treasury à l'aide d'objets OutboundPayment
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, à une livraison en 1 ou 2 jours ouvrés (lorsque vous utilisez le réseau ACH). Consultez le guide sur la chronologie des mouvements de fonds pour en savoir plus.
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 deviseusd
est prise en charge).financial_account
: le compte financier source depuis lequel les fonds sont transférés.destination_payment_method
oudestination_payment_method_data
: informations relatives au bénéficiaire des fonds du paiement.- Avec
destination_payment_method
, vous devez d’abord définir lePaymentMethod
pour les flux sortants à l’aide d’un SetupIntent. Vous devez également indiquer l’ID client qui correspond à l’objetCustomer
auquel est associé lePaymentMethod
. Vous pouvez aussi utiliser un BankAccount existant associé auCustomer
au lieu duPaymentMethod
. - Avec
destination_payment_method_data
, vous pouvez indiquer les informations de moyen de paiement en ligne. Cela peut vous servir à spécifier des coordonnées bancaires ou à envoyer des fonds vers un autre compte financier via le réseau Stripe.
- Avec
Création d'un OutboundPayment à destination d'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
.
Note
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 OutboundPayment
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 OutboundPayment
.
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.
Créer un OutboundPayment à destination d'un compte financier
Utilisez POST /v1/treasury/outbound_payments
avec un autre compte financier défini dans l’attribut destination_payment_method_data
pour transférer des fonds entre deux comptes financiers. Les deux comptes financiers doivent être associés à la même plateforme, mais il peut s’agir soit d’un compte financier associé à un compte connecté, soit du compte financier de la plateforme.
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.
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 « 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 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",
Lister des 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 des OutboundPayments
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 des 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éseauxach
etus_domestic_wire
)- Si vous transmettez un token
PaymentMethod
de test directement dansdestination_payment_method
, vous devez quand même transmettre un ID de client au paramètrecustomer
. 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, lePaymentMethod
existant doit être associé à unCustomer
, et ce même ID de client doit être transmis au paramètrecustomer
.
- Si vous transmettez un token
- En transmettant les numéros de routage et de compte de test à
destination_payment_method_data[us_bank_account]
(pour les réseauxach
etus_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’OutboundPayment
renvoie l’état processing. Stripe déclenche des webhooks pour les changements d’état pertinents, et la récupération de l’OutboundPayment
après sa création renvoie l’état attendu.
CRÉE | DESTINATION_PAYMENT_METHOD (AVEC UN OBJET CUSTOMER EN MODE TEST EXISTANT) | DESTINATION_PAYMENT_METHOD_DATA[US_BANK_ACCOUNT] |
---|---|---|
Un OutboundPayment à l’état initial processing | pm_usBankAccount_processing |
|
Un OutboundPayment qui passe à posted (de processing ) | pm_usBankAccount |
|
Un OutboundPayment qui passe à posted (de processing ), en ajoutant un jour à la date expected_arrival_date d’origine | pm_usBankAccount_expectedArrivalDateUpdated |
|
Un OutboundPayment qui passe à l’état canceled (de processing ) | pm_usBankAccount_canceledByUser |
|
Un OutboundPayment qui passe à failed (de processing ) | pm_usBankAccount_internalFailure |
|
Un OutboundPayment qui passe à returned en raison de la clôture du compte (de processing, après posted) | pm_usBankAccount_accountClosed |
|
Un OutboundPayment qui passe à l’état returned en raison d’un compte inexistant (de processing, après posted) | pm_usBankAccount_noAccount |
|
Un OutboundPayment qui passe à returned en raison d’un numéro de compte non valide (de processing, après posted) | pm_usBankAccount_invalidAccountNumber |
|
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’
OutboundPayment
identifié deprocessing
(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’
OutboundPayment
identifié deprocessing
(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’
OutboundPayment
identifié deprocessing
(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 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 Payment
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’OutboundPayment
après le changement d’état renvoie l’état attendu.
Webhooks relatifs aux OutboundPayments
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’unOutboundPayment
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 dateexpected_arrival_date
d’unOutboundPayment
.treasury.outbound_payment.tracking_details_updated
lorsque les détails de suivi d’unOutboundPayment
sont mis à jour.