API pro onboarding obchodníků

Vytvářejte obchodníky a odesílejte jejich onboarding nebo je k onboardingu zvěte přes Tapaya Platform API.

Všechny požadavky na této stránce používají váš Server Secret Token. Viz Autentizace.

Jeden onboarding pro platby v prodejně i online

Obchodník může v jedné žádosti o onboarding požádat o Přijímání plateb v prodejně, online platby nebo o obojí. Tato stránka platí pro každou integraci: Accept SDK, aplikaci Tapaya Terminal i Checkout. Použijte ji k vytváření a správě obchodníků přes API místo Tapaya Platform UI. Požádejte o platební funkce, které obchodník potřebuje. Samotné schválení pro platby v prodejně online platby nepovoluje.

Vytvořením obchodníka pomocí POST /integrator/merchant nebo pomocí POST /merchant/auth/register v integraci Accept SDK se vytvoří jeho účet, ale obchodník nemůže přijímat ostré platby v prodejně ani online, dokud není onboarding dokončen. Pro online platby požádejte o funkci Checkout a počkejte na schválení online zpracovatelem a na nastavení brány. Obchodníci se automaticky zobrazí v nastavení Checkoutu, kde můžete ověřit jejich připravenost a nastavit klíče a peněženky. Tapaya podporuje několik způsobů onboardingu; všechny lze spravovat z Tapaya Platform UI a tam, kde je to vhodné, automatizovat.

Postup	Kdy jej použít	Vstupní bod API
Tapaya Platform UI	Onboarding za obchodníka dokončí váš provozní tým.	Vytvořte nebo vyberte obchodníka v Tapaya Platform UI a otevřete tam hostovaný onboarding.
Vlastní UI	Údaje pro onboarding shromažďujete a ověřujete ve svém produktu.	Ověřte jednotlivé části pomocí `POST /integrator/merchant/onboarding/validate/*` a poté je odešlete pomocí `POST /integrator/merchant/onboarding`. Podrobnosti níže.
E-mailová pozvánka	Známý obchodník obdrží jednorázovou pozvánku k samostatnému onboardingu.	Pozvánku odešlete pomocí `POST /integrator/merchant/send-registration-invite`; uveďte `merchantToken`, chcete-li pozvánku svázat s existujícím základním záznamem obchodníka, a poté ji vypište nebo zrušte přes `/integrator/merchant/invites`.
Odkaz kampaně	Více obchodníků nebo dosud neznámí obchodníci používají opakovaně použitelný odkaz pro samostatnou registraci.	Odkaz vytvořte pomocí `POST /integrator/merchant/reusable-registration-invites`; odkazy vypíšete nebo zrušíte přes tentýž endpoint.

Podrobné srovnání těchto postupů najdete v průvodci onboardingem obchodníků.

Žádost o funkce online plateb

POST /integrator/merchant/onboarding vyžaduje capability. Stejnou hodnotu funkce použijte při ověřování obchodního profilu:

Hodnota	Funkce	Údaje o kanálu
`1`	Obojí	Uveďte `terminal` i `online`. Každý kanál vyžaduje vlastní schválení.
`2`	Terminály	Uveďte `terminal` pro platby v prodejně.
`3`	Checkout	Uveďte `online` pro online platby. Terminál není potřeba.

Pro Checkout přidejte vedle identity obchodníka, adresy, sdíleného objektu business a údajů KYB následující pole nejvyšší úrovně. Stejná pole kanálu platí i pro POST /integrator/merchant/onboarding/validate/business:

{
	"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 }]
	}
}

Částky jsou v nejmenších jednotkách měny. Web pro online prodej musí používat HTTP nebo HTTPS a jeho název hostitele musí obsahovat www. statementDescriptor má 5 až 22 znaků. purchaseChargeTiming je 1 pro zadání objednávky, 2 pro odeslání nebo 3 pro doručení. averageDeliveryDays je 0 až 999. Uveďte jednu až čtyři jedinečné topCountries, jejichž procentní podíly dávají v součtu 100.

Sdílené údaje o podpoře a finanční údaje ponechte v business. V režimu oddílů kanálů uveďte MCC, popis na výpisu (statement descriptor), popis produktu a odhady transakcí v příslušném objektu terminal nebo online. Před odesláním onboardingu payload ověřte a opravte vrácené chyby polí specifické pro daný kanál.

Pozvání obchodníka k dokončení hostovaného onboardingu

Tento postup použijte, když má formulář KYB hostovat Tapaya, ale vytváření obchodníků chcete i nadále řídit ze svého backendu.

Doporučeno, pokud merchantToken spravujete vy

Pokud identifikátor obchodníka, který později používá SDK nebo váš back office, spravuje váš systém, nejprve vytvořte základní záznam obchodníka pomocí POST /merchant/auth/register nebo POST /integrator/merchant a poté zavolejte POST /integrator/merchant/send-registration-invite se stejným merchantToken. Hostovaný onboarding tak zůstane připojený k tomuto obchodníkovi a nevytvoří se druhý.

Doporučený postup je:

Vytvořte základní záznam obchodníka:
- POST /merchant/auth/register, nebo
- POST /integrator/merchant
Odešlete pozvánku k hostovanému onboardingu pomocí POST /integrator/merchant/send-registration-invite
V případě potřeby sdílejte vrácenou adresu registrationUrl s obchodníkem a nechte jej vyplnit formulář hostovaný společností Tapaya
Připravenost obchodníka zjišťujte dotazováním přes GET /integrator/merchant/{merchantId}/status

Endpoint: POST /integrator/merchant/send-registration-invite

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"
    }'

Parametry:

Pole	Typ	Povinné	Popis
`email`	`string`	✓	E-mailová adresa, na kterou má přijít odkaz na hostovaný onboarding.
`merchantToken`	`string`		Existující token obchodníka, se kterým se má pozvánka svázat. Použijte jej, pokud jste již základní záznam obchodníka vytvořili a chcete, aby hostovaný onboarding vyplnil právě tohoto obchodníka. Pokud jej vynecháte, dokončením pozvánky se vytvoří nový obchodník.

Odpovědi:

Kód	Popis
`200`	Pozvánka vytvořena. Odpověď obsahuje `registrationUrl`
`400`	Chyba ověření požadavku
`401`	Neautorizováno
`404`	Organizace nebo obchodník nenalezen
`409`	Konflikt

Tělo odpovědi:

{
    "registrationUrl": "https://platform.tapaya.com/invite-merchant?token=...&merchantToken=unique_merchant_id_from_your_db"
}

Tapaya se také pokusí tento odkaz odeslat e-mailem. Doručení e-mailu však není zaručeno, proto vrácenou adresu registrationUrl vždy považujte za rozhodující zdroj pro své UI a nástroje podpory.

Nezaměňujte s pozvánkou uživatele obchodníka

POST /integrator/merchant/{merchantId}/invite je jiný postup. Zve uživatele platformy k přístupu k již existujícímu účtu obchodníka. Nezahajuje onboarding KYB a nevytváří ani neaktualizuje profil obchodníka.

Odeslání onboardingu přes API

Pokud chcete údaje pro onboarding shromažďovat ve vlastním produktu místo přesměrování obchodníků na Tapaya Platform, odešlete je přímo. Každou část ověřujte průběžně, jak ji obchodník vyplňuje, pomocí níže uvedených endpointů validate/* a poté vše odešlete jedním voláním, které vytvoří obchodníka spolu s jeho onboardingovým profilem a zaregistruje jej u preferovaného zpracovatele plateb vaší organizace.

Souhlas obchodníka a informace o ochraně osobních údajů

Před odesláním údajů pro onboarding přes API musíte získat souhlas obchodníka s obchodními podmínkami Tapaya pro integrátory a zásadami ochrany osobních údajů Tapaya. Přidejte do svého onboardingového formuláře zaškrtávací políčko s odkazy na oba dokumenty, nebo na dokumenty Tapaya odkažte z textu podmínek, se kterými obchodník souhlasí. Tapaya musíte také uvést jako zpracovatele osobních údajů ve svých vlastních zásadách ochrany osobních údajů.

Při selhání se obchodník nevytvoří

POST /integrator/merchant/onboarding vytvoří obchodníka a zároveň odešle onboarding jediným voláním. Pokud jsou údaje pro onboarding neplatné, vrátí 422 s chybami na úrovni polí a žádný obchodník se nevytvoří; neexistuje tedy žádný obchodník s rozpracovaným onboardingem, kterého by bylo nutné odstranit nebo u něhož by bylo nutné pokračovat.

Ověření identity

Endpoint: POST /integrator/merchant/onboarding/validate/identity

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"
    }'

Parametry:

Pole	Typ	Povinné	Popis
`legalName`	`string`	✓	Oficiální název firmy nebo jméno fyzické osoby, která je držitelem účtu.
`businessTypeId`	`int`	✓	Typ podnikatelského subjektu (`BusinessTypeEnum`).
`email`	`string`	✓	Kontaktní e-mailová adresa.
`registrationNumber`	`string`	✓	Oficiální registrační číslo firmy. Kontroluje se na duplicity v rámci vaší
organizace.
`vatNumber`	`string`		DIČ (registrační číslo pro DPH), pokud existuje.
`incorporationDate`	`date`		Datum právního vzniku firmy (`YYYY-MM-DD`).

Tělo odpovědi:

{
    "valid": true,
    "errors": []
}

Hodnota registrationNumber, kterou již používá jiný obchodník ve vaší organizaci, se vrátí jako chyba valid: false s code: "DUPLICATE_REGISTRATION_NUMBER", nikoli jako 409; tento endpoint vždy vrací 200.

Ověření adresy

Endpoint: POST /integrator/merchant/onboarding/validate/address

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
    }'

Parametry:

Pole	Typ	Povinné	Popis
`line1`	`string`	✓	První řádek adresy.
`line2`	`string`		Druhý řádek adresy, je-li potřeba.
`city`	`string`	✓	Název města.
`postalCode`	`string`	✓	PSČ.
`state`	`string`		Spolkový stát nebo region, je-li potřeba.
`countryId`	`int`	✓	Země (`CountryEnum`).

Tělo odpovědi: stejný tvar {valid, errors} jako u Ověření identity.

Ověření obchodního profilu

Endpoint: POST /integrator/merchant/onboarding/validate/business

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"
    }'

Parametry:

Pole	Typ	Povinné	Popis
`capability`	`int`	✓	Použijte funkci, kterou odešlete v onboardingu. Pro Checkout nebo Obojí uveďte údaje o kanálu.
`mcc`	`string`	✓	Čtyřmístný kód kategorie obchodníka (Merchant Category Code). V režimu oddílů kanálů použijte `terminal.mcc` nebo `online.mcc`.
`url`	`string`		URL webu firmy. Povinné je buď `url`, nebo `productDescription`.
`productDescription`	`string`		Popis produktů nebo služeb. Povinné je buď `url`, nebo
`productDescription`.
`supportPhone`	`string`	✓	Telefonní číslo zákaznické podpory ve formátu E.164.
`statementDescriptor`	`string`	✓	Text zobrazený na bankovních výpisech zákazníků (1–22 znaků).
`averageItemValue`	`long`		Průměrná hodnota transakce v nejmenších jednotkách měny.
`expectedMonthlyTurnover`	`long`		Očekávaný měsíční obrat v nejmenších jednotkách měny.
`numberOfEmployees`	`int`		Počet zaměstnanců firmy.
`annualTurnover`	`long`		Roční obrat v nejmenších jednotkách měny.
`balanceSheetTotal`	`long`		Bilanční suma v nejmenších jednotkách měny.

Tělo odpovědi: stejný tvar {valid, errors} jako u Ověření identity.

Ověření KYB

Endpoint: POST /integrator/merchant/onboarding/validate/kyb

Uveďte právě jedno z polí individual (OSVČ / živnostník) nebo company. U company uveďte v people každého vlastníka, ředitele a oprávněnou podepisující osobu.

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
                    }
                }
            ]
        }
    }'

Parametry:

Pole	Typ	Popis
`businessTypeId`	`int`	Typ podnikatelského subjektu (`BusinessTypeEnum`); určuje, zda jsou povinná pole `individual`, nebo
`company`.
`bankAccount`	`object`	Bankovní účet pro výplaty (číslo účtu/IBAN + BIC, měna, příjemce a adresa
banky).
`individual`	`object`	Údaje o vlastníkovi, který je fyzickou osobou, pro OSVČ. Vzájemně se vylučuje s `company`.
`company`	`object`	Údaje o společnosti, včetně pole `people` s vlastníky, řediteli a oprávněnými
podepisujícími osobami a volitelného `verificationDocument`. Vzájemně se vylučuje s `individual`.

Každá osoba v people (a individual) nese příznaky role.isOwner / isDirector / isRepresentative / isAuthorizedSignatory a volitelná identifikační pole (dateOfBirth, nationalityCountryId, officialIdType/officialIdNumber, address, ownershipPercentage, verificationDocuments). Záznam osoby musí být buď typu „jen pozvánka“, nebo plně vyplněný; částečně vyplněné záznamy osob jsou odmítnuty. Osobu lze odeslat dvěma způsoby:

Jen pozvánka: odešlete jen email a role. Osoba obdrží e-mail s pokyny, jak sama a přímo doplnit své osobní údaje a provést ověření identity, včetně nahrání vlastního dokladu totožnosti; nemusíte za ni shromažďovat nic dalšího a na vaší straně není nutné nahrávat žádný dokument.
Plně vyplněná: všechny osobní údaje osoby (jméno, datum narození, úřední doklad, adresu atd.) odešlete sami. V takovém případě musíte za tuto osobu také nahrát doklad totožnosti; pro každou plně vyplněnou osobu je to povinné, nikoli volitelné.

Dokumenty se nahrávají až poté, co obchodník existuje, protože endpoint pro nahrání dokumentu potřebuje merchantId vrácené voláním Vytvoření obchodníka s onboardingem. Nahraný dokument každé osoby se k ní přiřadí podle relatedOfficialIdNumber. Volitelná pole verificationDocuments.identityDocument, verificationDocuments.additionalDocument a company.verificationDocument přijímají objekt {frontFileId, backFileId} a mohou odkazovat jen na již nahrané soubory, proto je při vytváření nového obchodníka vynechte.

Bez ohledu na to, kolik osob je zadaných jen pozvánkou a kolik plně vyplněných, musíte vždy nahrát registrační či zakládací dokument společnosti, než bude možné obchodníka odeslat ke kontrole KYC.

Tělo odpovědi: stejný tvar {valid, errors} jako u Ověření identity.

Vytvoření obchodníka s onboardingem

Odešle vše z předchozích čtyř kroků jedním voláním, vytvoří obchodníka a zaregistruje jej u preferovaného zpracovatele plateb vaší organizace.

Endpoint: POST /integrator/merchant/onboarding

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
                        }
                    }
                ]
            }
        }
    }'

Parametry:

Pole	Typ	Povinné	Popis
`capability`	`int`	✓	`1` pro Obojí, `2` pro Terminály nebo `3` pro Checkout. Viz funkce online plateb.
`terminal`	`object`	Podle funkce	Údaje o terminálovém kanálu pro Terminály nebo Obojí.
`online`	`object`	Podle funkce	Údaje o online kanálu pro Checkout nebo Obojí.
`name`	`string`	✓	Název obchodníka.
`merchantToken`	`string`		Jedinečný stabilní identifikátor z vašeho systému. Pokud jej neuvedete, vygeneruje se
náhodný token.
`identity`	`object`	✓	Stejný tvar jako u Ověření identity.
`address`	`object`	✓	Stejný tvar jako u Ověření adresy.
`business`	`object`	✓	Stejný tvar jako u Ověření obchodního profilu.
`kyb`	`object`	✓	Stejný tvar jako u Ověření KYB.

Odpovědi:

Kód	Popis
`201`	Obchodník vytvořen a onboarding odeslán
`422`	Neplatné údaje pro onboarding, viz `errors`; obchodník se nevytvoří

Tělo odpovědi (201):

{
    "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 je vyplněné, když zpracovatel vyžaduje, aby obchodník dokončil další hostovaný onboarding (např. ověření identity), než bude moci přijímat ostré platby.

Tělo odpovědi (422):

{
    "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"
        }
    ]
}

Nahrání dokladu totožnosti osoby

Povinné pro každou plně vyplněnou osobu v kyb.company.people / kyb.individual (viz Ověření KYB); osoby zadané jen pozvánkou nahrávají svůj doklad samy přes odkaz z e-mailu.

Endpoint: POST /integrator/merchant/{merchantId}/document

Tělo požadavku je multipart/form-data, nikoli JSON.

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'

Parametry:

Pole	Typ	Povinné	Popis
`paymentProcessorId`	`int`	✓	Vždy `5`.
`documentType`	`int`	✓	Typ dokumentu (`DocumentTypeEnum`: `1` Other, `2` Id, `3` Address, `4` Company,
`5` BankStatement, `6` Passport, `7` RecentFinancials).
`frontFile`	`file`	✓	Snímek přední strany dokumentu.
`backFile`	`file`		Snímek zadní strany dokumentu, pokud ji dokument má.
`relatedOfficialIdNumber`	`string`		`officialIdNumber` osoby z Ověření KYB.
Povinné jen tehdy, když je `documentType` vázaný na osobu (např. Id, Passport, Address); jinak se ignoruje.
`submitMerchant`	`boolean`		Zde ponechte nenastavené/`false`: doklad totožnosti osoby není posledním nahraným souborem dávky.
Na `true` jej nastavte jen při nahrání dokumentu společnosti, jakmile budou nahrány dokumenty všech
osob.

Tělo odpovědi (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k",
    "uploadedAt": "2026-07-17T12:00:00Z"
}

Nahrání dokumentu společnosti

Povinné právě jednou pro každého obchodníka. Pokud údaje o osobách nebyly vyplněny, oprávněná podepisující osoba bude moci tento dokument nahrát přes odkaz z onboardingového e-mailu a tento endpoint není nutné volat.

Endpoint: POST /integrator/merchant/{merchantId}/document

Tělo požadavku je multipart/form-data, nikoli JSON.

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'

Parametry:

Pole	Typ	Povinné	Popis
`paymentProcessorId`	`int`	✓	Vždy `5`.
`documentType`	`int`	✓	V tomto kroku vždy `4` (`Company`).
`frontFile`	`file`	✓	Registrační či zakládací dokument společnosti.
`submitMerchant`	`boolean`		Nastavte na `true`, aby se po nahrání všech povinných
dokumentů spustila kontrola KYC u zpracovatele. Výchozí hodnota je `false`.

Tělo odpovědi (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": null,
    "uploadedAt": "2026-07-17T12:00:00Z"
}

Chybí vám něco na této stránce?Navrhněte funkci. Připojíme tuto stránku, aby tým viděl souvislosti.

API pro onboarding obchodníků

Na této stránce