Skip to main content
POST
/
v1
/
ugwo
/
{ugwoUid}
/
activities
curl https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.qnbBJaElzSTHOcaTzxbuDlIs/activities \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "charge",
    "data": {
      "medium": "bank_transfer",
      "expires_at": "2026-05-15T10:30:00+00:00"
    }
  }'

const res = await fetch(
  `https://api.kwugwo.africa/v1/ugwo/${ugwoUid}/activities`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "charge",
      data: { medium: "bank_transfer" },
    }),
  }
);
const activity = await res.json();

<?php
$ch = curl_init("https://api.kwugwo.africa/v1/ugwo/{$ugwoUid}/activities");
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([
        'type' => 'charge',
        'data' => ['medium' => 'bank_transfer'],
    ]),
]);
$activity = json_decode(curl_exec($ch), true);
curl_close($ch);

import os, requests

activity = requests.post(
    f"https://api.kwugwo.africa/v1/ugwo/{ugwo_uid}/activities",
    headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
    json={
        "type": "charge",
        "data": {"medium": "bank_transfer"},
    },
).json()

package main

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

func main() {
    body, _ := json.Marshal(map[string]any{
        "type": "charge",
        "data": map[string]any{"medium": "bank_transfer"},
    })

    url := fmt.Sprintf("https://api.kwugwo.africa/v1/ugwo/%s/activities", ugwoUid)
    req, _ := http.NewRequest("POST", url, 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))
}

{
  "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs",
  "activity_type": "charge",
  "checkout": {
    "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAATX",
    "currency": ["NGN", "Nigerian Naira (NGN)"],
    "mediums": [
      { "medium": "bank_transfer" },
      { "medium": "ussd" }
    ]
  },
  "ugwo_medium": null,
  "psp": "paystack_ng",
  "psp_external_id": "5kfxw34ugz",
  "next_action": {
    "type": "user_action",
    "instruction": "Transfer to bank",
    "headers": {
      "bank_name": "Test Bank",
      "expires_at": "2026-05-14T20:10:50+00:00",
      "account_name": "PAYSTACK CHECKOUT",
      "account_number": "1260881821"
    }
  },
  "status": "requires_action",
  "created_at": "2026-05-14T19:55:50+00:00",
  "error": null,
  "updated_at": "2026-05-14T19:55:51+00:00"
}

{
  "uid": "act.VCvr.w9qTsfJMQkBIaITiGRDucv1u",
  "activity_type": "charge",
  "checkout": {
    "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAATX",
    "currency": ["NGN", "Nigerian Naira (NGN)"],
    "mediums": [
      { "medium": "bank_transfer" },
      { "medium": "ussd" }
    ]
  },
  "ugwo_medium": null,
  "psp": "paystack_ng",
  "psp_external_id": "s09v485jla6ckt1",
  "next_action": {
    "type": "user_action",
    "instruction": "Please dial *737*33*4*92811# on your mobile phone to complete the transaction",
    "headers": {
      "ussd": "*737*33*4*92811#"
    }
  },
  "status": "requires_action",
  "created_at": "2026-05-15T16:10:18+00:00",
  "error": null,
  "updated_at": "2026-05-15T16:10:18+00:00"
}

{
  "title": "Validation Failed",
  "status": 422,
  "violations": [
    { "propertyPath": "provider", "title": "This value should not be blank." }
  ]
}
Creates an activity on the ugwo. The activity describes one attempt to act on the payment; today the only supported type is charge, which sends the ugwo to a PSP through the medium you specify. Activities are independent: a single ugwo can host many of them. If a mobile_money charge fails, you can immediately create a bank_transfer activity on the same ugwo without recreating it.
The ugwo must have a resolved checkout before you can create an activity against it. If the ugwo’s checkout is null (no checkout was supplied at creation and the workspace couldn’t route one), this endpoint returns 422.

​
Path parameters

​
ugwoUid
string
required
The ugwo to charge, ugw.XXXX.YYYY....

​
Body parameters

​
type
string
required
The activity type. Currently only charge is supported.
​
data
object
required
Type-specific payload. data.medium selects the payment medium, and the rest of the keys inside data are the parameters for that medium (see Medium parameters below).

​
Medium parameters

data.medium is one of bank_transfer, ussd, or mobile_money. The other keys inside data depend on which one you picked. 
{
  "type": "charge",
  "data": {
    "medium": "bank_transfer",
    "expires_at": "2026-05-15T10:30:00+00:00"
  }
}
​
expires_at
string
ISO-8601 (DATE_ATOM) timestamp for when the virtual account should stop accepting transfers. Optional; defaults to 15 minutes from now. Must be in the future and no more than 15 minutes ahead; timestamps in the past or further out than 15 minutes return 422.
Available for Nigeria (NGN).

​
Response

​
uid
string
Activity ID (act.…).
​
activity_type
string
Always charge for this endpoint.
​
status
string
Initial activity status. requires_action when the customer has more to do (bank transfer, USSD), processing when handed off to the PSP without further customer input, or failed on a synchronous error.
​
checkout
object | null
Snapshot of the checkout this activity was routed through. Includes uid, the currency as [code, label], and the configured mediums.
​
ugwo_medium
object | null
Tokenised medium (e.g. a stored card or wallet) the activity used; null for one-off mediums like bank_transfer.
​
psp
string
The PSP that handled the charge, e.g. paystack_ng.
​
psp_external_id
string | null
The reference the PSP issued for this attempt. Useful when cross-referencing in your PSP dashboard.
​
next_action
object | null
What the customer needs to do next, if anything. See next_action shape.
​
error
object | null
Populated when the activity failed synchronously.
​
created_at
string
ISO-8601 timestamp.
​
updated_at
string
ISO-8601 timestamp.

​
next_action shape

For bank_transfer, next_action.type is user_action and the headers block carries everything the customer needs to complete the transfer (account number, bank name, expiry, amount). 
{
  "type": "user_action",
  "instruction": "Transfer to bank",
  "headers": {
    "bank_name": "Test Bank",
    "expires_at": "2026-05-14T20:10:50+00:00",
    "account_name": "PAYSTACK CHECKOUT",
    "account_number": "1260881821"
  }
}

curl https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.qnbBJaElzSTHOcaTzxbuDlIs/activities \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "charge",
    "data": {
      "medium": "bank_transfer",
      "expires_at": "2026-05-15T10:30:00+00:00"
    }
  }'

const res = await fetch(
  `https://api.kwugwo.africa/v1/ugwo/${ugwoUid}/activities`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "charge",
      data: { medium: "bank_transfer" },
    }),
  }
);
const activity = await res.json();

<?php
$ch = curl_init("https://api.kwugwo.africa/v1/ugwo/{$ugwoUid}/activities");
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([
        'type' => 'charge',
        'data' => ['medium' => 'bank_transfer'],
    ]),
]);
$activity = json_decode(curl_exec($ch), true);
curl_close($ch);

import os, requests

activity = requests.post(
    f"https://api.kwugwo.africa/v1/ugwo/{ugwo_uid}/activities",
    headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
    json={
        "type": "charge",
        "data": {"medium": "bank_transfer"},
    },
).json()

package main

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

func main() {
    body, _ := json.Marshal(map[string]any{
        "type": "charge",
        "data": map[string]any{"medium": "bank_transfer"},
    })

    url := fmt.Sprintf("https://api.kwugwo.africa/v1/ugwo/%s/activities", ugwoUid)
    req, _ := http.NewRequest("POST", url, 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))
}

{
  "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs",
  "activity_type": "charge",
  "checkout": {
    "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAATX",
    "currency": ["NGN", "Nigerian Naira (NGN)"],
    "mediums": [
      { "medium": "bank_transfer" },
      { "medium": "ussd" }
    ]
  },
  "ugwo_medium": null,
  "psp": "paystack_ng",
  "psp_external_id": "5kfxw34ugz",
  "next_action": {
    "type": "user_action",
    "instruction": "Transfer to bank",
    "headers": {
      "bank_name": "Test Bank",
      "expires_at": "2026-05-14T20:10:50+00:00",
      "account_name": "PAYSTACK CHECKOUT",
      "account_number": "1260881821"
    }
  },
  "status": "requires_action",
  "created_at": "2026-05-14T19:55:50+00:00",
  "error": null,
  "updated_at": "2026-05-14T19:55:51+00:00"
}

{
  "uid": "act.VCvr.w9qTsfJMQkBIaITiGRDucv1u",
  "activity_type": "charge",
  "checkout": {
    "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAATX",
    "currency": ["NGN", "Nigerian Naira (NGN)"],
    "mediums": [
      { "medium": "bank_transfer" },
      { "medium": "ussd" }
    ]
  },
  "ugwo_medium": null,
  "psp": "paystack_ng",
  "psp_external_id": "s09v485jla6ckt1",
  "next_action": {
    "type": "user_action",
    "instruction": "Please dial *737*33*4*92811# on your mobile phone to complete the transaction",
    "headers": {
      "ussd": "*737*33*4*92811#"
    }
  },
  "status": "requires_action",
  "created_at": "2026-05-15T16:10:18+00:00",
  "error": null,
  "updated_at": "2026-05-15T16:10:18+00:00"
}

{
  "title": "Validation Failed",
  "status": 422,
  "violations": [
    { "propertyPath": "provider", "title": "This value should not be blank." }
  ]
}