Merchant Onboarding API

Valider l’identité

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

Paramètres :

Corps de la réponse :

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

Un registrationNumber déjà utilisé par un autre commerçant de votre organisation est renvoyé sous forme d’erreur valid: false avec code: "DUPLICATE_REGISTRATION_NUMBER" plutôt que sous forme de 409 ; cet endpoint renvoie toujours 200.

Valider l’adresse

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

Paramètres :

Corps de la réponse : même structure {valid, errors} que pour Valider l’identité.

Valider le profil d’entreprise

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

Paramètres :

Corps de la réponse : même structure {valid, errors} que pour Valider l’identité.

Valider le KYB

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

Fournissez exactement l’un des deux objets : individual (entrepreneur individuel / indépendant) ou company. Pour une company, listez chaque propriétaire, dirigeant et signataire autorisé dans people.

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

Paramètres :

Chaque personne de people (et individual) porte les indicateurs role.isOwner / isDirector / isRepresentative / isAuthorizedSignatory, ainsi que des champs d’identité facultatifs (dateOfBirth, nationalityCountryId, officialIdType/officialIdNumber, address, ownershipPercentage, verificationDocuments). Une entrée de personne doit être soit sur invitation uniquement, soit entièrement détaillée ; les personnes partiellement renseignées sont refusées. Il existe deux façons de soumettre une personne :

• Sur invitation uniquement : soumettez seulement email et un role. La personne reçoit un e-mail contenant des instructions pour renseigner elle-même ses informations personnelles et effectuer directement la vérification de son identité, y compris le téléversement de sa propre pièce d’identité ; vous n’avez rien d’autre à collecter pour elle, et aucun téléversement de document n’est requis de votre côté.
• Entièrement détaillée : soumettez vous-même toutes les informations personnelles de la personne (nom, date de naissance, pièce d’identité officielle, adresse, etc.). Dans ce cas, vous devez également téléverser une pièce d’identité pour cette personne ; c’est obligatoire, et non facultatif, pour chaque personne entièrement détaillée.

Les documents sont téléversés une fois le commerçant créé, car l’endpoint de téléversement de documents a besoin du merchantId renvoyé par Créer un commerçant avec onboarding. Chaque téléversement est associé à la personne concernée via relatedOfficialIdNumber. Les champs facultatifs verificationDocuments.identityDocument, verificationDocuments.additionalDocument et company.verificationDocument acceptent chacun un objet {frontFileId, backFileId} et ne peuvent référencer que des fichiers déjà téléversés : omettez-les donc lors de la création d’un nouveau commerçant.

Quel que soit le nombre de personnes sur invitation uniquement ou entièrement détaillées, vous devez toujours téléverser le document d’immatriculation/de constitution de la société avant que le commerçant puisse être soumis à l’examen KYC.

Corps de la réponse : même structure {valid, errors} que pour Valider l’identité.

Créer un commerçant avec onboarding

Soumet en un seul appel tout le contenu des quatre étapes précédentes, crée le commerçant et l’enregistre auprès du processeur de paiement préféré de votre organisation.

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

Paramètres :

Réponses :

Corps de la réponse (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 est renseigné lorsque le processeur exige que le commerçant suive un parcours d’onboarding hébergé supplémentaire (par exemple une vérification d’identité) avant de pouvoir traiter des paiements réels.

Corps de la réponse (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"
        }
    ]
}

Téléverser la pièce d’identité d’une personne

Obligatoire pour chaque personne entièrement détaillée dans kyb.company.people / kyb.individual (voir Valider le KYB) ; les personnes sur invitation uniquement téléversent elles-mêmes la leur, via le lien reçu par e-mail.

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

Le corps de la requête est au format multipart/form-data, et non 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'

Paramètres :

Corps de la réponse (200) :

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

Téléverser le document de la société

Obligatoire exactement une fois par commerçant. Si les informations des personnes n’ont pas été renseignées, le signataire autorisé pourra téléverser ce document à l’aide du lien figurant dans l’e-mail d’onboarding, et il n’est pas nécessaire d’appeler cet endpoint.

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

Le corps de la requête est au format multipart/form-data, et non 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'

Paramètres :

Corps de la réponse (200) :

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