Intégration d'un nouveau marchand

Audience

Cette surface API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt intégrant des placements sur leur propre page de paiement devraient utiliser les documents développeur Rokt Ecommerce à la place.

Cette recette suit le chemin canonique : d'un marchand tout neuf sur votre plateforme à un compte Rokt actif générant des revenus. Chaque étape est appelable depuis votre backend avec un jeton porteur API, l'en-tête X-Platform-Parent-Account-Id, et une clé d'idempotence.

info

Prérequis : vous avez lu Vue d'ensemble, Authentification, et Démarrage rapide. Vous avez un jeton API valide et votre platform_parent_account_id. Chaque exemple suppose que $PARENT contient cette valeur.

Vous avez également besoin que votre taxonomie de catégorie soit intégrée à votre compte parent. C'est une étape de configuration de plateforme unique effectuée par Rokt, et non quelque chose que vous faites pour chaque marchand ; l'étape 1 ci-dessous le confirme. Voir Taxonomie verticale.

1
Confirm the merchant's category is mapped
L'enregistrement résout la paire {vertical_id, sub_vertical_id} du marchand à travers le mappage intégré pour votre compte parent, et rejette avec 400 si la paire est manquante. Vérifiez qu'elle est dans l'ensemble d'abord.
curl "https://accounts.rokt.com/v1/partnership/vertical-mappings?parent_account_id=$PARENT" \ -H "Authorization: Bearer $TOKEN"
La forme de la réponse est dans Vérifiez ce qui est mappé. L'ensemble change rarement, donc mettez-le en cache plutôt que de l'appeler pour chaque marchand. Deux cas, traités différemment :
- Tableau vide : rien n'est intégré, donc aucun marchand ne s'enregistrera. Envoyez par email votre liste complète de catégories à smb-partnerships@rokt.com et attendez la confirmation.
- Paire absente d'un ensemble non vide : une ligne manque. Envoyez la paire et vos noms de catégories par email, puis suspendez ce marchand. Ne substituez pas une catégorie mappée non liée pour le faire passer ; le marchand serait en dehors des contrôles de sécurité de marque de votre réseau.

POST /v1/accounts/register/partnership avec la marque du marchand, les IDs de taxonomie partenaire, le pays, l'URL du magasin, et votre external_account_id stable. Capturez le account_id retourné depuis data.account_id; chaque appel ultérieur s'appuie dessus.

Passez le tableau optionnel pages pour déclarer sur quelles surfaces ce marchand affichera des placements. Chaque entrée mappe une surface orientée partenaire (confirmation, tracking, returns) à un style de mise en page (Overlay ou Embedded). Voir Pages et mises en page pour le vocabulaire complet des surfaces.

curl
python

curl -X POST https://accounts.rokt.com/v1/accounts/register/partnership \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Acme Apparel",
    "vertical_id": 1500,
    "sub_vertical_id": 1610,
    "country_code": "US",
    "platform_parent_account_id": "<your-platform-parent-account-id>",
    "store_identifier": "https://acme-apparel.example.com",
    "external_account_id": "partner-merchant-abc123",
    "pages": [
      { "surface": "confirmation", "layout_type": "Overlay"  },
      { "surface": "tracking",     "layout_type": "Embedded" }
    ]
  }'

import requests

r = requests.post(
    "https://accounts.rokt.com/v1/accounts/register/partnership",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Platform-Parent-Account-Id": parent_account_id,
    },
    json={
        "brand": "Acme Apparel",
        "vertical_id": 1500,
        "sub_vertical_id": 1610,
        "country_code": "US",
        "platform_parent_account_id": "<your-platform-parent-account-id>",
        "store_identifier": "https://acme-apparel.example.com",
        "external_account_id": "partner-merchant-abc123",
        "pages": [
            {"surface": "confirmation", "layout_type": "Overlay"},
            {"surface": "tracking",     "layout_type": "Embedded"},
        ],
    },
)
body = r.json()["data"]
account_id = body["account_id"]
pages = body.get("pages", [])
# Store each entry's page_identifier per surface; you'll pass these into
# the Web SDK's selectPlacements call later.

Réponse :

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...",
  "data": {
    "account_id": "<your-account-id>",
    "pages": [
      { "surface": "confirmation", "page_id": "bfb5b9be-...", "layout_id": "9d11d8aa-...", "page_identifier": "confirmation_page" },
      { "surface": "tracking",     "page_id": "2b9d8a5e-...", "layout_id": "f8700369-...", "page_identifier": "tracking_page" }
    ]
  }
}

remarque

L'enregistrement est idempotent sur external_account_id. Re-POSTer avec le même external_account_id retourne le même account_id; aucun compte dupliqué n'est créé. Utilisez ceci pour rendre votre intégration sécurisée contre les réessais.

attention

store_identifier doit être une URL valide entre 3 et 400 caractères et inclure le schéma. Envoyez https://acme.myshopify.com, pas acme.myshopify.com; le nom d'hôte nu renvoie une erreur 400.

3
Inspect default controls
Votre préréglage de partenariat initialise les contrôles de marché par défaut lors de la création du compte. Lisez-les avant de les personnaliser pour connaître votre base de référence.
curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
La charge utile de la réponse MCL (data.translated_verticals) liste la politique effective pour chaque sous-verticale mappée dans votre taxonomie partenaire; vertical_id est votre ID de sous-verticale, vous pouvez donc le joindre à vos propres noms de catégories pour l'affichage. Les IDs internes de Rokt ne sont pas exposés.

Customize marketplace controls (optional)

Envoyez la liste complète de blocage souhaitée. Ceci est une sémantique SET : envoyez la liste complète à chaque fois; tout ce que vous omettez devient débloqué. Voir Sémantique SET et la page conceptuelle Taxonomie Verticale.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Acme Network Controls",
    "blockedVerticals": [
      { "partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block", "position1Policy": "Block" },
      { "partnerVerticalId": 1500, "partnerSubVerticalId": 1611, "policy": "Block", "position1Policy": "Block" }
    ],
    "domains": [
      { "domain": "competitor.example.com", "policy": "Block" }
    ],
    "contentHash": null
  }'

astuce

contentHash: null est acceptable lors de la première écriture. Pour les mises à jour ultérieures, passez le hash du précédent GET pour opter pour les vérifications d'optimisme-concurrence. Le rejet de hash obsolète de bout en bout est en phase de prévisualisation : vérifié par acceptation mais pas encore observé en direct sur la surface partenaire. Voir Mise à jour des contrôles.

5
Start Stripe Connect payout setup
POST /v1/partnership/accounts/{account_id}/payout-setup pour initier l'intégration Stripe Connect. Choisissez une des deux formes :
- experience: "embedded": affichez l'interface utilisateur d'intégration de Stripe dans votre application. N'incluez pas contact; le serveur renvoie une erreur 400 si vous le faites.
- experience: "hosted_invite": Rokt envoie un lien par email au marchand. contact.email est requis.
# Embedded: no contact block curl -X POST https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/payout-setup \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "provider": "stripe_connect", "experience": "embedded" }' # Hosted-invite: contact required curl -X POST https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/payout-setup \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "provider": "stripe_connect", "experience": "hosted_invite", "contact": { "email": "merchant@example.com", "name": "Acme Apparel" } }'
La réponse contient une des deux sous-formes à l'intérieur de data:
- Pour embedded: data.embedded.publishable_key + data.embedded.client_secret. Intégrez-les dans Stripe.js pour afficher le flux.
- Pour hosted_invite: data.hosted_invite.invite_id + data.hosted_invite.email. Le marchand reçoit automatiquement l'email.
attention
Ne jamais inclure de champs de compte bancaire, carte, routage, SSN, IBAN, taxe, ou compte externe dans la requête ; ces noms de champs sont interdits à tout niveau d'imbrication et renvoient une erreur 400. Stripe collecte ces informations directement auprès du marchand.
6
Wait for payout completion
Sondez GET /v1/partnership/accounts/{account_id}/payout-setup/status jusqu'à ce que data.payouts_enabled === true et data.details_submitted === true. Cadence recommandée : toutes les 30 secondes, abandonnez après 7 jours. L'intégration Stripe est pilotée par le partenaire et peut prendre du temps ; ne bouclez pas trop serré.
curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/payout-setup/status \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
{ "status": 200, "error": null, "message": "ok", "request_id": "...", "data": { "provider": "stripe_connect", "setup_id": "stp_...", "managed_account_id": "<your-account-id>", "manager_account_id": "<your-platform-parent-account-id>", "connected_account_id": "acct_...", "details_submitted": false, "payouts_enabled": false, "charges_enabled": false, "requirements_currently_due_count": 3, "requirements_eventually_due_count": 0, "requirements_past_due_count": 0, "disabled_reason": null, "updated_at": "2026-05-20T19:14:00Z" } }
Si disabled_reason n'est pas nul ou requirements_past_due_count > 0, remontez cela au marchand pour qu'il puisse terminer.
Si votre fenêtre de sondage de 7 jours expire sans payouts_enabled === true, ne laissez pas le marchand bloqué. Récupérez avec cette séquence :
1. Ré-invoquez POST /v1/partnership/accounts/{account_id}/payout-setup pour générer une nouvelle session d'intégration. Le même marchand peut avoir plusieurs sessions en cours ; seule la dernière compte pour la finalisation, donc les anciens embedded secrets clients ou liens hosted_invite peuvent être abandonnés en toute sécurité. Utilisez une nouvelle Idempotency-Key pour la nouvelle session.
2. Remontez la disabled_reason sous-jacente (de la réponse de sondage la plus récente data.disabled_reason) au marchand textuellement afin qu'il sache exactement quoi corriger du côté de Stripe avant de redémarrer (par exemple, ID fiscal manquant, vérification d'identité échouée, compte bancaire non vérifié). Les chaînes de raisons définies par Stripe sont suffisamment stables pour générer un message d'aide intégré au produit.
3. Si disabled_reason indique un problème côté Stripe que vous ne pouvez pas remonter ou remédier (par exemple, requires_rokt_review, under_review, ou une valeur non documentée dans les documents d'intégration Stripe Connect), déposez un ticket de support. Incluez le X-Operation-Id de la réponse initiale de configuration des paiements et l'account_id du marchand ; cela suffit pour que les opérateurs Rokt puissent récupérer l'enregistrement du compte connecté et le débloquer.

Activate the partnership

Une fois les paiements terminés et que vous êtes satisfait des contrôles, passez le statut à active. La cascade active chaque variante de page non archivée sur le compte.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "status": "active" }'

8
Verify the cascade
Effectuez un aller-retour de lecture du statut pour confirmer que chaque variante a été activée.
curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
data.status devrait être "active" et chaque entrée dans data.variants[] devrait afficher "active". Si vous voyez "mixed", la cascade a manqué certaines variantes ; déposez un ticket de support avec votre Idempotency-Key et le request_id de l'enveloppe de réponse.
9
Wire the Web SDK on the merchant's pages
Rokt a provisionné le compte, les pages et les mises en page. L'étape restante se déroule sur le site du marchand : chargez le SDK Web Rokt une fois par page et appelez selectPlacements sur chaque surface, en passant le page_identifier correspondant de la réponse d'enregistrement.
<script type="module"> await window.RoktLauncherScriptPromise; const launcher = await window.Rokt.createLauncher({ accountId: "<account_id from registration>", sandbox: true }); // Confirmation page: await launcher.selectPlacements({ identifier: "confirmation_page", // ← from registration response's pages[].page_identifier attributes: { email, firstname, lastname, confirmationref, amount, currency, country } }); </script>
Les surfaces intégrées (Embedded type de mise en page) nécessitent un élément d'ancrage sur la page. Par défaut, le SDK recherche <div id="rokt-container"></div>. Voir Intégration SDK pour la configuration complète, y compris le snippet de chargement, la couverture des attributs et les notes SPA.

Personnalisation de l'expérience du marchandLien direct vers Personnalisation de l'expérience du marchand

L'enregistrement fournit à chaque marchand le thème et l'ensemble de surfaces par défaut du préréglage de partenariat. Une fois l'intégration en ligne, trois points de terminaison vous permettent de faire évoluer cette base sans vous réinscrire : le PATCH de mise en page à 5 jetons pour le thème visuel, le POST d'ajout de page pour ajouter de nouvelles surfaces (par exemple, tracking après que le marchand ait initialement lancé avec confirmation seulement), et le PUT de changement de page pour déplacer une page existante entre les types de mise en page. Tous sont appelables par le partenaire, idempotents, et limités au même compte géré ; aucune intervention du côté de Rokt n'est nécessaire.

Customize a merchant's layout

Thématiser la mise en page d'un marchand via le PATCH à 5 jetons (arrière-plan, primaire, secondaire, police, rayon de bordure).

Add pages after registration

Ajouter une nouvelle surface (confirmation, suivi, retours) à un marchand en ligne sans réinscription.

Switch a page's layout type

Déplacer une page existante entre Overlay et Embedded ; les modifications de thème et l'identifiant de la page sont préservés.

Le marchand est en ligne. Ensuite :

Updating Controls

Modèle GET-modify-PUT pour les modifications continues des contrôles du marché sans perte d'état.

Pausing & Resuming

Pause/reprise grossière pour les demandes des marchands, les suspensions pour fraude ou la résolution de litiges.