Dataspark Partner API

import hashlib, hmac, json, os, time
from flask import Flask, request

app = Flask(__name__)

@app.post("/dataspark-webhook")
def dataspark_webhook():
    raw = request.get_data()                       # the RAW bytes, exactly as we sent them
    header = request.headers.get("X-Dataspark-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)

    secret = os.environ["DATASPARK_WEBHOOK_SECRET"].encode()   # the whsec_... secret from your dashboard
    signed = parts.get("t", "").encode() + b"." + raw
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()

    fresh = abs(time.time() - int(parts.get("t", "0") or 0)) < 300      # reject old (replayed) messages
    if not fresh or not hmac.compare_digest(parts.get("v1", ""), expected):
        return "bad signature", 400

    event = json.loads(raw)
    # event["id"] is the same on every retry: if you have already handled it, just answer 200.
    if event["event"] == "order.completed":
        pass   # event["data"]["client_reference"] is YOUR reference: mark that order as delivered
    elif event["event"] == "order.failed":
        pass   # tell your customer; event["data"]["refunded"] says whether the money is back in your wallet
    return "", 200                                 # any 2xx = received

// Node.js 18+  (no dependencies)
// Run:  DATASPARK_API_KEY=dc_live_... node buy-bundle.mjs
const BASE_URL = "https://dataspark.store/api/v1";
const API_KEY = process.env.DATASPARK_API_KEY;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function api(method, path, body) {
  const res = await fetch(BASE_URL + path, {
    method,
    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(30_000),
  });
  return { status: res.status, data: await res.json() };
}

// Safe to retry: the same client_reference can never charge you twice.
async function placeOrder(order) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      const result = await api("POST", "/orders", order);
      if (result.status < 500 && result.status !== 429) return result; // 202 placed, 200 already placed, 4xx fix the request
    } catch (err) {
      // timeout or network error: retry with the SAME client_reference
    }
    await sleep(2000 * attempt);
  }
  throw new Error("Could not place the order. Look it up by client_reference before trying again.");
}

const { data: list } = await api("GET", "/bundles?network=mtn");
const bundle = list.data[0];
console.log(`Bundle: ${bundle.name} at GHS ${bundle.price.toFixed(2)}`);

const { status, data: order } = await placeOrder({
  bundle_id: bundle.id,
  phone: "0244123456",
  client_reference: `ORDER-${Date.now()}`, // use YOUR own unique order id here
});
if (status !== 200 && status !== 202) {
  console.error(`Order rejected: ${order.error.message}`);
  process.exit(1);
}
console.log(`Order placed: ${order.id} (${order.status})`);

let current;
for (let i = 0; i < 6; i++) {
  current = (await api("GET", `/orders/${order.id}`)).data;
  if (current.status !== "processing") break;
  await sleep(10_000); // checking every 10 seconds is plenty
}
console.log(`Status: ${current.status}`);

// Express (Node.js 18+)      npm install express
// Your website or app calls THIS endpoint. Only this server knows the API key.
import express from "express";

const BASE_URL = "https://dataspark.store/api/v1";
const API_KEY = process.env.DATASPARK_API_KEY; // keep it in an environment variable, never in browser code

const app = express();
app.use(express.json());

const call = (method, path, body) =>
  fetch(BASE_URL + path, {
    method,
    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(30_000),
  });

// POST /buy  { "orderId": "1001", "phone": "0244123456", "bundleId": "..." }
app.post("/buy", async (req, res) => {
  const { orderId, phone, bundleId } = req.body || {};
  if (!orderId || !phone || !bundleId) {
    return res.status(400).json({ ok: false, error: "orderId, phone and bundleId are required" });
  }
  try {
    const r = await call("POST", "/orders", { bundle_id: bundleId, phone, client_reference: String(orderId) });
    const data = await r.json();
    if (r.status === 200 || r.status === 202) return res.json({ ok: true, order: data });
    return res.status(r.status >= 500 ? 502 : r.status).json({ ok: false, error: data.error });
  } catch (err) {
    // Result unknown (timeout, network). Calling /buy again with the SAME orderId is safe.
    return res.status(502).json({ ok: false, error: "Could not reach the data service. Retry with the same orderId." });
  }
});

// GET /buy/1001  ->  status of that purchase
app.get("/buy/:orderId", async (req, res) => {
  try {
    const r = await call("GET", `/orders?client_reference=${encodeURIComponent(req.params.orderId)}`);
    const data = await r.json();
    return res.status(r.status >= 500 ? 502 : r.status).json(r.ok ? { ok: true, order: data } : { ok: false, error: data.error });
  } catch (err) {
    return res.status(502).json({ ok: false, error: "Could not reach the data service." });
  }
});

app.listen(process.env.PORT || 3000, () => console.log("Listening"));

# Python 3.8+      pip install requests
# Run:  DATASPARK_API_KEY=dc_live_... python buy_bundle.py
import os
import time

import requests

BASE_URL = "https://dataspark.store/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['DATASPARK_API_KEY']}"}


def place_order(order, attempts=3):
    """Safe to retry: the same client_reference can never charge you twice."""
    for attempt in range(1, attempts + 1):
        try:
            r = requests.post(f"{BASE_URL}/orders", json=order, headers=HEADERS, timeout=30)
            if r.status_code < 500 and r.status_code != 429:
                return r  # 202 placed, 200 already placed, 4xx fix the request
        except requests.RequestException:
            pass  # timeout or network error: retry with the SAME client_reference
        time.sleep(2 * attempt)
    raise RuntimeError("Could not place the order. Look it up by client_reference before trying again.")


bundles = requests.get(f"{BASE_URL}/bundles", params={"network": "mtn"}, headers=HEADERS, timeout=30).json()["data"]
bundle = bundles[0]
print(f"Bundle: {bundle['name']} at GHS {bundle['price']:.2f}")

r = place_order({
    "bundle_id": bundle["id"],
    "phone": "0244123456",
    "client_reference": f"ORDER-{int(time.time())}",  # use YOUR own unique order id here
})
order = r.json()
if r.status_code not in (200, 202):
    raise SystemExit(f"Order rejected: {order['error']['message']}")
print(f"Order placed: {order['id']} ({order['status']})")

for _ in range(6):
    current = requests.get(f"{BASE_URL}/orders/{order['id']}", headers=HEADERS, timeout=30).json()
    if current["status"] != "processing":
        break
    time.sleep(10)  # checking every 10 seconds is plenty
print(f"Status: {current['status']}")

<?php
// PHP 7.4+ with the cURL extension
// Run:  DATASPARK_API_KEY=dc_live_... php buy-bundle.php

const BASE_URL = 'https://dataspark.store/api/v1';
$apiKey = getenv('DATASPARK_API_KEY');

/** Returns [httpStatus, decodedJson]. httpStatus is 0 on a network error or timeout. */
function api(string $method, string $path, ?array $body = null): array
{
    global $apiKey;
    $ch = curl_init(BASE_URL . $path);
    $options = [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ["Authorization: Bearer $apiKey", 'Content-Type: application/json'],
    ];
    if ($body !== null) {
        $options[CURLOPT_POSTFIELDS] = json_encode($body);
    }
    curl_setopt_array($ch, $options);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($raw === false) {
        return [0, null];
    }
    return [$status, json_decode($raw, true)];
}

// Safe to retry: the same client_reference can never charge you twice.
function placeOrder(array $order): array
{
    for ($attempt = 1; $attempt <= 3; $attempt++) {
        [$status, $data] = api('POST', '/orders', $order);
        if ($status !== 0 && $status < 500 && $status !== 429) {
            return [$status, $data]; // 202 placed, 200 already placed, 4xx fix the request
        }
        sleep(2 * $attempt); // timeout or network error: retry with the SAME client_reference
    }
    throw new RuntimeException('Could not place the order. Look it up by client_reference before trying again.');
}

[, $list] = api('GET', '/bundles?network=mtn');
$bundle = $list['data'][0];
printf("Bundle: %s at GHS %.2f\n", $bundle['name'], $bundle['price']);

[$status, $order] = placeOrder([
    'bundle_id'        => $bundle['id'],
    'phone'            => '0244123456',
    'client_reference' => 'ORDER-' . time(), // use YOUR own unique order id here
]);
if ($status !== 200 && $status !== 202) {
    fwrite(STDERR, 'Order rejected: ' . $order['error']['message'] . "\n");
    exit(1);
}
echo "Order placed: {$order['id']} ({$order['status']})\n";

for ($i = 0; $i < 6; $i++) {
    [, $current] = api('GET', '/orders/' . $order['id']);
    if ($current['status'] !== 'processing') {
        break;
    }
    sleep(10); // checking every 10 seconds is plenty
}
echo "Status: {$current['status']}\n";

<?php
/**
 * Plugin Name: Dataspark Data Bundles for WooCommerce (example)
 * Description: When a WooCommerce order is paid, buys the matching data bundle through the Dataspark API.
 *
 * SETUP
 *  1. In wp-config.php (never in the database or the theme):
 *       define('DATASPARK_API_KEY', 'dc_live_...');
 *  2. On each WooCommerce product, add a custom field  _dataspark_bundle_id  = the bundle id from GET /bundles.
 *  3. Make sure checkout asks for the billing phone number (the number that receives the data).
 *
 * This is an EXAMPLE to adapt. Test it on a staging site with a small bundle first.
 */
defined('ABSPATH') || exit;

const DATASPARK_BASE_URL = 'https://dataspark.store/api/v1';

/** Returns [httpStatus, decodedJson]; httpStatus is 0 on a network error or timeout. */
function dataspark_request(string $method, string $path, ?array $body = null): array
{
    $args = [
        'method'  => $method,
        'timeout' => 30,
        'headers' => [
            'Authorization' => 'Bearer ' . DATASPARK_API_KEY,
            'Content-Type'  => 'application/json',
        ],
    ];
    if ($body !== null) {
        $args['body'] = wp_json_encode($body);
    }
    $response = wp_remote_request(DATASPARK_BASE_URL . $path, $args);
    if (is_wp_error($response)) {
        return [0, null];
    }
    return [(int) wp_remote_retrieve_response_code($response), json_decode(wp_remote_retrieve_body($response), true)];
}

/** Buys one bundle. Safe to run twice: the same client_reference can never charge you twice. */
function dataspark_buy_bundle(string $bundleId, string $phone, string $reference): array
{
    for ($attempt = 1; $attempt <= 3; $attempt++) {
        [$status, $data] = dataspark_request('POST', '/orders', [
            'bundle_id'        => $bundleId,
            'phone'            => $phone,
            'client_reference' => $reference,
        ]);
        if ($status !== 0 && $status < 500 && $status !== 429) {
            return [$status, $data]; // 202 placed, 200 already placed, 4xx a problem with the request
        }
        sleep(2 * $attempt);
    }
    return [0, null];
}

add_action('woocommerce_order_status_processing', function ($order_id) {
    $order = wc_get_order($order_id);
    if (!$order) {
        return;
    }
    foreach ($order->get_items() as $item_id => $item) {
        $bundleId = get_post_meta($item->get_product_id(), '_dataspark_bundle_id', true);
        if (!$bundleId) {
            continue; // not a data bundle product
        }
        if ($item->get_meta('_dataspark_order_id')) {
            continue; // already bought (the status hook can fire more than once)
        }
        $reference = "wc-{$order_id}-{$item_id}"; // unique and stable for this order line
        [$status, $data] = dataspark_buy_bundle($bundleId, $order->get_billing_phone(), $reference);

        if ($status === 200 || $status === 202) {
            $item->update_meta_data('_dataspark_order_id', $data['id']);
            $item->save();
            $order->add_order_note("Data bundle ordered (Dataspark order {$data['id']}).");
        } else {
            $why = $data['error']['message'] ?? 'No answer from the data service.';
            $order->add_order_note("Data bundle NOT ordered: {$why} Check before trying again.");
            $order->update_status('on-hold');
        }
    }
});

# Ruby 2.7+  (standard library only)
# Run:  DATASPARK_API_KEY=dc_live_... ruby buy_bundle.rb
require "json"
require "net/http"
require "uri"

BASE_URL = "https://dataspark.store/api/v1"
API_KEY = ENV.fetch("DATASPARK_API_KEY")

def api(method, path, body = nil)
  uri = URI(BASE_URL + path)
  request = Net::HTTP.const_get(method.capitalize).new(uri)
  request["Authorization"] = "Bearer #{API_KEY}"
  request["Content-Type"] = "application/json"
  request.body = JSON.generate(body) if body
  response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 30) { |http| http.request(request) }
  [response.code.to_i, JSON.parse(response.body)]
end

# Safe to retry: the same client_reference can never charge you twice.
def place_order(order)
  3.times do |i|
    begin
      status, data = api("post", "/orders", order)
      return [status, data] if status < 500 && status != 429 # 202 placed, 200 already placed, 4xx fix the request
    rescue StandardError
      # timeout or network error: retry with the SAME client_reference
    end
    sleep(2 * (i + 1))
  end
  raise "Could not place the order. Look it up by client_reference before trying again."
end

_, list = api("get", "/bundles?network=mtn")
bundle = list["data"].first
puts format("Bundle: %s at GHS %.2f", bundle["name"], bundle["price"])

status, order = place_order(
  "bundle_id" => bundle["id"],
  "phone" => "0244123456",
  "client_reference" => "ORDER-#{Time.now.to_i}" # use YOUR own unique order id here
)
abort("Order rejected: #{order['error']['message']}") unless [200, 202].include?(status)
puts "Order placed: #{order['id']} (#{order['status']})"

current = nil
6.times do
  _, current = api("get", "/orders/#{order['id']}")
  break unless current["status"] == "processing"
  sleep 10 # checking every 10 seconds is plenty
end
puts "Status: #{current['status']}"

// Java 17+  (no dependencies; in real projects parse JSON with Jackson or Gson)
// Run:  DATASPARK_API_KEY=dc_live_... java BuyBundle.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class BuyBundle {
    static final String BASE_URL = "https://dataspark.store/api/v1";
    static final String API_KEY = System.getenv("DATASPARK_API_KEY");
    static final HttpClient CLIENT = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build();

    record Reply(int status, String body) {}

    static Reply api(String method, String path, String jsonBody) throws Exception {
        HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(BASE_URL + path))
                .timeout(Duration.ofSeconds(30))
                .header("Authorization", "Bearer " + API_KEY)
                .header("Content-Type", "application/json");
        b.method(method, jsonBody == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(jsonBody));
        HttpResponse<String> r = CLIENT.send(b.build(), HttpResponse.BodyHandlers.ofString());
        return new Reply(r.statusCode(), r.body());
    }

    // Tiny helper so this sample needs no libraries: reads a top-level-looking string/number field.
    static String field(String json, String name) {
        Matcher m = Pattern.compile("\"" + name + "\"\\s*:\\s*(?:\"([^\"]*)\"|([0-9.]+))").matcher(json);
        return m.find() ? (m.group(1) != null ? m.group(1) : m.group(2)) : null;
    }

    // Safe to retry: the same client_reference can never charge you twice.
    static Reply placeOrder(String json) throws Exception {
        for (int attempt = 1; attempt <= 3; attempt++) {
            try {
                Reply r = api("POST", "/orders", json);
                if (r.status() < 500 && r.status() != 429) return r; // 202 placed, 200 already placed, 4xx fix the request
            } catch (java.io.IOException e) {
                // timeout or network error: retry with the SAME client_reference
            }
            Thread.sleep(2000L * attempt);
        }
        throw new IllegalStateException("Could not place the order. Look it up by client_reference before trying again.");
    }

    public static void main(String[] args) throws Exception {
        String list = api("GET", "/bundles?network=mtn", null).body();
        String bundleId = field(list, "id");
        System.out.printf("Bundle: %s at GHS %.2f%n", field(list, "name"), Double.parseDouble(field(list, "price")));

        String reference = "ORDER-" + System.currentTimeMillis(); // use YOUR own unique order id here
        Reply order = placeOrder("{\"bundle_id\":\"" + bundleId + "\",\"phone\":\"0244123456\",\"client_reference\":\"" + reference + "\"}");
        if (order.status() != 200 && order.status() != 202) {
            System.err.println("Order rejected: " + field(order.body(), "message"));
            System.exit(1);
        }
        String orderId = field(order.body(), "id");
        System.out.println("Order placed: " + orderId + " (" + field(order.body(), "status") + ")");

        String status = null;
        for (int i = 0; i < 6; i++) {
            status = field(api("GET", "/orders/" + orderId, null).body(), "status");
            if (!"processing".equals(status)) break;
            Thread.sleep(10_000); // checking every 10 seconds is plenty
        }
        System.out.println("Status: " + status);
    }
}

// C# / .NET 6+  (no packages needed)
// Run:  DATASPARK_API_KEY=dc_live_... dotnet run
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

const string BaseUrl = "https://dataspark.store/api/v1";
var apiKey = Environment.GetEnvironmentVariable("DATASPARK_API_KEY");

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

async Task<(int Status, JsonElement Body)> Api(HttpMethod method, string path, object? body = null)
{
    using var request = new HttpRequestMessage(method, BaseUrl + path);
    if (body != null)
        request.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
    using var response = await http.SendAsync(request);
    var text = await response.Content.ReadAsStringAsync();
    return ((int)response.StatusCode, JsonDocument.Parse(text).RootElement.Clone());
}

// Safe to retry: the same client_reference can never charge you twice.
async Task<(int Status, JsonElement Body)> PlaceOrder(object order)
{
    for (var attempt = 1; attempt <= 3; attempt++)
    {
        try
        {
            var result = await Api(HttpMethod.Post, "/orders", order);
            if (result.Status < 500 && result.Status != 429) return result; // 202 placed, 200 already placed, 4xx fix the request
        }
        catch (Exception e) when (e is HttpRequestException or TaskCanceledException)
        {
            // timeout or network error: retry with the SAME client_reference
        }
        await Task.Delay(2000 * attempt);
    }
    throw new Exception("Could not place the order. Look it up by client_reference before trying again.");
}

var list = (await Api(HttpMethod.Get, "/bundles?network=mtn")).Body;
var bundle = list.GetProperty("data")[0];
Console.WriteLine($"Bundle: {bundle.GetProperty("name").GetString()} at GHS {bundle.GetProperty("price").GetDecimal():F2}");

var (status, order) = await PlaceOrder(new
{
    bundle_id = bundle.GetProperty("id").GetString(),
    phone = "0244123456",
    client_reference = $"ORDER-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}", // use YOUR own unique order id here
});
if (status != 200 && status != 202)
{
    Console.Error.WriteLine($"Order rejected: {order.GetProperty("error").GetProperty("message").GetString()}");
    return 1;
}
var orderId = order.GetProperty("id").GetString();
Console.WriteLine($"Order placed: {orderId} ({order.GetProperty("status").GetString()})");

string? current = null;
for (var i = 0; i < 6; i++)
{
    current = (await Api(HttpMethod.Get, $"/orders/{orderId}")).Body.GetProperty("status").GetString();
    if (current != "processing") break;
    await Task.Delay(10_000); // checking every 10 seconds is plenty
}
Console.WriteLine($"Status: {current}");
return 0;

// Go 1.18+  (standard library only)
// Run:  DATASPARK_API_KEY=dc_live_... go run buy_bundle.go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

const baseURL = "https://dataspark.store/api/v1"

var (
	apiKey = os.Getenv("DATASPARK_API_KEY")
	client = &http.Client{Timeout: 30 * time.Second}
)

// api returns the HTTP status and the decoded JSON body.
func api(method, path string, body any) (int, map[string]any, error) {
	var reader *bytes.Reader
	if body != nil {
		payload, _ := json.Marshal(body)
		reader = bytes.NewReader(payload)
	} else {
		reader = bytes.NewReader(nil)
	}
	req, err := http.NewRequest(method, baseURL+path, reader)
	if err != nil {
		return 0, nil, err
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	res, err := client.Do(req)
	if err != nil {
		return 0, nil, err
	}
	defer res.Body.Close()
	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		return res.StatusCode, nil, err
	}
	return res.StatusCode, data, nil
}

// placeOrder is safe to retry: the same client_reference can never charge you twice.
func placeOrder(order map[string]any) (int, map[string]any, error) {
	for attempt := 1; attempt <= 3; attempt++ {
		status, data, err := api("POST", "/orders", order)
		if err == nil && status < 500 && status != 429 {
			return status, data, nil // 202 placed, 200 already placed, 4xx fix the request
		}
		time.Sleep(time.Duration(2*attempt) * time.Second) // timeout or network error: retry with the SAME client_reference
	}
	return 0, nil, fmt.Errorf("could not place the order; look it up by client_reference before trying again")
}

func main() {
	_, list, err := api("GET", "/bundles?network=mtn", nil)
	if err != nil {
		panic(err)
	}
	bundle := list["data"].([]any)[0].(map[string]any)
	fmt.Printf("Bundle: %s at GHS %.2f\n", bundle["name"], bundle["price"].(float64))

	status, order, err := placeOrder(map[string]any{
		"bundle_id":        bundle["id"],
		"phone":            "0244123456",
		"client_reference": fmt.Sprintf("ORDER-%d", time.Now().Unix()), // use YOUR own unique order id here
	})
	if err != nil {
		panic(err)
	}
	if status != 200 && status != 202 {
		fmt.Println("Order rejected:", order["error"].(map[string]any)["message"])
		os.Exit(1)
	}
	fmt.Printf("Order placed: %s (%s)\n", order["id"], order["status"])

	var current map[string]any
	for i := 0; i < 6; i++ {
		_, current, _ = api("GET", "/orders/"+order["id"].(string), nil)
		if current["status"] != "processing" {
			break
		}
		time.Sleep(10 * time.Second) // checking every 10 seconds is plenty
	}
	fmt.Printf("Status: %s\n", current["status"])
}