Documentazione Tecnica

API Reference

Documentazione completa per l'integrazione delle API NetworkPay nel tuo sistema. Gestisci programmaticamente carte virtuali e pagamenti delle commissioni.

Panoramica

L'API NetworkPay è un'interfaccia RESTful che consente l'integrazione programmatica del nostro sistema di carte prepagate virtuali. L'API si basa sull'infrastruttura Stripe Issuing e fornisce un layer di astrazione per semplificare le operazioni comuni di gestione carte e commissioni.

RESTful API

JSON over HTTPS

PCI-DSS Compliant

Level 1 Certified

99.9% Uptime

SLA Garantito

Autenticazione

L'API utilizza l'autenticazione Bearer Token. Ogni richiesta deve includere l'header Authorization con la tua API Key.

Sicurezza API Key

Non esporre mai la tua API Key nel codice client-side. Utilizza sempre chiamate server-to-server e conserva le credenziali in variabili d'ambiente.

Formato Header

http

Authorization: Bearer np_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tipi di API Key

Tipo	Prefisso	Ambiente	Utilizzo
Secret Key	np_live_	Produzione	Operazioni reali
Test Key	np_test_	Sandbox	Sviluppo e test
Publishable Key	np_pk_	Entrambi	Client-side (limitato)

Base URL

Tutte le richieste API devono essere effettuate al seguente endpoint base:

url

# Produzione
https://api.networkpay.me/v1

# Sandbox (Test)
https://sandbox.api.networkpay.me/v1

L'API supporta esclusivamente connessioni HTTPS. Le richieste HTTP non cifrate verranno rifiutate con errore 426 Upgrade Required.

Cardholders

L'oggetto Cardholder rappresenta un titolare di carta nel sistema. Ogni cardholder può avere una o più carte virtuali associate.

POST/v1/cardholders

Crea un nuovo cardholder

Request Body

json

{
  "name": "Mario Rossi",
  "email": "mario.rossi@example.com",
  "phone_number": "+393331234567",
  "type": "individual",
  "individual": {
    "first_name": "Mario",
    "last_name": "Rossi",
    "dob": {
      "day": 15,
      "month": 6,
      "year": 1985
    }
  },
  "billing": {
    "address": {
      "line1": "Via Roma 123",
      "city": "Milano",
      "postal_code": "20100",
      "country": "IT"
    }
  },
  "metadata": {
    "affiliate_id": "aff_12345",
    "tier": "gold"
  }
}

Response

json

{
  "id": "ich_1abc2def3ghi4jkl",
  "object": "issuing.cardholder",
  "name": "Mario Rossi",
  "email": "mario.rossi@example.com",
  "phone_number": "+393331234567",
  "type": "individual",
  "status": "active",
  "created": 1701432000,
  "livemode": true,
  "metadata": {
    "affiliate_id": "aff_12345",
    "tier": "gold"
  }
}

GET/v1/cardholders

Lista tutti i cardholders

Query Parameters

Parametro	Tipo	Descrizione
limit	integer	Max risultati (1-100, default: 10)
starting_after	string	Cursor per paginazione
status	string	Filtra per stato (active, inactive)
email	string	Filtra per email

Cards

L'oggetto Card rappresenta una carta virtuale Visa emessa per un cardholder.

POST/v1/cards

Emetti una nuova carta

Request Body

json

{
  "cardholder": "ich_1abc2def3ghi4jkl",
  "currency": "eur",
  "type": "virtual",
  "status": "active",
  "spending_controls": {
    "spending_limits": [
      {
        "amount": 500000,
        "interval": "monthly"
      }
    ],
    "allowed_categories": [
      "restaurants",
      "grocery_stores",
      "gas_stations"
    ]
  },
  "metadata": {
    "purpose": "commission_payments"
  }
}

Response

json

{
  "id": "ic_1xyz2abc3def4ghi",
  "object": "issuing.card",
  "brand": "Visa",
  "cardholder": "ich_1abc2def3ghi4jkl",
  "currency": "eur",
  "exp_month": 12,
  "exp_year": 2028,
  "last4": "4242",
  "status": "active",
  "type": "virtual",
  "created": 1701432000,
  "livemode": true,
  "wallets": {
    "apple_pay": {
      "eligible": true
    },
    "google_pay": {
      "eligible": true
    }
  }
}

GET/v1/cards/:id/sensitive

Ottieni dati sensibili carta

Endpoint Sensibile

Questo endpoint restituisce numero carta completo, CVC e data di scadenza. Richiede permessi aggiuntivi e viene loggato per compliance PCI-DSS.

Response

json

{
  "id": "ic_1xyz2abc3def4ghi",
  "object": "issuing.card",
  "number": "4000009990000013",
  "cvc": "123",
  "exp_month": 12,
  "exp_year": 2028,
  "cardholder": {
    "id": "ich_1abc2def3ghi4jkl",
    "name": "Mario Rossi"
  }
}

POST/v1/cards/:id/fund

Ricarica carta (commissione)

Request Body

json

{
  "amount": 15000,
  "currency": "eur",
  "description": "Commissione vendite - Marzo 2024",
  "metadata": {
    "commission_id": "comm_abc123",
    "period": "2024-03"
  }
}

Nota: L'importo è espresso in centesimi. 15000 = €150.00

Transactions

L'oggetto Transaction rappresenta un movimento sulla carta (acquisto, ricarica, rimborso).

GET/v1/transactions

Lista transazioni

json

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "ipi_1abc2def3ghi",
      "object": "issuing.transaction",
      "amount": -2500,
      "currency": "eur",
      "card": "ic_1xyz2abc3def4ghi",
      "cardholder": "ich_1abc2def3ghi4jkl",
      "type": "capture",
      "merchant_data": {
        "name": "Amazon EU",
        "category": "digital_goods",
        "city": "Luxembourg",
        "country": "LU"
      },
      "created": 1701432000
    }
  ]
}

Webhooks

I webhook consentono di ricevere notifiche in tempo reale sugli eventi del tuo account. Configura un endpoint HTTPS e sottoscrivi gli eventi desiderati.

Eventi Disponibili

Evento	Descrizione
cardholder.created	Nuovo cardholder creato
card.created	Nuova carta emessa
card.updated	Stato carta modificato
transaction.created	Nuova transazione registrata
authorization.request	Richiesta autorizzazione (real-time)
balance.updated	Balance Issuing modificato

Verifica Signature

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const timestamp = signature.split(',')[0].split('=')[1];
  const sig = signature.split(',')[1].split('=')[1];
  
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expectedSig)
  );
}

Error Handling

L'API utilizza codici HTTP standard e restituisce errori in formato JSON strutturato.

Codice	Tipo	Descrizione
200	OK	Richiesta completata con successo
400	Bad Request	Parametri mancanti o non validi
401	Unauthorized	API Key mancante o non valida
403	Forbidden	Permessi insufficienti
404	Not Found	Risorsa non trovata
429	Too Many Requests	Rate limit superato
500	Server Error	Errore interno del server

Formato Errore

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Il parametro 'cardholder' è obbligatorio",
    "param": "cardholder",
    "doc_url": "https://docs.networkpay.me/errors/parameter_missing"
  }
}

Rate Limits

Per garantire stabilità e performance, l'API applica limiti al numero di richieste.

Piano	Limite	Burst
Starter	100 req/min	20 req/sec
Business	500 req/min	50 req/sec
Enterprise	Illimitato*	200 req/sec

* Soggetto a fair use policy. Contattaci per esigenze di traffico elevato.

Headers di Rate Limit

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1701432060

SDKs & Librerie

SDK ufficiali per integrare rapidamente NetworkPay nel tuo stack tecnologico.

Node.js

v18+ supportato

npm install @networkpay/sdk

Python

3.8+ supportato

pip install networkpay

PHP

8.0+ supportato

composer require networkpay/sdk

Ruby

3.0+ supportato

gem install networkpay

Esempio Quick Start (Node.js)

javascript

const NetworkPay = require('@networkpay/sdk');

const client = new NetworkPay({
  apiKey: process.env.NETWORKPAY_API_KEY,
  environment: 'production' // o 'sandbox'
});

// Crea un cardholder
const cardholder = await client.cardholders.create({
  name: 'Mario Rossi',
  email: 'mario@example.com',
  phone_number: '+393331234567'
});

// Emetti una carta
const card = await client.cards.create({
  cardholder: cardholder.id,
  currency: 'eur',
  type: 'virtual'
});

// Carica commissione
await client.cards.fund(card.id, {
  amount: 15000, // €150.00
  description: 'Commissione Marzo 2024'
});

console.log(`Carta ${card.last4} creata e ricaricata!`);

Pronto per iniziare?

Richiedi le tue credenziali API per iniziare l'integrazione. Il nostro team tecnico è disponibile per supportarti durante l'implementazione.

Richiedi API Key Contatta il Team Tecnico