Перейти к содержанию

Подписки

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

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

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

Статус Описание
pending Первоначальный статус. Все недавно созданные подписки имеют статус pending перед началом обработки.
trial Активная или отмененная подписка пробного периода.
trial_processing Подписка обрабатывает платеж за пробный период.
processing Подписка обрабатывает платеж.
active Активная подписка, выплата по которой была в срок.
failed Неудавшаяся подписка. eComCharge был не в состоянии провести очередной платеж.
error Произошла ошибка при попытке eComCharge провести платеж.
canceled Подписка отменена и больше не действует.

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

Запрос

Отправьте POST запрос на https://api.ecomcharge.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 магазина, зарегистрированного в eComCharge. 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.

Ответ

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

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

Пример верного запроса на создание подписки 
curl https://api.ecomcharge.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.ecomcharge.com/v2/checkout?token=3241e439f8c87d941d92321a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "renew_at": null,
    "active_to": null,
    "state": "redirecting",
    "token": "3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "tracking_id": null
}
Пример запроса на создание подписки, когда параметр неверен или не передан 
curl https://api.ecomcharge.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.ecomcharge.com/subscriptions со следующими параметрами:

Параметр Тип Описание
customer * обязательный
 object Данные клиента. Содержит либо ID клиента, либо полные данные пользователя.
plan * обязательный
 object Данные плана подписки. Содержит либо ID плана, либо полные данные подписки.
tracking_id string(255) ID транзакции или заказа в вашей системе. Пожалуйста, используйте уникальное значение для того, чтобы при запросе статуса транзакции получить актуальную информацию. В противном случае вы получите первую найденную по tracking_id транзакцию.
device_id string ID устройства клиента, подписанного на ваш сервис.
return_url string URL, на который будет перенаправлен клиент после завершения оплаты. Если параметр не определен, клиент будет перенаправлен на URL магазина, зарегистрированного с eComCharge. 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 и eComCharge доставит банку-эквайеру данные карты с CVC2/CVV2/CID
holder * обязательный
 string(32) Имя владельца карты.
exp_month * обязательный
 string Месяц окончания срока действия карты, представленный двумя цифрами (например, 01).
exp_year * обязательный
 string Год срока окончания действия карты, представленный четырьмя цифрами (например, 2026).
token * условно обязательный
 string Вместо 5 параметров выше вы можете отправить токен карты, который вы получили из запроса на токенизацию карты или после успешной оплаты, авторизации или подписки.

Ответ

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

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

Пример запроса на создание подписки с данными карты 
{
  "card": {
    "exp_month": "01",
    "exp_year": "2026",
    "holder": "John Doe",
    "number": "420000000000000000",
    "verification_value": "123"
  },
  "customer": {
    "address": "1st Street",
    "city": "Denver",
    "country": "US",
    "email": "customer@example.com",
    "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": "customer@example.com",
    "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://processing.ecomcharge.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://api.ecomcharge.com/subscriptions/{subscription_id}, где {subscription_id} - идентификатор подписки.

Ответ

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

Пример запроса на получение информации о подписке с ID sbs_43cb5f79f8b56c17 
curl -u shop_id:secret \
  https://api.ecomcharge.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://api.ecomcharge.com/subscriptions/{subscription_id}/cancel, где {subscription_id} - это идентификатор подписки, со следующим параметром:

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

Ответ

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

Пример запроса на отмену подписки с ID sbs_b1b7139d9b664293 
curl https://api.ecomcharge.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:

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