Перейти к основному содержимому

Рекуррентные платежи

Рекуррентный платеж — это повторное списание денег с карты пользователя. Такие платежи бывают двух типов в зависимости от участия пользователя и проверки 3DS:

  • Без участия пользователя, по токену. Такие платежи называются Merchant Initialized Transaction (MIT).
  • С идентификацией пользователя через 3DS. Такие платежи называются Customer Initialized Transaction (CIT).

Сейчас проводить рекуррентные платежи можно только банковской картой, позже появятся другие способы.

Рекуррентные платежи MIT​

MIT — это платежи, которые вы инициируете без участия пользователя, используя ранее полученный токен карты. Пользователь не подтверждает каждый платеж, а только видит списание.

Основные шаги

  1. Получить согласие пользователя на безакцептные списания.
  2. Провести первый успешный платеж и получить токен.
  3. Выполнять следующие платежи по этому токену.

Согласие пользователя​

Рекуррентные платежи происходят автоматически, без участия пользователя. Вы несете полную ответственность за сумму, периодичность и за то, что пользователь действительно согласился на такие списания. Согласие потребуется в спорных ситуациях, например, если пользователь заявит, что не разрешал списывать деньги.

Как получить согласие

Любым способом, который позволит вам подтвердить факт согласия в спорной ситуации. Главное, чтобы пользователь узнал о последующих списаниях.

  1. Опишите условия подключения автоплатежей так, чтобы пользователь их точно прочел.
  2. Добавьте чекбокс с понятной подписью, например, Сохранить карту, Подключить автоплатеж, Подписаться на пожертвования и т.п.

Если пользователь отмечает чекбокс — автоплатеж включается, если нет — не включается.

Где разместить чекбокс:

  • На вашей стороне — вы сами решаете, как он выглядит и где находится.
  • В платежном виджете Zetplat — готовая опция, которую можно показать пользователю.

Токен для рекуррентных платежей​

Токен — это безопасный заменитель данных карты. Чтобы его получить, нужно провести первый успешный платеж с указанием сохранить данные карты. В ответ на такой платеж вернется токен. Полученный токен можно сохранить и использовать для:

  • последующих рекуррентных платежей,
  • выплат на ту же карту.

Способы получить токен

  • Через API (с чекбоксом на своей стороне). При создании платежной сессии или в любом запросе на проведение платежа передайте параметр allow_recurring=true (в объекте payment_settings). Если платеж успешен, в ответе вернется токен. При этом согласие пользователя вы должны получить заранее, например, через свой чекбокс.

  • Через платежный виджет Zetplat. В виджете можно включить отображение чекбокса с текстом Соглашаюсь на автоплатежи. Если пользователь отметит его и платеж пройдет успешно, токен будет возвращен автоматически.

Статусы токена

Статус (token_active)Значение
trueТокен активен, по нему можно проводить платежи
falseТокен неактивен, платеж не пройдет (вернется ошибка)

Чтобы проверить статус токена, отправьте запрос token/state. В поле type передайте значение recurring_token, в поле recurring_token.token — токен, статус которого нужно узнать.

В ответ придет token_info дата окончания действия токена (completed_date) и его статус (token_active). Дата окончания действия токена completed_date никак не проверяется на стороне Zetplat — токен останется активным и после даты, указанной в этом параметре.

Важно помнить, что активный токен не гарантирует успешное прохождения платежа, отказ может быть получен от банка-эмитента карты.

Как отключить токен

Если токен больше не нужен (например, пользователь отключил автоплатеж), отправьте запрос recurrent/disable.

В ответ придет recurring_token_info. Если статус token_active: false, значит, токен отключен, по нему больше нельзя проводить платежи.

После отключения в параметре completed_date может появиться дата, относящаяся к 2000 году. Это техническое значение, на которое можно не обращать внимания.

Как сделать рекуррентный платеж MIT​

1. Проведите успешный платеж с указанием создать токен​

Как провести платеж без виджета

При создании платежной сессии или в запросе на создание платежа в payment_settings передайте в поле allow_recurring значение true.

Пример
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/init/checkout \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "payment_info": {
      "type": "card_info",
      "card_info": {
        "type": "card_details",
        "card_details": {
          "card_number": "4242424242424242",
          "card_exp_month": "01",
          "card_exp_year": "22",
          "card_code": "087"
        }
      }
    },
    "sum_info": {
      "sum": 10000,
      "currency_code": "rub"
    },
    "user_info": {
      "user_id": "lucky"
    },
    "payment_settings": {
      "allow_recurring": true
    }
  }'

2. Сохраните токен после успешного платежа​

Если платеж пройдет успешно и при оплате через платежную форму пользователь согласится на рекуррентные списания, в вебхуке checkout_results вернется токен.

Пример
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "checkout_results",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "completed",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payments": [{
        "id": "pm_2705",
        "transaction_status": "successful",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "completed_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id":"lucky"
        },
        "payment_info": {
          "type": "card_info",
          "card_info": {
            "card_network": "visa",
            "card_last4": "4242"
          }
        },
        "recurring_token_info": {
          "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1",
          "created_date": "2020-07-14T13:17:11+03:00",
          "completed_date": "2020-07-31T16:05:42+03:00",
          "token_active": true,
          "type": "recurring_token"
          },
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        },
        "payment_settings": {
          "allow_recurring": true
        }
      }]
    }
  }'

3. Проводите платежи с использованием токена​

Отправьте запрос на проведение платежа с типом оплаты recurring_token_info. Вместо данных банковской карты передайте токен, который вы сохранили при предыдущем платеже.

Пример
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/init/checkout \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "payment_info": {
      "type": "recurring_token_info",
      "recurring_token_info": {
        "token": "e9876f32bcd947f79c324cf2da5726304a894f6ae2037de7705fdb3e0a134d39"
      }
    },
    "sum_info": {
      "sum": 10000,
      "currency_code": "rub"
    },
    "user_info": {
      "user_id": "lucky"
    }
  }'

Как сделать рекуррентный платеж CIT​

Рекуррентный платеж CIT (Customer Initialized Transaction) — это возможность проводить оплату по токену с верификацией плательщика через 3DS. Для гарантии успешной оплаты платежей CIT мы рекомендуем использовать идентификатор проекта, предназначенный для платежей с 3DS.

1. Создайте платежную сессию​

Отправьте запрос на создание сессии transaction/init/checkout. В запросе передайте значение payment_info.recurrent.initiated_by:client и URL для возврата плательщика после прохождения верификации 3DS в параметре back_url.

Пример
 curl -X POST \
   https://proxy-demo.zetplat.com/api/v1/transaction/init/checkout \
   -H 'Content-Type: application/json' \
   -H 'X-Project-Id: your_project_name' \
   -H 'X-Signature: signature' \
   -d '{
     "payment_info": {
       "type": "recurring_token_info",
       "recurring_token_info": {
         "token": "token_value",
         "initiated_by": "client"
       }
     },
     "sum_info": {
       "sum": 10000,
       "currency_code": "rub"
     },
     "user_info": {
       "user_id": "lucky"
     },
     "payment_settings": {
       "back_url": "https://zetplat.com"
     }
   }'

2. Получите данные для редиректа​

Получите от Zetplat вебхук action_pending с данными для редиректа на страницу прохождения 3DS.

Пример
 curl -X POST \
   https://partner.ru \
   -H 'Content-Type: application/json' \
   -H 'X-Signature: signature' \
   -d '{
     "type": "action_pending",
     "session_info": {
       "id": "ps_3230",
       "transaction_status": "active",
       "created_date": "2024-05-27T02:03:00.000000Z",
       "updated_at": "2024-05-27T02:03:00.000000Z",
       "payments": [{
         "id": "pm_2705",
         "transaction_status": "pending",
         "created_date": "2024-05-27T02:03:00.000000Z",
         "user_info": {
           "user_id":"user@152.ru"
         },
         "payment_info": {
           "type": "card_info",
           "card_info": {
             "card_network": "visa",
             "card_last4": "4242"
           }
         },
         "sum_info": {
           "sum": 10000,
           "currency_code": "rub"
         },
         "fee_info": {
           "fee": {
             "merchant_fee": {
               "sum": 10,
               "currency_code": "RUB"
             }
           }
         },
         "user_action": {
           "type": "destination_info",
           "destination_info": {
             "url_address": "https://proxy.zetplat.com?foo=bar",
             "domain": "https://proxy.zetplat.com",
             "http_method": "GET",
             "additional_params": {
               "foo": "bar"
             },
             "extra_params": {
               "paReq": "sdfew^//asdhbv",
               "MD": "abc75daefnn"
             }
           }
         }
       }]
     }
   }'

3. Перенаправьте пользователя на 3DS​

Получите из ответа Zetplat:

  • user_action.destination_info.url — адрес для перенаправления,
  • user_action.destination_info.method — метод запроса (GET или POST).

Выполните перенаправление указанным методом.

После прохождения 3DS пользователь вернется на ваш back_url. Метод вызова back_url также может быть GET или POST. Если это POST, а ваш обработчик ожидает GET, настройте преобразование (редирект) из POST в GET.

4. Дождитесь результата платежа​

Zetplat отправит вам вебхук checkout_results. Статус successful означает успешный платеж.

Пример
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "checkout_results",
    "session_info": {
      "id": "ps_3230",
      "transaction_status": "completed",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "updated_at": "2024-05-27T02:03:00.000000Z",
      "payments": [{
        "id": "pm_2705",
        "transaction_status": "successful",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "completed_date": "2024-05-27T02:03:00.000000Z",
        "user_info": {
          "user_id":"lucky"
        },
        "payment_info": {
           "type": "card_info",
           "card_info": {
             "card_network": "visa",
             "card_last4": "4242"
           }
        },
        "recurring_token_info": {
          "token": "feda2b2106a2e8747bbdc4c9f53c7f5f6ab845ffa1b7cc68ca839720af99b3d1",
          "created_date": "2020-07-14T13:17:11+03:00",
          "completed_date": "2020-07-31T16:05:42+03:00",
          "token_active": true,
          "type": "recurring_token"
          },
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        }
      }]
    }
  }'

Подробнее о статусах платежа
Описание кодов ошибок и их значений

Схема рекуррентного платежа CIT​