Tapaya
PrehľadPlatform APIAPI na onboarding obchodníkov

API na onboarding obchodníkov

Vytvárajte obchodníkov a odosielajte ich onboarding alebo ich na onboarding pozývajte cez Tapaya Platform API.

Všetky požiadavky na tejto stránke používajú váš Server Secret Token. Pozrite si Autentifikácia.

Jeden onboarding pre platby v predajni aj online

Obchodník môže v jednej žiadosti o onboarding požiadať o Prijímanie platieb v predajni, online platby alebo o oboje. Táto stránka platí pre každú integráciu: Accept SDK, aplikáciu Tapaya Terminal aj Checkout. Použite ju na vytváranie a správu obchodníkov cez API namiesto Tapaya Platform UI. Požiadajte o platobné funkcie, ktoré obchodník potrebuje. Samotné schválenie pre platby v predajni online platby nepovoľuje.

Vytvorením obchodníka pomocou POST /integrator/merchant alebo pomocou POST /merchant/auth/register v integrácii Accept SDK sa vytvorí jeho účet, ale obchodník nemôže prijímať ostré platby v predajni ani online, kým nie je onboarding dokončený. Pre online platby požiadajte o funkciu Checkout a počkajte na schválenie spracovateľom online platieb a na nastavenie brány. Obchodníci sa automaticky zobrazia v nastaveniach Checkoutu, kde môžete overiť ich pripravenosť a nastaviť kľúče a peňaženky. Tapaya podporuje niekoľko spôsobov onboardingu; všetky možno spravovať z Tapaya Platform UI a tam, kde je to vhodné, automatizovať.

PostupKedy ho použiťVstupný bod API
Tapaya Platform UIOnboarding za obchodníka dokončí váš prevádzkový tím.Vytvorte alebo vyberte obchodníka v Tapaya Platform UI a otvorte tam hostovaný onboarding.
Vlastné UIÚdaje na onboarding zhromažďujete a overujete vo svojom produkte.Overte jednotlivé časti pomocou POST /integrator/merchant/onboarding/validate/* a potom ich odošlite pomocou POST /integrator/merchant/onboarding. Podrobnosti nižšie.
E-mailová pozvánkaZnámy obchodník dostane jednorazovú pozvánku na samostatný onboarding.Pozvánku odošlite pomocou POST /integrator/merchant/send-registration-invite; uveďte merchantToken, ak chcete pozvánku zviazať s existujúcim základným záznamom obchodníka, a potom ju vypíšte alebo zrušte cez /integrator/merchant/invites.
Odkaz kampaneViacerí obchodníci alebo zatiaľ neznámi obchodníci používajú opakovane použiteľný odkaz na samostatnú registráciu.Odkaz vytvorte pomocou POST /integrator/merchant/reusable-registration-invites; odkazy vypíšete alebo zrušíte cez ten istý endpoint.

Podrobné porovnanie týchto postupov nájdete v sprievodcovi onboardingom obchodníkov.

Žiadosť o funkcie online platieb

POST /integrator/merchant/onboarding vyžaduje capability. Rovnakú hodnotu funkcie použite pri overovaní obchodného profilu:

HodnotaFunkciaÚdaje o kanáli
1ObojeUveďte terminal aj online. Každý kanál vyžaduje vlastné schválenie.
2TerminályUveďte terminal pre platby v predajni.
3CheckoutUveďte online pre online platby. Terminál nie je potrebný.

Pre Checkout pridajte popri identite obchodníka, adrese, zdieľanom objekte business a údajoch KYB nasledujúce polia najvyššej úrovne. Rovnaké polia kanála platia aj pre 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 }]
	}
}

Sumy sú v najmenších jednotkách meny. Web na online predaj musí používať HTTP alebo HTTPS a jeho názov hostiteľa musí obsahovať www. statementDescriptor má 5 až 22 znakov. purchaseChargeTiming je 1 pre zadanie objednávky, 2 pre odoslanie alebo 3 pre doručenie. averageDeliveryDays je 0 až 999. Uveďte jednu až štyri jedinečné topCountries, ktorých percentuálne podiely dávajú v súčte 100.

Zdieľané údaje o podpore a finančné údaje ponechajte v business. V režime sekcií kanálov uveďte MCC, popis na výpise (statement descriptor), popis produktu a odhady transakcií v príslušnom objekte terminal alebo online. Pred odoslaním onboardingu payload overte a opravte vrátené chyby polí špecifické pre daný kanál.

Pozvanie obchodníka na dokončenie hostovaného onboardingu

Tento postup použite, keď má formulár KYB hostovať Tapaya, ale vytváranie obchodníkov chcete aj naďalej riadiť zo svojho backendu.

Odporúčané, ak merchantToken spravujete vy

Ak identifikátor obchodníka, ktorý neskôr používa SDK alebo váš back office, spravuje váš systém, najprv vytvorte základný záznam obchodníka pomocou POST /merchant/auth/register alebo POST /integrator/merchant a potom zavolajte POST /integrator/merchant/send-registration-invite s tým istým merchantToken. Hostovaný onboarding tak zostane pripojený k tomuto obchodníkovi a nevytvorí sa druhý.

Odporúčaný postup je:

  1. Vytvorte základný záznam obchodníka:
    • POST /merchant/auth/register alebo
    • POST /integrator/merchant
  2. Odošlite pozvánku na hostovaný onboarding pomocou POST /integrator/merchant/send-registration-invite
  3. V prípade potreby zdieľajte vrátenú adresu registrationUrl s obchodníkom a nechajte ho vyplniť formulár hostovaný spoločnosťou Tapaya
  4. Pripravenosť obchodníka zisťujte opakovaným dopytovaním cez 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"
    }'

Parametre:

PoleTypPovinnéPopis
emailstring✓E-mailová adresa, na ktorú má prísť odkaz na hostovaný onboarding.
merchantTokenstringExistujúci token obchodníka, s ktorým sa má pozvánka zviazať. Použite ho, ak ste už základný záznam obchodníka vytvorili a chcete, aby hostovaný onboarding vyplnil práve tohto obchodníka. Ak ho vynecháte, dokončením pozvánky sa vytvorí nový obchodník.

Odpovede:

KódPopis
200Pozvánka vytvorená. Odpoveď obsahuje registrationUrl
400Chyba validácie požiadavky
401Neautorizované
404Organizácia alebo obchodník sa nenašli
409Konflikt

Telo odpovede:

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

Tapaya sa tiež pokúsi tento odkaz odoslať e-mailom. Doručenie e-mailu však nie je zaručené, preto vrátenú adresu registrationUrl vždy považujte za rozhodujúci zdroj pre svoje UI a nástroje podpory.

Nezamieňajte s pozvánkou používateľa obchodníka

POST /integrator/merchant/{merchantId}/invite je iný postup. Pozýva používateľa platformy na prístup k už existujúcemu účtu obchodníka. Nezačína onboarding KYB a nevytvára ani neaktualizuje profil obchodníka.

Odoslanie onboardingu cez API

Ak chcete údaje na onboarding zhromažďovať vo vlastnom produkte namiesto presmerovania obchodníkov na Tapaya Platform, odošlite ich priamo. Každú časť overujte priebežne, ako ju obchodník vypĺňa, pomocou endpointov validate/* uvedených nižšie a potom všetko odošlite jedným volaním, ktoré vytvorí obchodníka spolu s jeho onboardingovým profilom a zaregistruje ho u preferovaného spracovateľa platieb vašej organizácie.

Súhlas obchodníka a informácie o ochrane osobných údajov

Pred odoslaním údajov na onboarding cez API musíte získať súhlas obchodníka s obchodnými podmienkami Tapaya pre integrátorov a zásadami ochrany osobných údajov Tapaya. Pridajte do svojho onboardingového formulára začiarkavacie políčko s odkazmi na oba dokumenty alebo na dokumenty Tapaya odkážte z textu podmienok, s ktorými obchodník súhlasí. Tapaya musíte tiež uviesť ako sprostredkovateľa spracúvania údajov vo svojich vlastných zásadách ochrany osobných údajov.

Pri zlyhaní sa obchodník nevytvorí

POST /integrator/merchant/onboarding vytvorí obchodníka a zároveň odošle onboarding jediným volaním. Ak sú údaje na onboarding neplatné, vráti 422 s chybami na úrovni polí a žiadny obchodník sa nevytvorí; neexistuje teda žiadny obchodník s rozpracovaným onboardingom, ktorého by bolo potrebné odstrániť alebo pri ktorom by bolo potrebné pokračovať.

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

Parametre:

PoleTypPovinnéPopis
legalNamestring✓Oficiálny názov firmy alebo meno fyzickej osoby, ktorá je držiteľom účtu.
businessTypeIdint✓Typ podnikateľského subjektu (BusinessTypeEnum).
emailstring✓Kontaktná e-mailová adresa.
registrationNumberstring✓Oficiálne registračné číslo firmy (IČO). Kontroluje sa na duplicity v rámci vašej
organizácie.
vatNumberstringIČ DPH, ak existuje.
incorporationDatedateDátum právneho vzniku firmy (YYYY-MM-DD).

Telo odpovede:

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

Hodnota registrationNumber, ktorú už používa iný obchodník vo vašej organizácii, sa vráti ako chyba valid: false s code: "DUPLICATE_REGISTRATION_NUMBER", nie ako 409; tento endpoint vždy vracia 200.

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

Parametre:

PoleTypPovinnéPopis
line1string✓Prvý riadok adresy.
line2stringDruhý riadok adresy, ak je potrebný.
citystring✓Názov mesta.
postalCodestring✓PSČ.
statestringŠtát alebo región, ak je potrebný.
countryIdint✓Krajina (CountryEnum).

Telo odpovede: rovnaký tvar {valid, errors} ako pri Overení identity.

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

Parametre:

PoleTypPovinnéPopis
capabilityint✓Použite funkciu, ktorú odošlete v onboardingu. Pre Checkout alebo Oboje uveďte údaje o kanáli.
mccstring✓Štvormiestny kód kategórie obchodníka (Merchant Category Code). V režime sekcií kanálov použite terminal.mcc alebo online.mcc.
urlstringURL webu firmy. Povinné je buď url, alebo productDescription.
productDescriptionstringPopis produktov alebo služieb. Povinné je buď url, alebo
productDescription.
supportPhonestring✓Telefónne číslo zákazníckej podpory vo formáte E.164.
statementDescriptorstring✓Text zobrazený na bankových výpisoch zákazníkov (1–22 znakov).
averageItemValuelongPriemerná hodnota transakcie v najmenších jednotkách meny.
expectedMonthlyTurnoverlongOčakávaný mesačný obrat v najmenších jednotkách meny.
numberOfEmployeesintPočet zamestnancov firmy.
annualTurnoverlongRočný obrat v najmenších jednotkách meny.
balanceSheetTotallongBilančná suma v najmenších jednotkách meny.

Telo odpovede: rovnaký tvar {valid, errors} ako pri Overení identity.

Overenie KYB

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

Uveďte práve jedno z polí individual (živnostník / SZČO) alebo company. Pri company uveďte v people každého vlastníka, riaditeľa a oprávnenú podpisujúcu 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
                    }
                }
            ]
        }
    }'

Parametre:

PoleTypPovinnéPopis
businessTypeIdintTyp podnikateľského subjektu (BusinessTypeEnum); určuje, či sú povinné polia individual, alebo
company.
bankAccountobjectBankový účet na výplaty (číslo účtu/IBAN + BIC, mena, príjemca a adresa
banky).
individualobjectÚdaje o vlastníkovi, ktorý je fyzickou osobou, pre živnostníkov. Vzájomne sa vylučuje s company.
companyobjectÚdaje o spoločnosti vrátane poľa people s vlastníkmi, riaditeľmi a oprávnenými
podpisujúcimi osobami a voliteľného verificationDocument. Vzájomne sa vylučuje s individual.

Každá osoba v people (a individual) nesie príznaky role.isOwner / isDirector / isRepresentative / isAuthorizedSignatory a voliteľné identifikačné polia (dateOfBirth, nationalityCountryId, officialIdType/officialIdNumber, address, ownershipPercentage, verificationDocuments). Záznam osoby musí byť buď typu „iba pozvánka“, alebo úplne vyplnený; čiastočne vyplnené záznamy osôb sa odmietnu. Osobu možno odoslať dvoma spôsobmi:

  • Iba pozvánka: odošlite iba email a role. Osoba dostane e-mail s pokynmi, ako sama a priamo doplniť svoje osobné údaje a vykonať overenie identity vrátane nahratia vlastného dokladu totožnosti; nemusíte za ňu zhromažďovať nič ďalšie a na vašej strane nie je potrebné nahrávať žiadny dokument.
  • Úplne vyplnená: všetky osobné údaje osoby (meno, dátum narodenia, úradný doklad, adresu atď.) odošlete sami. V takom prípade musíte za túto osobu aj nahrať doklad totožnosti; pre každú úplne vyplnenú osobu je to povinné, nie voliteľné.

Dokumenty sa nahrávajú až potom, ako obchodník existuje, pretože endpoint na nahratie dokumentu potrebuje merchantId vrátené volaním Vytvorenie obchodníka s onboardingom. Nahratý dokument každej osoby sa k nej priradí podľa relatedOfficialIdNumber. Voliteľné polia verificationDocuments.identityDocument, verificationDocuments.additionalDocument a company.verificationDocument prijímajú objekt {frontFileId, backFileId} a môžu odkazovať iba na už nahraté súbory, preto ich pri vytváraní nového obchodníka vynechajte.

Bez ohľadu na to, koľko osôb je zadaných iba pozvánkou a koľko úplne vyplnených, musíte vždy nahrať registračný alebo zakladací dokument spoločnosti predtým, ako bude možné obchodníka odoslať na kontrolu KYC.

Telo odpovede: rovnaký tvar {valid, errors} ako pri Overení identity.

Vytvorenie obchodníka s onboardingom

Odošle všetko z predchádzajúcich štyroch krokov jedným volaním, vytvorí obchodníka a zaregistruje ho u preferovaného spracovateľa platieb vašej organizácie.

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

Parametre:

PoleTypPovinnéPopis
capabilityint✓1 pre Oboje, 2 pre Terminály alebo 3 pre Checkout. Pozrite si funkcie online platieb.
terminalobjectPodľa funkcieÚdaje o terminálovom kanáli pre Terminály alebo Oboje.
onlineobjectPodľa funkcieÚdaje o online kanáli pre Checkout alebo Oboje.
namestring✓Názov obchodníka.
merchantTokenstringJedinečný stabilný identifikátor z vášho systému. Ak ho neuvediete, vygeneruje sa
náhodný token.
identityobject✓Rovnaký tvar ako pri Overení identity.
addressobject✓Rovnaký tvar ako pri Overení adresy.
businessobject✓Rovnaký tvar ako pri Overení obchodného profilu.
kybobject✓Rovnaký tvar ako pri Overení KYB.

Odpovede:

KódPopis
201Obchodník vytvorený a onboarding odoslaný
422Neplatné údaje na onboarding, pozrite si errors; obchodník sa nevytvorí

Telo odpovede (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 vyplnené, keď spracovateľ vyžaduje, aby obchodník dokončil ďalší hostovaný onboarding (napr. overenie identity), skôr ako bude môcť prijímať ostré platby.

Telo odpovede (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"
        }
    ]
}

Nahratie dokladu totožnosti osoby

Povinné pre každú úplne vyplnenú osobu v kyb.company.people / kyb.individual (pozrite si Overenie KYB); osoby zadané iba pozvánkou nahrávajú svoj doklad samy cez odkaz z e-mailu.

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

Telo požiadavky je multipart/form-data, nie 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'

Parametre:

PoleTypPovinnéPopis
paymentProcessorIdint✓Vždy 5.
documentTypeint✓Typ dokumentu (DocumentTypeEnum: 1 Other, 2 Id, 3 Address, 4 Company,
5 BankStatement, 6 Passport, 7 RecentFinancials).
frontFilefile✓Snímka prednej strany dokumentu.
backFilefileSnímka zadnej strany dokumentu, ak ju dokument má.
relatedOfficialIdNumberstringofficialIdNumber osoby z Overenia KYB.
Povinné iba vtedy, keď je documentType viazaný na osobu (napr. Id, Passport, Address); inak sa ignoruje.
submitMerchantbooleanTu ponechajte nenastavené/false: doklad totožnosti osoby nie je posledným nahratým súborom dávky.
Na true ho nastavte iba pri nahratí dokumentu spoločnosti, keď budú nahraté dokumenty všetkých
osôb.

Telo odpovede (200):

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

Nahratie dokumentu spoločnosti

Povinné práve raz pre každého obchodníka. Ak údaje o osobách neboli vyplnené, oprávnená podpisujúca osoba bude môcť tento dokument nahrať cez odkaz z onboardingového e-mailu a tento endpoint nie je potrebné volať.

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

Telo požiadavky je multipart/form-data, nie 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'

Parametre:

PoleTypPovinnéPopis
paymentProcessorIdint✓Vždy 5.
documentTypeint✓V tomto kroku vždy 4 (Company).
frontFilefile✓Registračný alebo zakladací dokument spoločnosti.
submitMerchantbooleanNastavte na true, aby sa po nahratí všetkých povinných
dokumentov spustila kontrola KYC u spracovateľa. Predvolená hodnota je false.

Telo odpovede (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": null,
    "uploadedAt": "2026-07-17T12:00:00Z"
}
Chýba vám niečo na tejto stránke?Navrhnite funkciu. Pripojíme túto stránku, aby tím videl súvislosti.

Platform API

Prostredia, autentifikácia a sekcie Tapaya Platform API, ktoré vaša integrácia potrebuje.

Reporting a platby

Výpis obchodníkov, história a podrobnosti platieb, štatistiky a vrátenie platieb.

Na tejto stránke

Žiadosť o funkcie online platiebPozvanie obchodníka na dokončenie hostovaného onboardinguOdoslanie onboardingu cez APIOverenie identityOverenie adresyOverenie obchodného profiluOverenie KYBVytvorenie obchodníka s onboardingomNahratie dokladu totožnosti osobyNahratie dokumentu spoločnosti