The Next action object

When an activity is requires_action, its next_action tells you what the customer has to do: transfer to an account, dial a USSD code, approve a debit at their bank, or give you an OTP/PIN to submit. A next action is its own object with an ID, a status and an expiry. An activity can go through several in sequence (for example input_pin → input_otp); activity.next_action is always the current one, and List next actions returns the history.

Using the embedded checkout? It renders every next action for you. This page is for direct API integrations.

Attributes

string

Unique identifier, uac.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY. The ugwo.activity.next_action.* webhooks identify themselves with it.

object

The instruction. action.type decides the remaining keys. See Action types.

enum

pending while the customer still has to act, fulfilled once done, expired once it can no longer be completed. See Status.

enum | null

Why the last input submission was rejected: invalid_input (wrong OTP/PIN; ask the customer again) or unknown_error_try_again (temporary failure; resubmit). null if the last submission succeeded or none has been made.

string | null

When the action stops being usable, ISO-8601. null if it doesn’t expire. Show a countdown for bank transfers.

string

ISO-8601 timestamp.

string

ISO-8601 timestamp.

Action types

Show the customer instructions. Used by bank_transfer and ussd. Nothing to submit; the activity completes when the customer acts and the PSP confirms.

string

user_action

string

Display-ready sentence.

object

The same information as discrete fields, for your own UI. Keys depend on the medium:

bank_transfer: bank_name, account_number, account_name, expires_at
ussd: ussd (the code to dial)

bank_transfer

{
  "type": "user_action",
  "instruction": "Transfer to bank",
  "headers": {
    "bank_name": "Test Bank",
    "account_number": "1260881821",
    "account_name": "PAYSTACK CHECKOUT",
    "expires_at": "2026-05-14T20:10:50+00:00"
  }
}

ussd

{
  "type": "user_action",
  "instruction": "Please dial *737*33*4*92811# on your mobile phone to complete the transaction",
  "headers": { "ussd": "*737*33*4*92811#" }
}

Send the customer to a URL. Used by pay_with_bank: the customer approves the debit at their bank or wallet.

string

open_url

string

Where to send the customer.

object

Context to show next to the button so the customer can confirm the account, e.g. account_number and account_name. account_name is the bank’s name for the account, and is filled only when it fairly matches the account_name_fragment you sent; otherwise it is null. Keys vary by provider; render defensively.

boolean

true if the URL may be shown in an iframe. When false you must use a full redirect or a new window.

string | null

When the URL stops working.

{
  "type": "open_url",
  "url": "https://checkout.paystack.com/kzp7bxu1lfhy3s2",
  "headers": {
    "account_name": "ADA OKONKWO",
    "account_number": "8012345678"
  },
  "iframe": true,
  "expires_at": "2026-08-12T10:34:11+00:00"
}

Collect a one-time password the customer received from their bank or wallet, then submit it.

string

input_otp

boolean

If true, you can offer a “Resend code” button: submit { "otp": null } to send a new code.

{ "type": "input_otp", "supports_resend": true }

Submit: { "otp": "123456" } (string, up to 10 characters).

Collect the customer’s 4-digit PIN and submit it.

{ "type": "input_pin" }

Submit: { "pin": "1234" } (string, exactly 4 digits).

Collect the customer’s Bank Verification Number and submit it.

{ "type": "input_bvn" }

Submit: { "bvn": "22212345678" } (string, exactly 11 digits).

Collect the customer’s date of birth and submit it.

{ "type": "input_birthday" }

Submit: { "birthday": "1990-04-21" } (YYYY-MM-DD).

New action types may be added. If you build your own UI, handle an unknown action.type gracefully, for example by falling back to the embedded checkout.

Status

Status	Meaning
`pending`	The customer still has to act. For `input_*` types, submissions are accepted.
`fulfilled`	Done. The activity has moved on (it may now have a new `next_action`).
`expired`	Can no longer be completed. The activity is usually `expired` or `failed` too.

The Next action object

{
  "uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU",
  "action": {
    "type": "input_otp",
    "supports_resend": true
  },
  "status": "pending",
  "last_error": null,
  "expires_at": "2026-08-12T10:34:11+00:00",
  "created_at": "2026-08-12T10:24:11+00:00",
  "updated_at": "2026-08-12T10:24:11+00:00"
}

Get started

Plugins

Guides

Concepts

API basics

Payments (Ugwo)

Activities

Next actions

Refunds

Customers (Onye)

Checkouts

The Next action object

Attributes

Action types

Status

​Attributes

​Action types

​Status

Attributes

Action types

Status