Localpayment per sviluppatori

Costruisci attorno ai dettagli locali.

Trova le guide API, i requisiti per paese, gli strumenti di test e gli esempi di implementazione alla base di ogni flusso di pagamento supportato.

Vai alla documentazione Inizia il quickstart

REST + JSON
Webhook firmati HMAC
Sandbox Stage
Server MCP pubblico

POST /api/payin/

curl -X POST https://api.stage.localpayment.com/api/payin/
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -d '{
    "externalId": "order-8f2k-1043",
    "paymentMethod": { "type": "BankTransfer", "code": "1314" },
    "country": "BRA", "currency": "BRL",
    "amount": 1250.00
  }'

L’essenziale per sviluppatori

Documentazione

Vai dritto a ciò che ti serve

Link diretti a docs.localpayment.com: guide, reference dell’API e strumenti.

Le tue prime chiamate

Autentica, incassa, conferma

Tre passaggi coprono il ciclo principale: ottenere un token, creare un incasso e verificare il webhook firmato che lo conferma. Lo stesso modello di richieste, stati e webhook vale per tutti i paesi e i metodi di pagamento.

I token scadono dopo 5 minuti: rinnovali con POST /api/token/refresh/
Invia il tuo externalId univoco in ogni transazione
Lo stato finale arriva via webhook, firmato con HMAC-SHA256

Apri la reference dell’API

# 1) Ottieni un token di accesso (Stage · valido 5 minuti)
ACCESS_TOKEN=$(curl -s -X POST https://api.stage.localpayment.com/api/token/ \
  -H "Content-Type: application/json" \
  -d "{\"username\": \"$LP_API_USER\", \"password\": \"$LP_API_PASSWORD\"}" \
  | jq -r .access)

# 2) Crea un incasso Pix (esempio, valori fittizi)
curl -X POST https://api.stage.localpayment.com/api/payin/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": { "type": "BankTransfer", "code": "1314", "flow": "DIRECT" },
    "externalId": "7c1e2f7a-0000-4000-8000-000000000001",
    "country": "BRA",
    "currency": "USD",
    "amount": 100,
    "accountNumber": "<your-account-number>",
    "conceptCode": "0003",
    "merchant": { "type": "COMPANY", "name": "Nortia Commerce Ltda" },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "Maria",
      "lastname": "Silva",
      "document": { "type": "CPF", "id": "000.000.000-00" }
    }
  }'

Design dell’API

Prevedibile per progettazione

Convenzioni che restano identiche tra prodotti e paesi, così anche il tuo codice di integrazione non cambia.

REST e JSON
URL orientati alle risorse, verbi e codici HTTP standard, body JSON. I paesi usano codici ISO-3 come BRA o MEX.
Token Bearer a breve durata
POST /api/token/ restituisce un token di accesso valido 5 minuti e un refresh token valido 24 ore, inviato come Authorization: Bearer.
Il tuo ID e il nostro
Ogni transazione porta il tuo externalId e noi restituiamo il nostro internalId. Usa l’uno o l’altro per consultare lo stato o riconciliare.
A prova di duplicati
Riutilizzare un externalId restituisce 409 Conflict invece di creare una seconda transazione, così puoi ripetere in sicurezza una richiesta andata in timeout.
Codici su cui decidere
Ogni risposta contiene un oggetto status con code, description e detail, più un array errors. Le famiglie di codici ti dicono cosa fare dopo.
Rate limit con backoff
Troppe richieste restituiscono 429. Riprova con backoff esponenziale e circuit breaker, come per le risposte 5xx e il codice 800.

Gestione degli errori

Le famiglie di codici di stato in breve

Ogni risposta include status.code. La prima cifra ti dice se attendere, correggere, riprovare o stornare.

1xx
Significato
In attesa
Esempi
100 INPROGRESS
Cosa fare
Attendi il webhook o consulta lo stato
2xx
Significato
Successo
Esempi
200 COMPLETED
Cosa fare
Evadi l’ordine e aggiorna il tuo registro contabile
3xx
Significato
Validazione
Esempi
300 rifiutato (parametro non valido) · 301 non autorizzato per il paese
Cosa fare
Correggi la richiesta: non ripeterla invariata
7xx
Significato
Regole di business
Esempi
701 conto non valido · 702 fondi insufficienti
Cosa fare
Mostra un messaggio chiaro o avvisa il tuo team operations
8xx
Significato
Provider o sistema
Esempi
800 errore ripetibile
Cosa fare
Riprova con backoff esponenziale
9xx
Significato
Storni
Esempi
902 rimborsato · 904 abbonamento annullato dopo tentativi falliti · 906 chargeback
Cosa fare
Annulla l’evasione e aggiorna il tuo registro contabile

Famiglia	Significato	Esempi	Cosa fare
1xx	In attesa	100 INPROGRESS	Attendi il webhook o consulta lo stato
2xx	Successo	200 COMPLETED	Evadi l’ordine e aggiorna il tuo registro contabile
3xx	Validazione	300 rifiutato (parametro non valido) · 301 non autorizzato per il paese	Correggi la richiesta: non ripeterla invariata
7xx	Regole di business	701 conto non valido · 702 fondi insufficienti	Mostra un messaggio chiaro o avvisa il tuo team operations
8xx	Provider o sistema	800 errore ripetibile	Riprova con backoff esponenziale
9xx	Storni	902 rimborsato · 904 abbonamento annullato dopo tentativi falliti · 906 chargeback	Annulla l’evasione e aggiorna il tuo registro contabile

Stati HTTP in uso: 200, 201, 400, 401, 403, 404, 409, 429, 500, 502 e 503. Le tabelle dei codici per tipo di transazione sono nella reference della documentazione.

Percorso di integrazione

Dalla prima chiamata alla produzione

Gran parte del lavoro si svolge su Stage. L’accesso alla produzione arriva dopo una security review e la verifica della tua azienda.

01
Ottieni le credenziali Stage
Le credenziali Stage vengono rilasciate all’avvio della partnership. Registra gli IP dei tuoi server nel Business Portal.
Stage
02
Sviluppa e testa
Integra incassi, payout o conti virtuali, gestisci i webhook e simula scenari di errore con dati di test.
Stage
03
Security review e KYB
Esaminiamo la tua integrazione e completiamo la verifica aziendale (KYB) prima di rilasciare le credenziali di produzione.
Compliance
04
Vai live ed espanditi
Passa a credenziali e IP di produzione. Aggiungi paesi e metodi via configurazione, senza reintegrare.
Produzione

Strumenti di IA per sviluppatori

Fai leggere la documentazione al tuo assistente IA

La documentazione di Localpayment è pensata per funzionare con gli strumenti di sviluppo assistito dall’IA: include un server MCP, prompt pronti all’uso e un accesso strutturato progettato per i sistemi di IA.

Server MCP su docs.localpayment.com/mcp, senza autenticazione
Un indice llms.txt e una versione Markdown di ogni pagina della documentazione
Una libreria di prompt e agenti di integrazione e QA per i framework di agenti più diffusi
“Ask AI” integrato nella documentazione

Scopri gli strumenti di IA

{
  "mcpServers": {
    "localpayment-docs": {
      "url": "https://docs.localpayment.com/mcp"
    }
  }
}

Sicurezza

Sicuro di default, dalla prima richiesta

Controlli integrati nell’API e nel Business Portal, non aggiunti in un secondo momento.

Cifratura in transito e a riposo
TLS 1.2+ in transito e AES-256 a riposo, con rotazione delle chiavi tramite AWS KMS.
Solo server-to-server
Le chiamate passano via HTTPS dal tuo backend. Non esporre mai credenziali o token in un browser o in un’app mobile.
IP allowlisting
Solo gli IP dei server che autorizzi nel Business Portal possono chiamare l’API, sia su Stage sia in produzione.
Webhook firmati
Ogni notifica ha una firma HMAC-SHA256, così puoi rifiutare tutto ciò che non abbiamo inviato noi.
Payout con doppia firma
Richiedi un secondo approvatore prima che un payout lasci il tuo conto, via API o nel portale.
MFA e accessi per ruolo
Gli utenti del Business Portal accedono con autenticazione a più fattori e hanno solo i permessi richiesti dal loro ruolo.

FAQ per sviluppatori

C’è un SDK?

Non esistono SDK server ufficiali: l’API è semplice REST e JSON, quindi va bene qualsiasi client HTTP. Per i form delle carte, l’SDK JavaScript Smart Fields tokenizza i dati della carta in campi ospitati e riduce il tuo perimetro PCI.

Come ottengo le credenziali della sandbox?

Le credenziali Stage vengono rilasciate all’avvio della partnership. Raccontaci il tuo progetto tramite il modulo di contatto e il nostro team ti accompagnerà durante l’onboarding.

Quali base URL uso?

Stage: https://api.stage.localpayment.com. Produzione: https://api.v3.localpayment.com. Ogni ambiente ha le proprie credenziali.

Quanto dura un’integrazione?

In genere i team vanno live in poche settimane. Una volta integrato, aggiungi nuovi mercati via configurazione, senza reintegrare.

Come si gestiscono retry e duplicati?

Invia un externalId univoco per ogni transazione. Se ripeti con lo stesso externalId ricevi 409 Conflict invece di un duplicato. Ripeti 429, 5xx e il codice 800 con backoff esponenziale.

Dove controllo lo stato del servizio?

Su status.localpayment.com, che copre i servizi di incasso, payout e autenticazione, i circuiti locali e lo storico degli incidenti. Per assistenza scrivi a support@localpayment.com: il supporto è attivo 24/7.

Costruisci attorno ai dettagli locali.

L’essenziale per sviluppatori

Guide

Riferimento API

Strumenti per sviluppatori

Pagina di stato

Vai dritto a ciò che ti serve

Autenticazione

Il tuo primo pagamento di test

Incassi

Payout

Conti virtuali

Webhook

Stati e codici di errore

Collection Postman

Stato del sistema

Autentica, incassa, conferma

Prevedibile per progettazione

REST e JSON

Token Bearer a breve durata

Il tuo ID e il nostro

A prova di duplicati

Codici su cui decidere

Rate limit con backoff

Le famiglie di codici di stato in breve

Dalla prima chiamata alla produzione

Ottieni le credenziali Stage

Sviluppa e testa

Security review e KYB

Vai live ed espanditi

Fai leggere la documentazione al tuo assistente IA

Sicuro di default, dalla prima richiesta

Cifratura in transito e a riposo

Solo server-to-server

IP allowlisting

Webhook firmati

Payout con doppia firma

MFA e accessi per ruolo

FAQ per sviluppatori

Guide per sviluppatori

Quickstart

Sandbox

Webhook

Strumenti di IA

Roadmap

Business Portal

Pronto a sviluppare?