Come integrarsi con Perno Orchestration tramite API?

Questa guida è per chi vuole emettere e incassare pagamenti tramite Perno Orchestration dal proprio sistema (il backend di un negozio, un'app), invece di creare ogni link di pagamento a mano nella dashboard. Presuppone che tu abbia già un token API e almeno un account merchant - in caso contrario, vedi prima Come utilizzare le API di Perno? e Come aggiungere un account merchant in Perno?.

Prima di iniziare: due segreti diversi

Integrarsi con Orchestration coinvolge due segreti distinti, facili da confondere:

Segreto	A cosa serve
API Token	Ti autentica come utente. Inviato come `Authorization: Token YOUR_API_TOKEN` in ogni richiesta.
Transaction Signing Key	Usata solo per costruire il `trx_hash` quando crei un link di pagamento. Non viene mai inviata nel corpo della richiesta.

Trovi la Transaction Signing Key nelle impostazioni di Orchestration (contesto Perno Orchestration → Perno Orchestration nel menu laterale), insieme al gateway di pagamento predefinito, agli URL di ritorno (Default/Success/Cancel Return URL) e agli URL di notifica (Transaction e Payment Link Notification URL). I campi return_url* e notification_url dell'API sono opzionali proprio per questo: se li ometti, Perno usa i valori impostati qui.

Passo 1: verifica o crea un account merchant

Elenca gli account merchant collegati al tuo account Orchestration:

curl -X GET "https://perno.io/api/v1/orchestration/merchant-accounts/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Cerca quello con "default": true - è lì che viene indirizzato un link di pagamento se non specifichi un account diverso. Dettagli completi: Retrieve merchant accounts.

Se preferisci creare un account merchant in modo programmatico invece che dalla dashboard, usa Create merchant account:

curl -X POST "https://perno.io/api/v1/orchestration/merchant-accounts/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_account_name": "Stripe EU",
    "payment_gateway": "stripe",
    "payment_gateway_type": {"type": "production"},
    "default": true,
    "api_data_1": "sk_live_..."
  }'

supported_currencies, supported_languages, supported_countries e supported_payment_methods sono array di ID delle tabelle di riferimento di Perno, non codici testuali. Il modo più semplice è configurarli una volta nella dashboard (Come aggiungere un account merchant in Perno?) e poi rileggere i valori risultanti con GET - oppure controllare i codici dei metodi di pagamento al passo 2 qui sotto.

Per cambiare quale account è quello predefinito, chiama Set default merchant account:

curl -X POST "https://perno.io/api/v1/orchestration/merchant-accounts/{account_id}/set-default/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Passo 2: verifica i metodi di pagamento disponibili

Se stai costruendo un tuo checkout e vuoi mostrare subito al cliente i metodi di pagamento disponibili, invece di mandarlo direttamente alla pagina hosted di Perno, recuperali da List payment methods:

curl -X GET "https://perno.io/api/v1/orchestration/payment-methods/?merchant_account_id=1¤cy=PLN&amount=10.00" \
  -H "Authorization: Token YOUR_API_TOKEN"

La risposta è un elenco di oggetti {code, name, active, sequence}. L'endpoint accetta anche i filtri opzionali country, language e payment_gateway_type (production o sandbox), così puoi restringere il risultato a ciò che un dato cliente vedrà davvero.

Passo 3: firma e crea il link di pagamento

Creare un link di pagamento richiede un trx_hash valido, calcolato con la Transaction Signing Key:

trx_hash = SHA256("|" + amount + "|" + trx_id + "|" + transaction_signing_key)

Perno ricalcola lo stesso hash lato server e lo confronta - se non corrisponde, la richiesta viene rifiutata con un errore Wrong hash. Esempio in Python:

import hashlib

def build_trx_hash(amount, trx_id, transaction_signing_key):
    raw = f"|{amount}|{trx_id}|{transaction_signing_key}"
    return hashlib.sha256(raw.encode()).hexdigest()

Con un trx_hash valido in mano, chiama Create payment link:

curl -X POST "https://perno.io/api/v1/payment_links/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_account": 1,
    "amount": "10.00",
    "currency": "PLN",
    "trx_id": "order-4821",
    "trx_hash": "…hash calcolato…",
    "customer_email": "[email protected]",
    "one_time_link": true
  }'

Puoi omettere merchant_account - Perno userà allora l'account predefinito del passo 1. Lo stesso vale per return_url, return_url_success, return_url_cancel e notification_url - impostali solo quando un pagamento specifico richiede indirizzi diversi da quelli predefiniti di Orchestration. one_time_link: true impedisce che il link venga pagato due volte. La risposta include payment_hash - l'identificativo univoco del nuovo link.

Passo 4: invia il link al cliente

L'API non restituisce un URL pronto da condividere - gestisce solo il record. Un link creato tramite API compare nello stesso elenco dei link creati a mano: nella dashboard, nel contesto Perno Orchestration → Payment links, ogni voce ha il proprio indirizzo hosted nella colonna Link - copialo da lì per inviarlo al cliente (vedi Come gestire i link di pagamento in Perno?). Una volta aperto, porta a una pagina di checkout che mostra l'importo e metodi di pagamento come carta, Apple Pay, Revolut Pay o Klarna.

Passo 5: conferma il pagamento

L'approccio migliore è un webhook: il Payment Link Notification URL configurato nelle impostazioni di Orchestration viene chiamato ogni volta che lo stato di un link cambia, così il tuo endpoint viene informato del pagamento senza dover interrogare l'API. Se Send multiple webhooks è attivo in quelle impostazioni, aspettati che lo stesso evento arrivi più di una volta - rendi il tuo gestore del webhook idempotente (usando come chiave trx_id o payment_hash).

Se preferisci controllare tu stesso lo stato (o vuoi un metodo di riserva), recupera i dettagli del link con Get payment link details:

curl -X GET "https://perno.io/api/v1/payment-links/{payment_hash}/" \
  -H "Authorization: Token YOUR_API_TOKEN"

Il campo used passa a true una volta che il link è stato pagato (o consumato, per i link a uso singolo). Il record di pagamento completo e dettagliato - gateway, stato (paid, pending, need 3ds e così via) e collegamento al link di pagamento - si trova nella vista Transactions della dashboard (vedi Cos'è una transazione in Perno Orchestration?); le transazioni non sono ancora esposte come risorsa separata nell'API v1.

Passo 6: monitora l'integrazione

Per verificare se gli endpoint dei link di pagamento sono attivi, usa Health check payment links API - un buon candidato per il tuo monitoraggio di uptime:

curl -X GET "https://perno.io/api/v1/payment_links/health_check" \
  -H "Authorization: Token YOUR_API_TOKEN"

Il flusso, in sintesi

Configura un account merchant e la Transaction Signing Key (una sola volta).
Controlla l'account merchant predefinito e, facoltativamente, i metodi di pagamento disponibili.
Calcola trx_hash e crea un link di pagamento per l'ordine.
Prendi il suo indirizzo dalla dashboard e invialo al cliente.
Gestisci il webhook, oppure controlla il campo used, per confermare il pagamento.