Init subscription

Summary

Initializes a subscription flow for an MSISDN. On successful initiation, will either send an OTP to the user via SMS or returns SMS-channel instructions (short code + keyword), depending on the MNO.

Path

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

Headers

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

Request body

Field	Type	Required	Description
msisdn	string	yes	Subscriber phone number, international format.
service_code	string	yes	Service identifier provisioned for your merchant account.
country_code	string	yes	ISO-3166-1 alpha-2 country code, lower case (e.g. bg, my).
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
verif_request_id	string | null	Verification request ID to pass to /subscriptions/verify for OTP flows.
short_code	string | null	SMS short code the user texts (Optional - returned only with PSMS integrations).
keyword	string | null	SMS keyword the user texts to short_code (Optional - returned only with PSMS integrations).
carrier_code	string | null	Detected carrier code for the MSISDN.
redirect_url	string | null	URL to which the user has to be redirected to verify payment (Optional - market-dependant).

Errors

HTTP	message	When
400	BAD_REQUEST	Body fails JSON schema validation (missing msisdn/service_code/country_code).
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_MSISDN	The MSISDN failed lookup validation.
200	CARRIER_NOT_SUPPORTED	The detected carrier is not provisioned for the requested service and country
200	any CarrierError	The carrier rejected initiation.
500	ERROR	Unexpected server error.

Examples

Request

{
  "msisdn": "60123456789",
  "service_code": "NORDVPN",
  "country_code": "my",
  "language": "en"
}

Success response

{
  "status": "SUCCESS",
  "message": "",
  "status_code": 200,
  "payload": {
    "verif_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "short_code": "7777",
    "keyword": "NORDVPN",
    "carrier_code": "50010",
    "redirect_url": null
  }
}

Failure response (carrier not supported)

{
  "status": "FAIL",
  "message": "CARRIER_NOT_SUPPORTED",
  "status_code": 200,
  "payload": null
}

Code samples

curl

curl -X POST 'https://merchants.noju.io/subscriptions/init' \
  -H 'Content-Type: application/json' \
  -H "API-KEY: $NOJU_API_KEY" \
  -d '{"msisdn":"60123456789","service_code":"NORDVPN","country_code":"my","language":"en"}'

Python

import os
import requests

response = requests.post(
    'https://merchants.noju.io/subscriptions/init',
    headers={
        'Content-Type': 'application/json',
        'API-KEY': os.environ['NOJU_API_KEY'],
    },
    json={
        "msisdn": "60123456789",
        "service_code": "NORDVPN",
        "country_code": "my",
        "language": "en"
    },
    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([
    'msisdn' => '60123456789',
    'service_code' => 'NORDVPN',
    'country_code' => 'my',
    'language' => 'en',
]);

$ch = curl_init('https://merchants.noju.io/subscriptions/init');
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");
}