Quickstart

You’ll create a payment, charge it by bank transfer, and confirm it was paid. Everything runs against sandbox, so no real money moves. Pick your language in any code block; each step builds on the helper from step 1.

Before you start

A Kwugwo account with a sandbox workspace.
At least one PSP connected in sandbox (in its test mode), with a checkout that offers Bank transfer. See Testing in sandbox.
Your sandbox secret key from Dashboard → API Keys.

Your secret key goes on your server only. Never ship it to a browser or mobile app.

Set your key and make a first call

Put your key and the sandbox base URL in environment variables:

export KWUGWO_SECRET_KEY=sk.XXXX.your_sandbox_secret_key
export KWUGWO_API=https://sandbox-api.kwugwo.africa

Then add a small helper that sends authenticated JSON requests, and use it to list your checkouts:

curl $KWUGWO_API/v1/checkouts \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY"

// Node 18+ (built-in fetch). Save as quickstart.mjs
const API = process.env.KWUGWO_API;
const KEY = process.env.KWUGWO_SECRET_KEY;

async function kwugwo(method, path, body) {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${JSON.stringify(json)}`);
  return json;
}

console.log(await kwugwo("GET", "/v1/checkouts"));

// Node 18+ (built-in fetch). Save as quickstart.mts, run with `npx tsx quickstart.mts`
const API = process.env.KWUGWO_API!;
const KEY = process.env.KWUGWO_SECRET_KEY!;

interface Ugwo {
  uid: string;
  ref: string | null;
  amount: number;
  currency: string;
  status: "requires_ugwo" | "processing" | "ugwo_successful" | "partially_refunded" | "refunded" | "cancelled";
  total_amount_paid: number;
  checkout: { uid: string; currency: string; mediums: { medium: string }[] } | null;
}

interface Activity {
  uid: string;
  status: string;
  next_action: {
    uid: string;
    action: { type: string; instruction?: string; headers?: Record<string, string | null> };
    status: "pending" | "fulfilled" | "expired";
    expires_at: string | null;
  } | null;
}

async function kwugwo<T>(method: string, path: string, body?: unknown): Promise<T> {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${JSON.stringify(json)}`);
  return json as T;
}

console.log(await kwugwo("GET", "/v1/checkouts"));

# pip install requests. Save as quickstart.py
import os
import requests

API = os.environ["KWUGWO_API"]
KEY = os.environ["KWUGWO_SECRET_KEY"]

def kwugwo(method, path, body=None):
    res = requests.request(
        method,
        f"{API}{path}",
        headers={"Authorization": f"Bearer {KEY}"},
        json=body,
        timeout=30,
    )
    if not res.ok:
        raise RuntimeError(f"{res.status_code}: {res.text}")
    return res.json()

print(kwugwo("GET", "/v1/checkouts"))

<?php
// Save as quickstart.php
$API = getenv('KWUGWO_API');
$KEY = getenv('KWUGWO_SECRET_KEY');

function kwugwo(string $method, string $path, ?array $body = null): array
{
    global $API, $KEY;
    $ch = curl_init($API . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $KEY,
            'Content-Type: application/json',
        ],
    ]);
    if ($body !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    $raw    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($status >= 400) {
        throw new RuntimeException("$status: $raw");
    }
    return json_decode($raw, true);
}

print_r(kwugwo('GET', '/v1/checkouts'));

// Save as main.go, run with `go run main.go`
package main

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

var (
    api = os.Getenv("KWUGWO_API")
    key = os.Getenv("KWUGWO_SECRET_KEY")
)

func kwugwo(method, path string, body, out any) error {
    var reader io.Reader
    if body != nil {
        b, _ := json.Marshal(body)
        reader = bytes.NewReader(b)
    }
    req, _ := http.NewRequest(method, api+path, reader)
    req.Header.Set("Authorization", "Bearer "+key)
    req.Header.Set("Content-Type", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer res.Body.Close()
    raw, _ := io.ReadAll(res.Body)
    if res.StatusCode >= 400 {
        return fmt.Errorf("%d: %s", res.StatusCode, raw)
    }
    return json.Unmarshal(raw, out)
}

func main() {
    var checkouts []map[string]any
    if err := kwugwo("GET", "/v1/checkouts", nil, &checkouts); err != nil {
        panic(err)
    }
    fmt.Println(checkouts)
}

You should see your checkouts. A 401 means the key is wrong, or is a live key used against sandbox.

Create a payment

Charge ₦5,000.00. Amounts are in the smallest currency unit (kobo), so that’s 500000. ref is your order ID; it’s unique per workspace, so a retry can’t create a duplicate payment.

curl $KWUGWO_API/v1/ugwo \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "NGN",
    "ref": "order_4719",
    "description": "Order #4719",
    "onye_email": "ada@example.com"
  }'

const ugwo = await kwugwo("POST", "/v1/ugwo", {
  amount: 500000,
  currency: "NGN",
  ref: "order_4719",
  description: "Order #4719",
  onye_email: "ada@example.com",
});
console.log(ugwo.uid, ugwo.status); // ugw.… requires_ugwo

const ugwo = await kwugwo<Ugwo>("POST", "/v1/ugwo", {
  amount: 500000,
  currency: "NGN",
  ref: "order_4719",
  description: "Order #4719",
  onye_email: "ada@example.com",
});
console.log(ugwo.uid, ugwo.status); // ugw.… requires_ugwo

ugwo = kwugwo("POST", "/v1/ugwo", {
    "amount": 500000,
    "currency": "NGN",
    "ref": "order_4719",
    "description": "Order #4719",
    "onye_email": "ada@example.com",
})
print(ugwo["uid"], ugwo["status"])  # ugw.… requires_ugwo

$ugwo = kwugwo('POST', '/v1/ugwo', [
    'amount'      => 500000,
    'currency'    => 'NGN',
    'ref'         => 'order_4719',
    'description' => 'Order #4719',
    'onye_email'  => 'ada@example.com',
]);
echo $ugwo['uid'], ' ', $ugwo['status'], PHP_EOL; // ugw.… requires_ugwo

var ugwo struct {
    UID    string `json:"uid"`
    Status string `json:"status"`
}
err := kwugwo("POST", "/v1/ugwo", map[string]any{
    "amount":      500000,
    "currency":    "NGN",
    "ref":         "order_4719",
    "description": "Order #4719",
    "onye_email":  "ada@example.com",
}, &ugwo)
if err != nil {
    panic(err)
}
fmt.Println(ugwo.UID, ugwo.Status) // ugw.… requires_ugwo

Response (trimmed)

{
  "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwH_t",
  "ref": "order_4719",
  "amount": 500000,
  "currency": "NGN",
  "status": "requires_ugwo",
  "checkout": { "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAA_t", "currency": "NGN", "mediums": [{ "medium": "bank_transfer" }] },
  "total_amount_paid": 0
}

Save the uid with your order. If checkout is null, add "checkout": "chk.…" (from step 1) to the request.

Using the embedded checkout? Stop here: hand this uid to checkout.open({ ugwoUid }) in the browser and skip to step 4.

Charge it by bank transfer

Start a payment attempt (an activity). Bank transfer needs no extra parameters; other mediums take theirs in data.medium_params.

curl $KWUGWO_API/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwH_t/activities \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "charge",
    "data": { "medium": "bank_transfer" }
  }'

const activity = await kwugwo("POST", `/v1/ugwo/${ugwo.uid}/activities`, {
  type: "charge",
  data: { medium: "bank_transfer" },
});
console.log(activity.status);                     // requires_action
console.log(activity.next_action.action.headers); // account to pay into

const activity = await kwugwo<Activity>("POST", `/v1/ugwo/${ugwo.uid}/activities`, {
  type: "charge",
  data: { medium: "bank_transfer" },
});
console.log(activity.status);                      // requires_action
console.log(activity.next_action?.action.headers); // account to pay into

activity = kwugwo("POST", f"/v1/ugwo/{ugwo['uid']}/activities", {
    "type": "charge",
    "data": {"medium": "bank_transfer"},
})
print(activity["status"])                          # requires_action
print(activity["next_action"]["action"]["headers"])  # account to pay into

$activity = kwugwo('POST', "/v1/ugwo/{$ugwo['uid']}/activities", [
    'type' => 'charge',
    'data' => ['medium' => 'bank_transfer'],
]);
echo $activity['status'], PHP_EOL;                  // requires_action
print_r($activity['next_action']['action']['headers']); // account to pay into

var activity struct {
    UID        string `json:"uid"`
    Status     string `json:"status"`
    NextAction struct {
        Action struct {
            Type    string            `json:"type"`
            Headers map[string]string `json:"headers"`
        } `json:"action"`
    } `json:"next_action"`
}
err = kwugwo("POST", "/v1/ugwo/"+ugwo.UID+"/activities", map[string]any{
    "type": "charge",
    "data": map[string]any{"medium": "bank_transfer"},
}, &activity)
if err != nil {
    panic(err)
}
fmt.Println(activity.Status)                    // requires_action
fmt.Println(activity.NextAction.Action.Headers) // account to pay into

Response (trimmed)

{
  "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDl_t",
  "status": "requires_action",
  "next_action": {
    "action": {
      "type": "user_action",
      "instruction": "Transfer to bank",
      "headers": {
        "bank_name": "Test Bank",
        "account_number": "1260881821",
        "account_name": "PAYSTACK CHECKOUT",
        "expires_at": "2026-05-14T20:10:50+00:00"
      }
    },
    "status": "pending"
  }
}

In production you’d show the customer these account details. In sandbox, complete the transfer with your PSP’s test tools; see Testing in sandbox.

Confirm the payment

Kwugwo sends ugwo.successful to your webhook endpoint once the PSP confirms. Either way, confirm from your server by fetching the ugwo:

curl $KWUGWO_API/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwH_t \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY"

const latest = await kwugwo("GET", `/v1/ugwo/${ugwo.uid}`);
const paid =
  latest.status === "ugwo_successful" &&
  latest.total_amount_paid >= latest.amount &&
  latest.ref === "order_4719";
console.log(paid ? "Paid: fulfil the order" : `Not yet: ${latest.status}`);

const latest = await kwugwo<Ugwo>("GET", `/v1/ugwo/${ugwo.uid}`);
const paid =
  latest.status === "ugwo_successful" &&
  latest.total_amount_paid >= latest.amount &&
  latest.ref === "order_4719";
console.log(paid ? "Paid: fulfil the order" : `Not yet: ${latest.status}`);

latest = kwugwo("GET", f"/v1/ugwo/{ugwo['uid']}")
paid = (
    latest["status"] == "ugwo_successful"
    and latest["total_amount_paid"] >= latest["amount"]
    and latest["ref"] == "order_4719"
)
print("Paid: fulfil the order" if paid else f"Not yet: {latest['status']}")

$latest = kwugwo('GET', "/v1/ugwo/{$ugwo['uid']}");
$paid = $latest['status'] === 'ugwo_successful'
    && $latest['total_amount_paid'] >= $latest['amount']
    && $latest['ref'] === 'order_4719';
echo $paid ? 'Paid: fulfil the order' : "Not yet: {$latest['status']}", PHP_EOL;

var latest struct {
    Status          string `json:"status"`
    Amount          int    `json:"amount"`
    TotalAmountPaid int    `json:"total_amount_paid"`
    Ref             string `json:"ref"`
}
if err := kwugwo("GET", "/v1/ugwo/"+ugwo.UID, nil, &latest); err != nil {
    panic(err)
}
paid := latest.Status == "ugwo_successful" &&
    latest.TotalAmountPaid >= latest.Amount &&
    latest.Ref == "order_4719"
if paid {
    fmt.Println("Paid: fulfil the order")
} else {
    fmt.Println("Not yet:", latest.Status)
}

When status is ugwo_successful, total_amount_paid covers amount, and ref is your order, the order is paid. Validate and fulfil turns this into a webhook handler.

What you built

Next steps

Embed the checkout

Let Kwugwo render every medium, bank picker and instruction.

Build your own UI

Handle every next_action type yourself.

Validate and fulfil

The checks to run before you ship an order.

Webhooks

Receive and verify events.

Get started

Plugins

Guides

Concepts

API basics

Payments (Ugwo)

Activities

Next actions

Refunds

Customers (Onye)

Checkouts

Before you start

What you built

Next steps

Embed the checkout

Build your own UI

Validate and fulfil

Webhooks

​Before you start

​What you built

​Next steps

Embed the checkout

Build your own UI

Validate and fulfil

Webhooks

Before you start

What you built

Next steps