Virtual Card API v1

Introduction

The Virtual Card API lets you issue, list, and inspect virtual cards from your own systems. The API follows REST conventions: predictable URLs, JSON-encoded request bodies, JSON-encoded responses, and standard HTTP status codes.

To use the API you need:

1. A registered user account on this platform.
2. API access enabled on your account by an administrator (request access from your dashboard).
3. A non-zero wallet balance to cover card-issuance fees.
4. A valid API key generated from your dashboard.

Authentication

All requests must include your API key. Three carriers are accepted (in order of preference):

1. Bearer header (recommended)

Authorization: Bearer sk_live_YOUR_API_KEY

2. X-API-Key header

X-API-Key: sk_live_YOUR_API_KEY

3. Query parameter (testing only — not recommended in production)

?api_key=sk_live_YOUR_API_KEY

Base URL

All endpoints are served under:

https://gpaynow.net/api/v1

Example: to call /cards/issue the full URL is https://gpaynow.net/api/v1/cards/issue.

Errors & Status Codes

Error responses use a consistent envelope:

{
  "status":  "error",
  "remark":  "insufficient_balance",
  "message": "Insufficient balance. Required: 1.00, available: 0.50"
}

Rate Limits

To protect the platform we enforce two limits:

• Per-minute requests: 60 requests per token per minute.
• Daily card issuance: 100 cards per user per rolling 24 hours.

When you exceed a limit you receive HTTP 429 with a remark of either rate_limited or daily_limit.

GET /

Returns the service descriptor — useful as a probe / health check.

Response

{
  "status":  "success",
  "data": {
    "service":  "Virtual Card API",
    "version":  "v1",
    "enabled":  true,
    "fees":     { "visa": 1.00, "mastercard": 1.00, "currency": "USD" },
    "limits":   { "rate_per_minute": 60, "daily_card_limit": 100 },
    "allowed_brands": ["visa", "mastercard"]
  }
}

GET /account

Returns information about the calling user and the token in use.

Response

{
  "status": "success",
  "data": {
    "user":  { "id": 42, "username": "acme", "balance": 124.50, "currency": "USD" },
    "token": {
      "id": 7,
      "name": "Production",
      "masked": "sk_live_abcd••••••••wxyz",
      "total_requests": 1248,
      "total_cards_issued": 86,
      "total_spent": 86.00,
      "last_used_at": "2026-04-28T10:14:00+00:00"
    }
  }
}

GET /balance

Quick wallet-balance check.

Response

{ "status": "success", "data": { "balance": 124.50, "currency": "USD" } }

POST /cards/issue

Issues a new virtual card and debits the issuance fee from your wallet.

Request body

Example request

curl -X POST https://gpaynow.net/api/v1/cards/issue \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "visa",
    "billing_name": "Acme Inc.",
    "billing_zip": "10001",
    "billing_country": "US"
  }'

Example response (201 Created)

{
  "status": "success",
  "message": "Card issued successfully.",
  "data": {
    "card": {
      "id": 8421,
      "brand": "Visa",
      "card_number": "4539821345678901",
      "last4": "8901",
      "expiry_date": "08/29",
      "cvv": "721",
      "billing": {
        "name": "Acme Inc.", "address": null, "city": null, "state": null,
        "zip": "10001", "country": "US"
      },
      "status": "active",
      "issued_via": "api",
      "created_at": "2026-04-28T10:14:00+00:00"
    },
    "fee_charged": 1.00,
    "new_balance": 99.00
  }
}

GET /cards

Lists cards owned by the authenticated user. Card numbers and CVVs are masked in the list view — call GET /cards/{id} to retrieve the full PAN.

Query parameters

Example response

{
  "status": "success",
  "data": {
    "cards": [
      {
        "id": 8421, "brand": "Visa",
        "card_number": "•••• •••• •••• 8901",
        "last4": "8901", "expiry_date": "08/29", "cvv": "•••",
        "billing": { ... }, "status": "active",
        "issued_via": "api", "created_at": "2026-04-28T10:14:00+00:00"
      }
    ],
    "pagination": { "total": 86, "per_page": 20, "current_page": 1, "last_page": 5 }
  }
}

GET /cards/{id}

Returns full details for a single card, including the full card number and CVV.

Path parameter

Errors

404 not_found — card does not exist or does not belong to you.

The Card object

Code Examples

cURL

curl -X POST https://gpaynow.net/api/v1/cards/issue \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":"mastercard","billing_zip":"10001"}'

JavaScript (fetch)

const res = await fetch('https://gpaynow.net/api/v1/cards/issue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ brand: 'visa' })
});
const json = await res.json();
console.log(json.data.card);

Python (requests)

import os, requests

resp = requests.post(
    "https://gpaynow.net/api/v1/cards/issue",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"brand": "visa"},
    timeout=15,
)
resp.raise_for_status()
card = resp.json()["data"]["card"]
print(card["card_number"], card["expiry_date"], card["cvv"])

PHP

$ch = curl_init('https://gpaynow.net/api/v1/cards/issue');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode(['brand' => 'visa']),
]);
$body = curl_exec($ch);
curl_close($ch);
$data = json_decode($body, true);
print_r($data['data']['card']);

Node.js (axios)

const axios = require('axios');

const { data } = await axios.post(
  'https://gpaynow.net/api/v1/cards/issue',
  { brand: 'mastercard' },
  { headers: { Authorization: `Bearer ${process.env.API_KEY}` } }
);
console.log(data.data.card);

Changelog

• v1.0.0 — Sep 2026

  Initial release. Supports Visa & Mastercard issuance, balance/account/list/show endpoints, bearer auth, per-user gating, rate limiting.