Skip to main content
POST
/
v1
/
onye
curl https://api.kwugwo.africa/v1/onye \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "ref": "user_8821",
    "first_name": "Ada",
    "last_name": "Okeke",
    "billing_address": {
      "address": "12 Marina",
      "address2": "",
      "city": "Lagos",
      "state": "Lagos",
      "zip": "101001",
      "country": "NG"
    },
    "meta": { "source": "shopify" }
  }'

const onye = await fetch("https://api.kwugwo.africa/v1/onye", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "ada@example.com",
    ref: "user_8821",
    first_name: "Ada",
    last_name: "Okeke",
  }),
}).then(r => r.json());

<?php
$ch = curl_init("https://api.kwugwo.africa/v1/onye");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('KWUGWO_SECRET_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email'      => 'ada@example.com',
        'ref'        => 'user_8821',
        'first_name' => 'Ada',
        'last_name'  => 'Okeke',
    ]),
]);
$onye = json_decode(curl_exec($ch), true);
curl_close($ch);

import os, requests

onye = requests.post(
    "https://api.kwugwo.africa/v1/onye",
    headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
    json={
        "email": "ada@example.com",
        "ref": "user_8821",
        "first_name": "Ada",
        "last_name": "Okeke",
    },
).json()

body, _ := json.Marshal(map[string]any{
    "email":      "ada@example.com",
    "ref":        "user_8821",
    "first_name": "Ada",
    "last_name":  "Okeke",
})
req, _ := http.NewRequest("POST", "https://api.kwugwo.africa/v1/onye", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("KWUGWO_SECRET_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

{
  "uid": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
  "email": "ada@example.com",
  "ref": "user_8821",
  "first_name": "Ada",
  "last_name": "Okeke",
  "billing_address": {
    "address": "12 Marina",
    "address2": "",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "101001",
    "country": "NG"
  },
  "meta": { "source": "shopify" },
  "status": "active",
  "created_at": "2026-05-15T09:14:22+00:00"
}
Creates an onye (a customer) on the workspace that owns your secret key. Pass the resulting uid as onye when creating an ugwo to attach the payment to this customer.

​
Body parameters

​
email
string
required
Customer’s email address. Lowercased on save. Must be a valid email.
​
ref
string
Your own reference (max 150 chars), typically a user ID in your system.Case-sensitive. "Id" and "id" are stored and looked up as distinct values.
​
first_name
string
Up to 100 chars. Title-cased on save ("ada" → "Ada").
​
last_name
string
Up to 100 chars. Title-cased on save.
​
billing_address
object
Optional billing address. The object as a whole may be omitted, but when you provide it every field must be present. For a field you don’t have a value for (such as address2), pass an empty string ("") rather than omitting it. All fields are strings.
  • address: 1–100 chars
  • address2: 0–100 chars (pass "" when not available)
  • city: 1–50 chars
  • state: 1–50 chars
  • zip: 1–10 chars
  • country: exactly 2 chars (ISO-3166-1 alpha-2)
​
meta
object
Free-form { string: string | null } map for tagging; for example, a marketing source or internal segment.

​
Response

​
uid
string
Customer ID (ony.…).
​
email
string
Email address (lowercased).
​
ref
string | null
Your reference.
​
first_name
string | null
First name (title-cased).
​
last_name
string | null
Last name (title-cased).
​
billing_address
object | null
The address you provided.
​
meta
object
Echo of metadata.
​
status
string
Customer status; active for new records.
​
created_at
string
ISO-8601 timestamp.
curl https://api.kwugwo.africa/v1/onye \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "ref": "user_8821",
    "first_name": "Ada",
    "last_name": "Okeke",
    "billing_address": {
      "address": "12 Marina",
      "address2": "",
      "city": "Lagos",
      "state": "Lagos",
      "zip": "101001",
      "country": "NG"
    },
    "meta": { "source": "shopify" }
  }'

const onye = await fetch("https://api.kwugwo.africa/v1/onye", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "ada@example.com",
    ref: "user_8821",
    first_name: "Ada",
    last_name: "Okeke",
  }),
}).then(r => r.json());

<?php
$ch = curl_init("https://api.kwugwo.africa/v1/onye");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('KWUGWO_SECRET_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email'      => 'ada@example.com',
        'ref'        => 'user_8821',
        'first_name' => 'Ada',
        'last_name'  => 'Okeke',
    ]),
]);
$onye = json_decode(curl_exec($ch), true);
curl_close($ch);

import os, requests

onye = requests.post(
    "https://api.kwugwo.africa/v1/onye",
    headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
    json={
        "email": "ada@example.com",
        "ref": "user_8821",
        "first_name": "Ada",
        "last_name": "Okeke",
    },
).json()

body, _ := json.Marshal(map[string]any{
    "email":      "ada@example.com",
    "ref":        "user_8821",
    "first_name": "Ada",
    "last_name":  "Okeke",
})
req, _ := http.NewRequest("POST", "https://api.kwugwo.africa/v1/onye", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("KWUGWO_SECRET_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

{
  "uid": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
  "email": "ada@example.com",
  "ref": "user_8821",
  "first_name": "Ada",
  "last_name": "Okeke",
  "billing_address": {
    "address": "12 Marina",
    "address2": "",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "101001",
    "country": "NG"
  },
  "meta": { "source": "shopify" },
  "status": "active",
  "created_at": "2026-05-15T09:14:22+00:00"
}