> ## 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.

# Accept your first payment

> Create an ugwo and charge it end-to-end in under five minutes.

This walkthrough takes you from a freshly issued secret key to a
successful charge. You'll create a payment request, run a `charge`
activity against it, and poll for the result.

<Steps>
  <Step title="Set your secret key">
    Export the key from your dashboard's API Keys screen:

    ```bash theme={null}
    export KWUGWO_SECRET_KEY=sk.VCvr.1MsEBjzxlrfJdomgQlVgSlbZzFMjyQXCjnxayf6JnP6EsQEUcRgFPimPbtsP9nokwwpWmOeoweezF0Ja
    ```
  </Step>

  <Step title="Create an ugwo">
    Charge `5,000.00 NGN`. Amounts are sent in the **smallest
    currency unit** (kobo for NGN, pesewas for GHS, cents for USD).

    ```bash 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: 1x leather notebook",
        "metadata": { "order_id": "4719" }
      }'
    ```

    You'll get back the new ugwo. Save the `uid`.

    ```json theme={null}
    {
      "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
      "amount": 500000,
      "currency": "NGN",
      "status": "requires_ugwo",
      "ref": "order_4719",
      "...": "..."
    }
    ```
  </Step>

  <Step title="Charge it">
    Run a `charge` activity. The medium and any medium-specific
    parameters go in the `data` object.

    ```bash theme={null}
    curl https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE/activities \
      -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "charge",
        "data": { "medium": "bank_transfer" }
      }'
    ```

    The response includes the activity, its initial `status`, and any
    `next_action` your customer needs to take. For `bank_transfer`
    that's a `user_action` with a virtual account number and an
    `expires_at` in the `headers` block.
  </Step>

  <Step title="Poll the activity">
    Poll the activity (or wait for your webhook) until `status` is
    `successful` or `failed`. The same ugwo can host many activities,
    so make sure you track the specific `act.…` ID you just
    submitted.

    ```bash theme={null}
    curl https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE/activities/act.VCvr.X9yLp2KmRtV7nQ8sD4cYwHfE \
      -H "Authorization: Bearer $KWUGWO_SECRET_KEY"
    ```
  </Step>
</Steps>

## Next steps

* Persist the `uid` on your order so you can match webhook
  notifications later.
* Set up a [customer record](/customers/create) and pass its `uid` as
  `onye` when you create the ugwo, so your dashboard groups payments
  by payer.
* Configure a [hosted checkout](/checkouts/list) and reference it on
  the ugwo (`"checkout": "chk.…"`) to override the workspace's
  default routing rules.