Verify OTP

Summary

Verifies the OTP received by the user via SMS after a successful call to Init Subscription. On success, the subscription is activated and the first charge is attempted.

Path

POST https://merchants.noju.io/subscriptions/verify

Headers

Header	Required	Value
API-KEY	yes	Your merchant API key.
Content-Type	yes	application/json

Request body

Field	Type	Required	Description
verif_request_id	string	yes	UUID returned by init API call.
otp	string	yes	The OTP the subscriber received via SMS.
language	string	no	BCP-47 / ISO-639-1 language for SMS communications (e.g. en, fr). Defaults to the service's default language.

Success payload

On status: "SUCCESS", payload contains:

Field	Type	Description
subscription_id	string	UUID of the activated subscription. Persist it to query /subscriptions/status.

Errors

HTTP	message	When
400	BAD_REQUEST	Body fails JSON schema validation.
401	UNAUTHORIZED	API key missing, invalid, or merchant inactive.
403	UNAUTHORIZED	Source IP not allowlisted.
403	MERCHANT_SERVICE_NOT_CONFIGURED	No integration for the provided service_code + country_code.
200	INVALID_PIN / PIN_EXPIRED / MAX_PIN_RETRIES	OTP invalid, expired, or too many attempts.
200	INSUFFICIENT_FUNDS / BLACKLISTED / BARRED / NOT_ELIGIBLE / INVALID_USER / ALREADY_SUBSCRIBED / other CarrierError	OTP was correct but the carrier refused to charge.
500	ERROR	Unexpected server error.

Examples

Request

{
  "verif_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "otp": "1234"
}

Success response

{
  "status": "SUCCESS",
  "message": "",
  "status_code": 200,
  "payload": {
    "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Failure response (invalid OTP)

{
  "status": "FAIL",
  "message": "INVALID_PIN",
  "status_code": 200
}

Code samples

curl

curl -X POST 'https://merchants.noju.io/subscriptions/verify' \
  -H 'Content-Type: application/json' \
  -H "API-KEY: $NOJU_API_KEY" \
  -d '{"verif_request_id":"550e8400-e29b-41d4-a716-446655440000","otp":"1234"}'

Python

import os
import requests

response = requests.post(
    'https://merchants.noju.io/subscriptions/verify',
    headers={
        'Content-Type': 'application/json',
        'API-KEY': os.environ['NOJU_API_KEY'],
    },
    json={
        "verif_request_id": "550e8400-e29b-41d4-a716-446655440000",
        "otp": "1234"
    },
    timeout=30,
)

response.raise_for_status()
data = response.json()

if data['status'] == 'SUCCESS':
    print(data['payload'])
else:
    print(f"Failed: {data['message']}")

PHP

<?php
$apiKey = getenv('NOJU_API_KEY');

$payload = json_encode([
    'verif_request_id' => '550e8400-e29b-41d4-a716-446655440000',
    'otp' => '1234',
]);

$ch = curl_init('https://merchants.noju.io/subscriptions/verify');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'API-KEY: ' . $apiKey,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$responseBody = curl_exec($ch);
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($responseBody, true);

if (($data['status'] ?? null) === 'SUCCESS') {
    var_dump($data['payload']);
} else {
    fwrite(STDERR, 'Failed: ' . ($data['message'] ?? 'unknown') . "\n");
}