Globconnects API

API keys can be scoped with granular permissions, IP address allowlists, and automatic expiration to minimize blast radius in the event of credential leakage.

• IP Allowlist: Restrict key usage to specific static IPv4/IPv6 addresses or CIDR blocks (e.g. 198.51.100.4, 203.0.113.0/24).
• Key Expiration: Optionally set an automatic TTL (30 days, 90 days, 1 year) after which requests will return 401 Unauthorized.

To safely retry purchase requests without creating double debits or accidental duplicate transactions, pass a unique Idempotency-Key header (e.g. UUIDv4) with every mutating request (POST /purchase, POST /cards/*, POST /esim/*, POST /airtime/purchase).

Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

• 24-Hour Replay Window: If a request with an existing idempotency key is retried within 24 hours, our server safely replays the original response with the Idempotency-Replay: true header and zero additional wallet debit.
• Concurrency Protection: Simultaneous duplicate requests in-flight return 409 Conflict until the initial transaction has settled.

Response format

Responses share one envelope. On success, status is true and the result is in data. On failure, status is false with a human-readable message, and data is null.

{
  "status": true,        // false on error
  "message": "…",       // human-readable summary
  "data": { … }          // result, or null on error
}

Endpoint index

All v1 endpoints at a glance.

Confirms your API keys are valid. Does not touch your wallet.

curl https://globconnects.net/api/v1/ping \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

Returns your current wallet balance.

curl https://globconnects.net/api/v1/balance -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

{ "status": true, "data": { "wallet_balance": 15000.00, "currency": "NGN" } }

Returns the full catalogue as categories → products → variations. Use a variation's code as the variation_code when creating a purchase.

{ "status": true, "data": [
  { "code": "data-gifting", "service_type": "data", "products": [
    { "code": "data-gifting-mtn", "network": "MTN", "variations": [
      { "code": "mtn-1gb-30", "price": 600, "data_value": "1GB" }
    ] } ] } ] }

Returns the products in a single category.

Path parameters

curl https://globconnects.net/api/v1/products/airtime -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

Creates a purchase for any local service. Manual-amount services (airtime, electricity) also require amount.

Body parameters

curl -X POST https://globconnects.net/api/v1/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variation_code": "mtn-1gb-30", "recipient": "08012345678" }'

<?php
$ch = curl_init('https://globconnects.net/api/v1/purchase');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer PUBLIC_KEY:SECRET_KEY',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'variation_code' => 'mtn-1gb-30',
    'recipient' => '08012345678',
  ]),
]);
$res = json_decode(curl_exec($ch), true);
echo $res['data']['reference'];

// Server-side Node.js (v18+) — never expose API keys in browser client JavaScript!
const res = await fetch('https://globconnects.net/api/v1/purchase', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.GLOBCONNECTS_PUBLIC_KEY}:${process.env.GLOBCONNECTS_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    variation_code: 'mtn-1gb-30',
    recipient: '08012345678',
  }),
});
const { data } = await res.json();
console.log(data.reference, data.status);

{ "status": true, "message": "Transaction successful.", "data": {
  "reference": "GC240717ABC123", "status": "successful",
  "amount": 600, "wallet_balance": 14400.00 } }

Retrieves a transaction by reference. Use it to resolve orders that returned pending.

Path parameters

curl https://globconnects.net/api/v1/transactions/GC240717ABC123 \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

International airtime

Top up mobile numbers in 150+ countries. Airtime is priced live per country, so list operators first, then buy. Each operator is either FIXED (choose an options[] entry and send its sender value) or RANGE (send any amount between range.min and range.max). The ngn field is what your wallet is charged.

Opaque tokens: the id and code values here (and for data, gift cards and eSIMs) are opaque. Send them back exactly as received; do not parse or construct them.

Query parameters

curl "https://globconnects.net/api/v1/airtime/operators?country=US" \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

{ "status": true, "data": {
  "country": "US", "operators": [
    { "id": "~mJ8x2", "name": "AT&T USA", "currency": "USD",
      "denominationType": "RANGE",
      "range": { "min": 5, "max": 100, "ngnMin": 8400, "ngnMax": 168000 },
      "options": [] } ] } }

Body parameters

curl -X POST https://globconnects.net/api/v1/airtime/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operator_id": "~mJ8x2", "amount": 10,
        "phone": "+14155550123", "country": "US" }'

A pending status settles shortly. Poll /transactions/{reference} to confirm.

International data

Data bundles for numbers abroad, using the same live list-then-buy model as airtime. Operators return real bundle sizes in their options[] labels.

Query parameters

{ "status": true, "data": {
  "country": "US", "operators": [
    { "id": "~kQ2pR", "name": "T-Mobile Data USA", "currency": "USD",
      "denominationType": "FIXED",
      "options": [ { "sender": 10, "ngn": 16800, "label": "3GB - 30 days" } ] } ] } }

Body parameters

curl -X POST https://globconnects.net/api/v1/data/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operator_id": "~kQ2pR", "amount": 10,
        "phone": "+14155550123", "country": "US" }'

Gift cards

Sell branded gift cards priced live per country. The card is delivered by email to the recipient.

Query parameters

{ "status": true, "data": {
  "country": "US", "products": [
    { "id": "~7ZgT", "name": "Amazon US", "brand": "Amazon",
      "denominationType": "FIXED",
      "options": [ { "sender": 25, "ngn": 42000 } ] } ] } }

Body parameters

curl -X POST https://globconnects.net/api/v1/giftcards/purchase \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "~7ZgT", "amount": 25,
        "recipient_email": "friend@example.com" }'

Travel eSIMs

Global travel-data eSIMs, priced live in NGN. The flow is three steps: list plans for a destination, buy one, then fetch its QR / activation profile. Ordering is asynchronous. If the profile isn't ready, the eSIM returns PROCESSING; poll the status endpoint for it.

Query parameters

{ "status": true, "data": {
  "region": "US", "packages": [
    { "code": "~ifv-1qVTi6TN", "name": "USA 1GB 7 Days",
      "data": "1GB", "days": 7, "ngn": 2500.00 } ] } }

Body parameters

{ "status": true, "message": "eSIM ordered. View the QR to install.", "data": {
  "reference": "GC240717ESIM01", "status": "successful", "amount": 2500,
  "esim": {
    "plan": "USA 1GB 7 Days", "iccid": "8910300000...",
    "activation_code": "LPA:1$smdp.io$MATCHING-ID",
    "qr_image": "https://.../qr.png", "smdp": "smdp.io",
    "status": "GOT_RESOURCE" },
  "wallet_balance": 11900.00 } }

To install: scan qr_image, or enter activation_code manually (Settings → Add eSIM).

Re-fetches the QR / activation profile. Use it when a purchase returned status: PROCESSING.

curl https://globconnects.net/api/v1/esim/status/GC240717ESIM01 \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY"

Virtual USD cards

These endpoints require a verified business account. Unlike the rest of the API, an API key alone is not enough. A card is a spendable instrument on the open card networks, so we verify who is behind the account first. Two things must be true:

1. Your identity is verified, using your BVN, under Settings → Identity verification. Automatic.
2. Your business is approved. Upload your CAC certificate, TIN and director's ID under Settings → Business verification. Reviewed by a person, usually within one business day.

Until both pass, every endpoint below answers 403 with a machine-readable reason and the outstanding steps, so you can surface the right message to your own user:

{ "status": false,
  "message": "Virtual cards need a verified business account.",
  "data": {
    "reason": "BUSINESS_NOT_SUBMITTED",
    "steps": [ "Submit your CAC certificate, TIN and director's ID …" ] } }

Reason codes

Cards are issued in USD and funded from your Naira wallet at the rate quoted by GET /cards (ngn_per_unit, which already includes the margin). All amount values are in USD.

Every card on the account, plus the current FX quote and funding limits.

{ "status": true, "data": {
  "currency": "USD", "ngn_per_unit": 1680.00,
  "min_fund": 5, "max_fund": 1000,
  "cards": [
    { "reference": "CRD250822AB12CD", "label": "Ads card",
      "brand": "Visa", "currency": "USD", "last4": "4821",
      "expiry_month": "07", "expiry_year": "2029",
      "name_on_card": "ADA OKAFOR", "status": "active",
      "balance": 25.00 } ] } }

Issues a dedicated USD virtual card. Each card created via API is issued directly to your customer using their verified individual KYC details, creating an independent cardholder identity. Strict Policy: Each BVN and NIN is eligible for only one virtual card across the platform.

Body parameters

curl -X POST https://globconnects.net/api/v1/cards/create \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Joe",
    "last_name": "Doe",
    "email": "joe.doe@example.com",
    "phone": "080******78",
    "bvn": "222******55",
    "nin": "746******19",
    "date_of_birth": "1995-04-12",
    "street": "12 Commercial Avenue",
    "city": "Yaba",
    "state": "Lagos",
    "country": "NG",
    "zip_code": "101212",
    "amount": 5.00,
    "label": "Joe Doe Card"
  }'

Returns 201 with the newly issued card and your updated wallet_balance. If card issuance fails, the debited funds are reversed to your wallet automatically.

Body parameters

A frozen, expired or terminated card cannot be funded. Unfreeze it first. Repeated failures auto-freeze a card to protect the account.

Unloads USD from an active virtual card and credits the equivalent converted Naira directly into your main account wallet.

Body parameters

{
  "status": true,
  "message": "Card funds withdrawn successfully.",
  "data": {
    "card": {
      "reference": "CRD261010125217A300784E",
      "label": "Ads card",
      "currency": "USD",
      "balance": 10.00,
      "status": "active"
    },
    "wallet_balance": 485000.00
  }
}

Body parameters

Fetches real-time live balance and current status directly from the card network issuer.

{
  "status": true,
  "message": "Card balance fetched.",
  "data": {
    "card_reference": "CRD261010125217A300784E",
    "currency": "USD",
    "balance": 25.00,
    "status": "active",
    "updated_at": "2026-10-21T16:30:00+01:00"
  }
}

One card, in the same shape as the list endpoint. 404 if the reference isn't yours.

Fetches real-time transaction ledger, declines, and settlement history for this card.

Body parameters (for POST /cards/reveal)

Full PAN, CVV, and Address Verification System (AVS) billing details, fetched live from the card network issuer. Never stored by us, and never returned by any other endpoint. Requires cards:reveal (or *) API scope and Business KYC. Response is sent with Cache-Control: no-store, max-age=0, private and Pragma: no-cache.

{
  "status": true,
  "message": "Card details fetched.",
  "data": {
    "card": {
      "card_reference": "CRD261010125217A300784E",
      "pan": "4821000000004821",
      "cvv": "123",
      "expiry_month": "07",
      "expiry_year": "2029",
      "name_on_card": "ADA OKAFOR",
      "brand": "visa",
      "currency": "USD",
      "status": "active",
      "balance": 25.00,
      "billing_address": {
        "street": "332 S Michigan Ave Ste 121",
        "city": "Chicago",
        "state": "IL",
        "postal_code": "60604",
        "country": "US"
      }
    }
  }
}

Rate limited to 10 calls per hour per account. A 429 carries retry_after in seconds. Every call is audit-logged. Treat the response as cardholder data: do not log it, do not cache it, and serve it to your user over TLS only.

Webhooks

Orders that come back pending settle later. Rather than polling /transactions/{reference}, set a webhook URL in Settings → Webhook and we will POST the update to you as soon as it happens.

Supported Webhook Events

Only real state changes are sent. A pending order that is still pending produces nothing, and a repeated refund is not re-sent. You will never receive duplicate events for identical actions.

Request we send

Content-Type: application/json
Accept: application/json
User-Agent: Globconnects-Webhook/1.1
X-Globconnects-Signature: t=1725700000,v1=9f2c3d4e5f6a...  (HMAC-SHA512 of timestamp.event_id.raw_body)
X-Globconnects-Timestamp: 1725700000
X-Globconnects-Event-Id: evt_9f2c3d4e5f6a7b8c

{
  "id": "evt_9f2c3d4e5f6a7b8c",
  "event": "transaction.successful",
  "timestamp": 1725700000,
  "sent_at": "2026-08-07T09:14:22+00:00",
  "data": {
    "reference": "GC240717ABC123",
    "status": "successful",
    "service": "data-gifting",
    "product": "mtn",
    "plan": "gifting-mtn-1gb",
    "network": "MTN",
    "recipient": "08012345678",
    "amount": 480.00,
    "commission": 12.00,
    "channel": "api",
    "provider_reference": "AS-99182734",
    "message": "Delivered successfully.",
    "created_at": "2026-08-07 09:14:02"
  }
}

Payload fields

Responding

Reply 2xx to acknowledge. Anything else is recorded as a failed delivery. We wait up to 5 seconds for your response, do not follow redirects, and strictly require secure HTTPS URLs (plain HTTP and private/internal IP ranges are blocked for SSRF protection).

Verifying signatures & replay protection

Every outbound webhook carries security headers to prove authenticity and eliminate replay attacks:

• X-Globconnects-Signature: Formatted as t=<timestamp>,v1=<signature> where the signature is HMAC-SHA512 of timestamp . "." . event_id . "." . raw_body.
• X-Globconnects-Timestamp: Unix timestamp (seconds) when the delivery was initiated. Reject any requests older than 5 minutes.
• X-Globconnects-Event-Id: Unique event ID (e.g. evt_...). Integrators must verify this matches the id field in the JSON payload body.

<?php
$secret = getenv('GLOBCONNECTS_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_GLOBCONNECTS_SIGNATURE'] ?? '';
$eventIdHeader = $_SERVER['HTTP_X_GLOBCONNECTS_EVENT_ID'] ?? '';

// 1. Parse timestamp and signature
if (!preg_match('/t=(\d+),v1=([a-f0-9]+)/', $sigHeader, $m)) {
    http_response_code(401);
    exit('Invalid signature format');
}
[$full, $timestamp, $sig] = $m;

// 2. Replay attack protection (within 5 minutes)
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit('Timestamp expired');
}

$event = json_decode($raw, true);

// 3. Verify header Event-ID matches payload body ID
if ($eventIdHeader === '' || ($event['id'] ?? '') !== $eventIdHeader) {
    http_response_code(401);
    exit('Event ID mismatch');
}

// 4. Timing-safe HMAC verification over timestamp.event_id.raw_body
$expected = hash_hmac('sha512', $timestamp . '.' . $eventIdHeader . '.' . $raw, $secret);
if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Signature mismatch');
}

// Look the order up by reference and update your own records.
fulfil($event['data']['reference'], $event['data']['status']);

http_response_code(200);

const crypto = require('crypto');

// express: mount the RAW body for this route, not express.json()
app.post('/hooks/globconnects',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sigHeader = req.get('X-Globconnects-Signature') || '';
    const eventIdHeader = req.get('X-Globconnects-Event-Id') || '';
    const secret = process.env.GLOBCONNECTS_WEBHOOK_SECRET;

    const match = sigHeader.match(/t=(\d+),v1=([a-f0-9]+)/);
    if (!match) return res.status(401).send('Invalid signature format');

    const timestamp = parseInt(match[1], 10);
    const signature = match[2];

    // Replay protection: within 5 minutes
    if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) {
      return res.status(401).send('Timestamp expired');
    }

    const payload = JSON.parse(req.body.toString());

    // Verify header Event-ID matches payload body ID
    if (!eventIdHeader || payload.id !== eventIdHeader) {
      return res.status(401).send('Event ID mismatch');
    }

    // Timing-safe verification over timestamp.event_id.raw_body
    const expected = crypto
      .createHmac('sha512', secret)
      .update(timestamp + '.' + eventIdHeader + '.' + req.body.toString('utf8'))
      .digest('hex');

    if (expected.length !== signature.length ||
        !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
      return res.status(401).send('Signature mismatch');
    }

    fulfil(payload.data.reference, payload.data.status);
    res.sendStatus(200);
  });

import hmac, hashlib, os, time, re
from flask import Flask, request, abort

app = Flask(__name__)

@app.post('/hooks/globconnects')
def globconnects_hook():
    raw = request.get_data().decode('utf-8')
    sig_header = request.headers.get('X-Globconnects-Signature', '')
    event_id_header = request.headers.get('X-Globconnects-Event-Id', '')
    secret = os.environ['GLOBCONNECTS_WEBHOOK_SECRET']

    match = re.match(r't=(\d+),v1=([a-f0-9]+)', sig_header)
    if not match:
        abort(401)

    timestamp, signature = int(match.group(1)), match.group(2)

    # Replay protection: within 5 minutes
    if abs(int(time.time()) - timestamp) > 300:
        abort(401)

    event = request.get_json()

    # Verify header Event-ID matches payload body ID
    if not event_id_header or event.get('id') != event_id_header:
        abort(401)

    signed_payload = f'{timestamp}.{event_id_header}.{raw}'
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha512).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(401)

    fulfil(event['data']['reference'], event['data']['status'])
    return '', 200

Deliveries can arrive more than once if an order is settled and later refunded, so key your handling on data.reference or X-Globconnects-Event-Id and make it idempotent. Rotate the secret by clearing and re-saving your webhook URL.

Statuses & errors

The status field on a transaction is one of:

HTTP status codes