Partner API v1

Un Partner e' chi porta merchant a PayGlobe: un rivenditore, un'agenzia, un integratore. Ha credenziali proprie, vede i suoi merchant, i volumi che generano e quanto guadagna su ciascuno; via API puo' anche crearli e configurarli.

Base URL

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

Funzionalità Principali

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

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"
  }'

Dove si accede

Tutti gli indirizzi del programma partner. Non ce ne sono altri.

Portale partner

partner-login.html → si entra con API Key + API Secret. Dentro:

• periodo selezionabile (default: mese corrente);
• totali: transazioni incassate, volume lordo, rimborsato, commissioni PayGlobe, il tuo guadagno;
• tabella per merchant, con il pricing applicato a ciascuno;
• elenco transazioni filtrabile per merchant, con commissione e guadagno riga per riga.

La sessione scade dopo 30 minuti di inattivita'. Il secret non viene mai salvato nel browser.

GET /stats

Volumi, commissioni PayGlobe e guadagno del partner, per merchant e in totale. Gli stessi numeri del portale.

Parametri

curl "https://api.payglobe.it/paymentgw/partner/api/v1/stats?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer pk_partner_xxx"

Response

{
  "success": true,
  "from": "2026-09-01",
  "to": "2026-09-30",
  "currency": "EUR",
  "revenueSharePercent": 30.00,
  "merchants": [
    {
      "merchantId": "soluzioniservizi",
      "environment": "PRODUCTION",
      "isActive": true,
      "pricing": {
        "defined": true,
        "percent": 1.200, "fixed": 0.15, "notes": "listino personalizzato",
        "tiers": [
          { "category": "MYBANK",     "label": "MyBank",     "percent": 0.250, "fixed": 0.15 },
          { "category": "PREPAID",    "label": "Prepaid",    "percent": 1.100, "fixed": 0.15 },
          { "category": "DEBIT",      "label": "Debit",      "percent": 1.100, "fixed": 0.15 },
          { "category": "CREDIT",     "label": "Credit",     "percent": 1.100, "fixed": 0.15 },
          { "category": "COMMERCIAL", "label": "Commercial", "percent": 2.300, "fixed": 0.15 },
          { "category": "EXTRA_EEA",  "label": "Extra-EEA",  "percent": 2.300, "fixed": 0.15 }
        ]
      },
      "transactionCount": 42,
      "grossVolume": 3180.00,
      "refundedAmount": 150.00,
      "payglobeFees": 42.36,
      "partnerEarnings": 12.71,
      "byCategory": {
        "DEBIT":        { "transactionCount": 25, "grossVolume": 1900.00, "refundedAmount": 0.00,   "payglobeFees": 24.65, "partnerEarnings": 7.40 },
        "CREDIT":       { "transactionCount": 12, "grossVolume": 980.00,  "refundedAmount": 150.00, "payglobeFees": 12.58, "partnerEarnings": 3.77 },
        "EXTRA_EEA":    { "transactionCount": 3,  "grossVolume": 200.00,  "refundedAmount": 0.00,   "payglobeFees": 5.05,  "partnerEarnings": 1.52 },
        "UNCLASSIFIED": { "transactionCount": 2,  "grossVolume": 100.00,  "refundedAmount": 0.00,   "payglobeFees": 1.50,  "partnerEarnings": 0.45 }
      },
      "unclassifiedCount": 2
    }
  ],
  "totals": {
    "transactionCount": 42,
    "grossVolume": 3180.00,
    "refundedAmount": 150.00,
    "payglobeFees": 42.36,
    "partnerEarnings": 12.71
  }
}

GET /transactions

Transazioni dei merchant del partner, in sola lettura. Senza dati del compratore.

Parametri

Response

{
  "success": true,
  "total": 42, "page": 0, "size": 50,
  "transactions": [
    {
      "transactionId": "3f0c9a2e-...",
      "merchantId": "soluzioniservizi",
      "createdAt": "2026-09-12T10:41:07+02:00",
      "completedAt": "2026-09-12T10:41:52+02:00",
      "amount": 75.00,
      "refundedAmount": 0.00,
      "paymentMethod": "CARD",
      "status": "COMPLETED",
      "statusFamily": "COMPLETED",
      "orderId": "ORD-1187",
      "description": "Ordine 1187",
      "fee": 1.00,
      "partnerEarning": 0.30
    }
  ]
}

statusFamily vale COMPLETED, REFUNDED, AUTHORIZED, PENDING, FAILED, CANCELLED, DISPUTED: e' quella da usare nei conti. status e' lo stato grezzo del PSP (decine di valori) e cambia con l'integrazione.

Pricing e quota: come si calcola

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,
    "revenueSharePercent": 30.00,
    "apiCallCount": 1523
  }
}

GET /merchants

Lista tutti i merchant del partner.

POST /merchants

Crea un nuovo merchant.

Request Body

Il webhook lo imposta poi il merchant dalla propria dashboard. Sono accettati solo URL http(s) che risolvono a un indirizzo pubblico: localhost, reti private, 169.254.x.x e nomi che non risolvono vengono rifiutati con il motivo, e il controllo si ripete prima di ogni invio. Dettagli in partner.html.

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.

Lista Servizi Disponibili

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.

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.

Codici Errore

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.

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.