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

# Release Notes - 10.0.0 - September 2026

> Adds the Verify OTP endpoint (/api/v4/niobi-unified-process-transaction) to official API References with interactive schemas and clarified two-step flow guidance.

**Release Date:** September 2026

## TL;DR

* **Added to API Reference:** The Verify OTP endpoint (`POST /api/v4/niobi-unified-process-transaction`), previously supported and announced in earlier releases, is now formally documented in the [API Reference](/api-reference/collections/verify-otp) with interactive schemas, parameter definitions, and error codes.
* **Clarified Two-Step Flow:** Streamlined end-to-end guidance and sequence diagrams for corridors requiring interactive OTP authorization (e.g. Côte d'Ivoire Orange Money), clarifying the separation between Step 1 (`payment_token` issuance) and Step 2 (OTP verification).

***

## Updates & Improvements

### Verify OTP Published in API Reference (`/api/v4/niobi-unified-process-transaction`)

Certain mobile money operators, such as **Orange Money in Côte d'Ivoire** (`country_id: 3`, `currency: "XOF"`), require the payer to generate or receive an authorization one-time password (OTP) before funds can be debited.

While this two-step capability was previously supported, Release 10.0.0 brings this endpoint into the core **API Reference** suite with full documentation, interactive testing, and clearer developer guidance:

* **Endpoint:** `POST /api/v4/niobi-unified-process-transaction`
* **API Reference:** [Verify OTP](/api-reference/collections/verify-otp)
* **Guide:** [OTP-Verified Payins](/collecting-payments/methods#5-otp-verified-payins-c%C3%B4te-divoire-orange)

***

### The Two-Step Payment Flow

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Customer as Customer (Handset)
    participant Client as Your Backend / App
    participant Niobi as Niobi API
    participant Telco as Mobile Operator (e.g. Orange CI)

    Note over Client,Niobi: Step 1: Collection Initiation
    Client->>Niobi: POST /api/v4/niobi-unified-collections (payment_method_type: "orange")
    Niobi->>Telco: Request authorization session
    Telco-->>Customer: Deliver OTP via SMS (or customer dials #144*77#)
    Niobi-->>Client: Return payment_step: 1 & payment_token

    Note over Customer,Client: Customer enters received OTP<br/>in your checkout UI

    Note over Client,Niobi: Step 2: OTP Verification
    Client->>Niobi: POST /api/v4/niobi-unified-process-transaction (otp, payment_token)
    Niobi->>Telco: Validate OTP & debit wallet
    Telco-->>Niobi: Debit confirmed
    Niobi-->>Client: Immediate response (payment_step: 2, status: "success")
    Niobi-->>Client: Asynchronous webhook callback (payment_step: 2)
```

#### Step 1: Initiation (`POST /api/v4/niobi-unified-collections`)

Submit the standard signed collection payload specifying `payment_method_type: "orange"` and the customer's mobile number:

```json theme={null}
{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "timestamp": 1724835600,
  "salt": "random_salt_12345",
  "signature": "SHA256_SIGNATURE",
  "params": {
    "amount": 2000,
    "currency": "XOF",
    "country_id": 3,
    "mobile": "2250700000000",
    "payment_method_type": "orange",
    "callback_url": "https://yourdomain.com/niobi/callback",
    "third_party_reference_1": "TX-CI-COLL-1001"
  }
}
```

**Step 1 Response:** Niobi returns an acknowledgement with `payment_step: 1` and a `payment_token`:

```json theme={null}
{
  "success": true,
  "message": "We've sent a verification prompt to your phone. Please approve it to complete your payment.",
  "data": {
    "status": "success",
    "amount": 2000,
    "currency": "XOF",
    "country_id": 3,
    "payment_token": "NIO-S0000001",
    "payment_step": 1
  },
  "status_code": "000000"
}
```

<Tip>
  In production, the authorization OTP is valid for **2 minutes**.
</Tip>

***

#### Step 2: Verification (`POST /api/v4/niobi-unified-process-transaction`)

Prompt the customer to enter the OTP in your application, then dispatch a signed request containing the `payment_token` from Step 1 and the customer's `otp`:

```json theme={null}
{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "timestamp": 1724835620,
  "salt": "random_salt_67890",
  "signature": "SHA256_SIGNATURE",
  "params": {
    "otp": "1234",
    "payment_token": "NIO-S0000001"
  }
}
```

**Step 2 Response:** The endpoint completes debiting and returns the synchronous result with `payment_step: 2`:

```json theme={null}
{
  "success": true,
  "message": "Verification token was sent to your mobile number. Kindly verify to proceed payment.",
  "data": {
    "status": "success",
    "amount": 2000,
    "currency": "XOF",
    "payment_step": 2,
    "third_party_reference_1": "TX-CI-COLL-1001"
  },
  "status_code": "000000"
}
```

A terminal asynchronous webhook callback (`payment_step: 2`, `status: "success"`) is also dispatched to your `callback_url`.

***

### Sandbox Testing

To test this flow in the sandbox environment:

* Initiate the collection with any Côte d'Ivoire test MSISDN.
* In Step 2, pass `"otp": "000000"` to simulate a successful verification.

***

### Documentation Links

* [Verify OTP API Reference](/api-reference/collections/verify-otp)
* [Unified Collections API Reference](/api-reference/collections/unified-collections)
* [Côte d'Ivoire Country Guide](/countries/cote-d-ivoire#3-orange-money-otp-flow)
* [Collection Methods Guide](/collecting-payments/methods#5-otp-verified-payins-c%C3%B4te-divoire-orange)