Rattacher un marchand

Le plateforme ne peut pas attacher un marchand déjà inscrit par téléphone. Le Owner ou le Director de l'entreprise existante doit approuver dans l'application Kelyko. Tant que la demande n'est pas accepted, il n'y a pas de membre plateforme.

Si le téléphone n'existe pas encore, créez le compte avec l'onboarding.

Rattacher un marchand déjà inscrit

POST /partner_api/service_providers/business_link_requests

Requête :

{
  "phone": "+22507012345"
}

Réponse (201) : un tableau de demandes, une par entreprise dont cet utilisateur est Owner.

[
  {
    "id": "c1e15642-cdb5-404a-b028-26a51c94059b",
    "status": "pending",
    "merchantBusinessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "merchantBusinessName": "Magasin de Jean",
    "serviceProviderBusinessId": "a0b1c2d3-e4f5-6789-abcd-ef0123456789",
    "serviceProviderBusinessName": "Ma Marketplace",
    "ownerPhone": "+22507012345",
    "expiresAt": "2026-08-30T12:00:00.000Z",
    "createdAt": "2026-08-23T12:00:00.000Z",
    "serviceProviderMemberId": null,
    "redirectUrl": "https://destination.kelyko.invalid/a-configurer"
  }
]

redirectUrl ouvre cette demande dans l'application Kelyko. Envoyez le marchand vers cette URL (navigateur, QR code, ou redirection). L'application reconnaît aussi le schéma Kelyko://service_provider_link_requests/{id}. Le GET unitaire et la liste renvoient le même champ. Le webhook SERVICE_PROVIDER_LINK_REQUEST ne le contient pas.

Un POST répété pour la même paire (vous + ce marchand) renvoie la demande pending existante. Il n'y a pas de doublon.

`id` d'erreur	HTTP	Signification
`user_not_found`	404	Aucun utilisateur Kelyko pour ce téléphone. Utilisez l'onboarding
`no_owned_business`	409	L'utilisateur existe mais n'est Owner d'aucune entreprise. Un cashier ou un director d'une entreprise d'un tiers n'est pas ciblé
`already_linked`	409	Le rattachement existe déjà. Le champ `extras` contient le `merchantBusinessId` : vous pouvez créer des clés tout de suite

Suivre une demande

GET /partner_api/service_providers/business_link_requests/{linkRequestId}

Le corps est le même objet que dans le tableau du POST. status vaut pending, accepted, rejected ou expired. Les demandes expirent au bout de 7 jours.

GET /partner_api/service_providers/business_link_requests

La liste renvoie les demandes créées par votre plateforme, de la plus récente à la plus ancienne. Elle n'a pas de filtre. Un identifiant inconnu, ou une demande d'un autre plateforme, renvoie 404 sur le GET unitaire.

Quand status est accepted, serviceProviderMemberId est renseigné. Utilisez merchantBusinessId pour créer la clé API.

Si le marchand a déjà un webhook d'entreprise, Kelyko envoie aussi un POST signé (Kelyko-Signature). L'événement est l'en-tête Kelyko-Event: SERVICE_PROVIDER_LINK_REQUEST. Le corps n'est pas enveloppé :

{
  "id": "c1e15642-cdb5-404a-b028-26a51c94059b",
  "status": "pending",
  "merchantBusinessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "merchantBusinessName": "Magasin de Jean",
  "serviceProviderBusinessId": "a0b1c2d3-e4f5-6789-abcd-ef0123456789",
  "serviceProviderBusinessName": "Ma Marketplace",
  "ownerPhone": "+22507012345",
  "expiresAt": "2026-08-30T12:00:00.000Z",
  "createdAt": "2026-08-23T12:00:00.000Z",
  "serviceProviderMemberId": null
}

Ce n'est pas une transaction (amount et fees sont absents). L'en-tête Kelyko-Event vaut SERVICE_PROVIDER_LINK_REQUEST. Un abonnement qui liste uniquement TRANSACTION_COMPLETED ne le reçoit pas. Il part vers l'abonnement entreprise et vers le magasin dédié, pas vers les autres magasins du marchand. Voir Événements. Pour créer l'abonnement, voir Webhooks marchand.

Lister et détacher un rattachement

Les rattachements actifs (pas les demandes pending) se listent et se détachent côté plateforme.

GET /partner_api/service_providers/business_links

Réponse (200) : tableau des rattachements live. Un élément détaché n'apparaît plus.

[
  {
    "id": "29f81706-03a6-492f-92ee-5f0b2e9b18e7",
    "merchantBusinessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "merchantBusinessName": "Magasin de Jean",
    "serviceProviderBusinessId": "a0b1c2d3-e4f5-6789-abcd-ef0123456789",
    "serviceProviderBusinessName": "Ma Marketplace",
    "linkedAt": "2026-08-23T12:00:00.000Z"
  }
]

DELETE /partner_api/service_providers/business_links/{merchantBusinessId}

Réponse (200) : le rattachement qui vient d'être coupé.

Le détachement supprime logiquement le membre service_provider, les clés API que ce membre a créées, et le catalogue de frais assigné. Ces clés répondent ensuite 401. Les webhooks du marchand restent. Pour rattacher à nouveau, ouvrez une nouvelle demande : le marchand doit ré-approuver.

Le marchand peut aussi lister et détacher depuis l'API privée (GET / DELETE /businesses/{businessId}/service_provider_links).

`id` d'erreur	HTTP	Signification
`not_linked`	404	Aucun rattachement live entre vous et ce `merchantBusinessId`

Rattacher un marchand