API для оплаты лицом
- 1 Использование API
- 2 Транспорт и протокол
- 3 Общие положения
- 4 Коды ответа
- 5 Коды ошибок и их описание
- 6 Регистрация
- 6.1 Регистрация
- 6.1.1 Формат запроса
- 6.1.2 Формат ответа
- 6.2 Верификация
- 6.2.1 Формат запроса
- 6.2.2 Формат ответа
- 6.3 Установка ПИН-кода
- 6.3.1 Формат запроса
- 6.3.2 Формат ответа
- 6.4 Повторная отправка СМС
- 6.4.1 Формат запроса
- 6.1 Регистрация
- 7 Вход с другого устройства
- 7.1 Формат запроса
- 7.2 Формат ответа
- 8 Аутентификация
- 8.1 Аутентификация
- 8.1.1 Формат запроса
- 8.1.2 Формат ответа
- 8.2 Обновление токена
- 8.2.1 Формат запроса
- 8.2.2 Формат ответа
- 8.1 Аутентификация
- 9 Прикрепление банковской карты
- 9.1 Прикрепление банковской карты
- 9.1.1 Формат запроса
- 9.1.2 Формат ответа
- 9.2 Проверка статуса
- 9.2.1 Формат запроса
- 9.2.2 Формат ответа
- 9.3 Получение 3D Secure страницы
- 9.3.1 Формат запроса
- 9.3.2 Формат ответа
- 9.4 Получение списка карт
- 9.4.1 Формат запроса
- 9.4.2 Формат ответа
- 9.1 Прикрепление банковской карты
- 10 Смена приоритета карты
- 10.1 Формат запроса
- 10.2 Формат запроса
- 11 Удаление банковской карты
- 11.1 Формат запроса
- 12 Подключение сервиса SELFIETOPAY
- 12.1 Загрузка селфи
- 12.1.1 Формат запроса
- 12.1.2 Формат ответа
- 12.1.3 Формат запроса
- 12.1.4 Формат ответа
- 12.2 Загрузка фотографии паспорта
- 12.2.1 Формат запроса
- 12.2.2 Формат ответа
- 12.2.3 Формат запроса
- 12.3 Загрузка селфи с паспортом
- 12.3.1 Формат запроса
- 12.3.2 Формат ответа
- 12.3.3 Формат запроса
- 12.4 Установка пароля
- 12.4.1 Формат запроса
- 12.5 Получение пользовательского соглашения
- 12.5.1 Формат запроса
- 12.5.2 Формат ответа
- 12.5.3 Формат запроса
- 12.6 Подписание пользовательского соглашения
- 12.6.1 Формат запроса
- 12.7 Подключение функции SELFIETOPAY
- 12.7.1 Формат запроса
- 12.7.2 Формат ответа
- 12.8 Отключение сервиса SELFIETOPAY
- 12.8.1 Формат запроса
- 12.8.2 Формат ответа
- 12.1 Загрузка селфи
Использование API
SELFIETOPAY API - программный интерфейс для подключения сервиса SELFIETOPAY.
Транспорт и протокол
В качестве транспорта используется HTTPS протокол. Сообщения кодируются в JSON формат.
Общие положения
Мобильное приложение взаимодействует с сервером по протоколу REST. Протокол REST односторонний, только клиент может сделать запрос к серверу и получить ответ. Сервер не может передать данные на клиента без запроса. Многие операции на сервере асинхронные. Для их выполнения используется идентификатор (deferredId), по которому можно будет получить результат. После выполнения асинхронного запроса и получения в ответ deferredId, клиент в цикле запрашивает результат операции до тех пор, пока не получит непустое значение, либо не произойдет тайм-аут.
Для выполнения большинства запросов необходима аутентификация. Запрос должен содержать заголовок X-Auth-Token, значением которого является JWT-токен.
Список заголовков, которые необходимо обязательно передавать в API запросах:
X-Auth-Token | eyJhbGciOiJIUzUxMM....9rZ8VQ54JqWFe1Q | Токен приходит после регистрации или после входа в приложение. |
Api-Version | 2 | Версия API. |
Коды ответа
200 | Успешный запрос. |
|
400 | Неправильный запрос из-за нарушения правил взаимодействия с API. | bad_request |
401 | Неудачная авторизация. | unauthorized |
403 | Доступ запрещен. | forbidden |
404 | Ресурс по указанному id не был найден в системе SWiP. | not_found |
405 | Используется запрещенный или неподдерживаемый метод. | method_not_allowed |
429 | Отправлено слишком много запросов за короткий промежуток времени. | too_many_request |
500 | Внутренняя ошибка сервера. | internal_server_error |
Коды ошибок и их описание
1 | INTERNAL SERVER ERROR |
2 | AUTHENTICATION ERROR |
4 | ACCESS DENIED |
5 | VALIDATION FAILED |
6 | ILLEGAL STATE |
7 | METHOD NOT SUPPORTED |
8 | DUPLICATE |
9 | NOT FOUND |
10 | UNSUPPORTED MESSAGE |
11 | ORDER FLOW VIOLATION |
12 | SMS CODE EXPIRED |
13 | OPERATION TIMED OUT |
14 | DOESNT MATCH |
15 | PAYMENTS BLOCKED |
16 | TOKEN EXPIRED |
17 | JWT TOKEN ERROR |
18 | CONCURRENT PAYMENT ERROR |
19 | BANK PAYMENT ERROR |
20 | PAYMENT CARD BLOCKED |
21 | ACCOUNTING ERROR |
22 | REQUEST LIMIT EXCEEDED |
23 | EXTERNAL SYSTEM ERROR |
24 | CASHBACK PAYMENT ERROR |
25 | OPERATION IN PROGRESS |
26 | CUSTOMER DUPLICATE PIN |
27 | REVERSE UNAVAILABLE |
28 | ORDER ALREADY EXISTS |
29 | ORDER ALREADY REFUNDED |
30 | ORDER ALREADY CONFIRMED |
31 | ORDER NOT PAID |
32 | EXCESS TOTAL AMOUNT |
Регистрация
Пользователь регистрируется по номеру телефона с подтверждением по СМС. Сообщение на указанный номер телефона может быть отправлено не более одного раза в минуту.
Регистрация
Формат запроса
1
POST /v2/signups
Для регистрации нового пользователя необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Номер телефона, на который регистрируется приложение. |
Пример тела запроса
1
{"phone":"string"} // номер телефона в виде 11-ти цифр
Формат ответа
В ответ на запрос приходит токен для аутентификации.
Пример тела ответа
1
2
3
4
5
6
{
"token":"eyJhbGciOi...OsCJZDnxqQg",
"refreshToken":null,
"refreshPeriod":3600,
"tokenRefreshPeriod":3600
}
Верификация
Чтобы завершить регистрацию системе необходимо убедиться, что пользователь указал существующий номер телефона.
Формат запроса
1
POST /v2/signup-verifications
Для верификации номера телефона пользователя отправляется запрос с передачей следующих параметров:
| string, обязательный | Код, который приходит в СМС-сообщении от SWiP. |
Пример тела запроса
1
{"code":"6826"}
Формат ответа
В ответ на запрос приходит объект, который говорит о том, что такой номер телефона в базе ещё не зарегистрирован. Этот ответ означает, что необходимо перейти к установке ПИН-кода.
Пример тела ответа
1
{"new":true}
Установка ПИН-кода
Вызывает метод установки ПИН-кода.
На данный момент возможность восстановления ПИН-кода не реализована. Если пользователь его забыл, необходимо обратиться в службу поддержки.
Формат запроса
1
PUT v2/signups
Для установки ПИН-кода отправляется запрос с передачей следующих параметров:
| string, обязательный | Идентификатор устройства. |
| string, необязательный | Имя пользователя. |
| string, необязательный | Фамилия пользователя. |
| string, обязательный | ПИН-код, который ввел пользователь. |
Пример тела запроса
1
2
3
4
5
6
{
"deviceId": "string",
"firstName": "string",
"lastName": "string",
"password": "string"
}
Формат ответа
В ответ на запрос приходит токен и рефреш токен, с которыми приложение может делать запросы аутентификации.
Пример тела ответа
1
2
3
4
5
6
{
"token":"eyHkl...J67g",
"refreshToken":"eyJhb...36pvFFw",
"refreshPeriod":3600,
"tokenRefreshPeriod":3600
}
Повторная отправка СМС
Запрашивает метод для повторной отправки СМС. Необходим, если на мобильный телефон не пришло сообщение с кодом для верификации.
Формат запроса
1
POST /sms-messages
В качестве ответа используется HTTP-код.
Вход с другого устройства
При входе с другого устройства сначала необходимо выполнить регистрацию и верификацию. В ответ на запрос верификации приходит поле new со значением false.
Формат запроса
1
POST /v2/signup-devices
Для входа с другого устройства или после переустановки приложения необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор устройства. |
| string, обязательный | ПИН-код, который ввел пользователь. |
Пример тела запроса
1
2
3
4
{
"deviceId": "string",
"password": "string"
}
Формат ответа
В ответ на запрос приходит токен.
Пример тела ответа
1
2
3
4
5
6
{
"refreshPeriod": 0,
"refreshToken": "string",
"token": "string",
"tokenRefreshPeriod": 0
}
Аутентификация
Аутентификация происходит после перезапуска или после бездействия в приложении.
Аутентификация
Формат запроса
1
POST /auth
Для получения токена необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор устройства. |
| string, обязательный | Пин-код, который ввел пользователь. |
| string, обязательный | Номер телефона указанный при регистрации. |
Пример тела запроса
1
2
3
4
5
{
"deviceId":"9e044ffccc5d0916",
"password":"1111",
"username":"string"
}
Формат ответа
В ответ на запрос приходит следующий объект.
Пример тела ответа
1
2
3
4
5
6
7
8
{
"token":"eyJhbG....Wnp--Q",
"refreshToken":"eyJhbG.....fW9Gw",
"refreshPeriod":3600,
"tokenRefreshPeriod":3600,
"stpStatus":"OFF",
"deviceRegistrationRequired":false
}
Полученный токен действителен в течение 1 часа и не требует повторного запроса при каждой операции. По истечении его срока действия приходит ошибка. Чтобы продолжить работу необходимо отправить запрос на получение токена. Для этого нужно либо заново пройти процедуру аутентификации либо обновить токен, используя refreshToken.
Обновление токена
Токен можно обновить до окончания срока действия следующим запросом.
Формат запроса
1
PUT /auth
Формат ответа
В ответ на запрос приходит токен.
Пример тела ответа
1
2
3
4
5
6
{
"token":"eyHkl...J67g",
"refreshToken":"eyJhb...36pvFFw",
"refreshPeriod":3600,
"tokenRefreshPeriod":3600
}
Прикрепление банковской карты
Прикрепление карты необходимо для совершения платежей, а также для проверки того, что пользователь имеет доступ к данной карте (списание контрольной суммы, проверка через 3DS).
Прикрепление банковской карты
Формат запроса
1
POST /payment-cards
Для прикрепления банковской карты необходимо отправить запрос с передачей следующих параметров:
| boolean, обязательный | Использование карты по умолчанию. |
| string, обязательный | Имя держателя карты. |
| string, обязательный | Зашифрованные данные карты (год и месяц окончания срока действия карты, номер карты, CVV). |
Пример тела запроса
1
2
3
4
5
{
"addAsDefault":true,
"holder":"cardholder name",
"cryptogram":"string"
}
Формат ответа
В ответ на запрос приходит временный идентификатор карты.
Пример тела ответа
1
{"deferredId":"d83a617e-dae3-448b-875d-c62d163b030a"}
Проверка статуса
Запрос позволяет получить текущий статус привязки карты и идет в цикле c интервалом в одну секунду.
Формат запроса
1
GET /deferred-results/{id}/status
Для получения текущего статуса по привязке карты необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Временный идентификатор, по которому можно получить статус прикрепления карты. |
Формат ответа
В ответ на запрос приходит текущий статус привязки карты.
Пример тела ответа
1
2
3
4
5
{
"status":"PROCESSING",
"errorCode":"",
"errorMessage":""
}
Поле status
может принимать следующие значения:
| Карту не удалось прикрепить. |
| Карта успешно прикреплена. |
| Данные по карте обрабатываются. |
| Требуется ввод проверочного кода для подтверждение прикрепления карты. |
Получение 3D Secure страницы
Прикрепление карты проводится с применением технологии 3D Secure. После ввода проверочного кода временно блокируется 1 рубль на указанной банковской карте. Через некоторое время блокировка суммы снимается эмитентом карты.
Формат запроса
1
GET /deferred-results/{id}/binding-payment-card-3ds-result
Для получения 3D Secure страницы необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Временный идентификатор карты. |
Формат ответа
В ответ на запрос приходит HTML-код страницы, которая содержит форму для ввода проверочного кода от банка.
Пример тела ответа
1
2
3
{
"finish3dsHtml":"<!DOCTYPE html>\n<html>...HTML code...</html>"
}
Получение списка карт
Запрашивает список прикрепленных карт.
Формат запроса
1
GET /payment-cards
Формат ответа
В ответ приходит список прикрепленных карт.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
{
"id":"730818ac-4b3c-4356-b1dd-783a3d5ff676", // идентификатор карты в системе SWiP
"cardNumber":"**** **** **** 2009", // номер карты
"defaultForPayments":true, // использование карты по умолчанию
"bankName":"Название банка", // название банка
"bankLogo":"471b8f50-bb8d-11e6-9a11-08a47b0e7ea4", // логотип банка
"paymentSystem":"VISA", // платежная система
"createdAt":1543760701775, // время создания (в миллисекундах с 01.01.1970)
"blocked":false // блокировка карты
},
{
"id":"767818ac-4b3c-8567-b1dd-784r56ff676",
"cardNumber":"**** **** **** 1209",
"defaultForPayments":false,
"bankName":"Название банка",
"bankLogo":"501b8f50-bb8d-48e6-9a11-08a47b0e7ea4",
"paymentSystem":"МИР",
"createdAt":1543760702376,
"blocked":false
}
]
Смена приоритета карты
Первая добавленная в SWiP карта выбирается для использования по умолчанию.
Формат запроса
Если добавлено несколько карт и пользователь хочет изменить карту по умолчанию, следует выполнить следующий запрос.
1
POST /payment-cards/{id}/actions/set-as-default
Для выбора карты по умолчанию необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор банковской карты в системе SWiP. |
В качестве ответа используется HTTP-код.
Формат запроса
Если добавлено несколько карт и пользователь хочет отменить выбор карты по умолчанию, следует выполнить следующий запрос.
1
POST /payment-cards/{id}/actions/unset-as-default
Для отключения карты по умолчанию необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор банковской карты в системе SWiP. |
В качестве ответа используется HTTP-код.
Удаление банковской карты
Запрашивает удаление банковской карты на сервере SWiP.
Формат запроса
1
DELETE /payment-cards/{id}
Для удаления банковской карты необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор карты в системе SWiP. |
Подключение сервиса SELFIETOPAY
Для использования сервиса оплаты лицом требуется подтверждение личности пользователя. Необходимы следующие файлы: изображение лица, изображение паспорта, селфи пользователя с паспортом.
Загрузка селфи
Формат запроса
Передается изображение в виде массива байт с Content-Type: multipart/form-data.
1
POST /uploads
Формат ответа
В ответ на запрос приходит идентификатор изображения.
Пример тела ответа
1
{"photo":"515681b7-4e08-48cd-8786-b9ddccfa2f8b"}
Формат запроса
Обновляет идентификатор изображения в профиле.
1
PUT /profile
Для обновления изображения профиля необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор изображения в профиле. |
Пример тела запроса
1
{"profileImageId":"515681b7-4e08-48cd-8786-b9ddccfa2f8b"}
Формат ответа
В ответ на запрос приходит объект профиля в актуальном статусе.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"firstName":"string",
"lastName":"string",
"middleName": "string",
"city":"string",
"country":"string",
"email":"string",
"birthday":null,
"profileImageId":"515681b7-4e08-48cd-8786-b9ddccfa2f8b",
"passportImageId":"null",
"selfiePassportImageId":"null",
"allowPaymentWithoutPincode":false,
"stpStatus":"OFF",
"stpErrors":[
]
}
Загрузка фотографии паспорта
Формат запроса
Передается изображение в виде массива байт с Content-Type: multipart/form-data.
1
POST /uploads
Формат ответа
В ответ на запрос приходит идентификатор изображения.
1
{"photo":"926e6c2d-49a4-4fa9-b27b-dc9b0bde5dc2"}
Формат запроса
Обновляет идентификатор изображения в профиле.
1
PUT /profile/documents/passport
Для обновления изображения в профиле необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор изображения в профиле. |
Пример тела запроса
1
{"ref":"926e6c2d-49a4-4fa9-b27b-dc9b0bde5dc2"}
В качестве ответа используется HTTP-код.
Загрузка селфи с паспортом
Формат запроса
Передается изображение в виде массива байт с Content-Type: multipart/form-data.
1
POST /uploads
Формат ответа
В ответ на запрос приходит идентификатор изображения.
Пример тела ответа
1
{"photo":"eba38641-a40f-4714-8c67-3dd0f0a5ec9c"}
Формат запроса
Обновляет идентификатор изображения в профиле.
1
PUT /profile/documents/selfie-passport
Для обновления изображения в профиле необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор изображения в профиле. |
Пример тела запроса
1
{"ref":"eba38641-a40f-4714-8c67-3dd0f0a5ec9c"}
В качестве ответа используется HTTP-код.
Установка пароля
Пароль будет использован, если система во время оплаты распознает, что у пользователя есть близнец.
Формат запроса
1
PUT /profile/pincode
Для установки пароля необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Пароль, который вводит пользователь. |
В случае, если близнецы ввели одинаковый пароль, вернется ошибка с кодом 26. Необходимо повторить запрос.
Получение пользовательского соглашения
Запрашивает профиль пользователя.
Формат запроса
1
GET /profile
Формат ответа
В ответ приходит профиль пользователя в актуальном статусе.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"firstName":"string",
"lastName":"string",
"middleName": "string",
"city":"string",
"country":"string",
"email":"string",
"birthday":null,
"profileImageId":"515681b7-4e08-48cd-8786-b9ddccfa2f8b",
"passportImageId":"null",
"selfiePassportImageId":"null",
"allowPaymentWithoutPincode":false,
"userAgreementRef":"string",
"stpStatus":"AGREEMENT_SIGNING_REQUIRED",
"stpErrors":[
]
}
Если поле stpStatus
имеет значение AGREEMENT_SIGNING_REQUIRED
, вызывается метод для получения пользовательского соглашения.
Формат запроса
1
GET /profile/docs/{docId}/document-data
Для получения пользовательского соглашения необходимо отправить запрос с передачей следующих параметров:
| string, обязательный | Идентификатор PDF-документа. |
В ответ приходит PDF-документ, преобразованный в массив байтов.
Подписание пользовательского соглашения
Метод вызывается после просмотра и подписания пользователем соглашения.
Формат запроса
1
POST /profile/docs/{docId}/actions/sign-agreement
В качестве ответа используется HTTP-код.
Подключение функции SELFIETOPAY
После загрузки необходимых изображений следует подключить функцию SELFIETOPAY. При этом проводится проверка загруженных данных, которая может занять несколько часов.
Формат запроса
1
POST /profile/actions/enable-stp-payments
Формат ответа
В ответ на запрос приходит объект профиля в статусе обработки данных.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"firstName":"string",
"lastName":"string",
"middleName":"string",
"city":"string",
"country":"string",
"email":"string",
"birthday":null,
"profileImageId":"f6ad1fd9-0f6a-4e08-898c-5f7e04bb94e7",
"passportImageId":"926e6c2d-49a4-4fa9-b27b-dc9b0bde5dc2",
"selfiePassportImageId":"eba38641-a40f-4714-8c67-3dd0f0a5ec9c",
"allowPaymentWithoutPincode":false,
"userAgreementRef":"string",
"stpStatus":"PROCESSING",
"stpErrors":[
]
}
Чтобы получить актуальное значение поля stpStatus
требуется отправить запрос GET /profile
.
Поле stpStatus
может принимать следующие значения:
| Сервис STP подключен. |
| Сервис STP отключен. |
| Ошибка при проверке загруженных изображений. |
| Обработка после редактирования изображений. |
| Запрос на подключение STP находится в обработке. |
| Завершена проверка данных, необходимо подписать пользовательское соглашение. |
Поле stpErrors
может принимать следующие значения:
| Плохая фотография лица. |
| Плохая фотография паспорта. |
| Фотография лица и фотография на паспорте не совпадают. |
| Плохая фотография лица с паспортом. |
| Не все документы загружены. |
Отключение сервиса SELFIETOPAY
Формат запроса
1
POST /profile/actions/disable-stp-payments
Формат ответа
В ответ на запрос приходит объект профиля со статусом OFF
. Если загруженные изображения не были изменены, то включение сервиса SELFIETOPAY происходит без проверки данных. В противном случае необходимо заново пройти процедуру подключения.
Пример тела ответа
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"firstName":"string",
"lastName":"string",
"middleName":"string",
"city":"string",
"country":"string",
"email":"string",
"birthday":null,
"profileImageId":"f6ad1fd9-0f6a-4e08-898c-5f7e04bb94e7",
"passportImageId":"926e6c2d-49a4-4fa9-b27b-dc9b0bde5dc2",
"selfiePassportImageId":"eba38641-a40f-4714-8c67-3dd0f0a5ec9c",
"allowPaymentWithoutPincode":false,
"stpStatus":"OFF",
"stpErrors":[
]
}