3.30. /api/v4/update-recurring-payments

Введение

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

API URL

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

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

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

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

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

Note

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

Название параметра CSV

Описание

Значение

client-orderid

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

recurring-payment-id

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

credit-card-number

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

card-printed-name

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

expire-year

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

expire-month

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

amount

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

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
Длина: -

country

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

city

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

address1

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

first-name

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

last-name

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

customer-ip

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

order_desc

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

zip-code

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

birthday

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

email

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

ssn

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

phone

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

state

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

start-date

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

finish-date

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

max-repeats-number

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

purpose

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

notify_url

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

server_callback_url

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

Note

Экран сведений о RPI (профиль повторяющегося платежа) содержит информацию о связанных данных держателя карты и клиента, повторяющемся графике и обработанных транзакциях с этим RPI. Этот экран также содержит историю изменений для этого RPI. История изменений в настоящее время доступна только для исходных карт (SRC).
Введите native в пользовательском интерфейсе, чтобы настройка повторяющихся платежей и фактические списания производились в одном и том же банке-эквайере.
Если повторное списание переключилось на Stopped, вы можете обновить его расписание с помощью параметров start-date и finish-date. Однако его можно возобновить только через пользовательский интерфейс, нажав на Resume.
Чтобы остановить автоматическое повторяющееся расписание, используйте параметр :ex:finish-date с прошлой датой в разделе :ref:Параметры запроса<api_v4_update-recurring-payments_request_parameters>.

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

Note

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

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

Описание

type

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

status

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

serial-number

Уникальный номер, присваиваемый сервером Payneteasy конкретному запросу от Торговца

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

Шаг 1. Создайте CSV-файл с предоставленной структурой:
"client-orderid";"recurring-payment-id";"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 update-recurring-payments-example.csv
Шаг 3. Присвойте закодированное значение base64 параметру payload и отправьте запрос:
POST /paynet/api/v4/update-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="1727177782",oauth_nonce="Js4dwXkF8eI",oauth_version="1.0",oauth_signature="VwdA7BQ68v%2BmpB0N%2BUOxK%2BxYk355i1QzeUPGGGFwDEBn7Y8v1xpSolGQ45HehGmJHNjXHc7A1mP3x7V7r2pQju1LpDEvAb2MHNLSCHiCEjI95sCtrotE%2Fs5%2FmQmIJ8te%2FGFCR1uK%2BzMPG8bpHqn%2B5EIEsuLPq6TSOjD0N3RvnV%2BHdmjH5cxTcmtRrcY0u6VIpvkBUlqpKuTVJXLvbpxRexvgPMDow78QS3DLRQhi6G7Y%2FVshKpKC%2FSRThhe8L33tFckX6KaEbJ3XIMEmP7O%2F%2FQdLfWQBn4ldSp8K8lpkgZks4CZbAjDY%2BQpSfwdc1s8kJf17Ymk1R69aGBmjzJrw00tV4dzY4DE6XVqSTUR8X%2FCa0XMrtD46ichsFoRvFtIeyV%2FIud%2F%2FLSb8XDqk%2BaftSLazBokmT8Qe1FMf0UMgUYBLCl0B4O66Ys8kH4Z6guC2MXarwu%2BDlfuelrcAHevS68hewrMb%2FjppSJWAbQiBOABeW6s1Rb4dvbJnZribkKhEwrxmnT5drsTYvukC2UCoUblEOgVkFHdHk5E3OqT4wMxqXojlYr5Il7m1GkHVYELb964ukROLkohGoTjYEKj%2FUHirjybDWeynTCSaGe%2Bv3JtEbkydWXannkdtTvk0xkbT6LurBiNWy1FuSTmKod9ibqyNiEv6j%2Be14BBGXs3xc5A%3D"
Content-Length: 888
Connection: keep-alive

payload=cmVjdXJyaW5nLXBheW1lbnQtaWQ7dHlwZTtjbGllbnQtb3JkZXJpZDtwYXltZW50LWRlc2NyaXB0aW9uO2ZpcnN0LW5hbWU7bGFzdC1uYW1lO2FkZHJlc3MxO2NpdHk7emlwLWNvZGU7Y291bnRyeTtzdGF0ZTtwaG9uZTtlbWFpbDtjdXN0b21lci1pcDtwZXJpb2Q7aW50ZXJ2YWw7c3RhcnQtZGF0ZTtmaW5pc2gtZGF0ZTtjdXJyZW50LXJlcGVhdHMtbnVtYmVyO21heC1yZXBlYXRzLW51bWJlcjthbW91bnQ7YW1vdW50LWZyb207YW1vdW50LXRvO2Ftb3VudC1zZXF1ZW5jZTtjdXJyZW5jeTtjYXJkLXByaW50ZWQtbmFtZTtjcmVkaXQtY2FyZC1udW1iZXI7ZXhwaXJlLW1vbnRoO2V4cGlyZS15ZWFyO2N2djI7cHVycG9zZTtub3RpZnktdXJsO3NzbjtiaXJ0aGRheQ0KMTQ5MjI4NjttYW51YWw7MTIzNDU2Nzg5MDtPdXIgc3VwZXIgZ29vZHM7Sm9objtTbWl0aDsxMjM0IFBlYWNlIHN0cmVldDtDaGljYWdvOzEyMzQ1NjtVUztJTDsxMjM0NTY3ODtqb2huLnNtaXRoQGV4YW1wbGUuY29tOzEuMi4zLjQ7d2VlazsxOzAxLjAxLjIwMzA7MDEuMDEuMjA0MDswOzEwMDA7MTA7Ozs7VVNEO0pPSE4gU01JVEg7NDUzODA5NjQxNTA4NDc1NjsxMjsyMDIwOzEyMztObyBwdXJwb3NlIGF0IGFsbDtodHRwOi8vZXhhbXBsZS5jb20vbm90aWZ5LW1lOzEyMzQ7MDIuMDEuMTk4MA0K

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

Note

Успешный ответ имеет пустое тело и HTTP-код 200.
HTTP/1.1 200
Server: server
Date: Tue, 24 Sep 2024 11:40:45 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

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

Note

Неудачный ответ имеет пустое тело и HTTP-код 403.
HTTP/1.1 403
Server: server
Date: Wed, 25 Sep 2024 08:47:54 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