Gérer les obligations des comptesVersion bêta privée

Suivez les dépenses à crédit, le cycle de vie et les soldes de vos comptes connectés.

Une fois la CreditPolicy activée, Stripe crée une FundingObligation vous permettant de suivre le montant que vous doit le compte pour une période de crédit. Une nouvelle FundingObligation est automatiquement créée à chaque début de période, déclenchant un événement issuing_funding_obligation.created.

La FundingObligation indique uniquement les transactions réglées et n’inclut pas les autorisations en attente. Pour établir la liste des autorisations en attente, reportez-vous à la section Répertorier toutes les autorisations.

Pour illustrer le processus de financement par votre plateforme d’un compte connecté disposant d’une CreditPolicy, imaginons que Barbell (l’un des comptes connectés de Gymbox) dispose d’un plafond de crédit de 1 000 USD, et dépense 100 USD pour financer un lot de poids. Le tableau ci-dessous illustre la séquence des événements sur Stripe :

Action	Solde Issuing de Barbell	FundingObligation de Barbell envers Gymbox	Solde Issuing de Gymbox
Au début, Barbell a un solde de 0 USD et aucun historique de dépenses. Gymbox dispose d’un solde de 100 USD.	0 USD	0 USD	100 USD
Un titulaire de carte effectue une transaction de 100 USD. Celle-ci est autorisée, car Gymbox dispose de fonds suffisants. Suite à cette autorisation, une retenue de fonds de 100 USD est effectuée sur le compte Issuing de Gymbox.	−100 USD	0 USD	0 USD
Lors du traitement de l’autorisation (généralement le lendemain), Stripe : Transfère 100 USD du compte Issuing de Gymbox vers le solde Issuing du compte connecté de Barbell et lève la retenue de fonds. Ajoute 100 USD à la FundingObligation de Barbell. Pour plus d’information, consultez la section consacrée au suivi des mouvements de fonds.	0 USD	100 USD	0 USD
À la fin de la période de crédit de Barbell, Barbell rembourse sa `FundingObligation` à Gymbox.	0 USD	0 USD	0 USD

Suivre le cycle de vie de la FundingObligation

Stripe crée une nouvelle FundingObligation sur le compte connecté à la fin de la période de crédit en cours. Par exemple, supposons que Barbell dispose d’une période de crédit d’un mois se terminant le 15 de chaque mois. Cela signifie que le 15 de chaque mois, Stripe :

Finalise le montant amount_total de la FundingObligation actuelle
Crée une FundingObligation pour la nouvelle période

État de la FundingObligation

Chaque FundingObligation change d’état en fonction de la période de crédit définie dans la CreditPolicy et de la politique de crédit ou de recouvrement écrite convenue avec Stripe et la banque.

Une FundingObligation peut revêtir l’un des états suivants :

En attente : la FundingObligation comptabilise toujours les dépenses de la période de crédit en cours, et le amount_total est susceptible d’évoluer.
Impayé : la valeur amount_total de la FundingObligation est finalisée, comme l’indique l’horodatage finalized_at. Le compte doit s’acquitter de cette obligation au plus tard à l’horodatage due_at.
Payé : la FundingObligation est entièrement remboursée par le compte connecté.
En retard : la FundingObligation n’est pas entièrement payée et l’horodatage due_at a expiré. Stripe peut signaler les FundingObligations en retard à ses partenaires bancaires.
Imputation : la FundingObligation a dépassé le nombre de jours avant l’imputation spécifié dans votre politique de crédit ou de recouvrement écrite. Lors de la configuration de votre programme, Stripe configure le nombre de jours avant l’imputation après avoir pris connaissance de cette valeur dans votre politique de crédit écrite. Vous pouvez continuer à collecter le remboursement du compte connecté après que la FundingObligation a atteint l’état d’imputation. Stripe peut signaler les FundingObligations en retard à ses partenaires bancaires. Contactez l’équipe de conformité de Stripe en soumettant une demande via le formulaire de demande de modification à :
- Modifier le nombre de jours avant l’imputation, comme indiqué dans votre politique
- Planifier la vente de votre dette ponctuelle
Remboursement requis : la FundingObligation présente un montant amount_total négatif, signifiant que la plateforme doit une somme au compte connecté. Cette situation se produit uniquement lorsque les sommes reçues par le compte connecté au titre de remboursements ou de litiges remportés dépassent le montant dépensé durant la période de crédit.

Le champ due_at de la FundingObligation est déterminé par les champs credit_period_ends_at de la FundingObligation et days_until_due de la CreditPolicy.

Récupérer des FundingObligations

Au fil du temps, un compte connecté aura plusieurs instances de FundingObligation payées (ou past_due), mais jamais plus d’une FundingObligation en attente. Pour récupérer la FundingObligation de la période en cours, exécutez la commande suivante :

Exemple de réponse

[
  {
    "id": "ifo_123",
    "livemode": true,
    "created": 1654628149,
    "amount_total": 10000,
    "amount_outstanding": 10000,
    "amount_paid": 0,
    "currency": "usd",
    "status": "unpaid",
    "due_at": 1654714851,
    "owed_to": "acct_123",
    "credit_period_starts_at": 1654625149,
    "credit_period_ends_at":1654713851,
    "paid_at": nil,
    "finalized_at": 1654713860,
  },
]

Pour récupérer des FundingObligations à un état particulier, transmettez la valeur d’état voulue lorsque vous demandez une liste de FundingObligations. Cet appel à l’API récupère les FundingObligations à l’état (status) past_due :

Obtenir des transactions pour une FundingObligation

Récupérez la liste des transactions associées à la FundingObligation d’un compte connecté en transmettant le paramètre funding_obligation_for_account dans la requête d’API Établir la liste de toutes les transactions :

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_789",
      "funding_obligation_for_account": "ifo_456",
      // various other fields
    },
    {...}
  ]
}

Récapitulatif des webhooks

Pour rappel, vous pouvez surveiller ces quatre webhooks :

issuing_credit_policy.created : se déclenche à la création d’une CreditPolicy, ce qui se produit lorsque la fonctionnalité est demandée pour le compte connecté.
issuing_credit_policy.updated : se déclenche à chaque modification d’une CreditPolicy, ce qui peut se produire lorsque la plateforme met à jour la politique du compte connecté.
issuing_funding_obligation.created : se déclenche chaque fois qu’une FundingObligation est créée, ce qui se produit au début de chaque nouvelle période de crédit pour le compte connecté.
issuing_funding_obligation.updated : se déclenche à chaque fois qu’une FundingObligation est mise à jour, ce qui se produit lorsque la FundingObligation change d’état ou de champs de montant, ou a été mise à jour pour refléter un remboursement.

Rembourser la FundingObligation d’un compte

Si le paramètre FundingObligation vous indique le montant dû par un compte connecté à la fin de la période de crédit, c’est à vous de débiter ce compte connecté pour encaisser votre remboursement. Utilisez l’API Payment Intents de Stripe pour débiter le compte bancaire externe du compte connecté (ou acceptez un paiement par carte bancaire via Stripe Checkout ou Stripe Invoicing).

Assurez-vous d’enregistrer tous les paiements reçus du compte connecté dans la FundingObligation du compte afin de refléter avec précision son crédit disponible. Stripe détermine si elle peut approuver une autorisation en fonction du crédit disponible d’un compte. Stripe est susceptible de signaler les FundingObligations en retard et facturées aux partenaires bancaires.

Encaisser le remboursement

Vous pouvez choisir le mécanisme d’encaissement du remboursement qui vous convient. Cependant, nous vous recommandons d’utiliser les API Payments de Stripe afin de conserver tous les enregistrements et de faciliter le rapprochement des dépenses par carte et des remboursements de chaque utilisateur. Une fois le paiement encaissé, pensez à modifier la FundingObligation en conséquence. En effet, si vous utilisez les API Payments de Stripe, cette étape n’est pas automatique. Stripe détermine la valeur past_due en fonction du paramètre days_until_due défini dans CreditPolicy. Stripe détermine la valeur charged_off en fonction de votre politique de crédit ou de recouvrement écrite, qui définit après combien de jours une obligation past_due passe à charged_off.

Enregistrer les remboursements dans la FundingObligation

Après avoir encaissé le paiement d’un compte connecté, mettez à jour sa FundingObligation pour refléter le remboursement. L’état des FundingObligations ( unpaid, past_due ou charged_off) a une incidence sur le montant que le compte connecté pourra dépenser. Supposons par exemple que Barbell dispose d’un plafond de crédit de 1 000 USD et achète un tapis roulant d’un montant de 900 USD. La FundingObligation de Barbell indiquera un montant amount_total dû de 900 USD. Il ne lui restera donc que 100 USD de crédit disponible tant que la somme due n’aura pas été remboursée, intégralement ou en partie.

Imaginons que Barbell rembourse 500 USD à Gymbox à la fin de la période de crédit. Gymbox doit modifier la FundingObligation de Barbell pour tenir compte de ce remboursement. Le montant amount_outstanding de la FundingObligation descend alors à 400 USD, tandis que le crédit disponible de Barbell passe de 100 à 600 USD.

Supposons que les conditions de crédit de Barbell indiquent une période de 90 jours après la due_at pour imputer le montant amount_outstanding de la FundingObligation. En cas de retard (past_due) de plus de 90 jours, l’encours (amount_outstanding) de 400 USD de Barbell est imputé. 30 jours après l’imputation du montant amount_oustanding de la FundingObligation, le marchand reçoit un paiement de 100 USD de Barbell. Gymbox doit enregistrer ce remboursement via l’endpoint /pay et déduire ce montant du amount_outstanding imputé de la FundingObligation. Le crédit disponible passe ainsi de 600 à 700 USD. Si Gymbox ferme la ligne de crédit de Barbell et signale le motif avant le recouvrement complet, le montant amount_outstanding imputé demeure et les montants recouvrés par la suite ne peuvent plus servir à diminuer le montant amount_outstanding.

Exemple de réponse

{
  "id": "ifo_123",
  "status": "unpaid",
  "amount_total": 90000,
  "amount_outstanding": 40000,
  "amount_paid": 50000,
  "owed_to": "acct_123",
  // other fields
}

Cet appel à l’API augmente le montant amount_paid et diminue le montant amount_outstanding de la FundingObligation. Lorsque amount_paid=amount_total sur une FundingObligation, Stripe fait passer l’état de l’obligation à paid, indépendamment de l’état précédent (unpaid, past_due, ou charged_off). Ces mises à jour déclenchent un événement issuing_funding_obligation.updated.

Nous vous recommandons d’automatiser le processus d’encaissement du remboursement et de mise à jour de la FundingObligation, et de les combiner en appels séquentiels. Ainsi, vous mettrez à jour la FundingObligation du compte connecté immédiatement après l’encaissement du remboursement pour demander à Stripe d’augmenter son crédit.

Mettre à jour le montant payé sur la FundingObligation

Si vous effectuez un remboursement par erreur ou souhaitez mettre à jour le montant payé amount_paid du compte connecté pour une autre raison, vous pouvez le faire via l’endpoint /pay en utilisant le champ amount_paid.

Exemple de réponse

{
  "id": "ifo_789",
  "status": "unpaid",
  "amount_total": 90000,
  "amount_outstanding": 45000,
  "amount_paid": 45000,
  "owed_to": "acct_123",
  // other fields
}

Un événement issuing_funding_obligation.updated est envoyé.

Mettre à jour les métadonnées sur FundingObligations

Vous pouvez mettre à jour les métadonnées d’une FundingObligation pour y associer des données supplémentaires. Par exemple, vous pouvez enregistrer l’ID du paiement sortant qui correspond à un remboursement.

Exemple de réponse

{
  "id": "ifo_789",
  "status": "unpaid",
  "amount_total": 90000,
  "metadata": {
    "repayment_id": "obp_1NUy3y2eZvKYlo2C15gktUET"
  },
  "owed_to": "acct_123",
  // other fields
}

Un événement issuing_funding_obligation.updated est envoyé.

Crédit disponible

Stripe ne propose actuellement pas de champ indiquant le solde créditeur disponible du compte connecté. Vous pouvez calculer ce montant à l’aide de la formule suivante :

crédit disponible = `credit_limit_amount` - somme(`FundingObligation.amount_outstanding`)¹

Les fonds qu’un compte connecté peut dépenser correspondent à son crédit disponible et son solde Issuing.

¹sum(FundingObligation.amount_outstanding) est un raccourci qui vous permet d’obtenir le montant amount_outstanding de toutes les FundingObligations du compte connecté.

Suivre les mouvements de fonds

Bien que cela ne soit pas indispensable pour permettre à vos comptes connectés d’accéder à un compte de crédit, il peut être judicieux de suivre l’état des autorisations, transactions et transferts créés lorsqu’un compte connecté utilise des fonds avancés par votre plateforme.

Imaginons la situation de départ suivante :

Compte	Solde Issuing
Compte Issuing de Gymbox (plateforme)	70 USD
Compte Issuing de Barbell (compte connecté)	0 USD

Autorisations

Barbell, dont la CreditPolicy présente un montant credit_limit_amount de 100 $ auprès de Gymbox, dépense 10 $. Une autorisation de 10 $ est générée sur le compte de Barbell :

{
  "id": "iauth_1JVXl82eZvKYlo2CPIiWlzrn",
  "object": "issuing.authorization",
  "amount": 1000,
  "currency": "usd",
  "approved": true,
  "authorization_method": "online",
  "balance_transactions": [
      {
        "id": "txn_1234XYZ",
        "object": "balance_transaction",
        "amount": -1000,
        "type": "issuing_authorization_hold",
        ...
      }
  ],
  "card": {...},
  ...
}

En parallèle, le solde de Gymbox fait l’objet d’une retenue de même montant. Cette retenue permet de réserver ces fonds, qui ne pourront ainsi pas être utilisés par d’autres comptes connectés de Gymbox :

{
  "id": "txn_1Mgr6fXpL7qsPGZtDwrMkq3S",
  "object": "balance_transaction",
  "amount": -1000,
  "available_on": 1677682692,
  "created": 1677682692,
  "currency": "usd",
  "description": "Platform hold for authorization (account: acct_1MgC5JRcH5icH3Nz, authorization: iauth_1Mgr6dRcH5icH3NzezZCHnJF)",
  "exchange_rate": null,
  "fee": 0,
  "fee_details": [],
  "net": -1000,
  "reporting_category": "issuing_authorization_hold",
  "source": {
    "id": "iph_1Mgr6eXpL7qsPGZtAMb7x0N6",
    "object": "issuing.platform_hold",
    "amount": 1000,
    "currency": "usd",
    "originating_account": "acct_1MgC5JRcH5icH3Nz",
    "originating_authorization": "iauth_1Mgr6dRcH5icH3NzezZCHnJF",
    "originating_balance_transaction": "txn_1Mgr6dRcH5icH3NzYGRkgcn7"
  },
  "status": "available",
  "type": "issuing_authorization_hold"
}

Le solde est désormais de :

Compte	Solde Issuing
Compte Issuing de Gymbox (plateforme)	60 USD
Compte Issuing de Barbell (compte connecté)	−10 USD

Captures de transactions et transferts

Avant la capture des autorisations Issuing et la création des transactions Issuing, les fonds sont transférés vers le compte connecté, puis la retenue dont la plateforme fait l’objet est levée.

Sur le compte de Barbell, l’autorisation a été modifiée puis clôturée, levant la retenue des fonds :

{
  "id": "iauth_1JVXl82eZvKYlo2CPIiWlzrn",
  "object": "issuing.authorization",
  "amount": 1000,
  "currency": "usd",
  "approved": true,
  "authorization_method": "online",
  "balance_transactions": [
      {
        "id": "txn_1234XYZ",
        "object": "balance_transaction",
        "amount": -1000,
        "type": "issuing_authorization_hold",
        ...
      },
      {
        "id": "txn_4t355646t54w2",
        "object": "balance_transaction",
        "amount": 1000,
        "type": "issuing_authorization_release",
      },
  ],
  "card": {...},
  "status": "closed",
  "transactions": [
      {
        "id": "ipi_1032HU2eZvKYlo2CEPtcnUvl",
        "object": "issuing.transaction",
        "amount": -1000,
        "authorization": "iauth_1JVXl82eZvKYlo2CPIiWlzrn",
        "balance_transaction": "txn_1345r1KCr4trgtrg0WfNdUCbG1w",
        ...
     }
  ...
}

La retenue de fonds opérée sur le compte de la plateforme est également levée :

{
  "id": "txn_1Mgr6fXpL7qsPGZtDwrPz7bA",
  "object": "balance_transaction",
  "amount": 1000,
  "available_on": 1677682692,
  "created": 1677682692,
  "currency": "usd",
  "description": "Released platform hold for authorization (account: acct_1MgC5JRcH5icH3Nz, authorization: iauth_1Mgr6dRcH5icH3NzezZCHnJF)",
  "exchange_rate": null,
  "fee": 0,
  "fee_details": [],
  "net": 1000,
  "reporting_category": "issuing_authorization_hold",
  "source": {
    "id": "iph_1Mgr6eXpL7qsPGZtAMb7m8Z3",
    "object": "issuing.platform_hold",
    "amount": -1000,
    "currency": "usd",
    "originating_account": "acct_1MgC5JRcH5icH3Nz",
    "originating_authorization": "iauth_1Mgr6dRcH5icH3NzezZCHnJF",
    "originating_balance_transaction": "txn_1Mgr6dRcH5icH3NzYGR7bA4c"
  },
  "status": "available",
  "type": "issuing_authorization_hold"
}

Stripe transfère les fonds de Gymbox vers le compte Issuing de Barbell. Un objet Transfer est créé :

{
  "id": "tr_3JeQsp2eZvKYlo2C13DagtB0",
  "object": "transfer",
  "amount": 1000,
  "amount_reversed": 0,
  "balance_transaction": "txn_1032HU2eZvKYlo2CEPtcnUvl",
  "created": 1646912059,
  "currency": "usd",
  "description": null,
  "destination": "acct_1032D82eZvKYlo2C",
  "livemode": true,
  "metadata": {},
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/transfers/tr_3JeQsp2eZvKYlo2C13DagtB0/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "issuing_transaction": "ipi_1032HU2eZvKYlo2CEPtcnUvl",
  "metadata": {},
  "source_balance": {
    "type": "issuing",
  },
  // New destination_balance returned field links to the BT on the connected account side
  "destination_balance": {
    "type": "issuing",
    "issuing": {
      "balance_transaction": "txn_123",
    },
  },
  // ... other fields ...
}

La retenue des fonds, la levée de cette retenue et le transfert sont effectués avant la création de la transaction Issuing correspondante par Stripe. Le solde est désormais de :

Le solde est désormais de :

Compte	Solde Issuing
Compte Issuing de Gymbox (plateforme)	60 USD
Compte Issuing de Barbell (compte connecté)	0 USD

Si la transaction n’a pas fait l’objet d’une autorisation initiale et si le compte connecté ne dispose pas de fonds suffisants, le transfert de solde de la plateforme et le flux de création de la transaction se produisent tout de même.

Remboursements

Lorsqu’un compte connecté reçoit un remboursement, Stripe tente de déterminer si la transaction correspondante avait été financée par le solde du compte connecté ou par le compte de la plateforme. Si le compte connecté a financé la transaction, le remboursement est versé au solde du compte connecté. Si le compte de la plateforme a financé la transaction (par exemple via la ligne de crédit du compte connecté), le montant du remboursement est déduit de la FundingObligation du compte connecté. Le remboursement est ensuite versé au compte de la plateforme, car celle-ci a déjà payé Stripe pour cette transaction au nom du compte connecté.

Supposons que la FundingObligation de Barbell est de 100 USD. Si le montant est remboursé, alors :

La FundingObligation de Barbell passe de 100 à 0 USD
Les 100 USD sont transférés vers le compte Issuing de Gymbox, ce qui augmente son solde de plateforme de 100 USD

Il est possible que le montant amount_total d’une FundingObligation soit négatif si la seule transaction d’une période de crédit est un remboursement et qu’il n’y a aucune dépense par carte. Dans ce cas, l’état de la FundingObligation est « Remboursement requis ». Une FundingObligation peut être négative lorsque le montant total des remboursements est supérieur au montant total des dépenses par carte.

Litiges

Lorsqu’un client conteste une transaction de dépense à crédit sur un compte connecté, la contestation suit le processus décrit dans la section Contestation des litiges. Les litiges perdus ne donnent lieu à aucune action (aucun crédit n’est émis en faveur du compte connecté). En cas de litige remporté, le compte connecté est crédité, tel que décrit dans la section sur les remboursements.

Refus d’autorisation

Les autorisations effectuées sur un compte connecté disposant d’une CreditPolicy peuvent être refusées pour les motifs suivants :

Le compte connecté tente d’effectuer une dépense supérieure à son plafond de crédit disponible. Dans ce cas, le compte connecté présente peut-être des FundingObligations impayées qui réduisent son crédit disponible. Pour éviter tout refus d’Authorization, veillez à ce que les FundingObligations de votre compte connecté soient toujours à jour.
Votre compte de plateforme Issuing n’a plus de fonds disponibles et le solde Issuing disponible de votre compte connecté est également de zéro. Pour éviter les refus d’autorisation, ajoutez suffisamment de fonds à votre compte Issuing.