Подписки — обзор
XML API управления подписками биллинговой платформы i-Free. Все запросы отправляются методом POST на /Http/Services/{Method}.aspx — имя метода регистронезависимо.
Sandbox
| Эндпоинт | https://subs-sandbox.digitalspb.com/Http/Services/{Method}.aspx |
| Справочник | https://i-free.money/developers/ru/sandbox |
| Параметр | Значение |
|---|---|
| Content-Type | text/xml — XML-тело, либо application/x-www-form-urlencoded — те же поля form-параметрами |
| Корневой элемент | запроса — <Request>, ответа — <Response> |
| Ответ | XML <Response> с полем StatusName |
Версия протокола: 1.
Это не тот же протокол, что разовые платежи Callisto: другой адрес, другая формула подписи, другой набор методов. Общего кода между интеграциями почти нет.
Разная и модель ответственности: здесь график списаний ведёт платформа по расписанию проекта, партнёр не инициирует каждое списание. Если нужно наоборот — привязать реквизиты, а списывать по собственному расписанию, — это контракт в разовых платежах, см. Оплата с телефона (DCB).
Три способа активации
Метод создания подписки один — CreateSubscription; способ активации выбирается набором полей клиента в запросе.
| Способ | Поля запроса | Как активируется |
|---|---|---|
SMS_PIN | Subscriber_MSISDN (legacy-имя MSISDN тоже принимается) | Абонент вводит PIN из SMS → ApproveSubscription |
AUTH_PAGE — карта и СБП | CustomerType=Card + CustomerId | Редирект на AuthorizeUrl из ответа; для QR-кода СБП к адресу добавляется ?useSbpQr=True. ApproveSubscription не вызывается — подписка активируется по факту оплаты |
AUTH_PAGE — WAP | ClientIP без номера — номер определяет шлюз оператора | Абонент подтверждает подписку на странице AuthorizeUrl и возвращается с параметрами результата (action=approved / cancelled / alreadyexist) |
Сценарий SMS_PIN
CreateSubscription— инициализация подписки дляSubscriber_MSISDN. В ответеSubscriptionIDи канал подтверждения; статус подписки —Pending.ApproveSubscription— подтверждение PIN-кодом из SMS.- Коллбек
SubscriptionStatusNotificationсEventType=APPROVED— подписка активна. GetSubscriptionStatus— проверка состояния в любой момент.CancelSubscription— отмена по инициативе партнёра.
SubscriptionID из ответа CreateSubscription идентифицирует подписку во всех остальных методах — сохраните его. Повторный CreateSubscription для того же номера в границах проекта отклоняется с SubscriptionAlreadyCreated, пока прежняя подписка не отменена.
Статусы подписки
| Статус | Значение |
|---|---|
Pending | Создана, ждёт подтверждения абонента |
Active | Подтверждена — PIN или оплатой |
Cancelled | Отменена |
ApprovingFailed | Подтверждение не состоялось: исчерпаны попытки PIN либо отказ по карте |
Redelivering | Списание не прошло, будет повторная попытка |
RenewingFailed | Попытки списания исчерпаны — подписка закрыта |
Closed | Все циклы тарификации пройдены |
Sandbox
Тестовые данные песочницы
| Параметр | Значение |
|---|---|
SubscriptionProjectID | 2001 — другое значение отклоняется с SECURITY_ERROR |
SecretKey | subs_secret_key |
| PIN-код | 1234 — фиксированный, SMS песочница не отправляет. Три попытки, после третьей подписка навсегда в ApprovingFailed |
| Карты с ошибкой | Последние 4 цифры 0001…0005 — недостаточно средств, карта заблокирована, превышен лимит, отклонено банком, истёк срок |
| Номера с отказом | Окончание 0001 — SubscriberNotSupported, 0002 — SubscriberInBlacklist, 0003 вместе с ClientIP — ClientIPMSISDNCountryNotEqual |
Значения выше — опубликованные фикстуры песочницы, они годятся только для тестов. Боевые SubscriptionProjectID и SecretKey выдаются при подключении и не должны попадать в клиентский код или репозиторий.