# Gestion des commerçants (/fr/platform-api/merchant_management) Gérez les commerçants de votre organisation depuis votre backend. Chaque appel utilise votre Server Secret Token : conservez-le donc sur votre serveur. | Détail | Valeur | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | | URL de base | `https://api.sandbox.tapaya.com` pour la sandbox, `https://api.tapaya.com` pour la production | | Authentification | Server Secret Token dans `Authorization`. Consultez [Authentification](/platform-api#authentication). | | Montants | Unités monétaires mineures : `2500` avec `EUR` correspond à 25,00 EUR. Frais relatifs en points de base : `100` correspond à 1 %. | | Guide associé | [Onboarding des commerçants](/platform-api/merchant_onboarding) | ## Toutes les opérations [#all-operations] | Opération | À utiliser pour | | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [Lire un onboarding enregistré](#read-a-saved-onboarding) | Reprendre le formulaire d’onboarding d’un commerçant là où il s’est arrêté. | | [Enregistrer les canaux sélectionnés](#save-channel-selections) | Stocker les canaux de paiement choisis par un commerçant, sans soumettre la demande. | | [Lister les membres](#list-members) | Voir qui a déjà accès à un commerçant. | | [Lister les terminaux](#list-terminals) | Afficher les terminaux d’un commerçant et leurs appareils. | | [Lister les invitations par e-mail](#list-email-invites) | Suivre les invitations à usage unique envoyées à des destinataires connus. | | [Lister les liens réutilisables](#list-reusable-links) | Suivre les liens de campagne et savoir s’ils sont suspendus. | | [Créer un lien réutilisable](#create-a-reusable-link) | Lancer une campagne par laquelle de nombreux commerçants peuvent s’inscrire. | | [Modifier l’expiration d’une invitation](#change-an-invites-expiry) | Prolonger ou raccourcir une invitation, même expirée. | | [Suspendre ou réactiver un lien réutilisable](#pause-or-resume-a-reusable-link) | Bloquer temporairement les nouvelles inscriptions sans révoquer le lien. | | [Lister les ensembles tarifaires](#list-pricing-sets) | Trouver les ensembles tarifaires à partir desquels votre organisation peut créer des profils. | | [Lister les profils de commission](#list-commission-profiles) | Choisir un profil à attribuer à une invitation. | | [Créer un profil de commission](#create-a-commission-profile) | Proposer aux commerçants une liste tarifaire créée à partir d’un ensemble tarifaire. | | [Mettre à jour un profil de commission](#update-a-commission-profile) | Renommer un profil ou modifier ses tarifs. | | [Supprimer un profil de commission](#delete-a-commission-profile) | Supprimer un profil que vous ne proposez plus. | | [Définir le profil par défaut](#set-the-default-profile) | Choisir le profil utilisé par les invitations qui n’en désignent aucun. | | [Lire les tarifs du commerçant](#read-merchant-pricing) | Afficher les tarifs souscrits par un commerçant. | ## Brouillons d’onboarding [#onboarding-drafts] **À utiliser pour** reprendre le formulaire d’onboarding d’un commerçant avec tout ce qu’il a enregistré jusqu’à présent. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * C’est le seul appel qui renvoie l’intégralité de l’onboarding enregistré ; les appels de profil et de processeur n’en renvoient que des parties. * `pricingConstraints` liste ce que le commerçant peut choisir, et non des barèmes de frais. **Réponse :** | Champ | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | `identity` | Les informations d’identité du commerçant. | | `address` | L’adresse du commerçant. | | `business` | Les informations commerciales communes aux deux canaux. | | `kyb` | Comptes bancaires, compte principal, parties prenantes de la société ou personne physique, et leurs documents. | | `capability` | La fonctionnalité sélectionnée. | | `terminal` | Les détails enregistrés du canal en magasin. | | `online` | Les détails enregistrés du canal en ligne. | | `processors` | Le statut auprès de chaque processeur de paiement. | | `commissionProfileIds` | Les profils de commission attribués au commerçant. | | `pricingConstraints` | Les devises de règlement et MCC autorisés. | **À utiliser pour** stocker les canaux de paiement qu’un commerçant a choisis dans votre formulaire avant de terminer l’onboarding. ```bash curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/channel' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "capability": 2, "terminal": { "mcc": "5411", "statementDescriptor": "ACME STORE", "productDescription": "Groceries", "averageItemValue": 2500, "expectedMonthlyTurnover": 500000, "numberOfTerminals": 1 } }' ``` **Bon à savoir :** * Fonctionne uniquement pour un commerçant dont le brouillon d’onboarding et le profil sont déjà enregistrés. * Met à jour le brouillon et renvoie `200`. Cette opération ne soumet pas l’onboarding et n’enregistre pas de compte processeur. * Envoyez uniquement les sections des canaux sélectionnés par le commerçant. **Paramètres :** | Champ | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `capability` | Les canaux sélectionnés. Mêmes valeurs que dans [Onboarding des commerçants](/platform-api/merchant_onboarding#request-online-payment-capabilities). | | `terminal` | Les détails du canal en magasin, avec les mêmes champs que dans l’onboarding des commerçants. | | `online` | Les détails du canal en ligne, avec les mêmes champs que dans l’onboarding des commerçants. | ## Membres et terminaux [#members-and-terminals] **À utiliser pour** voir qui a déjà accès à un commerçant. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Renvoie un tableau des membres actuels. * Les invitations en attente ne sont pas incluses ; elles sont listées séparément. **Réponse :** pour chaque membre : | Champ | Description | | ----------- | -------------------------------------------------- | | `userId` | L’identifiant utilisateur du membre. | | `firstName` | Prénom. | | `lastName` | Nom. | | `email` | Adresse e-mail. | | `joinedAt` | Date à laquelle le membre a rejoint le commerçant. | **À utiliser pour** afficher les terminaux d’un commerçant et les appareils qui leur sont attribués. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Renvoie des terminaux, et non des points de vente actifs ; les points de vente ont leur propre liste. * La réponse contient `items` et `totalCount`. Chaque élément contient les identifiants du terminal et du point de vente, un libellé et les détails de l’appareil. * `terminalType` et `deviceIdentifier` décrivent l’appareil attribué actuellement, et non l’appareil qui a accepté un paiement antérieur. **Paramètres :** | Champ | Description | | --------------- | ---------------- | | `page` | Numéro de page. | | `pageSize` | Lignes par page. | | `sortBy` | Champ de tri. | | `sortDirection` | Sens du tri. | ## Invitations à l’inscription [#registration-invites] Utilisez une [invitation par e-mail](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding) pour un destinataire connu, ou un lien réutilisable pour une campagne. Les deux permettent de restreindre les canaux et d’attribuer des profils de commission. **À utiliser pour** suivre les invitations à usage unique que vous avez envoyées. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Chaque invitation indique l’e-mail du destinataire, l’URL, `capability` et `commissionProfileIds`. * Les invitations contiennent aussi `commissionProfileId`, la forme à profil unique de `commissionProfileIds`. **À utiliser pour** suivre vos liens de campagne et voir lesquels sont suspendus. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Chaque lien indique sa `capability`, les profils attribués et `pausedAt`. * `pausedAt` vaut `null` tant que le lien n’est pas suspendu. * Un lien suspendu qui n’a pas expiré et n’a pas été révoqué correspond toujours à `isActive=true`. Vérifiez `pausedAt` pour les distinguer. **À utiliser pour** lancer une campagne par laquelle de nombreux commerçants peuvent s’inscrire. ```bash curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "name": "Partner onboarding", "expiresAt": "2030-12-31T00:00:00Z", "capability": 2 }' ``` **Bon à savoir :** * `capability` limite les canaux que les commerçants peuvent choisir. Elle n’accorde pas l’approbation du processeur. * Omettez les champs de profil pour attribuer le profil par défaut de l’organisation. * `commissionProfileId` est toujours accepté pour un profil unique. Utilisez plutôt `commissionProfileIds`, et n’envoyez jamais les deux. **Paramètres :** | Champ | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Un nom pour la campagne. | | `expiresAt` | Horodatage ISO 8601 UTC, au moins un jour dans le futur. Il n’y a pas de maximum. | | `capability` | Facultatif. Mêmes valeurs que pour les [invitations par e-mail](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). | | `commissionProfileIds` | Facultatif. Mêmes règles que pour les invitations par e-mail. | **À utiliser pour** prolonger ou raccourcir une invitation, y compris une invitation déjà expirée. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/expires-at' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{"expiresAt": "2031-01-31T00:00:00Z"}' ``` **Bon à savoir :** * Pour une invitation par e-mail, appelez `PUT /integrator/merchant/invites/{inviteId}/expires-at` avec le même corps. * Renvoie `204`. * Les invitations révoquées et les invitations par e-mail déjà utilisées ne peuvent pas être prolongées. **Paramètres :** | Champ | Description | | ----------- | --------------------------------------------------------------------------------- | | `expiresAt` | Horodatage ISO 8601 UTC, au moins un jour dans le futur. Il n’y a pas de maximum. | **À utiliser pour** bloquer temporairement les nouvelles inscriptions sans révoquer le lien. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/pause' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Appelez `.../resume` sur le même lien pour accepter de nouveau les inscriptions. La réactivation ne prolonge pas l’expiration. * Les deux renvoient `204` et sont idempotents. * L’ouverture d’un lien suspendu renvoie `410`. ## Profils de commission [#commission-profiles] Un profil de commission est la liste tarifaire que vous proposez aux commerçants. Créez-le à partir d’un ensemble tarifaire pour lequel votre organisation est autorisée. **À utiliser pour** trouver les ensembles tarifaires à partir desquels vous pouvez créer des profils de commission. ```bash curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Chaque ensemble inclut ses barèmes contractuels pour le commerçant et l’intégrateur. * Utilisez un `pricingSetId` renvoyé lorsque vous créez un profil. **Paramètres :** | Champ | Description | | ------------- | ---------------------------------- | | `pricingType` | Facultatif. `online` ou `instore`. | **À utiliser pour** choisir un profil à attribuer à une invitation. ```bash curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Renvoie uniquement les profils activés et complets de votre organisation. * Chaque profil couvre un seul type de tarification. * Conservez la `revision` de chaque profil si vous prévoyez de le mettre à jour. **Paramètres :** | Champ | Description | | ------------- | ---------------------------------- | | `pricingType` | Facultatif. `online` ou `instore`. | **À utiliser pour** proposer aux commerçants une liste tarifaire créée à partir d’un ensemble tarifaire. ```bash curl -X POST 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "name": "Standard profile", "pricingModel": 1, "cardTypes": [ {"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0} ], "pricings": [ {"currency": "eur", "pricingSetId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a"} ] }' ``` **Bon à savoir :** * Un profil couvre un seul type de tarification, issu de ses ensembles tarifaires. * Les coûts de l’intégrateur et les parts de marge proviennent de l’ensemble tarifaire ; vous ne définissez que les tarifs du commerçant. * `region` vaut `1` national ou `2` international, `holderType` vaut `1` particulier ou `2` société, et `scheme` vaut `1` Visa ou `2` Mastercard. **Paramètres :** | Champ | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | Le nom du profil. | | `pricingModel` | `1` pour MDR ou `2` pour IC++. | | `cardTypes` | Chaque combinaison de région, de type de titulaire de carte et de réseau acceptée par le profil, avec ses frais d’apport. | | `pricings` | La devise et le `pricingSetId` pour chaque devise que vous proposez. | | `merchantPricingOverrides` | Facultatif. Entrées avec `holderCategory`, `regionSegment`, `relative` et `absolute`. Les combinaisons omises conservent les tarifs de l’ensemble tarifaire. | **À utiliser pour** renommer un profil ou modifier ses tarifs. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "name": "Standard profile 2027", "pricingModel": 1, "cardTypes": [ {"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0} ], "expectedRevision": 3 }' ``` **Bon à savoir :** * Transmettez la dernière `revision` lue comme `expectedRevision`. Une révision obsolète renvoie `409`. * Omettez `pricings` pour conserver les tarifs enregistrés. * Un profil attribué à des commerçants, ou non modifiable, n’accepte qu’un nouveau nom. **Paramètres :** | Champ | Description | | ------------------ | ---------------------------------------------------- | | `name` | Obligatoire. Le nom du profil. | | `pricingModel` | Obligatoire. `1` pour MDR ou `2` pour IC++. | | `cardTypes` | Obligatoire. Identique à la création. | | `pricings` | Facultatif. Identique à la création. | | `expectedRevision` | La `revision` du profil au moment où vous l’avez lu. | **À utiliser pour** supprimer un profil que vous ne proposez plus. ```bash curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Le profil par défaut ne peut pas être supprimé. Définissez d’abord un autre profil comme profil par défaut. * Un profil attribué à des commerçants ne peut pas être supprimé. Les deux cas renvoient `400`. **À utiliser pour** choisir le profil utilisé par les invitations qui n’en désignent aucun. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Votre organisation a un seul profil par défaut. * Le profil par défaut ne peut pas être supprimé. ## Tarifs du commerçant [#merchant-pricing] **À utiliser pour** afficher les tarifs souscrits par un commerçant, pour les paiements en magasin et en ligne. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \ -H 'Authorization: REPLACE_ME' ``` **Bon à savoir :** * Un canal sans tarifs enregistrés vaut `null`. Un commerçant sans aucune liste tarifaire enregistrée renvoie `404`. * Renvoie les tarifs contractuels, et non les barèmes de base du prestataire de paiement. Lisez les tarifs dans `cells` ; les composants `commission` ne sont pas des commissions réalisées. * Un modèle ou un coût intégrateur inconnu vaut `null`, et non zéro. * Les parts de marge répartissent la marge distribuable, et non le montant total du paiement. **Réponse :** | Champ | Description | | ------------------------------------- | ------------------------------------------------------------------------- | | `instore` | Les tarifs en magasin, ou `null`. | | `online` | Les tarifs en ligne, ou `null`. | | `currency` | La devise de tarification. | | `pricingModel` | Le modèle tarifaire du commerçant. | | `integratorPricingModel` | Le modèle tarifaire de l’intégrateur, indépendant de celui du commerçant. | | `priceListId` | La liste tarifaire enregistrée du commerçant, si disponible. | | `pricingSetVersionId` | La version de l’ensemble tarifaire source, si disponible. | | `pricingSetName` | Le nom de l’ensemble tarifaire source, si disponible. | | `cells` | Les tarifs par catégorie de titulaire de carte et région. | | `cells[].discountBps` | Tarif relatif final du commerçant en points de base. | | `cells[].transactionFeeMinor` | Frais fixes finaux du commerçant en unités monétaires mineures. | | `cells[].integratorCostRelativeBps` | Coût relatif contractuel de l’intégrateur en points de base. | | `cells[].integratorCostAbsoluteMinor` | Coût fixe contractuel de l’intégrateur en unités monétaires mineures. | | `cells[].revenueShareTapayaBps` | Part de Tapaya dans la marge distribuable en points de base. | | `cells[].revenueShareIntegratorBps` | Votre part de la marge distribuable en points de base. | ## Erreurs [#errors] Chaque opération renvoie ces codes de statut lorsqu’une requête échoue. | Code | Description | | ----- | --------------------------------------------------------------------------------------------------------------------------- | | `400` | Données de canal, sélection de profils, filtres ou expiration invalides, ou suppression d’un profil par défaut ou attribué. | | `401` | Le Server Secret Token est absent ou invalide. | | `404` | La ressource n’est pas accessible à votre organisation, ou l’onboarding ou les tarifs enregistrés n’existent pas. | | `409` | Révision de profil obsolète, état d’onboarding conflictuel, ou invitation utilisée ou révoquée. |