> For the complete documentation index, see [llms.txt](https://startbutton.gitbook.io/startbutton-product-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://startbutton.gitbook.io/startbutton-product-api/collections/server-to-server-integration-overview/s2s-mobile-money/otp-verify.md).

# OTP Verify

### Next Steps After Initiation

When you initiate a mobile money payment, the response includes a `nextStep` field inside `data`. It tells you what the customer must do to authorize the payment.

| `nextStep`         | What happens                                                                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIN`              | The customer receives a prompt on their phone, the same as a USSD prompt, and enters their PIN.                                                                      |
| `OTP`              | The customer receives a one-time password from their provider and enters it.                                                                                         |
| `UOTP--> USSD OTP` | <p>The customer dials a USSD code to generate an OTP, then enters that OTP. <br><br>See <a data-mention href="#handling-uotp">#handling-uotp</a>.</p>                |
| `URL`              | <p>The customer is taken to the provider's page to complete the payment, then redirected back.<br><br>See <a data-mention href="#handling-otp">#handling-otp</a></p> |

#### Handling UOTP

When `nextStep` is `UOTP`, the response includes instructions for the customer in `data.meta.beforePaymentInstruction`.

1. Display the content of `beforePaymentInstruction` on your UI. It contains the USSD code to dial and the steps to follow, formatted as HTML.
2. The customer dials the USSD code, which generates an OTP.
3. Provide a field where the customer can enter the generated code.
4. Send the code to the verify endpoint below.

**Sample response (UOTP):**

```json
{
  "success": true,
  "message": "Payment Request Successful",
  "data": {
    "reference": "1d7b31805081",
    "nextStep": "UOTP",
    "meta": {
      "beforePaymentInstruction": "<p>How to Pay</p>\n<ol><li><b>Generate Voucher/OTP:</b> Dial <b>*144*82#</b> using your mobile number 2250700000000 to receive an OTP/Voucher.</li><li><b>Submit Voucher/OTP:</b> Enter the code in the input field below to proceed with your payment.</li></ol>"
    }
  }
}
```

#### Handling OTP

The response returns a `paymentUrl`. Redirect the customer to complete the payment on the Provider's page. They are then redirected back.

Sample response (URL)

```json
{
  "success": true,
  "message": "Payment Request Successful",
  "data": {
    "reference": "82XXXXXXXX07",
    "nextStep": "URL",
    "paymentUrl": "https://pay.provider.example/checkout/xxxxxxxx",
    "meta": {}
  }
}
```

If your customer is new to the service, they'll receive an OTP initially. Afterwards, for subsequent transactions, they'll be provided with a PIN.

When it is an OTP; you need to present the User with a screen to enter OTP and then call the endpoint below.

`POST /transaction/initialize/s2s/mobile_money/otp-verify`

| Header        | Value               |
| ------------- | ------------------- |
| Authorization | `Bearer PUBLIC_KEY` |
| Content-Type  | `application/json`  |

**Verify OTP**

```json
{ 
  "reference": "610ae86889ee", 
  "otp": "123456" 
} 
```

{% tabs %}
{% tab title="Success Response" %}

```json
{ 
    "status": true, 
    "message": "Charge attempted", 
    "data": { 
        "status": "requery", 
        "message": "Confirming payment" 
    } 
}
```

{% endtab %}

{% tab title="Failed Response" %}

```json
{ 
    "success": false, 
    "message": "Invalid OTP", 
    "data": null 
}
```

{% endtab %}
{% endtabs %}

However, if the next step is a PIN your users only need to enter their PIN on the prompt on their phone.