Transfert de fonds avec Treasury à l'aide d'objets InboundTransfer

Comment transférer des fonds vers un compte financier Treasury depuis un autre de vos comptes.

Les transferts entrants sont des transferts de fonds effectués à l’aide du réseau ACH entre un compte bancaire des États-Unis externe et 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 de transfert de fonds.

Note

Vous pouvez utiliser les transferts entrants pour transférer des fonds à partir du compte bancaire d’un titulaire 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’un SetupIntent. Vous pouvez également utiliser un BankAccount 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 du titulaire du compte 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",
    ...
}

Avertissement

Dans de rares cas, Stripe peut annuler une demande d’InboundTransfer en raison de divers facteurs de risque. Dans ces cas, la demande API est erronée et renvoie le code de réponse 402. Le message d’erreur fournit des détails supplémentaires sur les facteurs de risque qui ont conduit à l’intervention.

ACH le jour même

Bêta

ACH le jour même existe actuellement en version bêta avec une disponibilité limitée, sous réserve de l’examen et de l’approbation de Stripe. Pour demander un accès, envoyez un e-mail à treasury-support@stripe.com.

Si vous n’y avez pas accès, les appels à l’API qui incluent des fonctionnalités ou des paramètres ACH le jour même renvoient une erreur.

L’utilisation de l’ACH le jour même permet aux fonds d’arriver sur le compte financier à l’origine de la transaction le même jour ouvrable si l’appel InboundTransfer est effectué avec succès avant l’heure limite. Pour utiliser l’ACH le jour même, attribuez la valeur same_day au paramètre origin_payment_method_options.us_bank_account.ach.submission.

Note

Avec le règlement rapide des virements entrants ACH le jour même, votre plateforme peut s’exposer à un risque financier plus important qu’avec les virements entrants ACH standard. Par exemple, un compte connecté peut initier un transfert entrant qui est retourné en raison d’une insuffisance de fonds sur le compte source. Le règlement le jour même augmente le risque que les fonds soient retirés du compte financier avant qu’ils ne soient renvoyés. Si le compte connecté retire les fonds et que le retour entraîne un solde négatif sur le compte financier, votre plateforme est responsable de cette perte.

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 “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": "{{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 (par exemple, 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’objet InboundTransfer prend d’abord l’état processing. Vous recevez des webhooks pour chaque changement d’état pertinent, et la récupération de l’objet 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’état succeeded avec l’ID associé.
POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed
Utilisez l’endpoint d’échec de test pour faire basculer directement le transfert sur l’état failed 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 l’endpoint de renvoi de test pour simuler la restitution de l’objet 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 de l’objet 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’un InboundTransfer.
treasury.inbound_transfer.{{new_status}} lorsqu’un InboundTransfer change d’état. Il peut prendre les états suivants :
- treasury.inbound_transfer.succeeded
- treasury.inbound_transfer.failed