Инструкция по интеграции API

Содержание:

Общие сведения

  1. Настройка учетной записи Получателя в Paytodo
    1. Регистрация Получателя в Paytodo
    2. Выбор способа вывода средств в Личном кабинете
    3. Создание проекта Получателя
  2. Интеграция API
    1. Формирование платежной формы
    2. Защита платежной формы
    3. Отмена сделки
    4. Массовое завершение сделок
    5. Завершение сделки
    6. Проверка статуса оплаты сделки
    7. Схема Сделка

Общие сведения

В инструкции используются следующие понятия:

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

Получатель – Пользователь, имеющий намерение принять Перевод в свою пользу посредством направления Электронного запроса. Физическое лицо, в пользу которого перечисляются денежные средства при совершении сделки.

Плательщик – Пользователь, имеющий намерение осуществить Перевод в пользу Получателя посредством направления Электронного запроса.

Интеграцию с Paytodo можно осуществить двумя способами.

Интеграция с платежной системой Paytodo через модули для CMS, если сайт Получателя сделан на платформе:

  • Wordpress WooCommerce
  • Webasyst Shop-script7
  • 1-С Битрикс
  • OpenCart
  • InSales

Для интеграции с Paytodo через модули CMS должны быть выполнены следующие шаги на сайте Paytodo:

  1. Необходимо пройти регистрацию на сайте Paytodo и получить учетную запись Получателя (раздел 1.1)
  2. В Личном кабинете необходимо выбрать способ вывода денежных средств при завершении сделки и указать реквизиты. Если вывод средств будет осуществляться на карту, то указать номер карты (раздел 1.2)
  3. Затем в Личном кабинете необходимо создать проект и указать URL вашего сайта, на которые будут перенаправлены Плательщики при удачной оплате, неудачной оплате, для callback. На этом же шаге необходимо будет ввести секретный код для генерации кода подтверждения (раздел 1.3)
  4. В Личном кабинете необходимо перейти в раздел «Модули для CMS», выбрать модуль для подключения к платежной системе Paytodo и скачать его плагин. При установке плагина в настройках следует указать введенные ранее при создании проекта в Paytodo URL и код подтверждения

Интеграция с платежной системой Paytodo через API включает следующие шаги:

  1. Необходимо пройти регистрацию на сайте Paytodo и получить учетную запись Получателя (раздел 1.1)
  2. В Личном кабинете необходимо выбрать способ вывода денежных средств при завершении сделки и указать реквизиты. Если вывод средств будет осуществляться на карту, то указать номер карты (раздел 1.2)
  3. Затем в Личном кабинете необходимо создать проект и указать URL вашего сайта, на которые будут перенаправлены Плательщики при удачной оплате, неудачной оплате, для callback. На этом же шаге необходимо будет ввести секретный код для генерации кода подтверждения (ключа API) (раздел 1.3). Ключ API будет передаваться в заголовках запросов
  4. Далее, используя API методы, можно подключить прием платежей на своем сайте (раздел 2)

 

1. Настройка учетной записи Получателя в Paytodo

1.1 Регистрация Получателя в Paytodo
  1. Открыть сайт paytodo.ru
  2. Нажать кнопку «Создать аккаунт»
  3. Ввести e-mail на форме создания аккаунта (Рисунок 1). На указанный адрес будет отправлено письмо с паролем.

     

    Рисунок 1

  4. На форме входа ввести e-mail и высланный пароль. Вы войдете в Личный кабинет

 

1.2 Выбор способа вывода средств в Личном кабинете
  1. В Личном кабинете открыть раздел «Способы вывода» и нажать «Добавить способ» (Рисунок 2).

     

    Рисунок 2

  2. Выбрать способ вывода средств из доступных, указать свои реквизиты и нажать «Вперед» (Рисунок 3).

     

    Рисунок 3

     

    Вывод средств возможен на:

     

    • карты, выпущенные в РФ
    • кошелек Киви
    • кошелек Яндекс
    • МТС
    • Билайн
    • Мегафон
    • Теле2

    Можно выбрать несколько способов получения средств, указав один основной (Рисунок 4). При завершении сделки вывод средств будет осуществляться основным способом.

    Рисунок 4

 

1.3 Создание проекта Получателя
  1. Открыть раздел «API» и нажать «Создать проект» (Рисунок 5)

     

    Рисунок 5

  2. Указать:

     

    • название проекта (URL вашего сайта), которое будет отображаться при оплате вашим Плательщикам
    • ссылки на страницы, на которые будут перенаправлены Плательщики при удачной оплате (URL удачной оплаты), неудачной оплате (URL неудачной оплаты)
    • ссылку на страницу для получения статусов по Сделкам (URL для callback) (Рисунок 6)

       

      Рисунок 6

  3. Здесь же указать секретный код для генерации ключа API, используемого для авторизации каждого запроса. Можно оставить предложенный секретный код. Нажать «Создать»
  4. Название проекта и сгенерированный API ключ будут показаны в разделе «API» (Рисунок 7).

     

    Рисунок 7

 

2 Интеграция API

2.1 Формирование платежной формы

Страница оплаты на сайте Получателя должна содержать платежную форму с параметрами сделки. Платежная форма содержит идентификатор сделки на стороне сайта Получателя, описание сделки, сумма сделки, API ключ.

POST-запрос – Создание сделки:

Название

Тип

Описание

Пример

order_id

string

Идентификатор сделки на стороне Получателя

my-id-1223

order_desc

string

Описание сделки

order_amount

number

Сумма сделки

100

signature

string

Подпись запроса

5e8b1509996af2e0903153f41fe37802fa71de86

 

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

Название

Описание

Тип

Тип данных

X-API-KEY

Ключ API

header

string

Accept

header

string

 

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

Ответ

Свойства

200 OK
Status 200

Схема

400 Bad Request
Status 400

error: string
API_KEY_EMPTY Ключ не передан
API_KEY_ERROR Ключ не существует либо просрочен.
INVALID_SIGNATURE Подпись не верна
Пример: API_KEY_EMPTY

 

2.2 Защита платежной формы

Параметры сделки передаются в Paytodo через веб-браузер, поэтому чтобы предотвратить изменение параметров сделки на стороне Плательщика, Получателю необходимо подписать параметры платежной формы.

Для этого Получателю необходимо добавить в платежную форму параметр signature, сформированный с использованием секретного ключа, полученного при создании проекта в Личном кабинете (раздел 1.3).

Запрос должен содержать параметр signature, который формируется путем объединения значений всех остальных параметров формы в алфавитном порядке их имен (без учета регистра) с добавлением в конец «секретного ключа» Получателя из Личного кабинета. Полученное после объединения параметров и «секретного ключа» значение, представленное в кодировке UTF-8, хешируется функцией md5 (hex-представление)

signature = md5(utf(sort_params(params) + secret_key)))

Ключ API передается в заголовках запроса: X-API-KEY

Callback будет отсылаться на «URL для callback», указанные в интерфейсе. Редирект Плательщика осуществляется на указанные «URL удачной оплаты» / «URL неудачной оплаты», указанных при добавлении API-ключа, либо отправленные через API-запрос из формы.

Ошибки ответа:

Код ошибки

Описание

API_KEY_EMPTY

Ключ не передан

API_KEY_ERROR

Ключ не существует либо просрочен

INVALID_SIGNATURE

Подпись не верна

 

Пример класса для работы с API на PHP

 

2.3 Отмена сделки

В случае отмены сделки Получателем выполняется PUT-запрос. Запрос должен содержать параметр signature.

PUT-запрос – Отмена сделки

Название

Тип

Описание

Пример

signature

string

Подпись запроса

5e8b1509996af2e0903153f41fe37802fa71de86

 

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

Название

Описание

Тип

Тип данных

object_id

Хэш сделки

path

string

 

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

Ответ

Свойства

200 OK
Status 200

Схема

 

2.4 Массовое завершение сделок

Завершает все сделки Получателя и перечисляет единой суммой средства на выбранный Основным способ вывода.

PUT-запрос Массовое завершение сделок

Название

Тип

Описание

Пример

signature

string

Подпись запроса

5e8b1509996af2e0903153f41fe37802fa71de86

deals

string[]

 

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

Ответ

Свойства

200 OK
Status 200

Схема

 

2.5 Завершение сделки

Завершает выбранную сделку и перечисляет средства на выбранный Основным способ вывода.

PUT-запрос Завершение сделки

Название

Тип

Описание

Пример

signature

string

Подпись запроса

5e8b1509996af2e0903153f41fe37802fa71de86

 

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

Название

Описание

Тип

Тип данных

object_id

Хэш сделки

path

string

 

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

Ответ

Свойства

200 OK
Status 200

Схема

 

2.6 Проверка статуса оплаты сделки

GET- запрос для проверки статуса Сделки.

Параметры GET-запроса - Проверка статуса сделки

Название

Описание

Тип

Тип данных

object_id

Хэш сделки

path

string

 

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

Ответ

Свойства

200 OK
Status 200

Схема

 

2.7 Схема Сделка

Название

Тип

Описание

Пример

create_date

string (date-time)

Дата создания

2018-07-30T09:44:40.847Z

order_id

string

Идентификатор сделки на стороне Получателя

my-id-1223

update_date

string (date-time)

Дата обновления

2018-07-30T09:44:40.847Z

object_id

string

Хэш сделки

247cf4eeb528d9c7ab8c0ef818e72bbb

redirect

string

Ссылка, по которой необходимо отправить пользователя на форму оплаты

https://api.paytodo.ru/api/v3/deals/247c/

order_amount

number

Сумма для оплаты

100

signature

string

Подпись

3b0171332ef77898ba17c527066642c4

expire_date

string

Оплатить до

2018-08-29T09:44:40.847Z

order_desc

string

Описание сделки

2018-08-29T09:44:40.847Z

status

string

Статус сделки

created