Créer des paiements et des transferts distincts

Utilisez des paiements et transferts distincts pour les comptes Express ou Custom lorsque vous percevez des paiements dont le montant peut être différent de celui versé à vos comptes connectés. La plateforme est tenue de payer les frais Stripe, les remboursements et les contestations de paiement. Pour en savoir plus sur les différents types de paiements Connect, consultez la documentation sur le choix d’une approche.

Stripe prend en charge des paiements et transferts distincts dans les régions suivantes :

• Australie
• Brésil
• Canada
• Europe
• Japon
• Malaisie
• Nouvelle-Zélande
• Singapour
• États-Unis

Pour associer un paiement à un transfert, créez d’abord une chaîne unique à utiliser comme identifiant de groupe. Lorsque vous créez un PaymentIntent, un paiement ou un transfert, affectez cette chaîne à son attribut transfer_group. Utilisez le paramètre transfer_group pour identifier les objets associés les uns aux autres.

Lorsque Stripe crée automatiquement un paiement pour un PaymentIntent avec une valeur transfer_group, la même valeur est affectée au transfer_group du paiement.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d amount=10000 \
  -d currency=usd \
  -d transfer_group=ORDER10

curl https://api.stripe.com/v1/transfers \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d amount=7000 \
  -d currency=usd \
  -d destination={{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -d transfer_group=ORDER10

curl https://api.stripe.com/v1/transfers \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d amount=2000 \
  -d currency=usd \
  -d destination={{OTHER_CONNECTED_STRIPE_ACCOUNT_ID}} \
  -d transfer_group=ORDER10

Pour le flux complet, voir Accepter un paiement.

Options de transfert

Vous pouvez attribuer n’importe quelle valeur à la chaîne transfer_group, mais elle doit représenter une seule action commerciale. Vous pouvez également effectuer un transfert sans paiement associé ou sans transfer_group, par exemple, lorsque vous devez payer un fournisseur, mais qu’il n’y a pas de paiement client associé.

Les montants des transferts et des paiements ne doivent pas nécessairement correspondre. Vous pouvez fractionner un paiement en plusieurs transferts ou inclure plusieurs paiements dans un même transfert. Vous pouvez effectuer des transferts et des paiements dans n’importe quel ordre.

Par défaut, une demande de transfert échoue lorsque le montant dépasse le solde de compte disponible de la plateforme. Vous pouvez néanmoins valider le montant du transfert en le comparant au paiement associé en spécifiant ce paiement comme source_transaction du transfert. Dans ce cas, la demande de transfert aboutit automatiquement, mais n’est exécutée que lorsque les fonds de ce paiement sont disponibles sur le compte de la plateforme.

Perception de frais

Lorsque vous créez des paiements et transferts distincts, la plateforme peut encaisser des frais en réduisant le montant transféré sur le compte de destination. Par exemple, imaginons une transaction de service de livraison, avec un paiement adressé au restaurant et un autre au livreur :

1. Le client paie 100 USD.
2. Stripe prélève des frais de 3,20 USD et ajoute les 96,80 USD restants au solde en attente du compte de la plateforme.
3. La plateforme transfère 70 USD vers le compte connecté du restaurant et 20 USD vers le compte connecté du chauffeur.
4. Des frais de plateforme de 6,80 USD restent sur le compte de la plateforme.

Pour en savoir plus sur le traitement des paiements dans plusieurs devises avec Connect, consultez Gérer plusieurs devises.

Remboursement des paiements

Les paiements créés sur votre plateforme peuvent être remboursés à l’aide de la clé secrète de votre plateforme. Cependant, le remboursement d’un paiement n’a aucun impact sur les transferts associés. Il incombe à votre plateforme de rapprocher tout montant qui lui est dû en réduisant le montant des transferts ultérieurs ou en annulant les transferts (comme expliqué ci-après).

curl https://api.stripe.com/v1/refunds \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d charge=
{{CHARGE_ID}}

Annulation des transferts

Connect prend en charge la possibilité d’annuler les transferts effectués sur les comptes connectés, totalement ou en partie (en définissant la valeur du montant pour le paramètre amount) :

curl https://api.stripe.com/v1/transfers/
{{TRANSFER_ID}}
/reversals \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d amount=500

Les annulations de transferts rajoutent le montant spécifié (ou l’intégralité du montant) au solde disponible de la plateforme, réduisant ainsi le solde disponible du compte connecté. Il n’est possible d’annuler un transfert que si le solde disponible du compte connecté est supérieur au montant de l’annulation ou si les réserves connectées sont activées.

Si l’annulation du transfert nécessite une conversion de devise et que le montant de l’annulation entraîne un solde nul après la conversion, une erreur est renvoyée.

Utilisation du paramètre on_behalf_of

Si vous le souhaitez, vous pouvez définir le paramètre on_behalf_of sur l’ID d’un compte connecté pour faire de ce compte l’entreprise de référence pour le paiement. Lorsque vous utilisez on_behalf_of :

• Les paiements sont réglés dans le pays du compte connecté et dans la devise de règlement.
• La structure des frais appliquée est celle du pays du compte connecté.
• Le libellé de relevé bancaire du compte connecté apparaît sur le relevé de carte bancaire du client.
• Si le compte connecté relève d’un autre pays que celui de la plateforme, l’adresse et le numéro de téléphone du compte connecté sont affichés sur le relevé de carte bancaire du client.
• Le nombre de jours durant lesquels un solde en attente est bloqué avant d’être versé dépend du paramètre delay_days du compte connecté.

Si le paramètre on_behalf_of est ignoré, la plateforme est l’entreprise de référence pour le paiement.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d amount=1000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d on_behalf_of=
{{CONNECTED_ACCOUNT_ID}}

Dans la dernière version de l’API, la spécification du paramètre automatic_payment_methods est facultative, car Stripe active sa fonctionnalité par défaut.

Disponibilité des transferts

Le comportement par défaut consiste à transférer les fonds à partir du solde disponible du compte de la plateforme. Toute tentative de transfert dont le montant dépasse le solde disponible échoue et entraîne une erreur. Pour éviter ce problème, lorsque vous créez un transfert, associez-le à un paiement existant en spécifiant l’ID du paiement comme paramètre source_transaction. En utilisant le paramètre source_transaction, la demande de transfert aboutit, quel que soit votre solde disponible. Cependant, les fonds ne deviennent disponibles sur le compte de destination que lorsque les fonds du paiement associé peuvent être transférés depuis le compte de la plateforme.

Si le paiement source a une valeur transfer_group, Stripe affecte la même valeur au transfer_group du transfert. Si ce n’est pas le cas, Stripe génère une chaîne au format group_ plus l’ID du PaymentIntent associé (par exemple : group_pi_2NHDDD589O8KAxCG0179Du2s), puis affecte cette chaîne en tant que transfer_group pour le paiement et le transfert.

curl https://api.stripe.com/v1/transfers \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d amount=1000 \
  -d currency=usd \
  -d source_transaction=
{{CHARGE_ID}} \
  -d destination=
{{CONNECTED_ACCOUNT_ID}}

Vous pouvez obtenir l’ID du paiement à partir du PaymentIntent :

• Obtenez l’attribut latest_charge du PaymentIntent. Cet attribut est l’ID du paiement le plus récent associé au PaymentIntent.
• Créez une requête de liste des paiements, en spécifiant le payment_intent dans la requête. Cette méthode renvoie l’intégralité des données de tous les paiements associés au PaymentIntent.

Pour utiliser ce paramètre :

• Le montant du transfert ne doit pas dépasser celui du paiement source
• Vous pouvez créer plusieurs transferts avec la même source_transaction, tant que la somme des transferts ne dépasse pas le montant du paiement source
• Le transfert prend l’état en attente du paiement associé : si les fonds du paiement deviennent disponibles dans X jours, le règlement que reçoit le compte de destination Stripe pour le transfert devient également disponible dans X jours
• Stripe crée automatiquement le transfer_group pour vous
• La devise de l’opération sur solde associée au paiement doit correspondre à celle du transfert

Les moyens de paiement asynchrones, comme ACH, peuvent échouer après toute demande de transfert ultérieure. Pour ces paiements, évitez d’utiliser source_transaction. Attendez plutôt qu’un événement charge.succeeded soit déclenché avant de transférer les fonds. Si vous devez utiliser source_transaction avec ces paiements, activez une fonctionnalité permettant de gérer les échecs de paiement.

Lorsqu’un paiement utilisé comme source_transaction échoue, des fonds provenant du solde de compte de votre plateforme sont transférés vers le compte connecté pour couvrir le paiement. Pour récupérer ces fonds, annulez le transfert associé à l’échec de la source_transaction.