Подписки
Ссылки для подписки клиентов на ваши планы отвечают за выставление счетов и проведение оплаты в соответствии с вашими интервалами оплаты.
Созданная подписка будет автоматически продлена на срок, указанный в плане, к которому она относится. Вы можете отслеживать свои подписки в кабинете PayCross или быть подписанным по email на уведомления об обработанных транзакциях (в настройках магазина). Дополнительно PayCross будет отправлять автоматические уведомления на notification_url
из запроса на создание подписки.
Статусы подписки
Статус | Описание |
---|---|
pending |
Первоначальный статус. Все недавно созданные подписки имеют статус pending перед началом обработки. |
trial |
Активная или отмененная подписка пробного периода. |
trial_processing |
Подписка обрабатывает платеж за пробный период. |
processing |
Подписка обрабатывает платеж. |
active |
Активная подписка, выплата по которой была в срок. |
failed |
Неудавшаяся подписка. PayCross был не в состоянии провести очередной платеж. |
error |
Произошла ошибка при попытке PayCross провести платеж. |
canceled |
Подписка отменена и больше не действует. |
Создание подписки
Запрос
Отправьте POST
запрос на https://data.pay-cross.com/subscriptions
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
customer | object | Данные клиента. Содержит либо ID клиента, либо полные данные пользователя. |
plan * обязательный |
object | Данные плана подписки. Содержит либо ID плана, либо полные данные плана. |
dynamic_billing_descriptor | string | Динамический идентификатор платежа |
tracking_id | string | ID транзакции или заказа в вашей системе. Максимальная длина: 255 символов. Пожалуйста, используйте уникальное значение для того, чтобы при запросе статуса транзакции получить актуальную информацию. В противном случае вы получите первую найденную по tracking_id транзакцию. |
device_id | string | ID устройства клиента, подписанного на ваш сервис. |
return_url | string | URL, на который будет перенаправлен клиент после завершения оплаты. Если параметр не определен, клиент будет перенаправлен на URL магазина, зарегистрированного в PayCross. 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 . |
Ответ
Если права доступа и параметры верны, PayCross вернет 201
код состояния HTTP и соответствующие данные подписки. Клиент должен быть перенаправлен на redirect_url
, чтобы ввести данные карты и совершить оплату для создания подписки.
Иначе, система вернет 422
код состояния HTTP и сообщение об ошибке.
Пример верного запроса на создание подписки
curl https://data.pay-cross.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://panel.pay-cross.com/v2/checkout?token=3241e439f8c87d941d92321a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
"renew_at": null,
"active_to": null,
"state": "redirecting",
"token": "3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
"tracking_id": null
}
Пример запроса на создание подписки, когда параметр неверен или не передан
curl https://data.pay-cross.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://data.pay-cross.com/subscriptions
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
customer * обязательный |
object | Данные клиента. Содержит либо ID клиента, либо полные данные пользователя. |
plan * обязательный |
object | Данные плана подписки. Содержит либо ID плана, либо полные данные подписки. |
tracking_id | string(255) | ID транзакции или заказа в вашей системе. Пожалуйста, используйте уникальное значение для того, чтобы при запросе статуса транзакции получить актуальную информацию. В противном случае вы получите первую найденную по tracking_id транзакцию. |
device_id | string | ID устройства клиента, подписанного на ваш сервис. |
return_url | string | URL, на который будет перенаправлен клиент после завершения оплаты. Если параметр не определен, клиент будет перенаправлен на URL магазина, зарегистрированного с PayCross. 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 и PayCross доставит банку-эквайеру данные карты с CVC2/CVV2/CID |
holder * обязательный |
string(32) | Имя владельца карты. |
exp_month * обязательный |
string | Месяц окончания срока действия карты, представленный двумя цифрами (например, 01). |
exp_year * обязательный |
string | Год срока окончания действия карты, представленный четырьмя цифрами (например, 2026). |
token * условно обязательный |
string | Вместо 5 параметров выше вы можете отправить токен карты, который вы получили из запроса на токенизацию карты или после успешной оплаты, авторизации или подписки. |
Ответ
Если права доступа и параметры верны, PayCross вернет 201
код состояния HTTP и соответствующие данные подписки. Клиент должен быть перенаправлен на redirect_url
для ввода данных карты.
Иначе, PayCross вернет 422
код состояния HTTP и сообщение об ошибке.
Пример запроса на создание подписки с данными карты
{
"card": {
"exp_month": "01",
"exp_year": "2026",
"holder": "John Doe",
"number": "4200000000000000",
"verification_value": "123"
},
"customer": {
"address": "1st Street",
"city": "Denver",
"country": "US",
"email": "[email protected]",
"first_name": "John",
"ip": "127.0.0.1",
"last_name": "Doe",
"phone": "+1-555-555-5555",
"state": "CO",
"zip": "92006"
},
"plan": {
"currency": "USD",
"plan": {
"amount": 20,
"interval": 20,
"interval_unit": "day"
},
"title": "Basic plan",
"trial": {
"amount": 10,
"interval": 10,
"interval_unit": "hour"
}
},
"tracking_id": "my_tracking_id"
}
Пример ответа на запрос на создание подписки с данными карты
{
"id": "sbs_43cb5f79f8b56c17",
"state": "successful",
"tracking_id": "my_tracking_id",
"device_id": null,
"created_at": "2021-07-01T13:05:45.699Z",
"renew_at": null,
"active_to": null,
"card": {
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"token": "1e2f9f69-a9d3-4d6d-a6c3-f029c3db70e6",
"token_provider": null,
"exp_month": 1,
"exp_year": 2026
},
"customer": {
"id": "cst_cebacd2a35f2041e"
},
"paid_billing_cycles": 0,
"number_failed_payment_attempts": 0,
"additional_data": {},
"plan": {
"id": "pln_7fd782ffa0fbc926",
"title": "Basic plan",
"currency": "USD",
"language": null,
"infinite": true,
"billing_cycles": null,
"trial": {
"amount": 10,
"interval": 10,
"interval_unit": "hour"
},
"plan": {
"amount": 20,
"interval": 20,
"interval_unit": "day"
},
"number_payment_attempts": 1,
"test": null
},
"last_transaction": {
"uid": "11749-e427d3dc44",
"status": "successful",
"message": "Successfully processed",
"created_at": "2021-07-01T13:05:46.447Z"
}
}
Пример запроса на создание подписки с return_url
, на который должен быть перенаправлен клиент, при включенной для магазина проверки 3-D Secure
{
"card": {
"exp_month": "01",
"exp_year": "2026",
"holder": "John Doe",
"number": "4012001037141112",
"verification_value": "123"
},
"customer": {
"address": "1st Street",
"city": "Denver",
"country": "US",
"email": "[email protected]",
"first_name": "Jane",
"ip": "127.1.2.3",
"last_name": "Doe",
"phone": "+1-555-555-555",
"state": "CO",
"zip": "92006"
},
"plan": {
"currency": "USD",
"plan": {
"amount": "90",
"interval": 3,
"interval_unit": "day"
},
"title": "Basic plan",
"trial": {
"amount": "10",
"interval": 24,
"interval_unit": "hour"
}
},
"return_url": "http://example.com/result-page"
}
Пример ответа на запрос на создание подписки с return_url
{
"card": {
"token": "159335feed5ee3facbc0d882f19d199fc5c60019f668e40fe15d6fedbd390295",
"holder": "John Doe",
"stamp": "lkdfsklba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"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": 2026
},
"created_at": "2015-03-18T10:06:01.406Z",
"customer": {
"id": "cst_5d6a3dbbfdfd29d5"
},
"device_id": null,
"id": "sbs_9d0912f6b8ab65bc",
"last_transaction": {
"created_at": "2015-03-18T10:06:01.000Z",
"message": null,
"redirect_url": "https://gateway.pay-cross.com/process/94-bb19e2c4bc",
"status": "incomplete",
"uid": "94-bb19e2c4bc"
},
"plan": {
"currency": "USD",
"id": "pln_e6851bf1a933bb3b",
"plan": {
"amount": 90,
"interval": 3,
"interval_unit": "day"
},
"title": "Mens Health",
"trial": {
"amount": 10,
"interval": 24,
"interval_unit": "hour"
}
},
"renew_at": null,
"active_to": null,
"state": "redirecting",
"tracking_id": null
}
Пример запроса на создание подписки, когда план, покупатель и токен карты были созданы
{
"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://data.pay-cross.com/subscriptions/{subscription_id}
, где {subscription_id}
- идентификатор подписки.
Ответ
Если подписка существует, PayCross вернет 200
код состояния и информацию о ней.
Пример запроса на получение информации о подписке с ID sbs_43cb5f79f8b56c17
curl -u shop_id:secret \
https://data.pay-cross.com/subscriptions/sbs_43cb5f79f8b56c17
Пример ответа на запрос на получение информации о подписке
{
"id": "sbs_43cb5f79f8b56c17",
"state": "successful",
"tracking_id": "my_tracking_id",
"device_id": null,
"created_at": "2021-07-01T13:05:45.699Z",
"renew_at": null,
"active_to": null,
"card": {
"holder": "John Doe",
"stamp": "pr334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"token": "1e2f9f69-a9d3-4d6d-a6c3-f029c3db70e6",
"token_provider": null,
"exp_month": 1,
"exp_year": 2026
},
"customer": {
"id": "cst_cebacd2a35f2041e"
},
"paid_billing_cycles": 0,
"number_failed_payment_attempts": 0,
"additional_data": {},
"plan": {
"id": "pln_7fd782ffa0fbc926",
"title": "Basic plan",
"currency": "USD",
"language": null,
"infinite": true,
"billing_cycles": null,
"trial": {
"amount": 10,
"interval": 10,
"interval_unit": "hour"
},
"plan": {
"amount": 20,
"interval": 20,
"interval_unit": "day"
},
"number_payment_attempts": 1,
"test": null
},
"last_transaction": {
"uid": "11749-e427d3dc44",
"status": "successful",
"message": "Successfully processed",
"created_at": "2021-07-01T13:05:46.447Z"
}
}
Отмена подписки
Запрос
Отправьте POST
запрос на https://data.pay-cross.com/subscriptions/{subscription_id}/cancel
, где {subscription_id}
- это идентификатор подписки, со следующим параметром:
Параметр | Тип | Описание |
---|---|---|
cancel_reason * обязательный |
string | Причина, по которой подписка отменяется, например Запрос клиента . |
Ответ
Если запрос был принят, PayCross вернет 200
код состояния и массив клиентов.
Пример запроса на отмену подписки с ID sbs_b1b7139d9b664293
curl https://data.pay-cross.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": 2026
},
"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
.