Verify PIN

Checks the PIN and, if the anti-fraud verdict allows, opens the subscription. This is the call that commits.

POST /api/sp/v1/dcb/subscription/verify

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.
pin	string	What the subscriber typed.
ti	string	The anti-fraud transaction identifier: the same one you used to fetch the script.
ts	string	The matching timestamp.

ti must be the one the script call registered

If this ti was never used to fetch the anti-fraud script (or you generated a fresh one for this call), you get FRAUD_TRANSACTION_UNKNOWN, on every attempt. It is not a decline and retrying will not help. See Anti-fraud.

What happens, in order

1. The PIN is checked.
2. The anti-fraud verdict is obtained.
3. The subscription is opened.

The fraud check runs after the PIN proves possession and before anything is charged. That ordering is deliberate: a wrong PIN costs no fraud check, and no charge happens behind an unverified interaction.

Response

{
  "requestId": "01JB2K9WQ4X7YH3M8N5P6R7T8V",
  "code": "OK",
  "data": {
    "subscriptionId": 4821,
    "state": "active",
    "subscribedAt": "2026-09-13T08:14:22.000000Z"
  }
}

Field	Notes
subscriptionId	Ours, not yours. Useful when quoting a subscription to us.
state	trial if a free period is running, active if the first charge succeeded.
subscribedAt	ISO 8601.

A failed first charge does not return this shape. It returns INSUFFICIENT_BALANCE or CHARGE_FAILED with the same fields under data - see the envelope.

What can refuse it

PIN_INVALID · PIN_EXPIRED · PIN_ATTEMPTS_EXCEEDED · PIN_NOT_REQUESTED · FRAUD_BLOCKED · FRAUD_TRANSACTION_UNKNOWN · FRAUD_CHECK_UNAVAILABLE (retryable) · ALREADY_SUBSCRIBED.

FRAUD_CHECK_UNAVAILABLE consumes nothing. Retry with the same spTransactionId and the same PIN: both are still valid.