Skip to main content

Getting Started

This guide walks you from zero to a verified subscription in four steps. All endpoints are JSON over HTTPS; every request must originate from an IP allowlisted on your merchant account.

Step 1 - Receive credentials​

After the commercial requirements and onboarding phase is done, Noju will share an API key and the service_code(s) provisioned for your merchant account. You receive a single API key per environment (sandbox and/or production), and your egress IPs are allowlisted as part of onboarding. Treat the key as an opaque secret; for rotation, contact your Noju account manager.

Step 2 - First request​

Once you have your API key, export it and POST to /subscriptions/init:

export NOJU_API_KEY='your-api-key'

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"
  }'

A successful response returns a verif_request_id (for OTP flows) or carrier-channel hints such as short_code and keyword (for SMS-driven flows).

Step 3 - Verify the OTP​

When the subscriber receives the OTP, submit it together with the verif_request_id from Step 2:

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"
  }'

A status: "SUCCESS" response means the subscription is active and the first charge has been attempted (for non-PSMS flows).

Step 4 - Check status​

To reconcile state at any time, POST the subscription_id to /subscriptions/status:

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

The response includes the subscription's current state, MSISDN, service, and lifecycle timestamps.

What's next​

  • Authentication — header format, IP allowlist, and key rotation.
  • Conventions — the response envelope and the HTTP-vs-status_code semantics.
  • Errors — global error codes and the carrier-error catalog.