# Händlerverwaltung (/de/platform-api/merchant_management)
Verwalten Sie die Händler Ihrer Organisation über Ihr Backend. Jeder Aufruf verwendet Ihr Server Secret Token; bewahren Sie es daher auf Ihrem Server auf.
| Detail | Wert |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Basis-URL | `https://api.sandbox.tapaya.com` für die Sandbox, `https://api.tapaya.com` für die Produktion |
| Authentifizierung | Server Secret Token in `Authorization`. Siehe [Authentifizierung](/platform-api#authentication). |
| Beträge | Kleinste Währungseinheiten: `2500` mit `EUR` entspricht 25,00 EUR. Relative Gebühren in Basispunkten: `100` entspricht 1 %. |
| Zugehöriger Leitfaden | [Händler-Onboarding](/platform-api/merchant_onboarding) |
## Alle Operationen [#all-operations]
| Operation | Zweck |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [Gespeichertes Onboarding lesen](#read-a-saved-onboarding) | Das Onboarding-Formular eines Händlers dort fortsetzen, wo er aufgehört hat. |
| [Kanalauswahl speichern](#save-channel-selections) | Die von einem Händler gewählten Zahlungskanäle speichern, ohne sie zu übermitteln. |
| [Mitglieder auflisten](#list-members) | Sehen, wer bereits Zugriff auf einen Händler hat. |
| [Terminals auflisten](#list-terminals) | Die Terminals eines Händlers und ihre Geräte anzeigen. |
| [E-Mail-Einladungen auflisten](#list-email-invites) | Einmalige Einladungen an bekannte Empfänger nachverfolgen. |
| [Wiederverwendbare Links auflisten](#list-reusable-links) | Kampagnenlinks nachverfolgen und sehen, ob sie pausiert sind. |
| [Wiederverwendbaren Link erstellen](#create-a-reusable-link) | Eine Kampagne starten, über die sich viele Händler registrieren können. |
| [Ablauf einer Einladung ändern](#change-an-invites-expiry) | Eine Einladung verlängern oder verkürzen, auch eine abgelaufene. |
| [Wiederverwendbaren Link pausieren oder reaktivieren](#pause-or-resume-a-reusable-link) | Neue Registrierungen vorübergehend stoppen, ohne den Link zu widerrufen. |
| [Preissätze auflisten](#list-pricing-sets) | Die Preissätze finden, aus denen Ihre Organisation Profile erstellen darf. |
| [Provisionsprofile auflisten](#list-commission-profiles) | Ein Profil auswählen, das einer Einladung zugewiesen wird. |
| [Provisionsprofil erstellen](#create-a-commission-profile) | Händlern eine Preisliste anbieten, die auf einem Preissatz basiert. |
| [Provisionsprofil aktualisieren](#update-a-commission-profile) | Ein Profil umbenennen oder seine Tarife ändern. |
| [Provisionsprofil löschen](#delete-a-commission-profile) | Ein Profil entfernen, das Sie nicht mehr anbieten. |
| [Standardprofil festlegen](#set-the-default-profile) | Das Profil wählen, das Einladungen ohne eigene Profilangabe verwenden. |
| [Händlerpreise lesen](#read-merchant-pricing) | Die Tarife anzeigen, mit denen sich ein Händler registriert hat. |
## Onboarding-Entwürfe [#onboarding-drafts]
**Zweck:** Das Onboarding-Formular eines Händlers mit allem fortsetzen, was er bisher gespeichert hat.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Dies ist der einzige Aufruf, der das gesamte gespeicherte Onboarding zurückgibt; die Profil- und Prozessor-Aufrufe liefern nur Teile davon.
* `pricingConstraints` listet auf, was der Händler wählen darf, keine Gebührentabellen.
**Rückgabe:**
| Feld | Beschreibung |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| `identity` | Die Identitätsdaten des Händlers. |
| `address` | Die Adresse des Händlers. |
| `business` | Geschäftsdaten, die für beide Kanäle gelten. |
| `kyb` | Bankkonten, das Hauptkonto, Beteiligte des Unternehmens oder die natürliche Person sowie deren Dokumente. |
| `capability` | Die ausgewählte Capability. |
| `terminal` | Gespeicherte Details zum Kanal vor Ort. |
| `online` | Gespeicherte Details zum Online-Kanal. |
| `processors` | Status bei jedem Zahlungsabwickler. |
| `commissionProfileIds` | Dem Händler zugewiesene Provisionsprofile. |
| `pricingConstraints` | Zulässige Abrechnungswährungen und MCCs. |
**Zweck:** Die Zahlungskanäle speichern, die ein Händler in Ihrem Formular gewählt hat, bevor er das Onboarding abschließt.
```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
}
}'
```
**Gut zu wissen:**
* Funktioniert nur für einen Händler, dessen Onboarding-Entwurf und Profil bereits gespeichert sind.
* Aktualisiert den Entwurf und gibt `200` zurück. Der Aufruf übermittelt kein Onboarding und registriert kein Prozessorkonto.
* Senden Sie nur die Kanalabschnitte, die der Händler ausgewählt hat.
**Parameter:**
| Feld | Beschreibung |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | Die ausgewählten Kanäle. Dieselben Werte wie beim [Händler-Onboarding](/platform-api/merchant_onboarding#request-online-payment-capabilities). |
| `terminal` | Details zum Kanal vor Ort, mit denselben Feldern wie beim Händler-Onboarding. |
| `online` | Details zum Online-Kanal, mit denselben Feldern wie beim Händler-Onboarding. |
## Mitglieder und Terminals [#members-and-terminals]
**Zweck:** Sehen, wer bereits Zugriff auf einen Händler hat.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Gibt ein Array der aktuellen Mitglieder zurück.
* Ausstehende Einladungen sind nicht enthalten; sie werden separat aufgelistet.
**Rückgabe:** für jedes Mitglied:
| Feld | Beschreibung |
| ----------- | ----------------------------------------------------------- |
| `userId` | Die Benutzer-ID des Mitglieds. |
| `firstName` | Vorname. |
| `lastName` | Nachname. |
| `email` | E-Mail-Adresse. |
| `joinedAt` | Zeitpunkt, zu dem das Mitglied dem Händler beigetreten ist. |
**Zweck:** Die Terminals eines Händlers und die ihnen zugewiesenen Geräte anzeigen.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Gibt Terminals zurück, keine aktiven Standorte; Standorte haben eine eigene Liste.
* Die Antwort enthält `items` und `totalCount`. Jeder Eintrag enthält Terminal- und Standort-IDs, eine Bezeichnung und Gerätedetails.
* `terminalType` und `deviceIdentifier` beschreiben das aktuell zugewiesene Gerät, nicht das Gerät, mit dem eine frühere Zahlung erfasst wurde.
**Parameter:**
| Feld | Beschreibung |
| --------------- | ----------------------------- |
| `page` | Seitennummer. |
| `pageSize` | Zeilen pro Seite. |
| `sortBy` | Feld, nach dem sortiert wird. |
| `sortDirection` | Sortierrichtung. |
## Registrierungseinladungen [#registration-invites]
Verwenden Sie eine [E-Mail-Einladung](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding) für einen bekannten Empfänger oder einen wiederverwendbaren Link für eine Kampagne. Beide können Kanäle einschränken und Provisionsprofile zuweisen.
**Zweck:** Die von Ihnen versendeten einmaligen Einladungen nachverfolgen.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Jede Einladung zeigt die E-Mail-Adresse des Empfängers, die URL, `capability` und `commissionProfileIds`.
* Einladungen enthalten außerdem `commissionProfileId`, die Einzelprofilform von `commissionProfileIds`.
**Zweck:** Ihre Kampagnenlinks nachverfolgen und sehen, welche pausiert sind.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Jeder Link zeigt seine `capability`, die zugewiesenen Profile und `pausedAt`.
* `pausedAt` ist `null`, solange der Link nicht pausiert ist.
* Ein pausierter Link, der weder abgelaufen noch widerrufen ist, entspricht weiterhin `isActive=true`. Prüfen Sie `pausedAt`, um beide zu unterscheiden.
**Zweck:** Eine Kampagne starten, über die sich viele Händler registrieren können.
```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
}'
```
**Gut zu wissen:**
* `capability` beschränkt, welche Kanäle Händler wählen können. Es erteilt keine Prozessorfreigabe.
* Lassen Sie die Profilfelder weg, um das Standardprofil der Organisation zuzuweisen.
* `commissionProfileId` wird für ein einzelnes Profil weiterhin akzeptiert. Verwenden Sie stattdessen `commissionProfileIds` und senden Sie niemals beide.
**Parameter:**
| Feld | Beschreibung |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | Ein Name für die Kampagne. |
| `expiresAt` | ISO-8601-UTC-Zeitstempel, mindestens einen Tag in der Zukunft. Es gibt kein Maximum. |
| `capability` | Optional. Dieselben Werte wie bei [E-Mail-Einladungen](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). |
| `commissionProfileIds` | Optional. Dieselben Regeln wie bei E-Mail-Einladungen. |
**Zweck:** Eine Einladung verlängern oder verkürzen, auch eine bereits abgelaufene.
```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"}'
```
**Gut zu wissen:**
* Rufen Sie für eine E-Mail-Einladung `PUT /integrator/merchant/invites/{inviteId}/expires-at` mit demselben Body auf.
* Gibt `204` zurück.
* Widerrufene Einladungen und bereits verwendete E-Mail-Einladungen können nicht verlängert werden.
**Parameter:**
| Feld | Beschreibung |
| ----------- | ------------------------------------------------------------------------------------ |
| `expiresAt` | ISO-8601-UTC-Zeitstempel, mindestens einen Tag in der Zukunft. Es gibt kein Maximum. |
**Zweck:** Neue Registrierungen vorübergehend stoppen, ohne den Link zu widerrufen.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/pause' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Rufen Sie `.../resume` für denselben Link auf, um wieder Registrierungen anzunehmen. Das Reaktivieren verlängert den Ablauf nicht.
* Beide geben `204` zurück und sind idempotent.
* Das Öffnen eines pausierten Links gibt `410` zurück.
## Provisionsprofile [#commission-profiles]
Ein Provisionsprofil ist die Preisliste, die Sie Händlern anbieten. Erstellen Sie es aus einem Preissatz, für den Ihre Organisation autorisiert ist.
**Zweck:** Die Preissätze finden, aus denen Sie Provisionsprofile erstellen können.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Jeder Satz enthält seine vertraglichen Händler- und Integratortarife.
* Verwenden Sie eine zurückgegebene `pricingSetId`, wenn Sie ein Profil erstellen.
**Parameter:**
| Feld | Beschreibung |
| ------------- | ---------------------------------- |
| `pricingType` | Optional. `online` oder `instore`. |
**Zweck:** Ein Profil auswählen, das einer Einladung zugewiesen wird.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Gibt nur aktivierte, vollständige Profile Ihrer Organisation zurück.
* Jedes Profil deckt einen Preistyp ab.
* Bewahren Sie die `revision` jedes Profils auf, wenn Sie es aktualisieren möchten.
**Parameter:**
| Feld | Beschreibung |
| ------------- | ---------------------------------- |
| `pricingType` | Optional. `online` oder `instore`. |
**Zweck:** Händlern eine Preisliste anbieten, die auf einem Preissatz basiert.
```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"}
]
}'
```
**Gut zu wissen:**
* Ein Profil deckt einen Preistyp ab, der sich aus seinen Preissätzen ergibt.
* Integratorkosten und Margenanteile stammen aus dem Preissatz; Sie legen nur die Händlertarife fest.
* `region` ist `1` für national oder `2` für international, `holderType` ist `1` für Verbraucher oder `2` für Unternehmen, und `scheme` ist `1` für Visa oder `2` für Mastercard.
**Parameter:**
| Feld | Beschreibung |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Der Profilname. |
| `pricingModel` | `1` für MDR oder `2` für IC++. |
| `cardTypes` | Jede Kombination aus Region, Karteninhabertyp und Kartennetzwerk, die das Profil akzeptiert, mit ihren Vermittlungsgebühren. |
| `pricings` | Währung und `pricingSetId` für jede Währung, die Sie anbieten. |
| `merchantPricingOverrides` | Optional. Einträge mit `holderCategory`, `regionSegment`, `relative` und `absolute`. Ausgelassene Kombinationen behalten die Tarife des Preissatzes. |
**Zweck:** Ein Profil umbenennen oder seine Tarife ändern.
```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
}'
```
**Gut zu wissen:**
* Senden Sie die zuletzt gelesene `revision` als `expectedRevision`. Eine veraltete Revision gibt `409` zurück.
* Lassen Sie `pricings` weg, um die gespeicherten Tarife beizubehalten.
* Ein Profil, das Händlern zugewiesen oder nicht bearbeitbar ist, akzeptiert nur einen neuen Namen.
**Parameter:**
| Feld | Beschreibung |
| ------------------ | ---------------------------------------------------- |
| `name` | Erforderlich. Der Profilname. |
| `pricingModel` | Erforderlich. `1` für MDR oder `2` für IC++. |
| `cardTypes` | Erforderlich. Wie beim Erstellen. |
| `pricings` | Optional. Wie beim Erstellen. |
| `expectedRevision` | Die `revision` des Profils zum Zeitpunkt des Lesens. |
**Zweck:** Ein Profil entfernen, das Sie nicht mehr anbieten.
```bash
curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Das Standardprofil kann nicht gelöscht werden. Legen Sie zuerst ein anderes Profil als Standard fest.
* Ein Profil, das Händlern zugewiesen ist, kann nicht gelöscht werden. Beide Fälle geben `400` zurück.
**Zweck:** Das Profil wählen, das Einladungen ohne eigene Profilangabe verwenden.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Ihre Organisation hat ein Standardprofil.
* Das Standardprofil kann nicht gelöscht werden.
## Händlerpreise [#merchant-pricing]
**Zweck:** Die Tarife anzeigen, mit denen sich ein Händler registriert hat, für Zahlungen vor Ort und Online-Zahlungen.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \
-H 'Authorization: REPLACE_ME'
```
**Gut zu wissen:**
* Ein Kanal ohne gespeicherte Preise ist `null`. Ein Händler ohne gespeicherte Preisliste gibt `404` zurück.
* Gibt vertragliche Tarife zurück, keine Basisgebührentabellen des Zahlungsanbieters. Lesen Sie die Tarife aus `cells`; die `commission`-Komponenten sind keine tatsächlich erzielten Provisionen.
* Ein unbekanntes Integratormodell oder unbekannte Kosten sind `null`, nicht 0.
* Margenanteile teilen die verteilbare Marge auf, nicht den gesamten Zahlungsbetrag.
**Rückgabe:**
| Feld | Beschreibung |
| ------------------------------------- | ------------------------------------------------------------------- |
| `instore` | Preise für Zahlungen vor Ort oder `null`. |
| `online` | Preise für Online-Zahlungen oder `null`. |
| `currency` | Die Preiswährung. |
| `pricingModel` | Das Preismodell des Händlers. |
| `integratorPricingModel` | Das Preismodell des Integrators, unabhängig von dem des Händlers. |
| `priceListId` | Die gespeicherte Händlerpreisliste, sofern verfügbar. |
| `pricingSetVersionId` | Die Version des ursprünglichen Preissatzes, sofern verfügbar. |
| `pricingSetName` | Der Name des ursprünglichen Preissatzes, sofern verfügbar. |
| `cells` | Tarife je Karteninhaberkategorie und Region. |
| `cells[].discountBps` | Endgültiger relativer Händlertarif in Basispunkten. |
| `cells[].transactionFeeMinor` | Endgültige feste Händlergebühr in kleinsten Währungseinheiten. |
| `cells[].integratorCostRelativeBps` | Vertragliche relative Integratorkosten in Basispunkten. |
| `cells[].integratorCostAbsoluteMinor` | Vertragliche feste Integratorkosten in kleinsten Währungseinheiten. |
| `cells[].revenueShareTapayaBps` | Anteil von Tapaya an der verteilbaren Marge in Basispunkten. |
| `cells[].revenueShareIntegratorBps` | Ihr Anteil an der verteilbaren Marge in Basispunkten. |
## Fehler [#errors]
Jede Operation antwortet mit diesen Statuscodes, wenn eine Anfrage fehlschlägt.
| Code | Beschreibung |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Ungültige Kanaldaten, Profilauswahl, Filter oder Ablaufzeit; oder der Versuch, ein Standardprofil oder zugewiesenes Profil zu löschen. |
| `401` | Das Server Secret Token fehlt oder ist ungültig. |
| `404` | Die Ressource ist für Ihre Organisation nicht verfügbar, oder das gespeicherte Onboarding beziehungsweise die Preise existieren nicht. |
| `409` | Eine veraltete Profilrevision, ein widersprüchlicher Onboarding-Zustand oder eine verwendete beziehungsweise widerrufene Einladung. |