Technical Documentation

API Reference

Complete documentation for integrating NetworkPay APIs into your system. Programmatically manage virtual cards and commission payments.

Overview

The NetworkPay API is a RESTful interface that enables programmatic integration of our virtual prepaid card system. The API is built on Stripe Issuing infrastructure and provides an abstraction layer to simplify common card management and commission operations.

RESTful API

JSON over HTTPS

PCI-DSS Compliant

Level 1 Certified

99.9% Uptime

SLA Guaranteed

Authentication

The API uses Bearer Token authentication. Each request must include the Authorization header with your API Key.

API Key Security

Never expose your API Key in client-side code. Always use server-to-server calls and store credentials in environment variables.

Header Format

http

Authorization: Bearer np_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key Types

Type	Prefix	Environment	Usage
Secret Key	np_live_	Production	Real operations
Test Key	np_test_	Sandbox	Development and testing
Publishable Key	np_pk_	Both	Client-side (limited)

Base URL

All API requests must be made to the following base endpoint:

url

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

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

The API supports HTTPS connections only. Unencrypted HTTP requests will be rejected with error 426 Upgrade Required.

Cardholders

The Cardholder object represents a cardholder in the system. Each cardholder can have one or more virtual cards associated.

POST/v1/cardholders

Create a new cardholder

Request Body

json

{
  "name": "John Smith",
  "email": "john.smith@example.com",
  "phone_number": "+447891234567",
  "type": "individual",
  "individual": {
    "first_name": "John",
    "last_name": "Smith",
    "dob": {
      "day": 15,
      "month": 6,
      "year": 1985
    }
  },
  "billing": {
    "address": {
      "line1": "123 Main Street",
      "city": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    }
  },
  "metadata": {
    "affiliate_id": "aff_12345",
    "tier": "gold"
  }
}

Response

json

{
  "id": "ich_1abc2def3ghi4jkl",
  "object": "issuing.cardholder",
  "name": "John Smith",
  "email": "john.smith@example.com",
  "phone_number": "+447891234567",
  "type": "individual",
  "status": "active",
  "created": 1701432000,
  "livemode": true,
  "metadata": {
    "affiliate_id": "aff_12345",
    "tier": "gold"
  }
}

GET/v1/cardholders

List all cardholders

Query Parameters

Parameter	Type	Description
limit	integer	Max results (1-100, default: 10)
starting_after	string	Pagination cursor
status	string	Filter by status (active, inactive)
email	string	Filter by email

Cards

The Card object represents a virtual Visa card issued for a cardholder.

POST/v1/cards

Issue a new card

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

POST/v1/cards/:id/fund

Load card (commission)

Request Body

json

{
  "amount": 15000,
  "currency": "eur",
  "description": "Sales commission - March 2024",
  "metadata": {
    "commission_id": "comm_abc123",
    "period": "2024-03"
  }
}

Note: Amount is expressed in cents. 15000 = €150.00

Transactions

The Transaction object represents a card movement (purchase, load, refund).

GET/v1/transactions

List transactions

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

Webhooks allow you to receive real-time notifications about events in your account. Configure an HTTPS endpoint and subscribe to desired events.

Available Events

Event	Description
cardholder.created	New cardholder created
card.created	New card issued
card.updated	Card status changed
transaction.created	New transaction recorded
authorization.request	Authorization request (real-time)
balance.updated	Issuing balance changed

Error Handling

The API uses standard HTTP codes and returns errors in structured JSON format.

Code	Type	Description
200	OK	Request completed successfully
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Missing or invalid API Key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Rate Limits

To ensure stability and performance, the API applies limits to the number of requests.

Plan	Limit	Burst
Starter	100 req/min	20 req/sec
Business	500 req/min	50 req/sec
Enterprise	Unlimited*	200 req/sec

* Subject to fair use policy. Contact us for high traffic needs.

SDKs & Libraries

Official SDKs to quickly integrate NetworkPay into your tech stack.

Node.js

v18+ supported

npm install @networkpay/sdk

Python

3.8+ supported

pip install networkpay

PHP

8.0+ supported

composer require networkpay/sdk

Ruby

3.0+ supported

gem install networkpay

Quick Start Example (Node.js)

javascript

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

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

// Create a cardholder
const cardholder = await client.cardholders.create({
  name: 'John Smith',
  email: 'john@example.com',
  phone_number: '+447891234567'
});

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

// Load commission
await client.cards.fund(card.id, {
  amount: 15000, // €150.00
  description: 'March 2024 Commission'
});

console.log(`Card ${card.last4} created and loaded!`);

Ready to get started?

Request your API credentials to begin integration. Our technical team is available to support you during implementation.

Request API Key Contact Technical Team