curl -X PUT https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE/activities/act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs/actions/uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU \
-H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "otp": "123456" }'
const action = await fetch(
`https://api.kwugwo.africa/v1/ugwo/${ugwoUid}/activities/${activityUid}/actions/${actionUid}`,
{
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ otp: customerOtp }),
}
).then(r => r.json());
import os, requests
action = requests.put(
f"https://api.kwugwo.africa/v1/ugwo/{ugwo_uid}/activities/{activity_uid}/actions/{action_uid}",
headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
json={"otp": customer_otp},
).json()
<?php
$ch = curl_init("https://api.kwugwo.africa/v1/ugwo/{$ugwoUid}/activities/{$activityUid}/actions/{$actionUid}");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('KWUGWO_SECRET_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['otp' => $customerOtp]),
]);
$action = json_decode(curl_exec($ch), true);
curl_close($ch);
{
"uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU",
"action": { "type": "input_otp", "supports_resend": true },
"status": "fulfilled",
"last_error": null,
"expires_at": "2026-08-12T10:34:41+00:00",
"created_at": "2026-08-12T10:24:41+00:00",
"updated_at": "2026-08-12T10:25:30+00:00"
}
{
"uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU",
"action": { "type": "input_otp", "supports_resend": true },
"status": "pending",
"last_error": "invalid_input",
"expires_at": "2026-08-12T10:34:41+00:00",
"created_at": "2026-08-12T10:24:41+00:00",
"updated_at": "2026-08-12T10:25:30+00:00"
}
{
"type": "validation.error",
"title": "An error occurred",
"status": 422,
"detail": "This value should have exactly 4 characters.",
"message": "Validation failed",
"errors": [
{ "field": "pin", "message": "This value should have exactly 4 characters." }
]
}
Next actions
Submit customer input
Send the OTP, PIN, BVN or date of birth the customer entered.
PUT
/
v1
/
ugwo
/
{ugwoUid}
/
activities
/
{activityUid}
/
actions
/
{actionUid}
curl -X PUT https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE/activities/act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs/actions/uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU \
-H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "otp": "123456" }'
const action = await fetch(
`https://api.kwugwo.africa/v1/ugwo/${ugwoUid}/activities/${activityUid}/actions/${actionUid}`,
{
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ otp: customerOtp }),
}
).then(r => r.json());
import os, requests
action = requests.put(
f"https://api.kwugwo.africa/v1/ugwo/{ugwo_uid}/activities/{activity_uid}/actions/{action_uid}",
headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
json={"otp": customer_otp},
).json()
<?php
$ch = curl_init("https://api.kwugwo.africa/v1/ugwo/{$ugwoUid}/activities/{$activityUid}/actions/{$actionUid}");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('KWUGWO_SECRET_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['otp' => $customerOtp]),
]);
$action = json_decode(curl_exec($ch), true);
curl_close($ch);
{
"uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU",
"action": { "type": "input_otp", "supports_resend": true },
"status": "fulfilled",
"last_error": null,
"expires_at": "2026-08-12T10:34:41+00:00",
"created_at": "2026-08-12T10:24:41+00:00",
"updated_at": "2026-08-12T10:25:30+00:00"
}
{
"uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU",
"action": { "type": "input_otp", "supports_resend": true },
"status": "pending",
"last_error": "invalid_input",
"expires_at": "2026-08-12T10:34:41+00:00",
"created_at": "2026-08-12T10:24:41+00:00",
"updated_at": "2026-08-12T10:25:30+00:00"
}
{
"type": "validation.error",
"title": "An error occurred",
"status": 422,
"detail": "This value should have exactly 4 characters.",
"message": "Validation failed",
"errors": [
{ "field": "pin", "message": "This value should have exactly 4 characters." }
]
}
When an activity’s
next_action.action.type starts with input_,
collect the value from the customer and send it here. Kwugwo forwards
it to the PSP and returns the updated next action.
OTPs, PINs and BVNs are sensitive. Send them straight from your
server to Kwugwo over TLS, and never log or store them.
Path parameters
string
required
The ugwo ID,
ugw.XXXX.YYYY....string
required
The activity ID,
act.XXXX.YYYY....string
required
The next action ID,
uac.XXXX.YYYY.... Must be the activity’s
current, pending next action.Body parameters
Send exactly the one field that matchesaction.type:
string | null
For
input_otp. Up to 10 characters. Send null to resend the
code when the action has supports_resend: true.string
For
input_pin. Exactly 4 digits.string
For
input_bvn. Exactly 11 digits.string
For
input_birthday. A date, YYYY-MM-DD.Response
The updated Next action object. Check, in order:last_erroris set andstatusis stillpending: the input was rejected. Ask the customer again (invalid_input) or resubmit (unknown_error_try_again).statusisfulfilled: accepted. Get the activity: it may now beprocessing,successful, orrequires_actionwith a newnext_action(for example an OTP after a PIN).statusisexpired: too late. The activity has ended; start a new one.
pending, or one whose
action.type takes no input (user_action, open_url), changes
nothing and returns it as is.
curl -X PUT https://api.kwugwo.africa/v1/ugwo/ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE/activities/act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs/actions/uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU \
-H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "otp": "123456" }'
const action = await fetch(
`https://api.kwugwo.africa/v1/ugwo/${ugwoUid}/activities/${activityUid}/actions/${actionUid}`,
{
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ otp: customerOtp }),
}
).then(r => r.json());
import os, requests
action = requests.put(
f"https://api.kwugwo.africa/v1/ugwo/{ugwo_uid}/activities/{activity_uid}/actions/{action_uid}",
headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
json={"otp": customer_otp},
).json()
<?php
$ch = curl_init("https://api.kwugwo.africa/v1/ugwo/{$ugwoUid}/activities/{$activityUid}/actions/{$actionUid}");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('KWUGWO_SECRET_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['otp' => $customerOtp]),
]);
$action = json_decode(curl_exec($ch), true);
curl_close($ch);
{
"uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU",
"action": { "type": "input_otp", "supports_resend": true },
"status": "fulfilled",
"last_error": null,
"expires_at": "2026-08-12T10:34:41+00:00",
"created_at": "2026-08-12T10:24:41+00:00",
"updated_at": "2026-08-12T10:25:30+00:00"
}
{
"uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU",
"action": { "type": "input_otp", "supports_resend": true },
"status": "pending",
"last_error": "invalid_input",
"expires_at": "2026-08-12T10:34:41+00:00",
"created_at": "2026-08-12T10:24:41+00:00",
"updated_at": "2026-08-12T10:25:30+00:00"
}
{
"type": "validation.error",
"title": "An error occurred",
"status": 422,
"detail": "This value should have exactly 4 characters.",
"message": "Validation failed",
"errors": [
{ "field": "pin", "message": "This value should have exactly 4 characters." }
]
}