# Merchant Onboarding API (/it/platform-api/merchant_onboarding) Tutte le richieste di questa pagina utilizzano il Suo Server Secret Token. Consulti [Autenticazione](/platform-api#authentication). Un esercente può richiedere l'[Accettazione in presenza](/in-store), i [Pagamenti online](/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](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations), 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](/online/integration/checkout_settings), 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. | Flusso | Quando utilizzarlo | Punto di accesso API | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tapaya Platform UI** | Il 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 propria** | Lei 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 email** | Un 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 campagna** | Più 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](/merchants/onboarding). ## Richiedere le funzionalità di pagamento online [#request-online-payment-capabilities] `POST /integrator/merchant/onboarding` richiede `capability`. Utilizzi la stessa funzionalità quando convalida il profilo dell'attività: | Valore | Funzionalità | Dati del canale | | ------ | ------------ | ------------------------------------------------------------------------------ | | `1` | Entrambi | Fornisca `terminal` e `online`. Ogni canale richiede una propria approvazione. | | `2` | Terminali | Fornisca `terminal` per i pagamenti in presenza. | | `3` | Checkout | Fornisca `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`: ```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 }] } } ``` 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 [#invite-a-merchant-to-complete-hosted-onboarding] Utilizzi questo flusso quando il modulo KYB deve essere ospitato da Tapaya, ma Lei desidera comunque controllare la creazione dell'esercente dal Suo backend. 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 ```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" }' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | --------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | `string` | ✓ | Indirizzo email che deve ricevere il link all'onboarding ospitato. | | `merchantToken` | `string` | | Token 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:** | Codice | Descrizione | | ------ | ---------------------------------------------------- | | `200` | Invito creato. La risposta include `registrationUrl` | | `400` | Errore di convalida della richiesta | | `401` | Non autorizzato | | `404` | Organizzazione o esercente non trovato | | `409` | Conflitto | **Corpo della risposta:** ```json { "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. `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 [#submit-onboarding-through-the-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. Prima di inviare i dati di onboarding tramite l'API, deve ottenere il consenso dell'esercente ai [Termini e condizioni Tapaya per gli integratori](https://tapaya.com/terms) e all'[Informativa sulla privacy di Tapaya](https://tapaya.com/privacy). 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. `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à [#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" }' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | -------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | `legalName` | `string` | ✓ | Ragione sociale dell'attività o nome del titolare persona fisica. | | `businessTypeId` | `int` | ✓ | Tipo di entità aziendale (`BusinessTypeEnum`). | | `email` | `string` | ✓ | Indirizzo email di contatto. | | `registrationNumber` | `string` | ✓ | Numero ufficiale di registrazione dell'attività. Viene verificata l'assenza di duplicati all'interno della Sua | | organizzazione. | | | | | `vatNumber` | `string` | | Partita IVA, se applicabile. | | `incorporationDate` | `date` | | Data di costituzione legale dell'attività (`YYYY-MM-DD`). | **Corpo della risposta:** ```json { "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 [#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 }' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | ------------ | -------- | ------------ | -------------------------------------------- | | `line1` | `string` | ✓ | Prima riga dell'indirizzo. | | `line2` | `string` | | Seconda riga dell'indirizzo, se applicabile. | | `city` | `string` | ✓ | Nome della città. | | `postalCode` | `string` | ✓ | Codice postale (CAP). | | `state` | `string` | | Stato o regione, se applicabile. | | `countryId` | `int` | ✓ | Paese (`CountryEnum`). | **Corpo della risposta:** stessa struttura `{valid, errors}` di [Convalidare l'identità](#validate-identity). ### Convalidare il profilo dell'attività [#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" }' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | ------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `capability` | `int` | ✓ | Utilizzi la funzionalità che invierà per l'onboarding. Per Checkout o Entrambi, fornisca i [dati del canale](#request-online-payment-capabilities). | | `mcc` | `string` | ✓ | Merchant Category Code a quattro cifre. Nella modalità a sezioni per canale, utilizzi `terminal.mcc` o `online.mcc`. | | `url` | `string` | | URL del sito web dell'attività. È obbligatorio `url` oppure `productDescription`. | | `productDescription` | `string` | | Descrizione dei prodotti o servizi. È obbligatorio `url` oppure | | `productDescription`. | | | | | `supportPhone` | `string` | ✓ | Numero di telefono dell'assistenza clienti, in formato E.164. | | `statementDescriptor` | `string` | ✓ | Testo mostrato sugli estratti conto bancari dei clienti (1–22 caratteri). | | `averageItemValue` | `long` | | Valore medio delle transazioni, nell'unità minore della valuta. | | `expectedMonthlyTurnover` | `long` | | Fatturato mensile previsto, nell'unità minore della valuta. | | `numberOfEmployees` | `int` | | Numero di dipendenti dell'attività. | | `annualTurnover` | `long` | | Fatturato annuo, nell'unità minore della valuta. | | `balanceSheetTotal` | `long` | | Totale di bilancio, nell'unità minore della valuta. | **Corpo della risposta:** stessa struttura `{valid, errors}` di [Convalidare l'identità](#validate-identity). ### Convalidare i dati KYB [#validate-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 ```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 } } ] } }' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | -------------------------------------------------------------------------------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------- | | `businessTypeId` | `int` | | Tipo di entità aziendale (`BusinessTypeEnum`); determina se sono obbligatori i campi `individual` o | | `company`. | | | | | `bankAccount` | `object` | | Conto bancario per gli accrediti (numero di conto/IBAN + BIC, valuta, beneficiario e indirizzo | | della banca). | | | | | `individual` | `object` | | Dati del titolare persona fisica, per le ditte individuali. Mutuamente esclusivo con `company`. | | `company` | `object` | | Dati 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à](#upload-a-persons-id-document) 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](#upload-a-persons-id-document) richiede il `merchantId` restituito da [Creare l'esercente con l'onboarding](#create-merchant-with-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à](#upload-the-company-document) prima che l'esercente possa essere inviato alla revisione KYC. **Corpo della risposta:** stessa struttura `{valid, errors}` di [Convalidare l'identità](#validate-identity). ### Creare l'esercente con l'onboarding [#create-merchant-with-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 ```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 } } ] } } }' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | --------------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `capability` | `int` | ✓ | `1` per Entrambi, `2` per Terminali o `3` per Checkout. Consulti le [funzionalità di pagamento online](#request-online-payment-capabilities). | | `terminal` | `object` | In base alla funzionalità | Dati del canale terminale per Terminali o Entrambi. | | `online` | `object` | In base alla funzionalità | Dati del canale online per Checkout o Entrambi. | | `name` | `string` | ✓ | Il nome dell'esercente. | | `merchantToken` | `string` | | Un identificativo univoco e stabile proveniente dal Suo sistema. Se non viene fornito, viene generato un | | token casuale. | | | | | `identity` | `object` | ✓ | Stessa struttura di [Convalidare l'identità](#validate-identity). | | `address` | `object` | ✓ | Stessa struttura di [Convalidare l'indirizzo](#validate-address). | | `business` | `object` | ✓ | Stessa struttura di [Convalidare il profilo dell'attività](#validate-business-profile). | | `kyb` | `object` | ✓ | Stessa struttura di [Convalidare i dati KYB](#validate-kyb). | **Risposte:** | Codice | Descrizione | | ------ | --------------------------------------------------------------------------------- | | `201` | Esercente creato e onboarding inviato | | `422` | Dati di onboarding non validi, si veda `errors`; l'esercente **non** viene creato | **Corpo della risposta (`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` 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`):** ```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" } ] } ``` ### Caricare il documento d'identità di una persona [#upload-a-persons-id-document] Obbligatorio per ogni persona inserita con dati completi in `kyb.company.people` / `kyb.individual` (si veda [Convalidare i dati KYB](#validate-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 ```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' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | | `paymentProcessorId` | `int` | ✓ | Sempre `5`. | | `documentType` | `int` | ✓ | Tipo di documento (`DocumentTypeEnum`: `1` Other, `2` Id, `3` Address, `4` Company, | | `5` BankStatement, `6` Passport, `7` RecentFinancials). | | | | | `frontFile` | `file` | ✓ | Immagine del fronte del documento. | | `backFile` | `file` | | Immagine del retro del documento, se applicabile. | | `relatedOfficialIdNumber` | `string` | | L'`officialIdNumber` della persona indicato in [Convalidare i dati KYB](#validate-kyb). | | Obbligatorio solo quando `documentType` è legato a una persona (ad es. Id, Passport, Address); altrimenti viene ignorato. | | | | | `submitMerchant` | `boolean` | | Qui 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à](#upload-the-company-document), dopo che i documenti di tutte le persone sono stati | | | | | caricati. | | | | **Corpo della risposta (`200`):** ```json { "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h", "backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k", "uploadedAt": "2026-07-17T12:00:00Z" } ``` ### Caricare il documento della società [#upload-the-company-document] 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 ```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' ``` **Parametri:** | Campo | Tipo | Obbligatorio | Descrizione | | ----------------------------------------------------------------- | --------- | ------------ | ------------------------------------------------------------------------------------------- | | `paymentProcessorId` | `int` | ✓ | Sempre `5`. | | `documentType` | `int` | ✓ | Sempre `4` (`Company`) per questo passaggio. | | `frontFile` | `file` | ✓ | Il documento di registrazione/costituzione della società. | | `submitMerchant` | `boolean` | | Lo 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`):** ```json { "frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h", "backFileId": null, "uploadedAt": "2026-07-17T12:00:00Z" } ```