Подписки

Ссылки для подписки клиентов на ваши планы отвечают за выставление счетов и проведение оплаты в соответствии с вашими интервалами оплаты.

Созданная подписка будет автоматически продлена на срок, указанный в плане, к которому она относится. Вы можете отслеживать свои подписки в кабинете Demo PSP или быть подписанным по email на уведомления об обработанных транзакциях (в настройках магазина). Дополнительно Demo PSP будет отправлять автоматические уведомления на notification_url из запроса на создание подписки.

Статусы подписки

Статус	Описание
`pending`	Первоначальный статус. Все созданные подписки имеют статус `pending` перед началом обработки.
`tokenizing`	Создание токена, необходимого для первого платежа через виджет.
`redirecting`	Перенаправление покупателя на платежный виджет.
`trial_get_status` -> `getting_status`	Повторный запрос статуса транзакции платежа при тайм-ауте ответа на предыдущий запрос статуса.
`trial`	Активная или отмененная подписка пробного периода.
`trial_processing`	Обработка платежа за пробный период.
`processing`	Обработка платежа.
`notified`	Получение нотификаций между внутренними компонентами системы Demo PSP.
`active`	Активная оплаченная подписка. Таким образом, после завершения пробного периода подписка проходит цикл `processing` -> `active` -> `processing`.
`failed_attempt`	Попытка оплаты завершилась статусом `failed`, но ранее в рамках этой подписки были успешные оплаты. Система будет осуществлять повторные попытки списания. Количество попыток списания будет равно значению, отправленному в параметре `number_failed_payment_attempts`.
`failed`	Конечное состояние подписки. Demo PSP был не в состоянии провести очередной платеж, система не будет делать дальнейших попыток списания.
`error`	Ошибка при попытке Demo PSP провести платеж.
`rescuing`	Попытка оплаты завершилась статусом `error`, однако ранее в рамках этой подписки были успешные оплаты. Система будет осуществлять повторные попытки списания. Количество попыток списания будет равно значению, отправленному в параметре `number_failed_payment_attempts`.
`expired`	Был создан токен для оплаты подписки, но время жизни токена истекло, и по нему не была инициирована транзакция.
`canceled`	Подписка отменена и больше не действует. Подписка отменена через API, или количество циклов оплаты достигло количества, указанного в параметре `billing_cycles` плана подписки.

Создание подписки

Запрос

Отправьте POST запрос на https://api.begateway.com/subscriptions со следующими параметрами:

Параметр	Тип	Описание
customer	object	Данные клиента. Содержит либо ID клиента, либо полные данные пользователя.
plan * обязательный	object	Данные плана подписки. Содержит либо ID плана, либо полные данные плана.
dynamic_billing_descriptor	string	Динамический идентификатор платежа
tracking_id	string	ID транзакции или заказа в вашей системе. Максимальная длина: 255 символов. Пожалуйста, используйте уникальное значение для того, чтобы при запросе статуса транзакции получить актуальную информацию. В противном случае вы получите массив данных по 10 последним транзакциям, найденным по указанному `tracking_id`.
device_id	string	ID устройства клиента, подписанного на ваш сервис.
return_url	string	URL, на который будет перенаправлен клиент после завершения оплаты. Если параметр не определен, клиент будет перенаправлен на URL магазина, зарегистрированного в Demo PSP. ID подписки будет добавлен в параметр `id` строки запроса, например: `http://example.com/return?id=sbs_f4117438947a554e`
notification_url	string	URL, на который будут приходить уведомления о созданных, продленных или отмененных подписках.
additional_data	object	Cекция, содержащая дополнительную информацию о подписке. Сюда вы можете добавить свои данные.
receipt_text	array	Текст, который будет добавлен в письмо клиенту и отображен на странице об успешной оплате. Должен быть представлен как массив строк, например `["Первая строка", "Вторая строка"]`.
avs_cvc_verification	object	AVS/CVC проверка.
settings	object	Настройки страницы оплаты провайдера платежей.
language	string	Язык платежного виджета. По умолчанию - `en`. Доступные значения параметра `language`.

Ответ

Если права доступа и параметры верны, Demo PSP вернет 201 код состояния HTTP и соответствующие данные подписки. Клиент должен быть перенаправлен на redirect_url, чтобы ввести данные карты и совершить оплату для создания подписки.

Иначе, система вернет 422 код состояния HTTP и сообщение об ошибке.

Пример верного запроса на создание подписки

curl https://api.begateway.com/subscriptions \
  -X POST -u shop_id:secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
    "notification_url": "http://merchant.com/subscription_notification",
    "plan": {
        "currency": "USD",
        "plan": {
            "amount": 20,
            "interval": 20,
            "interval_unit": "day"
        },
        "shop_id": 10,
        "title": "Basic plan",
        "trial": {
            "amount": 10,
            "interval": 10,
            "interval_unit": "hour"
        }
    },
    "settings": {
        "language": "it"
    }
}
'

Пример ответа на запрос на создание подписки

{
    "card": {},
    "created_at": "2015-05-11T12:48:14.067Z",
    "customer": {},
    "device_id": null,
    "id": "sbs_cdf887166553b5ae",
    "last_transaction": null,
    "plan": {
        "currency": "USD",
        "id": "pln_8f9c9dd63c9a5787",
        "plan": {
            "amount": 20,
            "interval": 20,
            "interval_unit": "day"
        },
        "title": "Title",
        "trial": {
            "amount": 10,
            "interval": 10,
            "interval_unit": "hour"
        }
    },
    "redirect_url": "https://checkout.begateway.com/v2/checkout?token=3241e439f8c87d941d92321a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "renew_at": null,
    "active_to": null,
    "state": "redirecting",
    "token": "3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "tracking_id": null
}

Пример запроса на создание подписки, когда параметр неверен или не передан

curl https://api.begateway.com/subscriptions \
  -X POST -u shop_id:secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
    "notification_url": "http://merchant.com/subscription_notification",
    "plan": {
        "currency": "LVL",
        "plan": {
            "amount": 20,
            "interval": 20,
            "interval_unit": "day"
        },
        "shop_id": 10,
        "title": "Basic plan",
        "trial": {
            "amount": 10,
            "interval": 10,
            "interval_unit": "hour"
        }
    },
    "settings": {
        "language": "it"
    }
}
'

Пример ответа на запрос на создание подписки, когда параметр неверен или не передан

{
    "errors": {
        "base": [
            "Currency is invalid"
        ]
    },
    "message": "Currency is invalid"
}

Создание подписки с данными кредитной карты

Запрос

Отправьте POST запрос на https://api.begateway.com/subscriptions со следующими параметрами:

Параметр	Тип	Описание
customer * обязательный	object	Данные клиента. Содержит либо ID клиента, либо полные данные пользователя.
plan * обязательный	object	Данные плана подписки. Содержит либо ID плана, либо полные данные подписки.
tracking_id	string(255)	ID транзакции или заказа в вашей системе. Пожалуйста, используйте уникальное значение для того, чтобы при запросе статуса транзакции получить актуальную информацию. В противном случае вы получите массив данных по 10 последним транзакциям, найденным по указанному `tracking_id`.
device_id	string	ID устройства клиента, подписанного на ваш сервис.
return_url	string	URL, на который будет перенаправлен клиент после завершения оплаты. Если параметр не определен, клиент будет перенаправлен на URL магазина, зарегистрированного с Demo PSP. ID подписки будет добавлен в параметр `id` строки запроса, например: `http://example.com/return?id=sbs_f4117438947a554e`.
notification_url	string	URL, на который будут приходить уведомления.
card	object	Секция данных карты.
number * обязательный	string	Номер карты, длина - от 12 до 19 цифр.
verification_value * обязательный	string	3-х или 4-х цифровой код безопасности (CVC2, CVV2 или CID, в зависимости от бренда карты). Может быть отправлен вместе с параметром `token` и Demo PSP доставит банку-эквайеру данные карты с CVC2/CVV2/CID
holder * обязательный	string(32)	Имя владельца карты.
exp_month * обязательный	string	Месяц окончания срока действия карты, представленный двумя цифрами (например, 01).
exp_year * обязательный	string	Год срока окончания действия карты, представленный четырьмя цифрами (например, 2027).
token * условно обязательный	string	Вместо 5 параметров выше вы можете отправить токен карты, который вы получили из запроса на токенизацию карты или после успешной оплаты, авторизации или подписки.

Ответ

Если права доступа и параметры верны, Demo PSP вернет 201 код состояния HTTP и соответствующие данные подписки. Клиент должен быть перенаправлен на redirect_url для ввода данных карты.

Иначе, Demo PSP вернет 422 код состояния HTTP и сообщение об ошибке.

Пример запроса на создание подписки с данными карты

{
  "card": {
    "exp_month": "01",
    "exp_year": "2027",
    "holder": "John Doe",
    "number": "5204240000015003",
    "verification_value": "123"
  },
  "customer": {
    "id": "cst_ec240ca02bac424b"
  },
  "plan": {
    "id": "pln_f5ee5ebd04e39daa"
  },
  "tracking_id": "my_tracking_id"
}

Пример ответа на запрос на создание подписки с данными карты

{
  "id": "sbs_cce60e7f2d661bc0",
  "state": "active",
  "tracking_id": "my_tracking_id",
  "device_id": null,
  "created_at": "2025-03-10T12:29:31Z",
  "renew_at": "2025-03-10T13:29:37Z",
  "active_to": "2025-03-10T13:29:37Z",
  "card": {
    "holder": "John Doe",
    "stamp": "1e2470e4c658e9cc143af8c1dc7a41d382fe53e30c62768a3dbebdc392146c64",
    "brand": "master",
    "last_4": "5003",
    "first_1": "5",
    "bin": "520424",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "token": "111b73a8-4d0c-4d06-a6b4-bccfc006f27b",
    "token_provider": null,
    "exp_month": 1,
    "exp_year": 2027,
    "sub_brand": null
  },
  "customer": {
    "id": "cst_ec240ca02bac424b"
  },
  "paid_billing_cycles": 1,
  "number_failed_payment_attempts": 0,
  "additional_data": {},
  "plan": {
    "id": "pln_f5ee5ebd04e39daa",
    "title": "Basic plan",
    "name": "Basic plan",
    "description": "Subscription. Main period: €1.00 each 1 hour.",
    "amount": 100,
    "currency": "EUR",
    "language": "ru",
    "infinite": true,
    "billing_cycles": null,
    "created_at": "2025-03-10T11:45:56Z",
    "updated_at": "2025-03-10T11:45:56Z",
    "trial": {
      "amount": null,
      "interval": null,
      "interval_unit": "hour"
    },
    "plan": {
      "amount": 100,
      "interval": 1,
      "interval_unit": "hour",
      "visible_fields": []
    },
    "number_payment_attempts": 3,
    "prevent_payments_at_night": false,
    "test": true,
    "pay_url": "https://api.begateway.com/plans/pln_f5ee5ebd04e39daa/pay",
    "payment_url": "https://api.begateway.com/plans/pln_f5ee5ebd04e39daa/pay",
    "confirm_url": "https://checkout.begateway.com/v2/confirm_order/pln_f5ee5ebd04e39daa/1673"
  },
  "last_transaction": {
    "uid": "f0eee433-703a-48d6-b91e-6f3a5696b68d",
    "status": "successful",
    "message": "Successfully processed",
    "created_at": "2025-03-10T12:29:33Z"
  }
}

Пример ответа на запрос на создание подписки с картой, для которой активирована проверка 3-D Secure

{
  "id": "sbs_3e558f16e7e05f96",
  "state": "redirecting",
  "tracking_id": "my_tracking_id",
  "device_id": null,
  "created_at": "2025-03-10T13:12:38Z",
  "renew_at": null,
  "active_to": null,
  "card": {
    "holder": "John Doe",
    "stamp": "ee02c1496a29180236cde09f44f4823efe793a7b68151dd43cad8577fb7ebc25",
    "brand": "visa",
    "last_4": "1097",
    "first_1": "4",
    "bin": "401200",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "token": "e97830d7-560a-4ae9-8e74-5a8353637545",
    "token_provider": null,
    "exp_month": 1,
    "exp_year": 2027,
    "sub_brand": null
  },
  "customer": {
    "id": "cst_ec240ca02bac424b"
  },
  "paid_billing_cycles": 0,
  "number_failed_payment_attempts": 0,
  "additional_data": {},
  "plan": {
    "id": "pln_f5ee5ebd04e39daa",
    "title": "Basic plan",
    "name": "Basic plan ",
    "description": "Subscription. Main period: €1.00 each 1 hour.",
    "amount": 100,
    "currency": "EUR",
    "language": "ru",
    "infinite": true,
    "billing_cycles": null,
    "created_at": "2025-03-10T11:45:56Z",
    "updated_at": "2025-03-10T11:45:56Z",
    "trial": {
      "amount": null,
      "interval": null,
      "interval_unit": "hour"
    },
    "plan": {
      "amount": 100,
      "interval": 1,
      "interval_unit": "hour",
      "visible_fields": []
    },
    "number_payment_attempts": 3,
    "prevent_payments_at_night": false,
    "test": true,
    "pay_url": "https://api.begateway.com/plans/pln_f5ee5ebd04e39daa/pay",
    "payment_url": "https://api.begateway.com/plans/pln_f5ee5ebd04e39daa/pay",
    "confirm_url": "https://checkout.begateway.com/v2/confirm_order/pln_f5ee5ebd04e39daa/1673"
  },
  "last_transaction": {
    "uid": "f3c46af4-fdb3-4e0c-98db-01306780c7a8",
    "status": "incomplete",
    "message": null,
    "created_at": "2025-03-10T13:12:39Z",
    "redirect_url": "https://demo-gateway.begateway.com/process/f3c46af4-fdb3-4e0c-98db-01306780c7a8"
  }
}

Пример запроса на создание подписки, когда план, покупатель и токен карты были созданы

{
  "card": {
    "token": "7982c829f83060eba2b27b0a7140c751ad02f28702a6475e901767614fe4c0e7"
    },
  "customer": {
    "id": "cst_c8dcec3e5ce21500"
  },
  "plan": {
    "id": "pln_cc22f0cda95f210f"
  },
  "tracking_id": "my_tracking_id"
}

Пример запроса на создание подписки и ответа, когда параметр неверен или не передан

{
  "card": {
    "token": "7982c829f83060eba2b27b0a7140c751ad02f28702a6475e9"
      },
  "plan": {
    "id": "1"
  }
}

Пример ответа на запрос на создание подписки, когда параметр неверен или не передан

{
    "errors": {
        "plan": {
            "base": [
                "plan with this ID doesn't exist for this account"
            ]
        }
    },
    "message": "plan with this ID doesn't exist for this account"
}

Получение информации о подписке

Запрос

Запрос на получение информации о подписке должен быть отправлен как GET запрос на https://api.begateway.com/subscriptions/{subscription_id}, где {subscription_id} - идентификатор подписки.

Ответ

Если подписка существует, Demo PSP вернет 200 код состояния и информацию о ней.

Пример запроса на получение информации о подписке с ID sbs_430955c932808d0f

curl -u shop_id:secret \
  https://api.begateway.com/subscriptions/sbs_430955c932808d0f

Пример ответа на запрос на получение информации о подписке

{
    "id": "sbs_430955c932808d0f",
    "state": "active",
    "tracking_id": null,
    "device_id": null,
    "created_at": "2025-03-10T11:46:13Z",
    "renew_at": "2025-03-10T12:46:42Z",
    "active_to": "2025-03-10T12:46:42Z",
    "card": {
        "holder": "KEVIN JACKSON",
        "stamp": null,
        "brand": "master",
        "last_4": "5003",
        "first_1": "5",
        "bin": null,
        "issuer_country": null,
        "issuer_name": null,
        "product": null,
        "token": "f6e16646-22f2-4645-854d-893ac6e10da7",
        "token_provider": null,
        "exp_month": 9,
        "exp_year": 2028,
        "sub_brand": null
    },
    "customer": {
        "id": "cst_1901069ea84fa2a7"
    },
    "paid_billing_cycles": 1,
    "number_failed_payment_attempts": 0,
    "additional_data": {},
    "plan": {
        "id": "pln_f5ee5ebd04e39daa",
        "title": "Basic plan",
        "name": "Basic plan",
        "description": "Subscription. Main period: €1.00 each 1 hour.",
        "amount": 100,
        "currency": "EUR",
        "language": "ru",
        "infinite": true,
        "billing_cycles": null,
        "created_at": "2025-03-10T11:45:56Z",
        "updated_at": "2025-03-10T11:45:56Z",
        "trial": {
            "amount": null,
            "interval": null,
            "interval_unit": "hour"
        },
        "plan": {
            "amount": 100,
            "interval": 1,
            "interval_unit": "hour",
            "visible_fields": []
        },
        "number_payment_attempts": 3,
        "prevent_payments_at_night": false,
        "test": true,
        "pay_url": "https://api.begateway.com/plans/pln_f5ee5ebd04e39daa/pay",
        "payment_url": "https://api.begateway.com/plans/pln_f5ee5ebd04e39daa/pay",
        "confirm_url": "https://checkout.begateway.com/v2/confirm_order/pln_f5ee5ebd04e39daa/1673"
    },
    "last_transaction": {
        "uid": "b7d8478d-fd2f-4a31-bdd5-65f503438e00",
        "status": "successful",
        "message": "Successfully processed",
        "created_at": "2025-03-10T11:46:32Z"
    }
}

Отмена подписки

Запрос

Отправьте POST запрос на https://api.begateway.com/subscriptions/{subscription_id}/cancel, где {subscription_id} - это идентификатор подписки, со следующим параметром:

Параметр	Тип	Описание
cancel_reason * обязательный	string	Причина, по которой подписка отменяется, например `Запрос клиента`.

Ответ

Если запрос был принят, Demo PSP вернет 200 код состояния и массив клиентов.

Пример запроса на отмену подписки с ID sbs_b1b7139d9b664293

curl https://api.begateway.com/subscriptions/sbs_b1b7139d9b664293/cancel \
  -u shop_id:secret \
  -X POST secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
    "cancel_reason": "Customer's request"
}
'

Пример ответа на запрос на отмену подписки

{
  "card": {
    "token": "064a120788b5847f866ff3def0c97ae12a6ff069407317fef172dcbafa3187e6",
    "holder": "John Doe",
    "stamp": "qr34ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
    "brand": "visa",
    "last_4": "0000",
    "first_1": "4",
    "bin": "420000",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "token_provider": null,
    "exp_month": 1,
    "exp_year": 2027
  },
  "created_at": "2015-01-27T15:59:55.609Z",
  "customer": {
    "id": "cst_e64cc8479090991e"
  },
  "id": "sbs_b1b7139d9b664293",
  "plan": {
    "currency": "USD",
    "id": "pln_068ed4bb9ce03298",
    "plan": {
      "amount": 20,
      "interval": 7,
      "interval_unit": "day"
    },
    "title": "Basic plan",
    "trial": {
      "amount": 10,
      "interval": 40,
      "interval_unit": "hour"
    }
  },
  "cancel_reason": "Customer's request",
  "cancelled_at": "2015-02-28T14:19:55.009Z",
  "renew_at": null,
  "active_to": "2015-03-28T01:54:32.684Z",
  "state": "canceled",
  "tracking_id": "my_tracking_id",
  "transaction": null
}

Автоматическая отмена подписки

В определенных случаях, подписка автоматически отменяется со статусом failed или error:

Если самая первая попытка снятия средств в рамках этой подписки возвращает статус failed, то подписка также отменяется со статусом failed.
Если попытка снятия средств возвращает статус failed, но ранее в рамках этой подписки были успешные транзакции, то система будет осуществлять попытки снятия средств, пока не закончится количество попыток, указанное в параметре number_payment_attempts. Если повторные попытки вернули статус failed, то подписка также отменяется со статусом failed.
Если самая первая попытка снятия средств в рамках этой подписки возвращает статус error (например, неверный формат номера карты, или шлюз не принимает валюту), то подписка отменяется со статусом failed.
Если самая первая попытка снятия средств в рамках этой подписки возвращает статус error, но ранее в рамках этой подписки были успешные транзакции, то система будет осуществлять попытки снятия средств, пока не закончится количество попыток, указанное в параметре number_payment_attempts. Если повторные попытки вернули статус error, то подписка также отменяется со статусом error.