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

# Submit customer input

> Send the OTP, PIN, BVN or date of birth the customer entered.

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.

> [!WARNING]
>
> OTPs, PINs and BVNs are sensitive. Send them straight from your
> server to Kwugwo over TLS, and **never log or store them**.

## Path parameters

**ugwoUid** `string` *required*

The ugwo ID, `ugw.XXXX.YYYY...`.

**activityUid** `string` *required*

The activity ID, `act.XXXX.YYYY...`.

**actionUid** `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 matches `action.type`:

**otp** `string | null`

For `input_otp`. Up to 10 characters. Send `null` to **resend** the
code when the action has `supports_resend: true`.

**pin** `string`

For `input_pin`. Exactly 4 digits.

**bvn** `string`

For `input_bvn`. Exactly 11 digits.

**birthday** `string`

For `input_birthday`. A date, `YYYY-MM-DD`.

## Response

The updated [Next action object](https://docs.kwugwo.africa/ugwo/next-action-object.md). Check, in
order:

1. **`last_error` is set** and `status` is still `pending`: the input was
   rejected. Ask the customer again (`invalid_input`) or resubmit
   (`unknown_error_try_again`).
2. **`status` is `fulfilled`**: accepted. [Get the
   activity](https://docs.kwugwo.africa/ugwo/get-activity.md): it may now be `processing`,
   `successful`, or `requires_action` with a **new** `next_action`
   (for example an OTP after a PIN).
3. **`status` is `expired`**: too late. The activity has ended; start a
   new one.

Submitting to a next action that is not `pending`, or one whose
`action.type` takes no input (`user_action`, `open_url`), changes
nothing and returns it as is.

```bash cURL theme={"system"}
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" }'
```

```js Node theme={"system"}
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());
```

```python Python theme={"system"}
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 PHP theme={"system"}
<?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);
```

```json 200 OK (accepted) theme={"system"}
{
  "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"
}
```

```json 200 OK (wrong code) theme={"system"}
{
  "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"
}
```

```json 422 Validation Failed theme={"system"}
{
  "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." }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.