Accept your first payment

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.

Set your secret key

Export the key from your dashboard’s API Keys screen:

export KWUGWO_SECRET_KEY=sk.VCvr.1MsEBjzxlrfJdomgQlVgSlbZzFMjyQXCjnxayf6JnP6EsQEUcRgFPimPbtsP9nokwwpWmOeoweezF0Ja

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

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.

{
  "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
  "amount": 500000,
  "currency": "NGN",
  "status": "requires_ugwo",
  "ref": "order_4719",
  "...": "..."
}

Charge it

Run a charge activity. The medium and any medium-specific parameters go in the data object.

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.

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.

curl https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE/activities/act.VCvr.X9yLp2KmRtV7nQ8sD4cYwHfE \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY"

Next steps

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

Getting Started

Quickstart

Payments (Ugwo)

Customers (Onye)

Checkouts

Accept your first payment

Next steps

​Next steps

Next steps