# Merchant Onboarding API (/de/platform-api/merchant_onboarding) Alle Anfragen auf dieser Seite verwenden Ihr Server Secret Token. Siehe [Authentifizierung](/platform-api#authentication). Ein Händler kann in einem einzigen Onboarding-Antrag die [Zahlungsannahme vor Ort](/in-store), [Online-Zahlungen](/online) oder beides beantragen. Diese Seite gilt für jede Integration: das Accept SDK, die App Tapaya Terminal und Checkout. Verwenden Sie sie, um Händler über die API statt über die Tapaya Platform UI anzulegen und zu verwalten. Beantragen Sie die Zahlungsfunktionen, die der Händler benötigt. Eine Freigabe für Zahlungen vor Ort allein aktiviert keine Online-Zahlungen. Wenn Sie einen Händler mit `POST /integrator/merchant` anlegen, oder mit `POST /merchant/auth/register` in einer [Accept-SDK-Integration](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations), wird sein Konto erstellt, doch der Händler kann erst echte Zahlungen vor Ort oder online abwickeln, wenn das Onboarding abgeschlossen ist. Für Online-Zahlungen beantragen Sie die Checkout-Funktion und warten auf die Freigabe durch den Online-Zahlungsabwickler und die Einrichtung des Gateways. Händler erscheinen automatisch in den [Checkout-Einstellungen](/online/integration/checkout_settings), wo Sie die Einsatzbereitschaft prüfen und Schlüssel und Wallets konfigurieren können. Tapaya unterstützt mehrere Onboarding-Varianten; alle lassen sich über die Tapaya Platform UI verwalten und bei Bedarf automatisieren. | Ablauf | Wann er sich eignet | Einstiegspunkt in der API | | ---------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tapaya Platform UI** | Ihr Operations-Team schließt das Onboarding im Namen des Händlers ab. | Legen Sie den Händler in der Tapaya Platform UI an oder wählen Sie ihn aus und öffnen Sie dort das gehostete Onboarding. | | **Eigene Oberfläche** | Sie erheben und validieren die Onboarding-Daten in Ihrem Produkt. | Validieren Sie die Abschnitte mit `POST /integrator/merchant/onboarding/validate/*` und reichen Sie sie dann mit `POST /integrator/merchant/onboarding` ein. Details siehe unten. | | **E-Mail-Einladung** | Ein bekannter Händler erhält eine Einladung zur einmaligen Verwendung, um das Onboarding selbst zu durchlaufen. | Senden Sie eine Einladung mit `POST /integrator/merchant/send-registration-invite`; geben Sie `merchantToken` an, um die Einladung an einen bestehenden Basis-Händlerdatensatz (Merchant Shell) zu binden, und listen Sie sie anschließend über `/integrator/merchant/invites` auf oder widerrufen Sie sie dort. | | **Kampagnenlink** | Mehrere oder noch unbekannte Händler nutzen einen wiederverwendbaren Link zur Selbstregistrierung. | Erstellen Sie einen Link mit `POST /integrator/merchant/reusable-registration-invites`; über dieselbe Ressource listen Sie Links auf oder widerrufen sie. | Einen ausführlichen Vergleich dieser Abläufe finden Sie im [Leitfaden zum Händler-Onboarding](/merchants/onboarding). ## Funktionen für Online-Zahlungen beantragen [#request-online-payment-capabilities] `POST /integrator/merchant/onboarding` erfordert `capability`. Verwenden Sie dieselbe Funktion, wenn Sie das Geschäftsprofil validieren: | Wert | Funktion | Kanaldetails | | ---- | --------- | --------------------------------------------------------------------------------- | | `1` | Beides | Geben Sie `terminal` und `online` an. Jeder Kanal erfordert eine eigene Freigabe. | | `2` | Terminals | Geben Sie `terminal` für Zahlungen vor Ort an. | | `3` | Checkout | Geben Sie `online` für Online-Zahlungen an. Es ist kein Terminal erforderlich. | Für Checkout fügen Sie zusätzlich zu Identität, Adresse, gemeinsamem `business` und KYB-Daten des Händlers die folgenden Felder auf oberster Ebene hinzu. Dieselben Kanalfelder gelten für `POST /integrator/merchant/onboarding/validate/business`: ```json { "capability": 3, "online": { "mcc": "5411", "statementDescriptor": "ACME CORP", "productDescription": "Groceries sold online", "averageItemValue": 2500, "expectedMonthlyTurnover": 500000, "url": "https://www.acme.example.com", "purchaseChargeTiming": 1, "averageDeliveryDays": 2, "topCountries": [{ "countryId": 1, "percentage": 100 }] } } ``` Beträge werden in der kleinsten Währungseinheit angegeben. Die Website für das Online-Geschäft muss HTTP oder HTTPS verwenden, und ihr Hostname muss `www` enthalten. `statementDescriptor` umfasst 5 bis 22 Zeichen. `purchaseChargeTiming` ist `1` für „Bestellung aufgegeben“, `2` für „versandt“ oder `3` für „erhalten“. `averageDeliveryDays` liegt zwischen 0 und 999. Geben Sie ein bis vier eindeutige `topCountries` an, deren Prozentsätze zusammen 100 ergeben. Gemeinsame Support- und Finanzangaben gehören in `business`. Im Kanalabschnittsmodus tragen Sie MCC, Text auf dem Kontoauszug (Statement Descriptor), Produktbeschreibung und Transaktionsschätzungen in das jeweilige Objekt `terminal` oder `online` ein. Validieren Sie die Payload, bevor Sie das Onboarding einreichen, und beheben Sie die zurückgegebenen kanalspezifischen Feldfehler. ## Händler zum gehosteten Onboarding einladen [#invite-a-merchant-to-complete-hosted-onboarding] Verwenden Sie diesen Ablauf, wenn Tapaya das KYB-Formular hosten soll, Sie das Anlegen des Händlers aber weiterhin aus Ihrem Backend steuern möchten. Wenn Ihr System die Händlerkennung verwaltet, die später vom SDK oder Ihrem Backoffice verwendet wird, legen Sie zuerst den Basis-Händlerdatensatz mit `POST /merchant/auth/register` oder `POST /integrator/merchant` an und rufen Sie dann `POST /integrator/merchant/send-registration-invite` mit demselben `merchantToken` auf. So bleibt das gehostete Onboarding diesem Händler zugeordnet, statt einen zweiten anzulegen. Die empfohlene Reihenfolge ist: 1. Basis-Händlerdatensatz anlegen: * `POST /merchant/auth/register` oder * `POST /integrator/merchant` 2. Einladung zum gehosteten Onboarding mit `POST /integrator/merchant/send-registration-invite` senden 3. Die zurückgegebene `registrationUrl` bei Bedarf mit dem Händler teilen und ihn das von Tapaya gehostete Formular ausfüllen lassen 4. Die Einsatzbereitschaft des Händlers regelmäßig über `GET /integrator/merchant/{merchantId}/status` abfragen **Endpoint:** `POST /integrator/merchant/send-registration-invite` cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/send-registration-invite' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "email": "admin@acme.com", "merchantToken": "unique_merchant_id_from_your_db" }' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | --------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | `string` | ✓ | E-Mail-Adresse, an die der Link zum gehosteten Onboarding gesendet werden soll. | | `merchantToken` | `string` | | Bestehendes Händler-Token, an das die Einladung gebunden wird. Verwenden Sie es, wenn Sie den Basis-Händlerdatensatz bereits angelegt haben und das gehostete Onboarding genau diesen Händler befüllen soll. Wird es weggelassen, legt das Abschließen der Einladung einen neuen Händler an. | **Antworten:** | Code | Beschreibung | | ----- | --------------------------------------------------------- | | `200` | Einladung erstellt. Die Antwort enthält `registrationUrl` | | `400` | Validierungsfehler der Anfrage | | `401` | Nicht autorisiert | | `404` | Organisation oder Händler nicht gefunden | | `409` | Konflikt | **Antworttext:** ```json { "registrationUrl": "https://platform.tapaya.com/invite-merchant?token=...&merchantToken=unique_merchant_id_from_your_db" } ``` Tapaya versucht außerdem, diesen Link per E-Mail zu versenden. Die Zustellung per E-Mail erfolgt ohne Garantie, behandeln Sie daher immer die zurückgegebene `registrationUrl` als maßgebliche Quelle für Ihre Oberfläche und Ihre Support-Tools. `POST /integrator/merchant/{merchantId}/invite` ist ein anderer Ablauf. Er lädt einen Plattformbenutzer ein, auf ein bereits bestehendes Händlerkonto zuzugreifen. Er startet **kein** KYB-Onboarding und legt kein Händlerprofil an und aktualisiert es auch nicht. ## Onboarding über die API einreichen [#submit-onboarding-through-the-api] Wenn Sie die Onboarding-Daten in Ihrem eigenen Produkt erheben möchten, statt Händler an die Tapaya Platform weiterzuleiten, reichen Sie sie direkt ein. Validieren Sie jeden Abschnitt, während der Händler ihn ausfüllt, mit den unten beschriebenen `validate/*`-Endpoints und reichen Sie dann alles in einem einzigen Aufruf ein. Dieser legt den Händler zusammen mit seinem Onboarding-Profil an und registriert ihn beim bevorzugten Zahlungsabwickler Ihrer Organisation. Bevor Sie Onboarding-Daten über die API einreichen, müssen Sie die Zustimmung des Händlers zu den [Tapaya Integrators Terms and Conditions](https://tapaya.com/terms) und der [Tapaya-Datenschutzerklärung](https://tapaya.com/privacy) einholen. Fügen Sie Ihrem Onboarding-Formular ein Kontrollkästchen hinzu, das auf beide Dokumente verweist, oder verlinken Sie aus dem Text der Bedingungen, denen der Händler zustimmt, auf die Tapaya-Dokumente. Außerdem müssen Sie Tapaya in Ihrer eigenen Datenschutzerklärung als Auftragsverarbeiter aufführen. `POST /integrator/merchant/onboarding` legt den Händler an **und** reicht das Onboarding in einem einzigen Aufruf ein. Sind die Onboarding-Daten ungültig, gibt der Aufruf `422` mit Fehlern auf Feldebene zurück, und **es wird kein Händler angelegt**; es gibt keinen teilweise eingerichteten Händler, den Sie bereinigen oder fortsetzen müssten.
### Identität validieren [#validate-identity] **Endpoint:** `POST /integrator/merchant/onboarding/validate/identity` cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/identity' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "legalName": "Acme Corp s.r.o.", "businessTypeId": 2, "email": "admin@acme.com", "registrationNumber": "12345678", "vatNumber": "CZ12345678", "incorporationDate": "2018-04-01" }' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | ----------------------------------- | -------- | ------------ | --------------------------------------------------------------------- | | `legalName` | `string` | ✓ | Rechtlicher Name des Unternehmens oder des einzelnen Kontoinhabers. | | `businessTypeId` | `int` | ✓ | Art der Unternehmensform (`BusinessTypeEnum`). | | `email` | `string` | ✓ | Kontakt-E-Mail-Adresse. | | `registrationNumber` | `string` | ✓ | Amtliche Handelsregisternummer des Unternehmens. Wird innerhalb Ihrer | | Organisation auf Duplikate geprüft. | | | | | `vatNumber` | `string` | | Umsatzsteuer-Identifikationsnummer, falls zutreffend. | | `incorporationDate` | `date` | | Datum der rechtlichen Gründung des Unternehmens (`YYYY-MM-DD`). | **Antworttext:** ```json { "valid": true, "errors": [] } ``` Eine `registrationNumber`, die bereits von einem anderen Händler in Ihrer Organisation verwendet wird, wird als Fehler mit `valid: false` und `code: "DUPLICATE_REGISTRATION_NUMBER"` zurückgegeben, nicht als `409`; dieser Endpoint liefert immer `200`. ### Adresse validieren [#validate-address] **Endpoint:** `POST /integrator/merchant/onboarding/validate/address` cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/address' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "line1": "Wenceslas Square 1", "city": "Prague", "postalCode": "11000", "countryId": 1 }' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | ------------ | -------- | ------------ | -------------------------------------------------- | | `line1` | `string` | ✓ | Erste Zeile der Straßenadresse. | | `line2` | `string` | | Zweite Zeile der Straßenadresse, falls zutreffend. | | `city` | `string` | ✓ | Name der Stadt. | | `postalCode` | `string` | ✓ | Postleitzahl. | | `state` | `string` | | Bundesland oder Region, falls zutreffend. | | `countryId` | `int` | ✓ | Land (`CountryEnum`). | **Antworttext:** dieselbe Struktur `{valid, errors}` wie bei [Identität validieren](#validate-identity). ### Geschäftsprofil validieren [#validate-business-profile] **Endpoint:** `POST /integrator/merchant/onboarding/validate/business` cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/business' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "capability": 2, "mcc": "5411", "url": "https://acme.example.com", "supportPhone": "+420123456789", "statementDescriptor": "ACME CORP" }' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | ------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `capability` | `int` | ✓ | Verwenden Sie die Funktion, die Sie für das Onboarding einreichen werden. Für Checkout oder Beides geben Sie die [Kanaldetails](#request-online-payment-capabilities) an. | | `mcc` | `string` | ✓ | Vierstelliger Merchant Category Code. Im Kanalabschnittsmodus verwenden Sie `terminal.mcc` oder `online.mcc`. | | `url` | `string` | | URL der Unternehmenswebsite. Entweder `url` oder `productDescription` ist erforderlich. | | `productDescription` | `string` | | Beschreibung der Produkte oder Dienstleistungen. Entweder `url` oder `productDescription` ist | | erforderlich. | | | | | `supportPhone` | `string` | ✓ | Telefonnummer des Kundensupports im Format E.164. | | `statementDescriptor` | `string` | ✓ | Text, der auf den Kontoauszügen der Kunden erscheint (1 bis 22 Zeichen). | | `averageItemValue` | `long` | | Durchschnittlicher Transaktionswert in der kleinsten Währungseinheit. | | `expectedMonthlyTurnover` | `long` | | Erwarteter Monatsumsatz in der kleinsten Währungseinheit. | | `numberOfEmployees` | `int` | | Anzahl der Beschäftigten des Unternehmens. | | `annualTurnover` | `long` | | Jahresumsatz in der kleinsten Währungseinheit. | | `balanceSheetTotal` | `long` | | Bilanzsumme in der kleinsten Währungseinheit. | **Antworttext:** dieselbe Struktur `{valid, errors}` wie bei [Identität validieren](#validate-identity). ### KYB validieren [#validate-kyb] **Endpoint:** `POST /integrator/merchant/onboarding/validate/kyb` Geben Sie genau eines der Objekte `individual` (Einzelunternehmer / Selbstständige) oder `company` an. Bei `company` führen Sie jeden Eigentümer, Geschäftsführer und Zeichnungsberechtigten in `people` auf. cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/kyb' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "businessTypeId": 2, "bankAccount": { "iban": "CZ6508000000192000145399", "bic": "GIBACZPX", "currencyId": 1, "beneficiaryName": "Acme Corp s.r.o." }, "company": { "name": "Acme Corp s.r.o.", "registrationNumber": "12345678", "people": [ { "email": "jane@acme.com", "firstName": "Jane", "lastName": "Doe", "role": { "isOwner": true, "isAuthorizedSignatory": true } } ] } }' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | ------------------------------------------------------------------------------------------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------- | | `businessTypeId` | `int` | | Art der Unternehmensform (`BusinessTypeEnum`); bestimmt, ob die Felder von `individual` oder | | `company` erforderlich sind. | | | | | `bankAccount` | `object` | | Bankkonto für Auszahlungen (Kontonummer/IBAN + BIC, Währung, Begünstigter und Adresse | | der Bank). | | | | | `individual` | `object` | | Angaben zum Inhaber als Einzelperson, für Einzelunternehmer. Schließt `company` aus. | | `company` | `object` | | Angaben zum Unternehmen, einschließlich eines Arrays `people` mit Eigentümern, Geschäftsführern und | | Zeichnungsberechtigten sowie eines optionalen `verificationDocument`. Schließt `individual` aus. | | | | Jede Person in `people` (und `individual`) hat die Flags `role.isOwner` / `isDirector` / `isRepresentative` / `isAuthorizedSignatory` sowie optionale Identitätsfelder (`dateOfBirth`, `nationalityCountryId`, `officialIdType`/`officialIdNumber`, `address`, `ownershipPercentage`, `verificationDocuments`). Ein Personeneintrag ist entweder ein reiner Einladungseintrag oder vollständig ausgefüllt; teilweise ausgefüllte Personen werden abgelehnt. Es gibt zwei Möglichkeiten, eine Person einzureichen: * **Nur Einladung:** Reichen Sie nur `email` und eine `role` ein. Die Person erhält eine E-Mail mit Anweisungen, ihre persönlichen Daten und die Identitätsverifizierung direkt selbst zu vervollständigen, einschließlich des Hochladens ihres eigenen Ausweisdokuments; Sie müssen für sie nichts weiter erheben, und auf Ihrer Seite ist kein Hochladen von Dokumenten erforderlich. * **Vollständig ausgefüllt:** Reichen Sie alle persönlichen Daten der Person (Name, Geburtsdatum, amtlicher Ausweis, Adresse usw.) selbst ein. In diesem Fall müssen Sie für diese Person außerdem [ein Ausweisdokument hochladen](#upload-a-persons-id-document); das ist für jede vollständig ausgefüllte Person erforderlich, nicht optional. Dokumente werden hochgeladen, nachdem der Händler existiert, da der [Endpoint zum Hochladen von Dokumenten](#upload-a-persons-id-document) die `merchantId` benötigt, die [Händler mit Onboarding anlegen](#create-merchant-with-onboarding) zurückgibt. Der Upload jeder Person wird ihr über `relatedOfficialIdNumber` zugeordnet. Die optionalen Felder `verificationDocuments.identityDocument`, `verificationDocuments.additionalDocument` und `company.verificationDocument` nehmen jeweils ein Objekt `{frontFileId, backFileId}` an und können nur auf bereits hochgeladene Dateien verweisen; lassen Sie sie daher weg, wenn Sie einen neuen Händler anlegen. Unabhängig davon, wie viele Personen nur eingeladen oder vollständig ausgefüllt sind, müssen Sie immer [das Registrierungs- bzw. Gründungsdokument des Unternehmens hochladen](#upload-the-company-document), bevor der Händler zur KYC-Prüfung eingereicht werden kann. **Antworttext:** dieselbe Struktur `{valid, errors}` wie bei [Identität validieren](#validate-identity). ### Händler mit Onboarding anlegen [#create-merchant-with-onboarding] Reicht alles aus den vorherigen vier Schritten in einem einzigen Aufruf ein, legt den Händler an und registriert ihn beim bevorzugten Zahlungsabwickler Ihrer Organisation. **Endpoint:** `POST /integrator/merchant/onboarding` cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding' \ -H 'Content-Type: application/json' \ -H 'Authorization: REPLACE_ME' \ -d '{ "name": "Acme Corp", "capability": 2, "merchantToken": "unique_merchant_id_from_your_db", "identity": { "legalName": "Acme Corp s.r.o.", "businessTypeId": 2, "email": "admin@acme.com", "registrationNumber": "12345678", "vatNumber": "CZ12345678" }, "address": { "line1": "Wenceslas Square 1", "city": "Prague", "postalCode": "11000", "countryId": 1 }, "business": { "mcc": "5411", "url": "https://acme.example.com", "supportPhone": "+420123456789", "statementDescriptor": "ACME CORP" }, "kyb": { "bankAccount": { "iban": "CZ6508000000192000145399", "bic": "GIBACZPX", "currencyId": 1, "beneficiaryName": "Acme Corp s.r.o." }, "company": { "people": [ { "email": "jane@acme.com", "firstName": "Jane", "lastName": "Doe", "role": { "isOwner": true, "isAuthorizedSignatory": true } } ] } } }' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | --------------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `capability` | `int` | ✓ | `1` für Beides, `2` für Terminals oder `3` für Checkout. Siehe [Funktionen für Online-Zahlungen](#request-online-payment-capabilities). | | `terminal` | `object` | Je nach Funktion | Details zum Terminal-Kanal für Terminals oder Beides. | | `online` | `object` | Je nach Funktion | Details zum Online-Kanal für Checkout oder Beides. | | `name` | `string` | ✓ | Der Name des Händlers. | | `merchantToken` | `string` | | Eine eindeutige, stabile Kennung aus Ihrem System. Wird sie nicht angegeben, wird ein zufälliges Token | | erzeugt. | | | | | `identity` | `object` | ✓ | Dieselbe Struktur wie bei [Identität validieren](#validate-identity). | | `address` | `object` | ✓ | Dieselbe Struktur wie bei [Adresse validieren](#validate-address). | | `business` | `object` | ✓ | Dieselbe Struktur wie bei [Geschäftsprofil validieren](#validate-business-profile). | | `kyb` | `object` | ✓ | Dieselbe Struktur wie bei [KYB validieren](#validate-kyb). | **Antworten:** | Code | Beschreibung | | ----- | ------------------------------------------------------------------------------ | | `201` | Händler angelegt und Onboarding eingereicht | | `422` | Onboarding-Daten ungültig, siehe `errors`; der Händler wird **nicht** angelegt | **Antworttext (`201`):** ```json { "merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e", "merchantToken": "unique_merchant_id_from_your_db", "name": "Acme Corp", "email": "admin@acme.com", "processors": [ { "processorId": 5, "registered": true, "onboardingUrl": null } ] } ``` `onboardingUrl` ist befüllt, wenn der Zahlungsabwickler verlangt, dass der Händler einen zusätzlichen gehosteten Onboarding-Ablauf (z. B. eine Identitätsverifizierung) abschließt, bevor er echte Zahlungen abwickeln kann. **Antworttext (`422`):** ```json { "errors": [ { "step": "identity", "field": "registrationNumber", "message": "A merchant with this registration number is already onboarded under this integrator (merchantId: 018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e).", "code": "DUPLICATE_REGISTRATION_NUMBER" } ] } ``` ### Ausweisdokument einer Person hochladen [#upload-a-persons-id-document] Erforderlich für jede vollständig ausgefüllte Person in `kyb.company.people` / `kyb.individual` (siehe [KYB validieren](#validate-kyb)); nur eingeladene Personen laden ihr Dokument stattdessen selbst über den per E-Mail gesendeten Link hoch. **Endpoint:** `POST /integrator/merchant/{merchantId}/document` Der Anfragetext ist `multipart/form-data`, nicht JSON. cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \ -H 'Authorization: REPLACE_ME' \ -F 'paymentProcessorId=5' \ -F 'documentType=2' \ -F 'relatedOfficialIdNumber=123456789' \ -F 'frontFile=@./jane-doe-id-front.jpg' \ -F 'backFile=@./jane-doe-id-back.jpg' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | ---------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------ | -------------------------------------------------------------------------------------------------------- | | `paymentProcessorId` | `int` | ✓ | Immer `5`. | | `documentType` | `int` | ✓ | Art des Dokuments (`DocumentTypeEnum`: `1` Other, `2` Id, `3` Address, `4` Company, | | `5` BankStatement, `6` Passport, `7` RecentFinancials). | | | | | `frontFile` | `file` | ✓ | Vorderseite des Dokumentbilds. | | `backFile` | `file` | | Rückseite des Dokumentbilds, falls zutreffend. | | `relatedOfficialIdNumber` | `string` | | Die `officialIdNumber` der Person aus [KYB validieren](#validate-kyb). | | Nur erforderlich, wenn `documentType` personengebunden ist (z. B. Id, Passport, Address); andernfalls ignoriert. | | | | | `submitMerchant` | `boolean` | | Hier nicht setzen bzw. `false` lassen: Der Ausweis einer Person ist nicht der letzte Upload des Stapels. | | Setzen Sie `true` erst beim [Hochladen des Unternehmensdokuments](#upload-the-company-document), wenn die Dokumente aller Personen | | | | | hochgeladen sind. | | | | **Antworttext (`200`):** ```json { "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h", "backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k", "uploadedAt": "2026-07-17T12:00:00Z" } ``` ### Unternehmensdokument hochladen [#upload-the-company-document] Genau einmal pro Händler erforderlich. Wurden die Personenangaben nicht ausgefüllt, kann der Zeichnungsberechtigte das Dokument über den Link aus der Onboarding-E-Mail hochladen, und dieser Endpoint muss nicht aufgerufen werden. **Endpoint:** `POST /integrator/merchant/{merchantId}/document` Der Anfragetext ist `multipart/form-data`, nicht JSON. cURL ```bash curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \ -H 'Authorization: REPLACE_ME' \ -F 'paymentProcessorId=5' \ -F 'documentType=4' \ -F 'frontFile=@./acme-corp-register-extract.pdf' \ -F 'submitMerchant=true' ``` **Parameter:** | Feld | Typ | Erforderlich | Beschreibung | | ------------------------------------------------------- | --------- | ------------ | --------------------------------------------------------------------------------------------------------- | | `paymentProcessorId` | `int` | ✓ | Immer `5`. | | `documentType` | `int` | ✓ | Bei diesem Schritt immer `4` (`Company`). | | `frontFile` | `file` | ✓ | Das Registrierungs- bzw. Gründungsdokument des Unternehmens. | | `submitMerchant` | `boolean` | | Auf `true` setzen, um die KYC-Prüfung durch den Zahlungsabwickler auszulösen, nachdem alle erforderlichen | | Dokumente hochgeladen wurden. Standardwert ist `false`. | | | | **Antworttext (`200`):** ```json { "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h", "backFileId": null, "uploadedAt": "2026-07-17T12:00:00Z" } ```