Issue PIN

Sends a PIN to the subscriber by SMS. Nothing is charged and no subscription exists yet: this step only establishes that the person holds the number.

POST /api/sp/v1/dcb/subscription/pin

Request

Field	Type	Notes
msisdn	string	The subscriber's number.
shortCode	string	The short code your credential is bound to.
serviceId	integer	The service.
spTransactionId	string	Yours to generate, unique per attempt. See Idempotency.
language	ar · en · ku	The language of the PIN message. Required: there is no default, because guessing a subscriber's language on their behalf is not ours to do.

Note what is absent: no ti/ts here. The anti-fraud identifiers are sent on Verify PIN, not on this call.

Response

Success means the PIN was accepted for sending. It does not mean the subscriber has received it: delivery is a network event and takes a moment.

{
  "requestId": "01JB2K9WQ4X7YH3M8N5P6R7T8V",
  "code": "OK",
  "data": { "expiresInMinutes": 10 }
}

Field	Notes
expiresInMinutes	How long the PIN stays valid. Read it rather than hard-coding it - it comes from configuration and can change without a new API version.

This flow tells you neither the price nor how often it recurs, and you need to show both

expiresInMinutes is the only field. No amount, no currency, and no billing period.

That is a real difference from one-time purchase, which returns amount and currency precisely so your confirmation screen and our SMS cannot disagree. Here the price lives only in the service configuration the operator team holds, so a landing page that quotes a subscription price is quoting your own copy of it.

Nothing in this API will catch a mismatch. If the tariff is changed on the platform and your copy is not, your page shows one number, the bill shows another, and the first you hear of it is a subscriber complaint. So:

• Keep the price in one place in your own system, not inline in a template.
• Treat a tariff change as a deployment, agreed with the operator team, not as a setting one side can move alone.
• Refuse to take a subscription when your price is unset rather than showing a blank or a default. A page that will not load is recoverable; a page that charges someone a figure they were never shown is not.

The billing period has exactly the same shape, and it is the easier one to get wrong, because daily is the common case and a sensible-looking default. A page whose cadence is a default rather than a decision agrees with the platform by coincidence, and a coincidence holds until someone moves the service to weekly or monthly, at which point your page keeps saying "per day" and nothing in this API disagrees with it.

Quoting the wrong cadence is not a smaller error than quoting the wrong amount. It is the same error multiplied by every renewal: "300 IQD per day" against a weekly service overstates the obligation sevenfold, and understating it in the other direction is what generates complaints and refunds. Treat the period exactly as you treat the price - one place, changed as a deployment, agreed with the operator team, and refused rather than defaulted.

What can refuse it

ALREADY_SUBSCRIBED · SUBSCRIBER_BLACKLISTED · SERVICE_NOT_ACTIVE · INVALID_MSISDN · PIN_RATE_LIMITED (retryable). Full meanings on Error codes.

PIN_RATE_LIMITED is a per-number ceiling, not a per-integration one. It usually means a subscriber is retrying rather than that you are.