Integrazioni
Collegati a modo tuo: API, pagine ospitate o senza codice
Scegli il percorso adatto al tuo team e al tuo perimetro PCI: sviluppa sull’API REST, inserisci un checkout ospitato, invia un Payment Link o carica un batch nel Business Portal e lascia che il tuo strumento di coding con IA legga il contratto reale.
- API REST
- Sandbox Stage
- Webhook firmati
- Server MCP pubblico
API RESTSette percorsi
Scegli come collegarti
Dietro ogni percorso ci sono gli stessi conti, saldi e report: puoi partire leggero e aggiungere altro in seguito.
API REST direttaPiù flessibile
Controllo completo su incassi, payout, conti virtuali, FX e reportistica. JSON su HTTPS, chiamato dal tuo server, con webhook firmati a ogni cambio di stato.
API REST diretta —WebCheckout ospitatoSenza codice
Porta i clienti su un checkout ospitato da Localpayment con i metodi locali che attivi. Nessun codice front-end da mantenere.
WebCheckout ospitato —Payment LinksSenza codice
Crea un link nel Business Portal e condividilo via e-mail, SMS o social. Ideale per fatture, vendite a distanza e pagamenti una tantum.
Payment Links —iframe incorporatoWhite-label
Inserisci un checkout white-label nella tua pagina e mantieni il tuo brand intorno, con un perimetro PCI ridotto.
iframe incorporato —SDK JS Smart FieldsForm su misura
Campi carta ospitati, tokenizzati nel browser e consolidati in un token monouso che il tuo server poi addebita. Il design del form lo decidi tu.
SDK JS Smart Fields —Batch nel Business PortalOperations
Carica file di payout e di conti virtuali e segui i risultati nel portale. Nessun lavoro di integrazione per finanza e operations.
Batch nel Business Portal —Server MCP per l’IAAssistito da IA
Un server MCP pubblico in sola lettura e llms.txt permettono a Cursor, VS Code, Claude e altri assistenti di sviluppare sull’API documentata.
Server MCP per l’IA —
Confronta
Impegno, perimetro PCI e uso ideale
Una guida per la preselezione. Il tuo perimetro PCI finale dipende da come acquisisci e conservi i dati carta; confermalo con il tuo assessor.
API REST diretta
- Impegno
- Alto: sviluppo lato server
- Perimetro PCI
- Dipende da come acquisisci i dati carta; abbinala a Smart Fields o a un’opzione ospitata
- Ideale per
- Piattaforme che vogliono il pieno controllo di incassi, payout e FX
WebCheckout ospitato
- Impegno
- Basso: reindirizzamento
- Perimetro PCI
- Minimo
- Ideale per
- Team che vogliono attivare in fretta i metodi locali
Payment Links
- Impegno
- Molto basso: senza codice
- Perimetro PCI
- Minimo
- Ideale per
- Fatture, vendite a distanza, pagamenti una tantum
iframe incorporato
- Impegno
- Da basso a medio
- Perimetro PCI
- Ridotto
- Ideale per
- Checkout col tuo brand senza gestire i campi carta
SDK JS Smart Fields
- Impegno
- Medio: front-end e server
- Perimetro PCI
- Condiviso
- Ideale per
- Design del checkout su misura con campi carta ospitati
Batch nel Business Portal
- Impegno
- Molto basso: caricamento file
- Perimetro PCI
- Nessun dato carta coinvolto
- Ideale per
- Finanza e operations che eseguono payout e conti virtuali
Server MCP per l’IA
- Impegno
- Basso: aggiungere un URL
- Perimetro PCI
- Non applicabile: nessun dato di pagamento
- Ideale per
- Ingegneri che usano assistenti di coding con IA
Le credenziali Stage (sandbox) vengono rilasciate all’avvio della partnership. L’accesso alla produzione arriva dopo test, revisione di sicurezza e verifica aziendale.
L’API in pratica
Un incasso API tipico, dall’inizio alla fine
Quattro attori, sei passaggi. Il tuo backend parla con una sola API; il circuito locale lo gestiamo noi.
- 1
Backend del merchantAPI Localpayment:
Autenticati
POST /api/token/ restituisce un token di accesso a breve durata. Le chiamate partono dal tuo server, da un IP autorizzato.
- 2
Backend del merchantAPI Localpayment:
Crea l’incasso
POST /api/payin/ con il tuo externalId, paese, valuta, importo e metodo di pagamento.
- 3
API LocalpaymentCircuito locale:
Instrada sul circuito locale
Localpayment invia la richiesta sul circuito che hai attivato, come Pix, SPEI o PSE.
- 4
Circuito localeAPI Localpayment:
Il cliente paga
Il circuito conferma il pagamento. I circuiti in tempo reale confermano in pochi secondi, 24/7.
- 5
API LocalpaymentEndpoint webhook:
Webhook firmato
Un webhook con l’header X-Signature HMAC-SHA256 annuncia il nuovo stato.
- 6
Endpoint webhookBackend del merchant:
Verifica e aggiorna
Controlla la firma, deduplica su externalId o internalId, rispondi 200 e aggiorna l’ordine.
Illustrazione semplificata con dati fittizi. Consulta il quickstart per i campi esatti di richiesta e risposta.
Vai in produzione
Dal contratto firmato alla produzione
Ricevi le credenziali Stage
Le credenziali sandbox arrivano all’avvio della partnership, così l’engineering parte mentre è in corso la revisione di compliance.
Sviluppa e testa in Stage
Stage replica la produzione senza denaro reale. Usa carte di test, il simulatore di conti virtuali e la collection Postman.
Revisione e verifica
Le credenziali di produzione arrivano dopo test completati, una revisione di sicurezza e la verifica aziendale.
Vai live in poche settimane
Cambia URL base e credenziali, autorizza i tuoi IP e parti. I nuovi mercati si attivano per configurazione, senza reintegrare.
FAQ
Domande sull’integrazione
Da quale percorso conviene partire?
Se ti serve controllo e hai sviluppatori, parti dall’API REST. Se vuoi attivare in fretta i metodi locali, usa WebCheckout o Payment Links. Puoi combinare i percorsi sullo stesso conto.
Offrite SDK lato server?
Non esistono SDK server ufficiali. L’API REST è JSON su HTTPS e la documentazione mostra esempi in cURL e Node.js. L’unico SDK è l’SDK JS Smart Fields, lato client.
Come sono protette le chiamate API?
Le chiamate usano HTTPS da ambienti server con token Bearer e richiedono l’autorizzazione degli IP. I webhook sono firmati con HMAC-SHA256 così puoi verificare che arrivino da Localpayment.
Come evitiamo addebiti duplicati?
Invia il tuo externalId univoco a ogni transazione. Un duplicato restituisce HTTP 409 e chi riceve i webhook deve deduplicare su externalId o internalId.
Come incide sul nostro perimetro PCI?
Dipende dal percorso. WebCheckout ospitato e Payment Links mantengono il perimetro minimo, l’iframe incorporato lo riduce e Smart Fields lo condivide. Conferma il risultato con il tuo assessor.
Come aiutano gli strumenti di coding con IA?
Aggiungi il server MCP pubblico in sola lettura (docs.localpayment.com/mcp) a Cursor, VS Code, Claude o strumenti simili. Leggeranno l’API documentata invece di tirare a indovinare.
Quanto dura l’integrazione?
Le credenziali Stage arrivano all’avvio della partnership e il go-live richiede alcune settimane, a seconda del percorso e dei tuoi cicli di revisione. Parla con il team commerciale per un piano su misura.
Inizia a costruire oggi
Raccontaci i tuoi mercati e il tuo stack. Ti consiglieremo il percorso di integrazione e prepareremo le tue credenziali Stage.