> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kwugwo.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an ugwo

> Create a new payment request.

Creates a payment request (an **ugwo**) on the workspace that owns
your secret key. The ugwo starts in the `requires_ugwo` status;
running a [`charge` activity](/ugwo/create-activity) against it moves
it through the rest of its lifecycle.

## Body parameters

<ParamField body="amount" type="integer" required>
  Amount to charge, in the **smallest currency unit** (kobo for `NGN`,
  pesewas for `GHS`, cents for `USD`).
</ParamField>

<ParamField body="currency" type="string" required>
  ISO-4217 currency code. Must be a [supported
  currency](/concepts#currencies) and must be enabled on at least one
  of your PSPs.
</ParamField>

<ParamField body="onye" type="string">
  ID of an existing customer (`ony.…`). When set, the ugwo is
  attached to that customer and the merchant dashboard groups it under
  their record.

  If `onye` is omitted, the workspace (nzube) must have a **default
  payment email** configured in its settings; otherwise the request
  fails with `422`.
</ParamField>

<ParamField body="onye_email" type="string">
  Email address used to resolve the customer when `onye` is not
  provided. Must be a valid email. If an onye with this email already
  exists on the workspace, that onye is attached to the ugwo;
  otherwise a new onye is created with this email and attached.

  Ignored when `onye` is provided. If neither `onye` nor `onye_email`
  is provided, the workspace's **default payment email** is used (see
  `onye` above).
</ParamField>

<ParamField body="ref" type="string">
  Your own reference (max 150 chars), typically an order number or
  invoice ID. Echoed back on the ugwo and on webhook deliveries.

  **Case-sensitive.** `"Id"` and `"id"` are stored and looked up as
  distinct values.
</ParamField>

<ParamField body="description" type="string">
  Human-readable description (max 150 chars) shown to the customer on
  the hosted checkout. Must not contain newline characters.
</ParamField>

<ParamField body="checkout" type="string">
  ID of a [checkout](/checkouts/list) (`chk.…`). When set, the ugwo
  is pinned to this checkout and Kwugwo's automatic checkout routing
  is bypassed; the workspace's routing rules are ignored for this
  ugwo.
</ParamField>

<ParamField body="meta" type="object">
  Free-form `{ string: string }` map for your own tagging. Stored
  verbatim and surfaced on the dashboard. Not shown to the customer.
</ParamField>

## Response

<ResponseField name="uid" type="string">
  The new ugwo's ID (`ugw.…`). Persist this on your order.
</ResponseField>

<ResponseField name="amount" type="integer">Amount in smallest currency unit.</ResponseField>
<ResponseField name="currency" type="string">ISO-4217 code.</ResponseField>
<ResponseField name="status" type="string">Always `requires_ugwo` for a freshly created ugwo.</ResponseField>
<ResponseField name="ref" type="string | null">Your reference, if you sent one.</ResponseField>
<ResponseField name="description" type="string | null">Description, if you sent one.</ResponseField>
<ResponseField name="meta" type="object">Echoed metadata.</ResponseField>
<ResponseField name="onye" type="object | null">The attached customer, if any (`null` otherwise).</ResponseField>
<ResponseField name="checkout" type="object | null">The attached checkout, if any.</ResponseField>
<ResponseField name="created_at" type="string">ISO-8601 timestamp.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.kwugwo.africa/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": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
      "meta": { "order_id": "4719", "channel": "web" }
    }'
  ```

  ```js Node theme={null}
  const res = await fetch("https://api.kwugwo.africa/v1/ugwo", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 500000,
      currency: "NGN",
      ref: "order_4719",
      description: "Order #4719",
      onye: "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
      meta: { order_id: "4719", channel: "web" },
    }),
  });
  const ugwo = await res.json();
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.kwugwo.africa/v1/ugwo");
  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([
          'amount'      => 500000,
          'currency'    => 'NGN',
          'ref'         => 'order_4719',
          'description' => 'Order #4719',
          'onye'        => 'ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE',
          'meta'        => ['order_id' => '4719', 'channel' => 'web'],
      ]),
  ]);
  $ugwo = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```

  ```python Python theme={null}
  import os, requests

  ugwo = requests.post(
      "https://api.kwugwo.africa/v1/ugwo",
      headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
      json={
          "amount": 500000,
          "currency": "NGN",
          "ref": "order_4719",
          "description": "Order #4719",
          "onye": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
          "meta": {"order_id": "4719", "channel": "web"},
      },
  ).json()
  ```

  ```go Go theme={null}
  package main

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

  func main() {
      body, _ := json.Marshal(map[string]any{
          "amount":      500000,
          "currency":    "NGN",
          "ref":         "order_4719",
          "description": "Order #4719",
          "onye":        "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
          "meta":        map[string]string{"order_id": "4719", "channel": "web"},
      })

      req, _ := http.NewRequest("POST", "https://api.kwugwo.africa/v1/ugwo", 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()
      out, _ := io.ReadAll(resp.Body)
      fmt.Println(string(out))
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
    "amount": 500000,
    "currency": "NGN",
    "status": "requires_ugwo",
    "ref": "order_4719",
    "description": "Order #4719",
    "meta": { "order_id": "4719", "channel": "web" },
    "onye": {
      "uid": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Okeke"
    },
    "checkout": null,
    "created_at": "2026-05-15T09:14:22+00:00"
  }
  ```

  ```json 422 Validation Failed theme={null}
  {
    "title": "Validation Failed",
    "status": 422,
    "violations": [
      { "propertyPath": "amount", "title": "The amount must be an integer." }
    ]
  }
  ```
</ResponseExample>