> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orqex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Next actions

> When a payment attempt requires customer interaction, the attempt returns a next_action object describing exactly what to do.

After creating an attempt, check `active_attempt.next_action.type` on the returned intent. Depending on the type, you either show something to the customer and wait, or collect input from the customer and call confirm or authorize.

## Confirm vs. authorize

Two endpoints accept the customer's input:

| Endpoint                                                        | Use when                                                                       |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `POST /payment/intents/{intentId}/authorize`                    | You do not have the attempt id — targets the intent's currently active attempt |
| `POST /payment/intents/{intentId}/attempts/{attemptId}/confirm` | You have the specific attempt id                                               |

Both accept the same optional body fields: `otp` (string, max 10 characters) and `confirmation_data` (object). Both return the updated payment intent.

## Action types

### `none`

The attempt is processing. No customer action is required.

| Field     | Description                   |
| --------- | ----------------------------- |
| `message` | Human-readable status message |

Wait for the webhook or poll the intent.

***

### `approve_on_phone`

The customer must approve the payment on their phone (e.g. via a USSD prompt or an in-app notification from their provider).

| Field          | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| `dial_code`    | Dial code or short code to trigger the approval                      |
| `instructions` | Array of step-by-step instruction strings to display to the customer |
| `message`      | Summary message                                                      |

Display the instructions to the customer. The attempt resolves asynchronously — do not call confirm. Wait for the webhook or poll.

***

### `collect_otp`

The customer has received a one-time password (e.g. via SMS) and must enter it.

| Field          | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `digits`       | Expected number of OTP digits                                                         |
| `is_strict`    | When `true`, the OTP must match exactly. When `false`, a best-effort match is applied |
| `dial_code`    | Country dial code for context                                                         |
| `instructions` | Array of instruction strings                                                          |
| `message`      | Summary message                                                                       |
| `fields`       | Additional fields the customer must complete, if any                                  |

Collect the OTP from the customer and call **confirm or authorize**:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orqex.com/v1/payment/intents/pi_.../authorize \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{ "otp": "123456" }'
  ```

  ```php PHP theme={null}
  use Orqex\Client;

  $client = new Client('sk_live_...');

  $intent = $client->paymentIntents->authorize('pi_...', [
      'otp' => '123456',
  ]);
  ```
</CodeGroup>

***

### `redirect_to_url`

The customer must visit an external URL to complete payment (e.g. a 3DS page or a provider-hosted form).

| Field               | Description                                                                          |
| ------------------- | ------------------------------------------------------------------------------------ |
| `url`               | The URL to redirect the customer to                                                  |
| `method`            | HTTP method to use: `GET` or `POST`                                                  |
| `post_data`         | Key/value pairs to submit as a POST form body (only present when `method` is `POST`) |
| `can_auto_redirect` | Whether it is safe to redirect automatically without customer confirmation           |

If `can_auto_redirect` is `true`, redirect immediately. Otherwise, show a "Continue to payment" button. After the redirect returns, check the intent status or wait for the webhook. Do not call confirm.

***

### `embed_iframe`

Embed a provider-hosted page within your UI.

| Field | Description                  |
| ----- | ---------------------------- |
| `url` | The URL to load in an iframe |

Render an `<iframe>` pointing at `url`. The attempt resolves when the customer completes the flow inside the iframe. Wait for the webhook or poll. Do not call confirm.

***

### `scan_qr_code`

The customer must scan a QR code with their device.

| Field       | Description                                  |
| ----------- | -------------------------------------------- |
| `content`   | The raw QR code content (e.g. a payment URI) |
| `image_url` | URL of a pre-rendered QR code image          |

Display the QR code using `image_url` or render it from `content`. The attempt resolves asynchronously once the customer completes the payment in their app. Do not call confirm.

***

### `display_payment_instructions`

Show the customer a set of structured instructions (e.g. a bank transfer reference).

| Field     | Description                                                                                |
| --------- | ------------------------------------------------------------------------------------------ |
| `title`   | Instruction section title                                                                  |
| `fields`  | Array of `{ label, value }` pairs — display each as a labelled field the customer can copy |
| `message` | Summary message                                                                            |

Render all fields. The attempt resolves asynchronously once the provider confirms receipt. Do not call confirm.

***

### `complete_with_sdk`

A provider SDK must run in the browser to complete the payment (e.g. to handle a native 3DS challenge).

| Field           | Description                                  |
| --------------- | -------------------------------------------- |
| `provider`      | The SDK provider identifier                  |
| `sdk_url`       | URL to load the provider SDK from            |
| `public_key`    | Public key to initialise the SDK             |
| `client_params` | Parameters to pass when initialising the SDK |
| `container_id`  | DOM element id the SDK should mount into     |

Load the SDK from `sdk_url`, initialise it with `public_key` and `client_params`, and mount it into the element with `container_id`. Once the SDK completes and provides a reference, call **confirm or authorize** with that reference in `confirmation_data`.

<Note>
  `complete_with_sdk` is the only action type (besides `collect_otp`) that requires a confirm or authorize call. All others resolve without one.
</Note>