Post-financer votre intégration à StripeVersion bêta privée
Découvrez comment rembourser Stripe après des dépenses par carte.
En tant qu’utilisateur direct ou plateforme Connect, vous pouvez désormais accumuler un solde Issuing négatif sur les dépenses effectuées par carte et les post-financer en remboursant Stripe dans un second temps. Autrement dit, vous approvisionnez votre solde Issuing après la capture des autorisations par le réseau (généralement 1 jour après la création de l’autorisation) au lieu de préfinancer votre solde Issuing avant toute dépense effectuée par carte. Chaque jour, Stripe vous informe du montant dû. Vous pouvez alors effectuer un virement bancaire le jour même pour rembourser Stripe avant l’heure limite (généralement 20 h 00 UTC) afin d’éviter les frais de retard et autres pénalités.
Connect
Si vous postfinancez une plateforme Connect, le comportement de votre compte connecté est identique à celui décrit dans :
La relation entre votre plateforme et votre compte connecté est inchangée. La principale différence est qu’au lieu d’avoir à financer à l’avance chaque dépense de vos comptes connectés, vous pouvez les financer après coup.
Avant de commencer
- Constitution d’une réserve (accessible uniquement en cas de défaillance opérationnelle)
- La possibilité d’envoyer des virements depuis votre compte bancaire
CreditPolicy du programme de cartes
Stripe configure pour votre programme de cartes une CreditPolicy contenant des informations essentielles sur vos obligations et conditions de remboursement. La CreditPolicy de votre programme de cartes est distincte de la CreditPolicy que vous définissez pour vos comptes connectés. La CreditPolicy de votre programme de cartes est définie et contrôlée par Stripe. Elle contient les principaux champs suivants :
credit_: il s’agit du montant total maximum qui peut être dépensé par l’ensemble de vos comptes connectés (ou par votre compte, en cas d’utilisateur direct). Ce paramètre étant défini par Stripe, vous devez nous envoyer une demande pour toute modification. Cette valeur correspond à ce que nous appelons votre limite d’exposition.limit_ amount required_: le montant minimum que vous devez détenir dans votre réserve Stripe.reserve_ amount credit_etperiod_ interval credit_: ces deux champs définissent la période pendant laquelle les dépenses par carte peuvent s’accumuler avant d’arriver à échéance. Pour votre programme de cartes, l’intervalle de crédit est d’un jour, ce qui signifie que vous devrez rembourser Stripe chaque jour.period_ interval_ count
Pour consulter la CreditPolicy de votre programme de cartes, appelez l’endpoint de l’API GET CreditPolicy.
GET /v1/issuing/credit_policy
Exemple de réponse
{ "livemode": true, "credit_limit_amount": 10000, // minor units "credit_limit_currency": "usd", "required_reserve_amount": 9000, // minor units "reserve_currency": "usd", "status": "active", "credit_period_interval": "day", "credit_period_interval_count": 1 // other fields for upcoming/last effective attributes }
FundingObligation du programme de cartes
Si votre CreditPolicy définit les paramètres généraux de votre programme de post-financement, votre FundingObligation représente votre obligation actuelle envers Stripe au titre des dépenses par carte effectuées par l’ensemble de vos comptes connectés (ou par votre compte, dans le cas d’un utilisateur direct).
Chaque matin, Stripe envoie un événement de webhook issuing_ contenant la FundingObligation que vous devez à Stripe. Pour une FundingObligation donnée, la valeur amount_ représente le montant que vous devez ce jour-là.
{ "id": "icfo_123", "amount_total": 95000000, // minor units "amount_outstanding": 95000000, // minor units "amount_paid": 0, "currency": "usd", "status": "unpaid", "due_at": "timestamp_on_t1", "paid_at": "nil", "owed_to": "stripe", "finalized_at": "timestamp_on_t2", "grace_period_ends_at": "timestamp_on_t3", …, }
Paiements en retard
Chaque FundingObligation contient un champ due_, qui indique la date d’échéance de la FundingObligation.
{ "id": "icfo_123", "amount_total": 95000000, // minor units "amount_outstanding": 95000000, // minor units "amount_paid": 0, "currency": "usd", "status": "unpaid", "due_at": "timestamp_on_t1", "paid_at": "nil", "owed_to": "stripe", "finalized_at": "timestamp_on_t2", "grace_period_ends_at": "timestamp_on_t3", …, }
Si vous ne payez pas votre FundingObligation à échéance :
- Remplace le
statusdeFundingObligationparpast_, ce qui déclenche un événement de webhookdue issuing_funding_ obligation. updated - Engendre des frais de retard de paiement, comme indiqué dans votre contrat avec Stripe
Plusieurs retards de paiement peuvent entraîner des pénalités supplémentaires pour votre plateforme (par exemple, une réduction de la limite d’exposition de votre programme de cartes).
Déterminer le montant que vous devez à Stripe
Stripe publie chaque jour une FundingObligation pour votre programme de cartes, y compris le week-end et les jours fériés. Le meilleur moyen de vous assurer que votre compte est en règle et d’éviter les frais de retard ou pénalités est de calculer chaque jour le montant total dû à partir de la valeur amount_ de toutes les FundingObligation unpaid et past_ à l’aide d’une formule telle que :
total_ = somme(unpaid FundingObligations)1 + somme(past_due FundingObligations)2 |
La somme 1sum(unpaid FundingObligations) correspond au total de toutes les FundingObligations avec status=unpaid.
2sum(past_due FundingObligations) est le total de toutes les FundingObligations dont status=past_.
Week-ends et jours fériés : soldes dus le jour ouvrable suivant
Alors qu’une FundingObligation créée un jour de semaine est due le jour même, une FundingObligation créée un week-end ou un jour férié est due le jour ouvrable suivant. Cela signifie que lors d’un week-end type, vous aurez trois FundingObligations dues le lundi. Il est donc important de calculer correctement le montant total dû à Stripe.
Rembourser votre FundingObligation
Pour rembourser quotidiennement le montant total dû à Stripe en vous basant sur l’horodatage due_, utilisez l’une des méthodes suivantes :
- Virements le même jour : vous pouvez effectuer un virement le jour même de votre banque vers votre solde Stripe Issuing afin de régler une
FundingObligation. Utilisez l’API FundingInstructions pour récupérer le numéro de compte et le numéro de routage de votre solde Issuing, et utilisez-les comme destination pour le virement bancaire. - Transferts de solde : aux États-Unis, vous pouvez transférer instantanément des fonds de votre solde Stripe vers votre solde Issuing et les utiliser pour rembourser votre
FundingObligationvia le Dashboard ou l’API (contactez Stripe pour obtenir un accès à l’API). - Solde Issuing préfinancé existant : Stripe impute à votre
FundingObligationsuivante tout montant préfinancé ou excédentaire de la veille.
Une fois que Stripe a reçu le montant total dû sur la FundingObligation, nous mettons à jour son état et ses montants, et déclenchons un événement de webhook issuing_.
{ "id": "icfo_123", "amount_total": 95000000, // minor units "amount_outstanding": 0, "amount_paid": 95000000, // minor units "currency": "usd", "status": "paid", "due_at": "timestamp_on_t1", "paid_at": "timestamp_of_payment", "owed_to": "stripe", "grace_period_ends_at": "timestamp_on_t2" …, }
Si vous ne payez qu’une partie du montant total dû, Stripe met à jour les montants, mais l’état reste unpaid, ce qui est reflété dans l’événement webhook issuing_.
{ "id": "icfo_123", "amount_total": 95000000, // minor units "amount_outstanding": 3000000, // minor units "amount_paid": 92000000, // minor units "currency": "usd", "status": "unpaid", "due_at": "timestamp_on_t1", "paid_at": "timestamp_of_payment", "owed_to": "stripe", "grace_period_ends_at": "timestamp_on_t2" …, }
Si le solde reste impayé après la date limite due_, l’état (status) passe à past_, ce qui déclenche un autre événement de webhook issuing_.
Récupérer les transactions d’une FundingObligation
Pour obtenir la liste des transactions qui composent une FundingObligation, transmettez l’un des paramètres suivants dans une demande de liste des transactions à l’API :
- Le paramètre funding_obligation_for_account pour les utilisateurs directs
- Le paramètre funding_obligation_for_platform pour les plateformes
Direct
Exemple de réponse
{ "object": "list", "url": "/v1/issuing/transactions", "has_more": false, "data": [ { "id": "ipi_123", "object": "issuing.transaction", // various other fields "funding_obligation_for_platform": null, "funding_obligation_for_account": "ifo_123", // various other fields }, { "id": "ipi_123", "object": "issuing.transaction", // various other fields "funding_obligation_for_platform": null, "funding_obligation_for_account": "ifo_123", // various other fields }, {...} ] }
Plateforme
Les plateformes Connect doivent spécifier l’ID d’un compte connecté dans l’en-tête Stripe-Account. Utilisez le paramètre funding_obligation_for_platform pour récupérer la FundingObligation de la plateforme, ou le paramètre funding_obligation_for_account si vous connaissez la FundingObligation d’un compte connecté.
Exemple de réponse
{ "object": "list", "url": "/v1/issuing/transactions", "has_more": false, "data": [ { "id": "ipi_123", "object": "issuing.transaction", // various other fields "funding_obligation_for_platform": "ifo_123", "funding_obligation_for_account": "ifo_456", // various other fields }, { "id": "ipi_123", "object": "issuing.transaction", // various other fields "funding_obligation_for_platform": "ifo_123", "funding_obligation_for_account": "ifo_789", // various other fields }, {...} ] }
Gérer votre réserve
Pour post-financer des dépenses par carte, vous devez d’abord constituer une réserve sur Stripe (appelée « garantie » dans votre contrat de programme). Cette réserve est versée sur un compte détenu et contrôlée par Stripe afin de garantir les sommes dues et de rembourser les éventuelles FundingObligations à l’état past_. Si Stripe prélève des fonds dans la réserve, des frais de retard pourront vous être facturés. Par ailleurs Stripe pourra diminuer le credit_ de votre plateforme ou augmenter le montant de votre réserve. Pour éviter cette situation, approvisionnez votre solde Stripe Issuing par virement bancaire ou transfert de solde avant la date due_ indiquée sur la FundingObligation de votre intégration de crédit.
Obtenir vos exigences de réserve
Vous trouverez le required_ dans votre CreditPolicy. Vous devez créditer votre réserve à hauteur de ce montant pour pouvoir profiter des fonctionnalités de post-financement.
GET /v1/issuing/credit_policy
Exemple de réponse
{ "livemode": true, "credit_limit_amount": 10000, // minor units "credit_limit_currency": "usd", "required_reserve_amount": 9000, // minor units "reserve_currency": "usd", "status": "active", "credit_period_interval": "day", "credit_period_interval_count": 1 // other fields for upcoming/last effective attributes }
Ajouter des fonds au solde de votre réserve
Stripe prend en charge le transfert de fonds vers votre réserve. Vous trouverez les renseignements relatifs au compte associé à votre réserve dans la FundingInstruction, qui contient les informations de compte bancaire et de routage nécessaires au transfert de fonds.
Mise en garde
Ces instructions diffèrent de celles que Stripe utilise pour financer votre solde Issuing. Le paramètre destination_ des instructions de financement de votre réserve doit correspondre à issuing_.
Exemple de réponse
{ "id": "fi_XYZ", "object": "funding_instruction", "livemode": "true", "currency": "usd", "bank_transfer": { "type": 'us_bank_account', "country": "US", "financial_addresses": [{ "supported_networks": ['ach', 'domestic_wire_us'], "type": 'aba', "aba": { "account_number": "546475644", "bank_name": "Wells Fargo", "routing_number": "123456" }, }] }, "destination_balance": "issuing_credit_reserved", "funding_type": "bank_transfer", }
Les fonds transférés (via un virement bancaire ou ACH) sur le compte bancaire récupéré de la ressource FundingInstructions sont crédités sur le solde de votre réserve. Une fois les fonds crédités, vous recevez une notification de webhook topup..
{ "id": "tu_XYZ", "object": "topup", "amount": 9000, "balance_transaction": "txn_123", "destination_balance": "issuing_credit_reserved" "created": 123456789, ... }
Consulter le solde de votre réserve
Vous pouvez à tout moment utiliser l’API /v1/balance pour consulter le solde de votre réserve :
Exemple de réponse
{ "object": "balance", "available": [ ... ], "connect_reserved": [ ... ], "issuing": { ... }, "issuing_credit_reserved": [ { "amount": 9000, "currency": "usd" } ], "livemode": true, "pending": [ ... ] }
Prélèvement de Stripe dans la réserve
Si vous avez une FundingObligation à l’état past_, Stripe effectue d’abord un prélèvement dans votre réserve pour rembourser la FundingObligation. Nous utilisons le webhook issuing_ pour vous en informer, et l’objet FundingObligation est mis à jour pour indiquer le montant remboursé via votre réserve. Si les fonds de votre réserve ne suffisent pas à rembourser l’intégralité du montant impayé amount_ de la FundingObligation, la FundingObligation reste à l’état past_. Pour en savoir plus sur les retards de paiement, consultez la page Obligations de financement en retard.
L’exemple suivant affiche une FundingObligation intégralement remboursée à l’aide des fonds présents sur la réserve :
{ "id": "icfo_123" "amount_total": 95000000, // minor units "amount_outstanding": 0, "amount_paid": 95000000, // minor units "amount_paid_from_reserve": 95000000, // minor units "currency": "usd", "status": "paid", "due_at": "timestamp_on_t1", "paid_at": "timestamp_of_payment_with_reserve", "owed_to": "stripe", "grace_period_ends_at": "timestamp_on_t2", …, }
L’objet BalanceTransfer (et les objets BalanceTransactions associés) représente le transfert de fonds automatisé de votre solde de réserve vers votre solde Issuing.
Exemple de réponse
{ "id": "btr_1MinsBCq7itcH1tbDkk4sY8w", "object": "balance_transfer", "amount": 10000, "currency": "usd", "destination_balance": { "issuing": { "balance_transaction": "txn_123_inbound" }, "type": "issuing" }, ... "source_balance": { "issuing_credit_reserved": { "balance_transaction": "txn_123_outbound" }, "type": "issuing_credit_reserved" } }
Exemple de réponse
{ "id": "txn_123_outbound", "object": "balance_transaction", "amount": 100, "currency": "usd", ... "type": "balance_transfer_outbound", "balance_type": "issuing_credit_reserved", "reporting_category": "issuing_credit_reserved_funds" } { "id": "txn_123_inbound", "object": "balance_transaction", "amount": 100, "currency": "usd", ... "type": "balance_transfer_inbound", "balance_type": "issuing", "reporting_category": "issuing_credit_reserved_funds" }
Réapprovisionner votre réserve
Si Stripe puise dans votre réserve pour rembourser une FundingObligation, vous devez la réapprovisionner à hauteur du reserve_ minimal indiqué dans votre CreditPolicy. Stripe génère une FundingObligation, qui vous informe du montant et de la date limite de réapprovisionnement de la réserve. Vous recevez également un webhook issuing_. Pour reconstituer votre réserve, vous devez transférer des fonds en utilisant le même solde de réserve FundingInstruction que celui précédemment utilisé. Vous devez procéder au réapprovisionnement avant l’horodatage due_ de la FundingObligation.
{ "id" : "fo_456", "object": "issuing.funding_obligation", "amount_outstanding": 10000, "amount_paid": 0, "amount_total": 10000, "currency": "usd", "status": "pending", "due_at": "timestamp_t1", "grace_period": "timestamp_t2", "balance_type": "issuing_credit_reserved" ... }
Écouter les mises à jour d’exigences relatives aux réserves
Le montant de votre réserve obligatoire peut changer à mesure que votre programme évolue, ce qui entraîne une mise à jour du champ required_ de votre CreditPolicy. Si votre réserve augmente en raison du développement de votre programme, votre limite d’exposition augmente également en conséquence. Écoutez le webhook issuing_ pour recevoir une notification en cas de modification.
Augmentation des exigences de réserve
Le processus d’augmentation de vos exigences de réserve (comme indiqué dans votre CreditPolicy) est similaire au réapprovisionnement de votre réserve. Vous recevez une FundingObligation pour la réserve, qui doit être payée dans les délais indiqués dans la FundingObligation.
{ "id" : "fo_321", "object": "issuing.funding_obligation", "amount_outstanding": 2000, "amount_paid": 0, "amount_total": 0, "currency": "usd", "status": "pending", "due_at": "timestamp_t1", "grace_period": "timestamp_t2", "balance_type": "issuing_credit_reserved" ... }
Diminution des exigences de réserve
Lorsque votre exigence de réserve diminue (comme indiqué dans votre CreditPolicy), nous transférons les fonds excédentaires sur votre solde Issuing afin que vous puissiez décider de les consacrer à vos dépenses ou de les virer sur le compte bancaire associé à votre intégration Issuing.
Obligations de réserve impayées
Si votre obligation de financement de la réserve passe à l’état past_ (c’est-à-dire si la date due_ est dépassée), nous commençons à refuser les autorisations de transaction. Si vous rencontrez un problème lors de l’approvisionnement de votre réserve, contactez le responsable de votre compte.
Montant disponible pour les dépenses du programme de cartes
Stripe ne propose actuellement pas de champ ou de solde qui indique le montant pouvant être dépensé dans le cadre de votre programme de cartes. Pour le calculer, utilisez la formule suivante :
crédit disponible = credit_ + solde Issuing (le solde Issuing peut être négatif en cas de dépenses supplémentaires ne dépassant pas la limite d’exposition) |
Refus d’autorisation dans le cadre d’un post-financement
En cas de post-financement, les autorisations peuvent être refusées pour les motifs suivants :
past_due FundingObligations- Non-réapprovisionnement de votre réserve
Refus de paiement dus à des FundingObligations à l’état past_due
Stripe refuse les autorisations lorsqu’une FundingObligation est à l’état past_ et que la période de grâce définie dans l’horodatage grace_ de la FundingObligation est écoulée. Pour trouver le paramètre grace_, procédez comme suit :
{ "id": "icfo_123", "amount_total": 95000000, // minor units "amount_outstanding": 95000000, // minor units "amount_paid": 0, "currency": "usd", "status": "past_due", "due_at": "timestamp_on_t1", "paid_at": nil, "owed_to": "stripe", "grace_period_ends_at": "timestamp_on_t2", ..., }
Si la période de grâce est écoulée, les autorisations Issuing sont refusées et des événements issuing_authorization.created sont générés avec les éléments suivants :
{ "id": "iauth_123", "object": "issuing_authorization", "approved": false, ..., "status": "closed", "request_history": [ { "amount": 100, // minor units "approved": false, "reason": "past_due_funding_obligation_to_stripe", ..., } ] }
Non-réapprovisionnement de votre réserve
Chaque fois que Stripe puise dans votre réserve pour rembourser une FundingObligation, vous disposez d’un délai de grâce (généralement de 24 heures) pour la réapprovisionner à hauteur de la required_ de votre CreditPolicy. Si vous continuez à dépenser les fonds de votre réserve sans la réapprovisionner, Stripe refusera les autorisations Issuing dès votre période de grâce écoulée, et vous recevrez l’événement issuing_ suivant :
{ "id": "iauth_123", "object": "issuing_authorization", "approved": false, // other fields... "status": "closed", "request_history": [ { "amount": 100, // minor units "approved": false, ..., "reason": "insufficient_reserve_balance", } ] }
Activer les notifications de plafond de dépenses pour votre plateforme
Vous pouvez utiliser vos paramètres pour activer l’envoi de notifications par e-mail afin de surveiller votre plafond de dépenses sur la plateforme. Ce plafond correspond à la limite totale des dépenses sur votre plateforme. Le plafond de dépenses de votre plateforme est représenté par l’attribut credit_limit_amount dans votre objet Platform CreditPolicy. Par défaut, l’envoi de cette notification par email est activé lorsque votre intégration est activée en mode production et que le seuil est fixé à 25 % de l’attribut credit_ dans votre objet Platform CreditPolicy. Vous recevez une alerte chaque fois que vos dépenses disponibles tombent en dessous du seuil fixé.
Pour mettre à jour ces notifications dans des environnements de production ou de test :
- Accédez à vos paramètres de notifications par e-mail.
- Sous Plafond de dépenses Issuing, choisissez parmi deux options d’alertes :
- Aucune notification Sélectionnez cette option pour désactiver les notifications par e-mail pour tous les destinataires.
- Seuil de dépenses Issuing Mettez à jour cette valeur en utilisant le champ de saisie. Par défaut, cette valeur est définie sur 25 %.
Le tableau suivant calcule les dépenses disponibles pour une plateforme lorsque le paramètre credit_ est fixé à 100 USD et que le seuil d’alerte du plafond de dépenses Issuing est fixé à 25 %. (Supposons que la plateforme ait un solde d’émission de -80 USD).
| Conditions d’utilisation | Mode de détermination | Exemple de plateforme |
| Seuil d’alerte des dépenses disponibles | Le credit_ définit le seuil d’alerte. | 100 * 0,25 = 25 USD |
| Dépenses actuelles disponibles | Le credit_ additionné au solde Issuing actuel (le solde Issuing est négatif pour les dépenses à crédit). | 100 - 80 = 20 USD |
| La plateforme reçoit une notification par e-mail | Lorsque les dépenses actuelles disponibles sont en dessous du seuil de dépenses disponibles. | La plateforme est notifiée |
Vous pouvez configurer les destinataires de ces alertes dans votre profil d’utilisateur en sélectionnant Plafond de dépenses Issuing sous Préférences d’e-mail.