Paiements Partagés pour Marketplace

Cette fonctionnalité permet aux commerçants de partager les paiements entre plusieurs destinataires, ce qui est particulièrement utile pour les modèles de marketplace où les transactions doivent être divisées entre différents vendeurs ou parties prenantes. Les marchands peuvent spécifier comment le paiement est partagé, y compris les montants, les destinataires et tous les frais applicables.

La fonctionnalité de paiement partagé dépend du support du fournisseur de paiement sélectionné. Yuno agit uniquement comme l'orchestrateur du paiement, pas le processeur. Assurez-vous que votre fournisseur prend en charge les paiements partagés avant d'utiliser cette fonctionnalité.

Fonctionnalités Clés

Les fonctionnalités clés des paiements partagés pour marketplace comprennent :

• Paiements partagés: Définir comment le montant total du paiement est distribué entre différents destinataires.
• Configuration flexible: Prend en charge les partages basés sur des montants absolus.
• Intégration avec les fournisseurs: Les partages peuvent être exécutés par des fournisseurs de paiement qui prennent en charge cette fonctionnalité.
• Gestion détaillée des frais: Le système permet un réglage précis de la manière dont les frais de transaction et les rejets de débit sont gérés.
• Transfert d'enregistrement: Permet le transfert des enregistrements entre différents destinataires.

Pour utiliser cette fonctionnalité, vous devez d'abord enregistrer vos destinataires pour le partage de paiement, puis créer le paiement en spécifiant les informations nécessaires.

1. Enregistrement

Le modèle d'enregistrement de Yuno est conçu pour aider les marketplaces à connecter et gérer de manière transparente leurs sous-marchands à travers plusieurs fournisseurs de paiement. Au cœur de ce système se trouve l'objet destinataire, qui représente chaque sous-marchand au sein de l'écosystème de la marketplace.

• Chaque propriétaire de marketplace est représenté dans Yuno comme une organisation.
• Au sein d'une organisation, un ou plusieurs comptes peuvent être créés, chacun configuré avec son propre ensemble de connexions à des fournisseurs de paiement (par exemple, Stripe, Adyen, dLocal).
• Pour chaque compte, la marketplace peut enregistrer un ou plusieurs destinataires - ce sont les sous-marchands à enregistrer.
• Chaque destinataire est ensuite lié individuellement à une ou plusieurs connexions, selon les processeurs de paiement qu'il utilisera.

Cette architecture permet :

• Un processus d'enregistrement unique et unifié.
• Un suivi de statut indépendant par fournisseur.
• Une mise à l'échelle facile des opérations des sous-marchands à travers les fournisseurs.

Cette conception assure flexibilité, transparence et traçabilité complète tout au long du cycle de vie de l'enregistrement. L'endpoint destinataires est utilisé pour créer et gérer chaque profil de sous-marchand et pour déclencher les flux d'enregistrement spécifiques au fournisseur correspondant.

Flux d'Enregistrement

Yuno propose deux flux d'enregistrement pour les sous-marchands, offrant une flexibilité basée sur le statut actuel du sous-marchand auprès des fournisseurs de paiement.

1. Comptes pré-enregistrés: Si un sous-marchand a déjà terminé le processus d'enregistrement auprès d'un fournisseur spécifique (par exemple, via un tableau de bord ou une plateforme externe), la marketplace peut fournir le recipient_id correspondant lors de la création. Dans ce scénario, aucun enregistrement supplémentaire n'est requis et le statut sera immédiatement défini sur SUCCEEDED (onboardings.type=PREVIOUSLY_ONBOARDED).

2. Enregistrement dynamique: Si aucune information d'identification n'est fournie, Yuno lancera le processus d'enregistrement pour le fournisseur choisi (onboardings.type=ONE_STEP_ONBOARDING ou TWO_STEP_ONBOARDING). Ce processus peut inclure :

   1. Soumission de formulaire ou redirection vers une page d'enregistrement hébergée.
   2. Téléchargement de documents juridiques ou financiers.
   3. Complétion des étapes de validation KYC/KYB.

Tout au long du cycle de vie de l'enregistrement, un destinataire peut connaître divers statuts qui reflètent l'état actuel du processus :

Ces statuts aident la marketplace à comprendre le cycle de vie de l'enregistrement et à mettre en œuvre des mécanismes appropriés de nouvelle tentative, d'alerte ou de repli si nécessaire.

Cette approche flexible permet aux marketplaces d'adapter le processus d'enregistrement à leurs besoins opérationnels, en conservant le contrôle et la visibilité.

Processus

Le flux d'enregistrement suit un processus structuré qui garantit que les sous-marchands sont correctement intégrés dans l'écosystème de la marketplace. Le diagramme ci-dessous illustre le flux complet, de la configuration initiale au traitement des paiements.

Étapes du flux :

1. Organisation et configuration des comptes: Le propriétaire de la place de marché crée une organisation dans Yuno et configure les comptes avec les connexions des fournisseurs de paiement.

2. Création du Destinataire: Pour chaque sous-marchand, la marketplace crée un destinataire à l'aide du l'endpoint API Create Recipients, en spécifiant soit :

   • provider_recipient_id pour les sous-marchands pré-enregistrés
   • Détails de connexion au fournisseur pour le nouvel enregistrement

3. Exécution de l'Enregistrement:

   • Pré-enregistré: Le statut devient immédiatement SUCCEEDED
   • Nouvel enregistrement: Yuno lance le flux spécifique au fournisseur avec une progression du statut de CREATED → PENDING → SUCCEEDED

4. Création de paiements: Une fois les destinataires enregistrés avec succès (statutSUCCEEDED ), la marketplace peut créer des paiements avec l'objet split_marketplace .

5. Traitement du Partage: Le fournisseur de paiement exécute le partage selon la distribution définie, transférant les fonds à la part désignée de chaque destinataire.

2. Intégration du Partage de Paiement

Dans cette section, nous explorons comment l'objet split_marketplace est utilisé pour diviser  payment  entre plusieurs destinataires. Cet objet est un tableau où chaque entrée spécifie un destinataire et sa part correspondante du paiement.

ℹ️

À cette étape, référencez les destinataires créés à l'Étape 1 (Enregistrement).

Pour type = PURCHASE ou MARKETPLACE, incluez le recipient_id de ce destinataire.

Pour PAYMENTFEE, VAT  et  COMMISSION, recipient_id est facultatif.

{
  "split_marketplace": [
    {
      "provider_recipient_id": "recipient_123",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

{
  "split_marketplace": [
    {
      "recipient_id": "4b31a9b8-4cd2-4e47-93cf-03729241bd68",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "recipient_id": "9104911d-5df9-429e-8488-ad41abea1a4b",
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

3. Transfert d'Enregistrement

L'objectif de ce flux est de permettre le transfert des enregistrements entre destinataires de manière contrôlée et réversible.

Le processus comporte plusieurs étapes. Premièrement, le destinataire initial est créé avec son enregistrement (une étape préalable). Plus tard, lorsqu'un transfert est requis, suivez les étapes pour créer le nouveau destinataire, utiliser le service de transfert et, si nécessaire, inverser l'opération.

1. Destinataire et enregistrement (avant tout transfert): Créez le destinataire, puis créez l'enregistrement.

📘

Cette étape se produit à l'avance lorsqu'un nouveau destinataire est créé et que son enregistrement est attribué. Cela ne fait pas partie du transfert lui-même.

Si vous décidez de transférer l'enregistrement à un autre destinataire, continuez le flux :

2. Créer le nouveau destinataire et l'enregistrement: Utilisez les endpoints " créer un destinataire " et " créer un enregistrement" pour configurer le destinataire et l'enregistrement qui recevront le transfert.

3. Transférer l'enregistrement: Utilisez le transfert d'enregistrement et incluez:

   • recipient_idl'ID du destinataire cible
   • onboarding_idl'enregistrement à transférer

   L'enregistrement sera transféré au nouveau destinataire.

4. Inverser le transfert (facultatif): Utilisez  Inverser le transfert pour annuler le transfert précédent, en fournissant le même recipient_id  et  onboarding_id.

Le champ onboarding comprend un élément history qui stocke la traçabilité complète de l'enregistrement. Cet historique inclut non seulement les mises à jour de l'objet, mais aussi les événements liés aux transferts entre destinataires, assurant une visibilité complète du cycle de vie.

Validations

Dans cette section, nous décrivons les validations nécessaires pour assurer le succès des paiements partagés.

• Le total de tous les partages doit correspondre au montant total du paiement.
• Pour chaque partage, un objet doit être envoyé pour chaque participant, garantissant que la somme des montants est égale au montant total du paiement.
• Dans les scénarios où un ID de destinataire direct n'est pas nécessaire pour le propriétaire de la marketplace (par exemple, avec Adyen), le champ type peut servir de drapeau (par exemple, COMMISSION) pour désigner la part du propriétaire de la marketplace, rendant le provider_recipient_id facultatif pour ce partage spécifique.
• Soit recipient_id ou provider_recipient_id doit être inclus pour le partage, mais pas les deux.
• S'il manque des champs obligatoires ou s'ils sont invalides, la requête entraînera une erreur.
• Si vous utilisez plusieurs fournisseurs de paiement pour les paiements partagés, nous vous recommandons d'utiliser l'objet destinataires, car il permet de définir plus d'un fournisseur pour chaque destinataire.

endpoint API Impliqués

Cette section répertorie les endpoints API impliqués dans la gestion des paiements partagés.

• Créer des destinataires: POST: https://api-sandbox.y.uno/v1/recipients
• Créer un enregistrement: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings
• Continuer l'enregistrement: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/continue
• Créer un paiement: POST: https://api-sandbox.y.uno/v1/payments
• Autorisation de capture: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/capture
• Rembourser un paiement: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/refund
• Annuler ou rembourser un paiement: POST: https://api-sandbox.y.uno/v1/payments/{id}/cancel-or-refund
• Annuler ou rembourser un paiement avec transaction: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/cancel-or-refund
• Transférer l'enregistrement: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/transfer
• Inverser le transfert d'enregistrement: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/reverse-transfer