Tapaya
PanoramicaPlatform APIMerchant Onboarding API

Merchant Onboarding API

Creare esercenti e inviarne l'onboarding, oppure invitarli a completarlo, tramite la Tapaya Platform API.

Tutte le richieste di questa pagina utilizzano il Suo Server Secret Token. Consulti Autenticazione.

Un unico onboarding per pagamenti in presenza e online

Un esercente può richiedere l'Accettazione in presenza, i Pagamenti online o entrambi in un'unica richiesta di onboarding. Questa pagina vale per ogni integrazione: l'Accept SDK, l'app Tapaya Terminal e il Checkout. La utilizzi per creare e gestire gli esercenti tramite l'API anziché tramite la Tapaya Platform UI. Richieda le funzionalità di pagamento di cui l'esercente ha bisogno. Un'approvazione per i pagamenti in presenza, da sola, non abilita i pagamenti online.

La creazione di un esercente con POST /integrator/merchant, oppure con POST /merchant/auth/register in un'integrazione dell'Accept SDK, ne crea l'account, ma l'esercente non può elaborare pagamenti live, né in presenza né online, finché l'onboarding non è completato. Per i pagamenti online, richieda la funzionalità Checkout e attenda l'approvazione del processore online e la configurazione del gateway. Gli esercenti compaiono automaticamente nelle impostazioni di Checkout, dove può verificarne lo stato di preparazione e configurare chiavi e wallet. Tapaya supporta diverse modalità di onboarding; tutte possono essere gestite dalla Tapaya Platform UI e, dove opportuno, automatizzate.

FlussoQuando utilizzarloPunto di accesso API
Tapaya Platform UIIl Suo team operativo completa l'onboarding per conto dell'esercente.Crei o selezioni l'esercente nella Tapaya Platform UI e apra lì l'onboarding ospitato.
UI propriaLei raccoglie e convalida le informazioni di onboarding nel Suo prodotto.Convalidi le sezioni con POST /integrator/merchant/onboarding/validate/*, quindi le invii con POST /integrator/merchant/onboarding. Dettagli più avanti.
Invito via emailUn esercente noto riceve un invito monouso per completare autonomamente l'onboarding.Invii un invito con POST /integrator/merchant/send-registration-invite; includa merchantToken per collegare l'invito a un record di base dell'esercente esistente, quindi lo elenchi o lo revochi tramite /integrator/merchant/invites.
Link di campagnaPiù esercenti, o esercenti non ancora noti, utilizzano un link riutilizzabile per registrarsi autonomamente.Crei un link con POST /integrator/merchant/reusable-registration-invites; elenchi o revochi i link tramite la stessa risorsa.

Per un confronto dettagliato di questi flussi, consulti la guida all'onboarding degli esercenti.

Richiedere le funzionalità di pagamento online

POST /integrator/merchant/onboarding richiede capability. Utilizzi la stessa funzionalità quando convalida il profilo dell'attività:

ValoreFunzionalitàDati del canale
1EntrambiFornisca terminal e online. Ogni canale richiede una propria approvazione.
2TerminaliFornisca terminal per i pagamenti in presenza.
3CheckoutFornisca online per i pagamenti online. Non è richiesto alcun terminale.

Per il Checkout, aggiunga i seguenti campi di primo livello insieme ai dati di identità, all'indirizzo, alla sezione condivisa business e ai dati KYB dell'esercente. Gli stessi campi del canale valgono per 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 }]
	}
}

Gli importi sono espressi nell'unità minima della valuta. Il sito web online deve utilizzare HTTP o HTTPS e il suo hostname deve contenere www. statementDescriptor ha una lunghezza da 5 a 22 caratteri. purchaseChargeTiming vale 1 per ordine effettuato, 2 per ordine spedito o 3 per ordine ricevuto. averageDeliveryDays va da 0 a 999. Fornisca da uno a quattro topCountries univoci, le cui percentuali diano in totale 100.

Mantenga i dati condivisi di assistenza e finanziari in business. Nella modalità a sezioni per canale, inserisca MCC, statement descriptor, descrizione dei prodotti e stime delle transazioni nel relativo oggetto terminal o online. Convalidi il payload prima di inviare l'onboarding e risolva gli errori sui campi specifici del canale restituiti.

Invitare un esercente a completare l'onboarding ospitato

Utilizzi questo flusso quando il modulo KYB deve essere ospitato da Tapaya, ma Lei desidera comunque controllare la creazione dell'esercente dal Suo backend.

Consigliato se il merchantToken è gestito da Lei

Se l'identificativo dell'esercente usato in seguito dall'SDK o dal Suo back office è gestito dal Suo sistema, crei prima il record di base dell'esercente con POST /merchant/auth/register o POST /integrator/merchant, quindi chiami POST /integrator/merchant/send-registration-invite con lo stesso merchantToken. In questo modo l'onboarding ospitato resta collegato a quell'esercente invece di crearne un secondo.

La sequenza consigliata è:

  1. Creare il record di base dell'esercente:
    • POST /merchant/auth/register, oppure
    • POST /integrator/merchant
  2. Inviare l'invito all'onboarding ospitato con POST /integrator/merchant/send-registration-invite
  3. Se necessario, condividere con l'esercente il registrationUrl restituito e lasciargli completare il modulo ospitato da Tapaya
  4. Interrogare periodicamente lo stato di preparazione dell'esercente tramite 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"
    }'

Parametri:

CampoTipoObbligatorioDescrizione
emailstring✓Indirizzo email che deve ricevere il link all'onboarding ospitato.
merchantTokenstringToken dell'esercente esistente a cui collegare l'invito. Lo utilizzi quando ha già creato il record di base dell'esercente e desidera che l'onboarding ospitato completi i dati di quello stesso esercente. Se omesso, il completamento dell'invito crea un nuovo esercente.

Risposte:

CodiceDescrizione
200Invito creato. La risposta include registrationUrl
400Errore di convalida della richiesta
401Non autorizzato
404Organizzazione o esercente non trovato
409Conflitto

Corpo della risposta:

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

Tapaya tenta inoltre di inviare questo link via email. La consegna dell'email avviene secondo il principio del best effort, quindi consideri sempre il registrationUrl restituito come fonte attendibile per la Sua UI e per gli strumenti di assistenza.

Da non confondere con l'invito di un utente dell'esercente

POST /integrator/merchant/{merchantId}/invite è un flusso diverso. Invita un utente della piattaforma ad accedere a un account dell'esercente già esistente. Non avvia l'onboarding KYB e non crea né aggiorna il profilo di un esercente.

Inviare l'onboarding tramite l'API

Se desidera raccogliere le informazioni di onboarding nel Suo prodotto anziché indirizzare gli esercenti alla Tapaya Platform, le invii direttamente. Convalidi ogni sezione man mano che l'esercente la compila con gli endpoint validate/* descritti di seguito, quindi invii tutto in un'unica chiamata, che crea insieme l'esercente e il suo profilo di onboarding e lo registra presso il processore di pagamento preferito dalla Sua organizzazione.

Consenso dell'esercente e informativa sulla privacy

Prima di inviare i dati di onboarding tramite l'API, deve ottenere il consenso dell'esercente ai Termini e condizioni Tapaya per gli integratori e all'Informativa sulla privacy di Tapaya. Aggiunga al Suo modulo di onboarding una casella di spunta con il link a entrambi i documenti, oppure inserisca un link ai documenti Tapaya nel testo delle condizioni a cui l'esercente presta il consenso. Deve inoltre indicare Tapaya come responsabile del trattamento dei dati nella Sua informativa sulla privacy.

Nessun esercente creato in caso di errore

POST /integrator/merchant/onboarding crea l'esercente e invia l'onboarding in un'unica chiamata. Se i dati di onboarding non sono validi, restituisce 422 con errori a livello di campo e non viene creato alcun esercente; non esiste alcun esercente con onboarding parziale da ripulire o da riprendere.

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

Parametri:

CampoTipoObbligatorioDescrizione
legalNamestring✓Ragione sociale dell'attività o nome del titolare persona fisica.
businessTypeIdint✓Tipo di entità aziendale (BusinessTypeEnum).
emailstring✓Indirizzo email di contatto.
registrationNumberstring✓Numero ufficiale di registrazione dell'attività. Viene verificata l'assenza di duplicati all'interno della Sua
organizzazione.
vatNumberstringPartita IVA, se applicabile.
incorporationDatedateData di costituzione legale dell'attività (YYYY-MM-DD).

Corpo della risposta:

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

Un registrationNumber già utilizzato da un altro esercente della Sua organizzazione viene restituito come errore valid: false con code: "DUPLICATE_REGISTRATION_NUMBER" anziché come 409; questo endpoint restituisce sempre 200.

Convalidare l'indirizzo

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

Parametri:

CampoTipoObbligatorioDescrizione
line1string✓Prima riga dell'indirizzo.
line2stringSeconda riga dell'indirizzo, se applicabile.
citystring✓Nome della città.
postalCodestring✓Codice postale (CAP).
statestringStato o regione, se applicabile.
countryIdint✓Paese (CountryEnum).

Corpo della risposta: stessa struttura {valid, errors} di Convalidare l'identità.

Convalidare il profilo dell'attività

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

Parametri:

CampoTipoObbligatorioDescrizione
capabilityint✓Utilizzi la funzionalità che invierà per l'onboarding. Per Checkout o Entrambi, fornisca i dati del canale.
mccstring✓Merchant Category Code a quattro cifre. Nella modalità a sezioni per canale, utilizzi terminal.mcc o online.mcc.
urlstringURL del sito web dell'attività. È obbligatorio url oppure productDescription.
productDescriptionstringDescrizione dei prodotti o servizi. È obbligatorio url oppure
productDescription.
supportPhonestring✓Numero di telefono dell'assistenza clienti, in formato E.164.
statementDescriptorstring✓Testo mostrato sugli estratti conto bancari dei clienti (1–22 caratteri).
averageItemValuelongValore medio delle transazioni, nell'unità minore della valuta.
expectedMonthlyTurnoverlongFatturato mensile previsto, nell'unità minore della valuta.
numberOfEmployeesintNumero di dipendenti dell'attività.
annualTurnoverlongFatturato annuo, nell'unità minore della valuta.
balanceSheetTotallongTotale di bilancio, nell'unità minore della valuta.

Corpo della risposta: stessa struttura {valid, errors} di Convalidare l'identità.

Convalidare i dati KYB

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

Fornisca esattamente uno tra individual (ditta individuale / lavoratore autonomo) e company. Per una company, elenchi in people ogni titolare, amministratore e firmatario autorizzato.

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

Parametri:

CampoTipoObbligatorioDescrizione
businessTypeIdintTipo di entità aziendale (BusinessTypeEnum); determina se sono obbligatori i campi individual o
company.
bankAccountobjectConto bancario per gli accrediti (numero di conto/IBAN + BIC, valuta, beneficiario e indirizzo
della banca).
individualobjectDati del titolare persona fisica, per le ditte individuali. Mutuamente esclusivo con company.
companyobjectDati della società, incluso un array people di titolari, amministratori e firmatari
autorizzati, oltre a un verificationDocument facoltativo. Mutuamente esclusivo con individual.

Ogni persona in people (e in individual) ha i flag role.isOwner / isDirector / isRepresentative / isAuthorizedSignatory, oltre a campi di identità facoltativi (dateOfBirth, nationalityCountryId, officialIdType/officialIdNumber, address, ownershipPercentage, verificationDocuments). Una persona deve essere inserita solo tramite invito oppure con tutti i dati; le persone compilate solo in parte vengono rifiutate. Esistono due modi per inviare una persona:

  • Solo invito: invii soltanto email e un role. La persona riceve un'email con le istruzioni per completare direttamente i propri dati personali e la verifica dell'identità, incluso il caricamento del proprio documento d'identità; Lei non deve raccogliere nient'altro per questa persona e non è richiesto alcun caricamento di documenti da parte Sua.
  • Dati completi: invii Lei stesso tutti i dati personali della persona (nome, data di nascita, documento d'identità ufficiale, indirizzo, ecc.). In questo caso deve anche caricare un documento d'identità per quella persona; è obbligatorio, non facoltativo, per ogni persona inserita con dati completi.

I documenti vengono caricati dopo che l'esercente è stato creato, perché l'endpoint di caricamento dei documenti richiede il merchantId restituito da Creare l'esercente con l'onboarding. Il documento caricato per ciascuna persona viene associato a quest'ultima tramite relatedOfficialIdNumber. I campi facoltativi verificationDocuments.identityDocument, verificationDocuments.additionalDocument e company.verificationDocument accettano ciascuno un oggetto {frontFileId, backFileId} e possono fare riferimento solo a file già caricati, quindi li ometta quando crea un nuovo esercente.

Indipendentemente da quante persone siano inserite solo tramite invito o con dati completi, deve sempre caricare il documento di registrazione/costituzione della società prima che l'esercente possa essere inviato alla revisione KYC.

Corpo della risposta: stessa struttura {valid, errors} di Convalidare l'identità.

Creare l'esercente con l'onboarding

Invia in un'unica chiamata tutti i dati dei quattro passaggi precedenti, crea l'esercente e lo registra presso il processore di pagamento preferito dalla Sua organizzazione.

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

Parametri:

CampoTipoObbligatorioDescrizione
capabilityint✓1 per Entrambi, 2 per Terminali o 3 per Checkout. Consulti le funzionalità di pagamento online.
terminalobjectIn base alla funzionalitàDati del canale terminale per Terminali o Entrambi.
onlineobjectIn base alla funzionalitàDati del canale online per Checkout o Entrambi.
namestring✓Il nome dell'esercente.
merchantTokenstringUn identificativo univoco e stabile proveniente dal Suo sistema. Se non viene fornito, viene generato un
token casuale.
identityobject✓Stessa struttura di Convalidare l'identità.
addressobject✓Stessa struttura di Convalidare l'indirizzo.
businessobject✓Stessa struttura di Convalidare il profilo dell'attività.
kybobject✓Stessa struttura di Convalidare i dati KYB.

Risposte:

CodiceDescrizione
201Esercente creato e onboarding inviato
422Dati di onboarding non validi, si veda errors; l'esercente non viene creato

Corpo della risposta (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 viene valorizzato quando il processore richiede all'esercente di completare un ulteriore flusso di onboarding ospitato (ad es. la verifica dell'identità) prima di poter elaborare pagamenti live.

Corpo della risposta (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"
        }
    ]
}

Caricare il documento d'identità di una persona

Obbligatorio per ogni persona inserita con dati completi in kyb.company.people / kyb.individual (si veda Convalidare i dati KYB); le persone inserite solo tramite invito caricano invece il proprio documento tramite il link ricevuto via email.

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

Il corpo della richiesta è multipart/form-data, 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'

Parametri:

CampoTipoObbligatorioDescrizione
paymentProcessorIdint✓Sempre 5.
documentTypeint✓Tipo di documento (DocumentTypeEnum: 1 Other, 2 Id, 3 Address, 4 Company,
5 BankStatement, 6 Passport, 7 RecentFinancials).
frontFilefile✓Immagine del fronte del documento.
backFilefileImmagine del retro del documento, se applicabile.
relatedOfficialIdNumberstringL'officialIdNumber della persona indicato in Convalidare i dati KYB.
Obbligatorio solo quando documentType è legato a una persona (ad es. Id, Passport, Address); altrimenti viene ignorato.
submitMerchantbooleanQui lo lasci non impostato/false: il documento d'identità di una persona non è l'ultimo caricamento del lotto.
Lo imposti su true solo nel caricamento del documento della società, dopo che i documenti di tutte le persone sono stati
caricati.

Corpo della risposta (200):

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

Caricare il documento della società

Obbligatorio esattamente una volta per esercente. Se i dati delle persone non sono stati compilati, il firmatario autorizzato potrà caricarlo tramite il link contenuto nell'email di onboarding e non è necessario chiamare questo endpoint.

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

Il corpo della richiesta è multipart/form-data, 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'

Parametri:

CampoTipoObbligatorioDescrizione
paymentProcessorIdint✓Sempre 5.
documentTypeint✓Sempre 4 (Company) per questo passaggio.
frontFilefile✓Il documento di registrazione/costituzione della società.
submitMerchantbooleanLo imposti su true per avviare la revisione KYC del processore, ora che tutti i documenti
obbligatori sono stati caricati. Il valore predefinito è false.

Corpo della risposta (200):

{
    "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
    "backFileId": null,
    "uploadedAt": "2026-07-17T12:00:00Z"
}
Manca qualcosa in questa pagina?Richieda una funzionalità. Alleghiamo questa pagina, così il team vede il contesto.

Platform API

Ambienti, autenticazione e quali sezioni della Tapaya Platform API servono alla Sua integrazione.

Reportistica e pagamenti

Elencare gli esercenti, recuperare lo storico e i dettagli dei pagamenti, consultare le statistiche e rimborsare i pagamenti.

In questa pagina

Richiedere le funzionalità di pagamento onlineInvitare un esercente a completare l'onboarding ospitatoInviare l'onboarding tramite l'APIConvalidare l'identitàConvalidare l'indirizzoConvalidare il profilo dell'attivitàConvalidare i dati KYBCreare l'esercente con l'onboardingCaricare il documento d'identità di una personaCaricare il documento della società