Transfert de fonds avec Treasury à l'aide d'objets InboundTransfer
Les transferts entrants sont des mouvements de fonds effectués avec le réseau ACH depuis un compte états-unien externe vers un compte financier. Ces transferts sont effectués à l’aide des objets InboundTransfer
.
Les transferts entrants sont effectués sous 2 à 4 jours ouvrables, sauf si vous utilisez la fonctionnalité de règlement ACH le jour même. Pour plus d’informations, consultez le guide dédié aux délais des mouvements de fonds.
Note
Vous pouvez utiliser les transferts entrants pour transférer des fonds à partir du compte bancaire d’un propriétaire de compte financier. Pour accepter des fonds provenant d’un tiers sur un compte financier, effectuez un prélèvement ACH sur le solde des paiements, suivi d’un virement sur le compte financier.
Créer un InboundTransfer
Utilisez POST /v1/treasury/inbound_transfers
pour créer un objet InboundTransfer
qui représente des transferts de type « pull » réalisés sur l’un de vos comptes externes à destination de votre compte financier. Un InboundTransfer
vous permet ainsi de transférer des fonds sur votre compte financier en débitant votre compte bancaire externe des États-Unis. Votre requête doit inclure les paramètres suivants :
amount
: le montant en centimes à transférer sur le compte financier.currency
: le code de devise ISO à trois lettres (usd
étant à ce jour la seule valeur prise en charge).financial_account
: l’ID du compte financier sur lequel les fonds sont transférés.origin_payment_method
: la source de fonds qu’utilisera le transfert entrant. Vous devez d’abord configurer le moyen de paiement associé au compte pour la prise en charge des flux entrants et vérifier les informations du compte bancaire à l’aide d’unSetupIntent
. Vous pouvez également utiliser unBankAccount
existant, préalablement vérifié et configuré en tant qu’ExternalAccount
. Que vous utilisiez un moyen de paiement ou un compte bancaire, vous devez obtenir l’autorisation de l’utilisateur pour débiter les fonds du compte.
Le code JSON suivant affiche les données que vous pouvez inclure dans le corps de votre requête.
{ // The source PaymentMethod or BankAccount. Funds are pulled from this account. "origin_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}", // The destination FinancialAccount. Funds arrive in this account. "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // The amount to debit. 10.00 USD in this case. "amount": 1000, "currency": "usd", // An optional, internal description for the InboundTransfer. "description": "Funds for vendor payment payment_234281", // An optional descriptor for the InboundTransfer to send // to the network with the debit request. Max 10 characters "statement_descriptor": "payment_1", // Stripe does not support updating InboundTransfers after creation. // You can only set metadata at creation time. "metadata": null | {{Hash}} }
La requête suivante déclenche un virement de 200 USD sur le compte financier correspondant à l’ID fourni à l’aide d’un moyen de paiement associé au compte. La valeur de l’en-tête Stripe-Account
permet d’identifier le compte Stripe qui détient le compte financier et le moyen de paiement.
Sauf échec de l’opération, la réponse renvoie l’objet InboundTransfer
qui inclut une hosted_regulatory_receipt_url
permettant au titulaire du compte de consulter les informations relatives à la transaction sur votre plateforme.
{ "id": "{{INBOUND_TRANSFER_ID}}", "object": "inbound_transfer", "amount": 20000, "created": 1648071297, "currency": "usd", "description": "Funds for repair", "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{IBT_URL}}", "linked_flows": null, "livemode": false, "metadata": {}, "origin_payment_method": "{{PAYMENT_METHOD_ID}}", ... "statement_descriptor": "Invoice 12", "status": "processing", ... }
Note
origin_payment_method_options[us_bank_account][ach][submission]=same_day
pour que les fonds soient versés au compte financier d’origine le même jour ouvrable, si l’appel InboundTransfer
aboutit avant l’heure limite. Si ce paramètre n’est pas inclus à la création d’un InboundTransfer
, 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. Récupérer un InboundTransfer
Utilisez GET /v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}
pour récupérer l’objet InboundTransfer
avec l’ID associé.
Le code JSON suivant affiche les données que vous pouvez inclure dans le corps de votre requête. 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.
{ "id": "{{INBOUND_TRANSFER_ID}}", "object": "inbound_transfer", "livemode": false, "created": "{{Timestamp}}", "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable "amount": 1000, "currency": "usd", // The only current valid PaymentMethod type for InboundTransfers is us_bank_account "origin_payment_method": "{{PAYMENT_METHOD_ID}}",
La requête suivante permet de récupérer l’InboundTransfer
avec la valeur id
de l’{{INBOUND_TRANSFER_ID}}
. Avec transaction
dans le tableau expand[]
du corps, les informations développées pertinentes sont renvoyées.
Sauf échec de l’opération, la réponse renvoie l’objet InboundTransfer
avec les informations développées.
{ "id": "{{INBOUND_TRANSFER_ID}}", "object": "inbound_transfer", "amount": 20000, "created": 1648071297, "currency": "usd", "description": "Inbound transfer", "failure_details": null, "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{INBOUND_TRANSFER_ID}}",
Lister des InboundTransfers
Utilisez GET /v1/treasury/inbound_transfers
pour récupérer tous les InboundTransfers
du compte financier avec l’ID associé. Vous pouvez filtrer la liste en utilisant les paramètres de liste standard ou le status
.
{ // Standard list parameters "limit", "starting_after", "ending_before", // Filter by status "status": "processing" | "succeeded" | "failed", // Filter by FinancialAccount (Required) "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Required }
La requête suivante permet de récupérer tous les transferts entrants qui présentent l’état succeeded
pour le compte financier avec l’ID {{FINANCIAL_ACCOUNT_ID}}
, qui est associé au compte connecté avec l’ID {{CONNECTED_ACCOUNT_ID}}
.
États d'un InboundTransfer
Le tableau suivant détaille chaque état ainsi que les éventuels états de transition.
ÉTAT | DESCRIPTION | PASSE À L’ÉTAT |
---|---|---|
processing | L’InboundTransfer a été créé. Stripe peut déclencher le transfert des fonds sur le réseau. | failed , canceled , succeeded |
failed (définitif) | La confirmation de l’InboundTransfer a échoué. Aucune transaction n’a été créée et le payment_method n’a pas été débité. | S.O. |
canceled (définitif) | L’InboundTransfer a été annulé avant son envoi au réseau. Stripe annule la transaction et les fonds ne sont pas prélevés sur le compte bancaire externe. | S.O. |
succeeded (définitif) | L’InboundTransfer a abouti et les fonds ont été versés sur le compte. Une transaction a été créée. Les InboundTransfers peuvent être restitués après avoir aboutis si le compte externe récupère les fonds, opération représentée par un ReceivedDebit associé. | S.O. |
Tester des InboundTransfers
Pour tester votre intégration de bout en bout, utilisez les requêtes SetupIntents en mode test pour créer un PaymentMethod
, puis transmettez ce PaymentMethod
dans une demande de création d’InboundTransfer
. Les PaymentMethods
valides génèrent des InboundTransfers
aboutis, tandis que les PaymentMethods
non valides (à savoir ceux qui ne sont pas pris en charge, qui contiennent un compte bancaire non vérifié ou qui n’acceptent pas les flux entrants) produisent les mêmes erreurs qu’en mode production.
Tester les états d'un InboundTransfer
Stripe met également à votre disposition des tokens PaymentMethod
de test que vous pouvez utiliser pour déclencher des changements d’état spécifiques :
VALEUR DU PAYMENT_METHOD | RÉSULTAT |
---|---|
pm_usBankAccount | Un InboundTransfer qui passe de processing à succeeded . |
pm_usBankAccount_processing | Un InboundTransfer qui reste à l’état processing . |
pm_usBankAccount_internalFailure | Un InboundTransfer qui passe de processing à failed . |
Pour vous permettre de tester plus rapidement divers cas particuliers, certains tokens PaymentMethod
simulent des types d’échecs spécifiques :
VALEUR DU PAYMENT_METHOD | RÉSULTAT |
---|---|
pm_usBankAccount_noAccount | Un InboundTransfer qui passe à l’état failed avec l’indication failure_details.code= "no_account" . |
pm_usBankAccount_accountClosed | Un InboundTransfer qui passe à l’état failed avec l’indication failure_details.code= "account_closed" . |
pm_usBankAccount_invalidAccountNumber | Un InboundTransfer qui passe à l’état failed avec l’indication failure_details.code= "invalid_account_number" . |
pm_usBankAccount_insufficientFunds | Un InboundTransfer qui passe à l’état failed avec l’indication failure_details.code= "insufficient_funds" . |
pm_usBankAccount_debitNotAuthorized | Un InboundTransfer qui passe à l’état failed avec l’indication failure_details.code= "debit_not_authorized" . |
pm_usBankAccount_dispute | Un InboundTransfer qui passe de processing à succeeded et est ensuite contesté. inbound_transfer.returned prend la valeur true et un ReceivedDebit associé est créé. |
Dans tous les cas, l’InboundTransfer
prend initialement l’état processing
. Vous recevez des webhooks pour chaque changement d’état pertinent, et la récupération de l’InboundTransfer
après sa création renvoie l’état attendu.
Endpoints d'aide au test des objets InboundTransfer
Stripe fournit aussi des endpoints qui facilitent le test des InboundTransfers
dans différents états. Créez un InboundTransfer
, puis :
Utilisez le endpoint de test
succeed
pour faire passer directement le transfert à l’étatsucceeded
à l’aide de l’ID associé.POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed
Utilisez le endpoint de test
fail
pour faire basculer directement le transfert sur l’étatfailed
avec l’ID associé.POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/fail
Ces endpoints sont particulièrement utiles pour tester des scénarios d’erreur, tels que des retours, qui nécessiteraient autrement une action de la part du compte externe depuis lequel provenait l’InboundTransfer.
Incluez le paramètre facultatif failure_details.code
dans le corps de la requête pour indiquer le motif de l’échec du transfert. Si vous ne fournissez pas ce paramètre, le transfert échoue et affiche par défaut le code d’échec could_not_process
.
{ "failure_details": { "code": "account_closed" | "account_frozen" | "bank_account_restricted" | "bank_ownership_changed" | "could_not_process" | // Generic fallback code "invalid_account_number" | "incorrect_account_holder_name" | "invalid_currency" | "no_account" } }
Treasury propose également un endpoint return
qui permet de simuler un InboundTransfer qui aboutit mais qui est restitué par la suite.
Utilisez le endpoint de test return
pour simuler la restitution de l’InboundTransfer
avec l’ID associé.
POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/return
Tous les endpoints de test déclenchent des webhooks pour chaque changement d’état pertinent, et la récupération du InboundTransfer
après le changement d’état renvoie l’état attendu.
Webhooks relatifs aux InboundTransfers
Stripe émet les événements InboundTransfer
suivants à votre endpoint de webhook :
treasury.inbound_transfer.created
à la création d’unInboundTransfer
.treasury.inbound_transfer.{{new_status}}
lorsqu’unInboundTransfer
change d’état. Il peut prendre les états suivants :treasury.inbound_transfer.succeeded
treasury.inbound_transfer.failed