3.28. /api/v4/create-recurring-payments

Введение

Если запрос принят без ошибок, платежный шлюз создает отдельные профили повторяющихся платежей для каждой записи, предоставленной в запросе, и назначает каждому из них новый recurring-payment-id. Повторяющиеся транзакции будут обрабатываться в соответствии с созданными профилями повторяющихся платежей с использованием платежных данных, сохраненных в каждом профиле.
Создание повторяющихся платежей Multiple инициируется через запрос HTTPS POST с использованием URLs и parameters, указанных ниже. Используйте OAuth RSA-SHA256 для аутентификации.

API URLs

Интеграционная среда

Производственная среда

https://sandbox.payneteasy.com/paynet/api/v4/create-recurring-payments/ENDPOINTID

https://gate.payneteasy.com/paynet/api/v4/create-recurring-payments/ENDPOINTID

Параметры Запроса

Note

Запрос должен иметь content-type=application/x-www-form-urlencoded и Заголовки авторизации.
Ниже приведено описание каждого параметра, который можно включить в CSV и добавить к параметру payload, который будет использоваться в запросе.
Подробную информацию о профиле повторяющихся платежей можно просмотреть только через пользовательский интерфейс.

Имя параметра CSV

Описание

Значение

rp_card_type

SRC — Исходная карта отправителя. DST — Карта назначения получателя.
Необходимость: Обязательно
Тип: Enum
Длина: 3

client-orderid

Идентификатор заказа Присоединяющейся стороны. Поддерживается для типов SRC и DST.
Необходимость: Обязательно
Тип: String
Длина: 128

credit-card-number

Номер кредитной карты плательщика. Поддерживается для типа SRC и DST.
Необходимость: Обязательно
Тип: Numeric
Длина: 19

cvv2

Код CVV2 плательщика. CVV2 (Card Verification Значение) — это трех- или четырехзначное число, напечатанное на обратной стороне карты в области подписи.
Необходимость: Опционально
Тип: Numeric
Длина: 3-4

card-printed-name

Напечатанное имя плательщика на карте. Обязательно для SRC, необязательно для DST.
Необходимость: Условно
Тип: String
Длина: 128

expire-year

Срок истечения года карты плательщика. Обязательно для SRC, необязательно для DST.
Необходимость: Условно
Тип: Numeric
Длина: 4

expire-month

Срок истечения месяца карты плательщика. Обязательно для SRC, необязательно для DST.
Необходимость: Условно
Тип: Numeric
Длина: 2

amount

Сумма валюты должна совпадать с валютой назначенного проекта. По достижении даты окончания, регулярный платеж перейдет в статус - остановлен. Поддерживается для типов SRC и DST. Требуется, если не используются amount-from и amount-to или amount-sequence.
Необходимость: Условно
Тип: Numeric
Длина: 10

currency

Тип валюты. Поддерживается для типа SRC и DST.
Необходимость: Обязательно
Тип: String
Длина: 3

country

Страна плательщика. Не поддерживается для DST.
Необходимость: Обязательно
Тип: String
Длина: 2

city

Город плательщика. Не поддерживается для DST.
Необходимость: Обязательно
Тип: String
Длина: 128

zip-code

Почтовый индекс плательщика. Не поддерживается для DST.
Необходимость: Обязательно
Тип: String
Длина: 10

address1

Адрес плательщика. Не поддерживается для DST.
Необходимость: Обязательно
Тип: String
Длина: 256

first-name

Имя плательщика. Не поддерживается для DST.
Необходимость: Обязательно
Тип: String
Длина: 128

last-name

Фамилия плательщика. Не поддерживается для DST.
Необходимость: Обязательно
Тип: String
Длина: 128

email

Электронная почта плательщика. Не поддерживается для DST.
Необходимость: Обязательно
Тип: String
Длина: 128

amount-from

Если выбрана комбинация amount-from и amount-to, каждая плата будет иметь случайную сумму между этими двумя числами. Поддерживается для типов SRC и DST. Требуется, если amount или amount-sequence не используются.
Необходимость: Условно
Тип: Numeric
Длина: 10

amount-to

Если выбрана комбинация amount-from и amount-to, каждая плата будет иметь случайную сумму между этими двумя числами. Поддерживается для типов SRC и DST. Требуется, если amount или amount-sequence не используются.
Необходимость: Условно
Тип: Numeric
Длина: 10

amount-sequence

Если выбрана последовательность сумм, с клиента будет списана сумма из этого списка. Пример настройки последовательности сумм: 10.5, 24.6, 32.0. Если количество повторов больше количества элементов в последовательности сумм, каждое новое списание будет с последней суммы в последовательности сумм. Для того чтобы списание начиналось с первой суммы в цепочке, текущее количество повторов должно быть установлено как 0. Поддерживается для типов SRC и DST. Требуется, если amount-from и amount-to или amount не используются.
Необходимость: Условно
Тип: Numeric
Длина: 10

period

Возможные значения: ежедневно, еженедельно и ежемесячно. В случае, если выбрано ежедневно, клиент будет платить каждый день. Если выбрано еженедельно - каждые 7 дней. Если выбрано ежемесячно, клиент будет платить в тот же день месяца, с начальной даты, независимо от того, сколько дней в месяце. Interval и period можно указывать или опускать только вместе. Не поддерживается для DST.
Необходимость: Условно
Тип: String
Длина: 32

interval

Interval — это множитель, применяемый к периоду. Например, если интервал равен 2, а период выбран как «Ежедневно», клиент будет платить раз в 2 дня. Interval и period можно указывать или опускать только вместе. Не поддерживается для DST.
Необходимость: Условно
Тип: Int
Length: -

order_desc

Описание периодического платежа. Поддерживается для типа SRC и DST.
Необходимость: Опционально
Тип: String
Длина: 65K

customer-ip

IP-адрес плательщика. Поддерживается для типа SRC и DST.
Необходимость: Опционально
Тип: String
Длина: 45

ssn

Поле номера социального страхования. Не поддерживается для DST.
Необходимость: Опционально
Тип: String
Длина: 32

birthday

Дата рождения плательщика. Не поддерживается для DST.
Необходимость: Опционально
Тип: 8/Numeric, DD.MM.YYYY
Длина: 8

phone

Номер телефона плательщика. Не поддерживается для DST.
Необходимость: Опционально
Тип: String
Длина: 128

state

Штат плательщика. Пожалуйста, см. Обязательные коды штатов для списка допустимых кодов штатов. Требуется для США, Канады и Австралии. Не поддерживается для DST.
Необходимость: Опционально
Тип: String
Длина: 2-3

start-date

Дата, когда запланировано первое списание. Если дата начала установлена как текущая дата и тип установлен как авто, первое списание будет произведено в этот же день. Поддерживается для типов SRC и DST.
Необходимость: Опционально
Тип: 8/Numeric, DD.MM.YYYY
Длина: 8

finish-date

Дата, когда с плательщика будет взиматься плата в последний раз. Поддерживается для типов SRC и DST.
Необходимость: Опционально
Тип: 8/Numeric, DD.MM.YYYY
Длина: 8

max-repeats-number

Индекс повторяющейся транзакции, первый платеж будет иметь индекс 0. Текущее число повторов увеличивается, даже если платеж был неудачным. Когда текущее число повторов достигает максимального числа повторов, повторяющийся платеж переходит в статус остановки, и клиент больше не платит. Если платеж был произведен автоматически, никаких дополнительных платежей взиматься не будет (если это не сделано вручную), даже если повторяющийся платеж остановлен и перенесен снова. Поддерживается для типов SRC и DST.
Необходимость: Опционально
Тип: Int
Length: -

purpose

Цель транзакции. Не поддерживается для DST.
Необходимость: Опционально
Тип: String
Длина: 128

notify_url

Поле Notify url. Также можно использовать параметр server_callback_url. Для получения дополнительной информации см. Обратный вызов Присоединяющейся Стороны. Поддерживается для типов SRC и DST.
Необходимость: Опционально
Тип: String
Длина: 1024

server_callback_url

URL-адрес Присоединяющейся Стороны, который получит запрос обратного вызова, как только транзакция достигнет окончательного статуса. сервера Присоединяющаяся сторона может использовать URL-адрес обратного вызова для индивидуальной обработки завершения транзакции, например, для сбора данных о платежах в информационной системе Присоединяющейся Стороны. Подробности обратного вызова см. в Параметры обратного вызова Присоединяющейся Стороны. Отправьте либо notify_url, либо server_callback_url, но не оба.
Необходимость: Опционально
Тип: String
Длина: 128

Note

Если повторное списание переключилось на Stopped, вы можете обновить его расписание с помощью параметров start-date и finish-date. Однако его можно возобновить только через пользовательский интерфейс, нажав на Resume.
Введите native в пользовательском интерфейсе, чтобы настройка повторяющихся платежей и фактические списания производились в одном и том же банке-эквайере.
Чтобы создать профиль повторяющегося платежа с автоматическим повторяющимся графиком, отправьте параметры interval и period. Чтобы создать профиль повторяющегося платежа без автоматического повторяющегося графика, не отправляйте параметры interval и period. Чтобы остановить автоматический повторяющийся график, используйте /api/v4/update-recurring-payments. Доступно только для SRC.

Параметры ответа

Note

Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля кодируются как x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра.

Параметры ответа

Описание

type

Тип ответа. Может быть create-recurring-payment-response, validation-error, error. Если тип равен validation-error или error, параметры error-message и error-code содержат сведения об ошибке. Может быть получено несколько кодов ошибок: 200, 403 и 500. Для кода ошибки 500 будет возвращен дополнительный идентификатор ошибки.

recurring-payment-id

Повторяющийся идентификатор, присвоенный заказу Payneteasy.

status

Подробности смотрите в Список статусов.

serial-number

Уникальный номер, присваиваемый сервером Payneteasy конкретному запросу от Присоединяющейся стороны.

Пример запроса

Шаг 1. Создайте CSV-файл с предоставленной структурой:
"client-orderid";"rp_card_type";"payment-description";"first-name";"last-name";"address1";"city";"zip-code";
"country";"state";"phone";"email";"customer-ip";"period";"interval";"start-date";"finish-date";"max-repeats-number";"amount";
"amount-from";"amount-to";"amount-sequence";"currency";"card-printed-name";"credit-card-number";"expire-month";"expire-year"
Шаг 2. Кодируйте CSV в base64 с помощью следующей команды:
base64 create-recurring-payments-example.csv
Шаг 3. Присвойте закодированное значение base64 параметру payload и отправьте запрос:
POST /paynet/api/v4/create-recurring-payments/ HTTP/1.1
Host: sandbox.payneteasy.com
User-Agent: curl/8.4.0
Accept: */*
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant",oauth_signature_method="RSA-SHA256",oauth_timestamp="1727178538",oauth_nonce="cdtNANOCATq",oauth_version="1.0",oauth_signature="B5m%2FOQOSBgqWI%2F%2FG3GhZw2kCJZDda7J6fLpOu6wFyBEj60PJp5u1mqBnIufzkkmrSkyZkCT6v12WIhwE%2BWTtJ7Wg%2BRx9cqXPfhk5JhQpnofsVheXpCpftoLvvBTqn8p67WaS%2B6kfzGtGhdXHYVBzIxXDxabnMjMC8u8EtfWsovzTp%2BAYfZKn2H0qH7B62dfUW4PuRCTmy9svbwLhbPULkh3oJ3a1M%2BnRqXIasIrd3WY1MD9lkqUetAtW3xIWnOoMvPZ0wzk2UEbU%2BoZ2KTiA9KO09%2Ffq7OylRhiDpqtz65EMBiKujFFSF42bzYsB1SmPssk09xJoWmsNR9tFZsdx2Hgl7yFZTXhxV3nlSZTGDVZaVe2pPSi8va5W9yTlPMPU5HcNE5MuZ3T9PSEURQvM691UcPSdlJAi8q7B0EhXDzwOlgLV7DsFDtpsXSeXopFpG6uHiNPIjW65p6XFQ31xr4foZCahVeymuIoiXE6uAkHJJ89oHqKsOBnI7xILu2UpflHnl7gn%2BvX9IWdUHx1xEMdBPWdUQRFNllGvT2N8nYrtZe96L%2BfwxarYR2Fh1LtyqwCtEXhQm5jhjpR3NQpqddY3NSd75NUP7zlDQwXCknMQps6uSdng9Uv%2B7IFx3oNUfjVMxp4CGcmEtSxH7Ykx8dX5srNOKLDJT5tyExLLjXk%3D"
Content-Length: 754
Connection: keep-alive

payload=Y2xpZW50LW9yZGVyaWQ7cnBfY2FyZF90eXBlO29yZGVyX2Rlc2M7Zmlyc3QtbmFtZTtsYXN0LW5hbWU7YWRkcmVzczE7Y2l0eTt6aXAtY29kZTtjb3VudHJ5O3N0YXRlO3Bob25lO2VtYWlsO3BlcmlvZDtpbnRlcnZhbDtzdGFydC1kYXRlO2ZpbmlzaC1kYXRlO21heC1yZXBlYXRzLW51bWJlcjthbW91bnQ7YW1vdW50LWZyb207YW1vdW50LXRvO2Ftb3VudC1zZXF1ZW5jZTtjdXJyZW5jeTtjYXJkLXByaW50ZWQtbmFtZTtjcmVkaXQtY2FyZC1udW1iZXI7ZXhwaXJlLW1vbnRoO2V4cGlyZS15ZWFyO2N2djI7cHVycG9zZTtub3RpZnktdXJsO3NzbjtiaXJ0aGRheQ0KMTIzNDU2Nzg5MDtTUkM7O1dpbGw7U3RpbGw7MTIzNCBSZWluO1JlaW1zOzEyMzQ1NjtGUjtCUkU7MTIzNDU2Nzg7d2lsbHN0aWxsQGV4YW1wbGUuY29tO3dlZWs7MTsxNi4wOS4yMDI0OzE3LjA5LjIwMjQ7MTAwMDsxMDs7OztVU0Q7V0lMTCBTVElMTDs0NDU4MjA0NjgxMzg3MDUzOzEyOzIwNDA7MTIzO05vIHB1cnBvc2UgYXQgYWxsO2h0dHA6Ly9leGFtcGxlLmNvbS9jcmVhdGUtbWU7MTIzNDsyMi4wMS4xOTgwDQo%3D

Пример успешного ответа

Note

Успешный ответ имеет пустое тело и HTTP-код 200.
HTTP/1.1 200
Server: server
Date: Tue, 24 Sep 2024 09:44:01 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000

Пример неуспешного ответа

Note

Неуспешный ответ имеет пустое тело и HTTP-код 403.
HTTP/1.1 403
Server: server
Date: Wed, 25 Sep 2024 08:45:42 GMT
Content-Length: 0
Connection: keep-alive
Keep-Alive: timeout=60
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000