Partner API v1

API RESTful per la gestione programmatica dei merchant PayGlobe.

Autenticazione API Key

Ogni Partner ha credenziali API dedicate:

  • API Key (pk_partner_xxx) - Usata per autenticazione
  • API Secret (sk_partner_xxx) - Per webhook signatures

Base URL

https://api.payglobe.it/paymentgw/partner/api/v1

Funzionalità Principali

Gestione Merchant
Crea, configura e gestisci i tuoi merchant via API
Configurazione Servizi
Abilita/disabilita gateway per ogni merchant
Multi-Gateway
IGFS, Shift4, PayPal, BANCOMAT Pay, Zonda, etc.
Sicurezza
API Key + IP Whitelist + Webhook Signatures

Autenticazione

Tutte le richieste API devono includere l'header Authorization con il tuo API Key:

curl -X GET https://api.payglobe.it/paymentgw/partner/api/v1/me \
  -H "Authorization: Bearer pk_partner_xxxxxxxxxxxxxxxx"
Errori di Autenticazione
CodiceDescrizione
401API Key mancante o non valida
403IP non in whitelist (se configurato)

Quick Start

Esempio completo: crea un merchant e abilita BANCOMAT Pay

# 1. Crea un nuovo merchant
curl -X POST https://api.payglobe.it/paymentgw/partner/api/v1/merchants \
  -H "Authorization: Bearer pk_partner_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "STORE_001",
    "merchantName": "Il Mio Negozio",
    "environment": "TEST"
  }'

# 2. Abilita BANCOMAT Pay
curl -X POST ".../merchants/STORE_001/services/BANCOMAT_PAY/enable" \
  -H "Authorization: Bearer pk_partner_xxx"

# 3. Configura BANCOMAT Pay
curl -X PUT ".../merchants/STORE_001/services/BANCOMAT_PAY/config" \
  -H "Authorization: Bearer pk_partner_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "idPg": "ABCDE",
    "idNegozio": "12345678901",
    "merchantName": "Il Mio Negozio",
    "mode": "sandbox"
  }'

GET /me

Ottieni informazioni sul partner autenticato.

Response
{
  "success": true,
  "partner": {
    "id": 1,
    "partnerCode": "GRUPPO_RETAIL",
    "name": "Gruppo Retail SpA",
    "role": "PARTNER",
    "allowedServices": "[\"IGFS\",\"BANCOMAT_PAY\",\"PAYPAL\"]",
    "maxMerchants": 100,
    "apiCallCount": 1523
  }
}

GET /merchants

Lista tutti i merchant del partner.

POST /merchants

Crea un nuovo merchant.

Request Body
ParametroTipoDescrizione
merchantId *stringID univoco del merchant
merchantNamestringNome visualizzato
environmentstringTEST o LIVE
Importante: Le chiavi API sono mostrate solo nella risposta di creazione. Salvale subito!

GET /merchants/{merchantId}

Ottieni dettagli di un merchant.

PATCH /merchants/{merchantId}

Aggiorna configurazione (parziale).

DELETE /merchants/{merchantId}

Disattiva un merchant (soft delete).

GET /services

Lista servizi disponibili per il partner.

POST /merchants/{id}/services/{service}/enable

Abilita un servizio per un merchant.

POST /merchants/{id}/services/{service}/disable

Disabilita un servizio per un merchant.

PUT /merchants/{id}/services/{service}/config

Configura un servizio. I parametri variano per servizio.

BANCOMAT_PAY
idPg, idNegozio, merchantName, certificate, privateKey, mode
PAYPAL
clientId, clientSecret, mode
SHIFT4
merchantId, signatureKey, mode

Lista Servizi Disponibili

CodiceNomeDescrizione
IGFSIGFS/NexiPagamenti carta di credito
SHIFT4Shift4Pagamenti carta via Shift4
PAYPALPayPalPagamenti PayPal
AMAZON_PAYAmazon PayPagamenti Amazon Pay
BANCOMAT_PAYBANCOMAT PayPagamenti BANCOMAT Pay
BIZUMBizum (Redsys)Pagamento istantaneo conto-a-conto, solo Spagna
SKRILLSkrill (Quick Checkout)Wallet Skrill; dalla stessa pagina anche carta, Neteller, Rapid Transfer, PaysafeCard
ZONDAZonda CryptoPayPagamenti criptovalute
SATISPAYSatispayPagamenti Satispay
ASSIOPAYAssiopayBuoni pasto elettronici

Adapter di compatibilità

Oltre alle API PayGlobe native, due adapter permettono a un merchant di restare sul protocollo che già usa. Non sono servizi da abilitare qui: si configurano emettendo le credenziali dell'adapter e ripuntando la Base URL del client.

AdapterPer chi arriva daBase URLDocumentazione
Mandala Stripe (SDK backend + Stripe.js) https://api.payglobe.it/mandala/v1 mandala
IGFS Adapter IGFS diretto (N&TS/Nexi PGW REST) https://api.payglobe.it/MONEYNET_CG_SERVICES igfs-adapter.html

L'IGFS Adapter espone init, verify, capture, reversal e refund in protocollo IGFS nativo, con la stessa HTTP-Signature. Il client cambia solo Base URL, merId (max 16 caratteri) e secret. auth diretto, selector, tokenizer e pay-by-mail non sono ancora esposti.

IGFS è un marchio e un prodotto di N&TS Group. PayGlobe non è affiliata a N&TS Group e non è autorizzata a distribuire la documentazione di integrazione IGFS. L'adapter è rivolto esclusivamente ai merchant che hanno già un'integrazione IGFS attiva e la relativa documentazione N&TS: le specifiche del protocollo vanno richieste a N&TS Group.

Codici Errore

HTTPDescrizione
400Parametri mancanti o non validi
401API Key mancante o non valida
403IP non autorizzato o servizio non consentito
404Risorsa non trovata
409Conflitto: ID già esistente, oppure Idempotency-Key riusata con un corpo diverso
500Errore interno del server

Ritentativi: Idempotency-Key

Su ogni chiamata che muove denaro — incasso, storno, annullo, addebito su carta salvata — invia l'header Idempotency-Key con un valore diverso per ogni operazione. Se ripeti la richiesta con la stessa chiave, ricevi la risposta originale invece di eseguirla una seconda volta.

Serve soprattutto sugli storni parziali. Uno storno totale ripetuto viene rifiutato da solo, perché non resta saldo da restituire; ma un secondo storno parziale dello stesso importo è un'operazione legittima, quindi senza chiave viene eseguito e il cliente riceve i soldi due volte.

Se una chiamata fallisce senza un esito confermato, ritentala con la stessa chiave: è l'unico modo di non decidere alla cieca. Riusare una chiave con un corpo diverso è un 409. Le chiavi restano valide 30 giorni.