Subscriptions — overview
XML API for managing subscriptions on the i-Free billing platform. All requests are sent via POST to /Http/Services/{Method}.aspx — the method name is case-insensitive.
Sandbox
| Endpoint | https://subs-sandbox.digitalspb.com/Http/Services/{Method}.aspx |
| Reference | https://i-free.money/developers/en/sandbox |
| Parameter | Value |
|---|---|
| Content-Type | text/xml — XML body, or application/x-www-form-urlencoded — the same fields as form parameters |
| Root element | <Request> for requests, <Response> for responses |
| Response | XML <Response> with a StatusName field |
Protocol version: 1.
This is not the same protocol as Callisto one-time payments: a different host, a different signature formula, a different set of methods. The integrations share almost no code.
The responsibility model differs too: here the platform runs the charging schedule set for the project, and the partner does not initiate each charge. For the opposite — bind the payment details and charge on your own schedule — use a contract in one-time payments, see Mobile phone payments (DCB).
Three activation channels
There is a single creation method — CreateSubscription; the activation channel is chosen by the set of customer fields in the request.
| Channel | Request fields | How it is activated |
|---|---|---|
SMS_PIN | Subscriber_MSISDN (the legacy name MSISDN is also accepted) | The subscriber enters the PIN from SMS → ApproveSubscription |
AUTH_PAGE — card and SBP | CustomerType=Card + CustomerId | Redirect to AuthorizeUrl from the response; for an SBP QR code append ?useSbpQr=True to it. ApproveSubscription is not called — the subscription is activated once the payment completes |
AUTH_PAGE — WAP | ClientIP with no number — the operator gateway determines it | The subscriber confirms on the AuthorizeUrl page and comes back with the result parameters (action=approved / cancelled / alreadyexist) |
SMS_PIN flow
CreateSubscription— initialize a subscription forSubscriber_MSISDN. The response containsSubscriptionIDand the confirmation channel; the subscription status isPending.ApproveSubscription— confirm with the PIN code from SMS.SubscriptionStatusNotificationwithEventType=APPROVED— the subscription is active.GetSubscriptionStatus— check the status at any time.CancelSubscription— cancellation initiated by the partner.
The SubscriptionID from the CreateSubscription response identifies the subscription in every other method — store it. A repeated CreateSubscription for the same number within the project is rejected with SubscriptionAlreadyCreated until the previous subscription is cancelled.
Subscription statuses
| Status | Meaning |
|---|---|
Pending | Created, waiting for the subscriber to confirm |
Active | Confirmed — by PIN or by payment |
Cancelled | Cancelled |
ApprovingFailed | Confirmation did not happen: PIN attempts exhausted or the card was declined |
Redelivering | A charge failed, a retry follows |
RenewingFailed | Charge attempts exhausted — the subscription is closed |
Closed | All billing cycles are done |
Sandbox
Sandbox test data
| Parameter | Value |
|---|---|
SubscriptionProjectID | 2001 — other values are rejected with SECURITY_ERROR |
SecretKey | subs_secret_key |
| PIN code | 1234 — fixed, the sandbox sends no SMS. Three attempts; after the third the subscription stays in ApprovingFailed forever |
| Failing cards | Last 4 digits 0001…0005 — insufficient funds, card blocked, limit exceeded, declined by bank, card expired |
| Failing numbers | Ending 0001 — SubscriberNotSupported, 0002 — SubscriberInBlacklist, 0003 together with ClientIP — ClientIPMSISDNCountryNotEqual |
The values above are published sandbox fixtures, suitable for testing only. Production SubscriptionProjectID and SecretKey are issued at onboarding and must never end up in client-side code or the repository.