# Gestione degli esercenti (/it/platform-api/merchant_management) Gestisca gli esercenti della Sua organizzazione dal Suo backend. Ogni chiamata utilizza il Server Secret Token, quindi lo conservi sul Suo server. | Dettaglio | Valore | | --------------- | --------------------------------------------------------------------------------------------------------------------- | | URL di base | `https://api.sandbox.tapaya.com` per la sandbox, `https://api.tapaya.com` per la produzione | | Autenticazione | Server Secret Token in `Authorization`. Si veda [Autenticazione](/platform-api#authentication). | | Importi | Unità minori: `2500` con `EUR` corrisponde a 25,00 EUR. Commissioni relative in punti base: `100` corrisponde all'1%. | | Guida correlata | [Onboarding degli esercenti](/platform-api/merchant_onboarding) | ## Tutte le operazioni [#all-operations] | Operazione | Serve a | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | [Leggere un onboarding salvato](#read-a-saved-onboarding) | Riprendere il modulo di onboarding di un esercente dal punto in cui l'ha lasciato. | | [Salvare i canali selezionati](#save-channel-selections) | Memorizzare i canali di pagamento scelti da un esercente, senza inviare la domanda. | | [Elencare i membri](#list-members) | Vedere chi ha già accesso a un esercente. | | [Elencare i terminali](#list-terminals) | Mostrare i terminali di un esercente e i relativi dispositivi. | | [Elencare gli inviti via e-mail](#list-email-invites) | Monitorare gli inviti monouso inviati a destinatari noti. | | [Elencare i link riutilizzabili](#list-reusable-links) | Monitorare i link delle campagne e verificare se sono sospesi. | | [Creare un link riutilizzabile](#create-a-reusable-link) | Avviare una campagna tramite cui molti esercenti possono registrarsi. | | [Modificare la scadenza di un invito](#change-an-invites-expiry) | Prolungare o accorciare un invito, anche scaduto. | | [Sospendere o riattivare un link riutilizzabile](#pause-or-resume-a-reusable-link) | Bloccare temporaneamente nuove registrazioni senza revocare il link. | | [Elencare i set tariffari](#list-pricing-sets) | Trovare i set tariffari da cui la Sua organizzazione può creare profili. | | [Elencare i profili di commissione](#list-commission-profiles) | Scegliere un profilo da assegnare a un invito. | | [Creare un profilo di commissione](#create-a-commission-profile) | Offrire agli esercenti un listino basato su un set tariffario. | | [Aggiornare un profilo di commissione](#update-a-commission-profile) | Rinominare un profilo o modificarne le tariffe. | | [Eliminare un profilo di commissione](#delete-a-commission-profile) | Rimuovere un profilo che non offre più. | | [Impostare il profilo predefinito](#set-the-default-profile) | Scegliere il profilo utilizzato dagli inviti che non ne indicano nessuno. | | [Leggere le tariffe dell'esercente](#read-merchant-pricing) | Mostrare le tariffe con cui un esercente si è registrato. | ## Bozze di onboarding [#onboarding-drafts] **Serve a** riprendere il modulo di onboarding di un esercente con tutto ciò che ha salvato finora. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * È l'unica chiamata che restituisce l'intero onboarding salvato; le chiamate del profilo e del processore ne restituiscono solo una parte. * `pricingConstraints` elenca ciò che l'esercente può scegliere, non tariffari delle commissioni. **Restituisce:** | Campo | Descrizione | | ---------------------- | ------------------------------------------------------------------------------------------------- | | `identity` | I dati identificativi dell'esercente. | | `address` | L'indirizzo dell'esercente. | | `business` | Informazioni commerciali condivise da entrambi i canali. | | `kyb` | Conti bancari, conto principale, stakeholder della società o persona fisica e relativi documenti. | | `capability` | La capability selezionata. | | `terminal` | Dettagli salvati del canale in presenza. | | `online` | Dettagli salvati del canale online. | | `processors` | Stato presso ciascun processore di pagamento. | | `commissionProfileIds` | Profili di commissione assegnati all'esercente. | | `pricingConstraints` | Valute di regolamento e MCC consentiti. | **Serve a** memorizzare i canali di pagamento scelti da un esercente nel Suo modulo prima che completi l'onboarding. ```bash curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/channel' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "capability": 2, "terminal": { "mcc": "5411", "statementDescriptor": "ACME STORE", "productDescription": "Groceries", "averageItemValue": 2500, "expectedMonthlyTurnover": 500000, "numberOfTerminals": 1 } }' ``` **Da sapere:** * Funziona soltanto per un esercente la cui bozza di onboarding e il cui profilo sono già salvati. * Aggiorna la bozza e restituisce `200`. Non invia la domanda di onboarding né registra un account presso il processore. * Invii soltanto le sezioni dei canali selezionati dall'esercente. **Parametri:** | Campo | Descrizione | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `capability` | I canali selezionati. Stessi valori di [Onboarding degli esercenti](/platform-api/merchant_onboarding#request-online-payment-capabilities). | | `terminal` | Dettagli del canale in presenza, con gli stessi campi di Onboarding degli esercenti. | | `online` | Dettagli del canale online, con gli stessi campi di Onboarding degli esercenti. | ## Membri e terminali [#members-and-terminals] **Serve a** vedere chi ha già accesso a un esercente. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Restituisce un array dei membri attuali. * Gli inviti in attesa non sono inclusi; sono elencati separatamente. **Restituisce:** per ciascun membro: | Campo | Descrizione | | ----------- | ------------------------------------------ | | `userId` | L'ID utente del membro. | | `firstName` | Nome. | | `lastName` | Cognome. | | `email` | Indirizzo e-mail. | | `joinedAt` | Quando il membro si è unito all'esercente. | **Serve a** mostrare i terminali di un esercente e i dispositivi assegnati. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Restituisce i terminali, non le sedi attive; le sedi hanno un elenco a parte. * La risposta contiene `items` e `totalCount`. Ogni elemento include gli ID del terminale e della sede, un'etichetta e i dettagli del dispositivo. * `terminalType` e `deviceIdentifier` descrivono il dispositivo assegnato ora, non il dispositivo che ha acquisito un pagamento precedente. **Parametri:** | Campo | Descrizione | | --------------- | ------------------------- | | `page` | Numero di pagina. | | `pageSize` | Righe per pagina. | | `sortBy` | Campo di ordinamento. | | `sortDirection` | Direzione di ordinamento. | ## Inviti di registrazione [#registration-invites] Utilizzi un [invito via e-mail](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding) per un destinatario noto, oppure un link riutilizzabile per una campagna. Entrambi possono limitare i canali e assegnare profili di commissione. **Serve a** monitorare gli inviti monouso che ha inviato. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Ogni invito mostra l'e-mail del destinatario, l'URL, `capability` e `commissionProfileIds`. * Gli inviti riportano anche `commissionProfileId`, la forma a profilo singolo di `commissionProfileIds`. **Serve a** monitorare i link delle Sue campagne e vedere quali sono sospesi. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Ogni link mostra `capability`, i profili assegnati e `pausedAt`. * `pausedAt` è `null` finché il link non è sospeso. * Un link sospeso non scaduto né revocato corrisponde ancora a `isActive=true`. Controlli `pausedAt` per distinguerli. **Serve a** avviare una campagna tramite cui molti esercenti possono registrarsi. ```bash curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "name": "Partner onboarding", "expiresAt": "2030-12-31T00:00:00Z", "capability": 2 }' ``` **Da sapere:** * `capability` limita i canali che gli esercenti possono scegliere. Non concede l'approvazione del processore. * Ometta i campi dei profili per assegnare il profilo predefinito dell'organizzazione. * `commissionProfileId` è ancora accettato per un singolo profilo. Utilizzi invece `commissionProfileIds` e non li invii mai entrambi. **Parametri:** | Campo | Descrizione | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Un nome per la campagna. | | `expiresAt` | Timestamp ISO 8601 UTC, almeno un giorno nel futuro. Non esiste un massimo. | | `capability` | Facoltativo. Stessi valori degli [inviti via e-mail](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). | | `commissionProfileIds` | Facoltativo. Stesse regole degli inviti via e-mail. | **Serve a** prolungare o accorciare un invito, anche se è già scaduto. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/expires-at' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{"expiresAt": "2031-01-31T00:00:00Z"}' ``` **Da sapere:** * Per un invito via e-mail, chiami `PUT /integrator/merchant/invites/{inviteId}/expires-at` con lo stesso corpo. * Restituisce `204`. * Gli inviti revocati e gli inviti via e-mail già utilizzati non possono essere prolungati. **Parametri:** | Campo | Descrizione | | ----------- | --------------------------------------------------------------------------- | | `expiresAt` | Timestamp ISO 8601 UTC, almeno un giorno nel futuro. Non esiste un massimo. | **Serve a** bloccare temporaneamente nuove registrazioni senza revocare il link. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/pause' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Chiami `.../resume` sullo stesso link per accettare di nuovo le registrazioni. La riattivazione non prolunga la scadenza. * Entrambe le chiamate restituiscono `204` e sono idempotenti. * L'apertura di un link sospeso restituisce `410`. ## Profili di commissione [#commission-profiles] Un profilo di commissione è il listino che offre agli esercenti. Lo crei a partire da un set tariffario per cui la Sua organizzazione è autorizzata. **Serve a** trovare i set tariffari da cui può creare profili di commissione. ```bash curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Ogni set include i tariffari contrattuali dell'esercente e dell'integratore. * Utilizzi un `pricingSetId` restituito quando crea un profilo. **Parametri:** | Campo | Descrizione | | ------------- | ---------------------------------- | | `pricingType` | Facoltativo. `online` o `instore`. | **Serve a** scegliere un profilo da assegnare a un invito. ```bash curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Restituisce soltanto i profili abilitati e completi della Sua organizzazione. * Ogni profilo copre un solo tipo di tariffazione. * Conservi la `revision` di ciascun profilo se prevede di aggiornarlo. **Parametri:** | Campo | Descrizione | | ------------- | ---------------------------------- | | `pricingType` | Facoltativo. `online` o `instore`. | **Serve a** offrire agli esercenti un listino basato su un set tariffario. ```bash curl -X POST 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "name": "Standard profile", "pricingModel": 1, "cardTypes": [ {"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0} ], "pricings": [ {"currency": "eur", "pricingSetId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a"} ] }' ``` **Da sapere:** * Un profilo copre un solo tipo di tariffazione, derivato dai suoi set tariffari. * I costi dell'integratore e le quote di margine provengono dal set tariffario; Lei imposta soltanto le tariffe dell'esercente. * `region` vale `1` nazionale o `2` internazionale, `holderType` vale `1` consumatore o `2` azienda e `scheme` vale `1` Visa o `2` Mastercard. **Parametri:** | Campo | Descrizione | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Il nome del profilo. | | `pricingModel` | `1` per MDR o `2` per IC++. | | `cardTypes` | Ogni combinazione di regione, tipo di titolare della carta e circuito accettata dal profilo, con le relative commissioni di segnalazione. | | `pricings` | Valuta e `pricingSetId` per ciascuna valuta offerta. | | `merchantPricingOverrides` | Facoltativo. Voci con `holderCategory`, `regionSegment`, `relative` e `absolute`. Le combinazioni omesse mantengono le tariffe del set tariffario. | **Serve a** rinominare un profilo o modificarne le tariffe. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \ -H 'Authorization: REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{ "name": "Standard profile 2027", "pricingModel": 1, "cardTypes": [ {"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0} ], "expectedRevision": 3 }' ``` **Da sapere:** * Invii la `revision` letta per ultima come `expectedRevision`. Una revisione obsoleta restituisce `409`. * Ometta `pricings` per conservare le tariffe salvate. * Un profilo assegnato a esercenti, o non modificabile, accetta soltanto un nuovo nome. **Parametri:** | Campo | Descrizione | | ------------------ | --------------------------------------------------- | | `name` | Obbligatorio. Il nome del profilo. | | `pricingModel` | Obbligatorio. `1` per MDR o `2` per IC++. | | `cardTypes` | Obbligatorio. Come nella creazione. | | `pricings` | Facoltativo. Come nella creazione. | | `expectedRevision` | La `revision` del profilo al momento della lettura. | **Serve a** rimuovere un profilo che non offre più. ```bash curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Il profilo predefinito non può essere eliminato. Imposti prima un altro profilo come predefinito. * Un profilo assegnato a esercenti non può essere eliminato. Entrambi i casi restituiscono `400`. **Serve a** scegliere il profilo utilizzato dagli inviti che non ne indicano nessuno. ```bash curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * La Sua organizzazione ha un solo profilo predefinito. * Il profilo predefinito non può essere eliminato. ## Tariffe dell'esercente [#merchant-pricing] **Serve a** mostrare le tariffe con cui un esercente si è registrato, per i pagamenti in presenza e online. ```bash curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \ -H 'Authorization: REPLACE_ME' ``` **Da sapere:** * Un canale senza tariffe salvate è `null`. Un esercente senza alcun listino salvato restituisce `404`. * Restituisce tariffe contrattuali, non tariffari di base del fornitore di servizi di pagamento. Legga le tariffe da `cells`; i componenti `commission` non sono commissioni realizzate. * Un modello o un costo dell'integratore sconosciuto è `null`, non zero. * Le quote di margine ripartiscono il margine distribuibile, non l'intero importo del pagamento. **Restituisce:** | Campo | Descrizione | | ------------------------------------- | ------------------------------------------------------------------------------ | | `instore` | Tariffe per i pagamenti in presenza, oppure `null`. | | `online` | Tariffe per i pagamenti online, oppure `null`. | | `currency` | La valuta delle tariffe. | | `pricingModel` | Il modello tariffario dell'esercente. | | `integratorPricingModel` | Il modello tariffario dell'integratore, indipendente da quello dell'esercente. | | `priceListId` | Il listino salvato dell'esercente, se disponibile. | | `pricingSetVersionId` | La versione del set tariffario di origine, se disponibile. | | `pricingSetName` | Il nome del set tariffario di origine, se disponibile. | | `cells` | Tariffe per categoria del titolare della carta e regione. | | `cells[].discountBps` | Tariffa relativa finale dell'esercente in punti base. | | `cells[].transactionFeeMinor` | Commissione fissa finale dell'esercente in unità minori. | | `cells[].integratorCostRelativeBps` | Costo relativo contrattuale dell'integratore in punti base. | | `cells[].integratorCostAbsoluteMinor` | Costo fisso contrattuale dell'integratore in unità minori. | | `cells[].revenueShareTapayaBps` | Quota di Tapaya sul margine distribuibile in punti base. | | `cells[].revenueShareIntegratorBps` | La Sua quota sul margine distribuibile in punti base. | ## Errori [#errors] Ogni operazione risponde con questi codici di stato quando una richiesta non va a buon fine. | Codice | Descrizione | | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Dati dei canali, selezione dei profili, filtri o scadenza non validi; oppure tentativo di eliminare un profilo predefinito o assegnato. | | `401` | Il Server Secret Token è assente o non valido. | | `404` | La risorsa non è disponibile per la Sua organizzazione, oppure l'onboarding o le tariffe salvati non esistono. | | `409` | Revisione obsoleta del profilo, stato di onboarding in conflitto oppure invito utilizzato o revocato. |