CYPIX API V 2.5

Общие принципы взаимодействия с Системой

API платежной системы осуществляет прием платежей для web-сервисов.

Инициализация платежа производится через отправку запроса на сервер Cypix.

По факту выполнения или не выполнения платежа на URL оплачиваемого сервиса платформа Cypix отправляет уведомление.

Исходные данные

Для начала работы с платформой партнеру необходимо предоставить следующие данные:

URL для отправки уведомлений о статусе запросов на проведение платежей.

Со стороны Cypix партнеру выдаются:

- Идентификатор сервиса партнера.

- Секретный ключ

Инициализация платежа без переадресации Покупателя на платежную форму

Для некоторых платежных систем, таких как QIWI или Мобильная коммерция, партнер может не перенаправлять пользователя на платежную форму, что позволяет легко интегрировать механизм оплаты в интерфейс любого сайта или приложения.

Для совершения платежа пользователем, партнёру необходимо послать запрос на оплату методом GET на адрес https://api.cypix.ru/transaction/ с передачей следующих параметров:
ПараметрОписание
service_idИдентификатор сервиса партнера. Создается на стороне Cypix и выдается вашим менеджером перед началом работы.

Пример: 5432

order_idУникальный идентификатор платежа, сгенерированный на стороне Партнера (до 64 символов)

Пример: 12345678asdfgh

payment_method_idИдентификатор метода оплаты (таблица методов оплаты в Приложении 3)

Пример: 2

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

Пример: 120.20

currencyВалюта, трехбуквенный код валюты по ISO 4217 (рубль: RUB)

Пример: RUB

msisdnНеобязателен; указывается только в случае оплаты через систему Мобильной коммерции, представляет из себя номер мобильного телефона в международном формате, то есть без +

Пример: 79031234567

descriptionНеобязателен; используется в тексте SMS-сообщений или в описании услуги на форме

Пример: Оплата заказа №123

hashКонтрольная сумма. Высчитывается как md5(service_id+order_id+summ+currency +payment_method_id+ description+msisdn+secret), где “+”- знак конкатенации, “secret” - секретный ключ, выдаваемый при регистрации сервиса. Если необязательный параметр не передается, то он не участвует в расчете хеша.

Пример: 7373d616ba14400a7d2a6f4876dd7182

Пример запроса на инициализацию платежа

https://api.cypix.ru/transaction/?service_id=2&order_id=test_1456858950&summ=10¤cy=RUB&payment_method_id=1&msisdn=79121234567&hash=6409d9e491ef8116ad0901dad7a9778b

Где строка для генерации хеша (если секретный ключ имеет значение «7373d616ba14400a7d2a6f4876dd7182»):

2test_145685895010RUB1791212345677373d616ba14400a7d2a6f4876dd7182

В ответ на запрос партнер получит ответ HTTP 200 OK с результатом принятия заявки в теле ответа в формате JSON, с следующими параметрами:

ПараметрОписание
processing_statusСтатус обработки платежа

ACCEPTED - Заявка принята, ожидаются действия пользователя по совершению платежа;

REDIRECT - Для продолжения оформления заявки необходимо направить пользователя на указанный URL;

DENIED - Заявка не принята;

error_codeВ случае processing_status=DENIED в ответе указывается код ошибки, согласно Приложения 1
locationВ случае processing_status=REDIRECT указывается URL, на который необходимо перенаправить Покупателя.
transaction_idВ случае processing_status=ACCEPTED указывается номер транзакции на стороне сервера Cypix (целое число, до 20 знаков)

Пример: 2016030

Пример тела ответа в случае успешного принятия заявки:

{
	“transaction_id”: “123456”,
	“processing_status”: “ACCEPTED”,
	“error_code”: “0”
}

Пример тела ответа, в случае, если запрос на инициализацию платежа не принят

{
	“processing_status”: “DENIED”,
	“error_code”: “1”
}

Интерфейс определения оператора абонента по MSISDN

В случаях, когда партнёру необходимо узнать оператора абонента по MSISDN, он может воспользоваться данным интерфейсом
Для этого, партнёру необходимо послать запрос методом GET на адрес https://api.cypix.ru/operator/ с передачей следующих параметров:

ПараметрОписание
service_idИдентификатор сервиса партнера. Создается на стороне Cypix и выдается вашим менеджером перед началом работы.

Пример: 5432

secretСекретный ключ сервиса, выдаваемый при регистрации сервиса
msisdnНомер мобильного телефона в международном формате, начинающийся с кода страны без +

Пример: 790312345678

В ответ на запрос партнер получит ответ HTTP 200 OK с результатом принятия заявки в теле ответа в формате JSON, с следующими параметрами:

ПараметрОписание
operator_nameНазвание оператора латинскими буквами согласно Приложения 2.

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

{
        “operator_name”:”beeline”
}

В случае неверно заданных параметров, будет выдан ответ HTTP – 400 В случае некорректного secret, будет выдан ответ HTTP – 401

Уведомление Партнера о совершенных платежах

После того, как транзакция прошла успешно или была отклонена, платформа Cypix отсылает HTTP запрос методом GET на URL для уведомлений, предоставленный Партнером для сервиса перед началом работы.
Запрос, отсылаемый сервису, содержит следующие параметры с информацией о транзакции:

ПараметрОписание
service_idИдентификатор сервиса партнера. Создается на стороне Cypix и выдается вашим менеджером перед началом работы.

Пример: 5432

order_idУникальный идентификатор платежа, сгенерированный на стороне Партнера (до 64 символов)

Пример: 12345678asdfgh

processing_statusСтатус обработки транзакции:

PROCESSED - Транзакция прошла успешно

FAILED - Транзакция была отклонена

error_codeКод ошибки, в случае processing_status=FAILED, согласно Приложения 1
priceСумма транзакции в валюте поступления, число с 2-мя знаками в дробной части, разделитель целой и дробной части - точка.

Пример: 120.20

price_rubСумма транзакции в рублях, число с 2-мя знаками в дробной части, разделитель целой и дробной части - точка.

Пример: 120.20

currencyВалюта поступления на счет партнера, трехбуквенный код валюты по ISO 4217 (рубль: RUB).

Пример: RUB

shareВознаграждение Партнера в валюте платежа, число с 2-мя знаками в дробной части, разделитель целой и дробной части - точка.

Пример: 120.20

share_rubВознаграждение Партнера в рублях, число с 2-мя знаками в дробной части, разделитель целой и дробной части - точка.

Пример: 120.20

transaction_dateДата проведения транзакции на стороне Платформы Cypix в формате YYYY-MM-DD HH:mm:ss

Пример: 2016-03-08 00:51:52

transaction_idИдентификатор транзакции на стороне платформы Cypix, целое число, до 20 знаков.

Пример: 2016030

payment_method_idИдентификатор способа оплаты. согласно Приложения 3.

Пример: 2

hashКонтрольная сумма.
Высчитывается как md5:
service_id+transaction_id+order_id+processing_status+price+price_rub+currency+share +share_rub+ transaction_date+payment_method_id+secret
где “+”- знак конкатенации,
“secret” - секретный ключ, выдаваемый при регистрации сервиса.
Если необязательный параметр не передается, то он не участвует в расчете хеша.

Пример: 7373d616ba14400a7d2a6f4876dd7182

Приложение 1. Список кодов ошибок

Код ошибкиОписание
0Операция успешна, ошибки отсутствуют
1Неверное значение параметра hash
2Неверное значение параметра service_id
3Некорректный запрос, отсутствует один или несколько обязательных параметров
4Внутренняя ошибка обработки запроса, необходимо обратиться в техническую поддержку Cypix
5Запрос на инициализацию платежа не может быть принят
500Платеж отклонен оператором (причина неизвестна)
504Платеж отклонен оператором (ожидается подтверждение другого платежа)
505Превышен таймаут ожидания подтверждения платежа
51Передан некорректный идентификатор пользователя(например некорректный MSISDN при оплате через QIWI/МК)
516Платеж отклонен оператором (абонент имеет признак - запрет возврата части аванса)
517Платеж отклонен оператором (у абонента отсутствует разрешение на передачу персональных данных)
52Оплата через данного оператора временно не доступна
59Платеж отклонен оператором (причина не известна)
6Оплату данным методом платежа невозможно провести без перенаправления пользователя на платежную форму Cypix.
7Некорректная сумма платежа
701Недостаточно средств для проведения платежа
71Сумма платежа превышает допустимую сумму
72Сумма платежа меньше минимально разрешенной
73Некорректная валюта
8MSISDN заблокирован
81MSISDN внесен в черный список
82Превышен лимит по количеству платежей за определенный период времени по данному MSISDN
9Определение MSISDN через XBR недоступно

Приложение 2. Список идентификаторов операторов сотовой связи

ОператорИдентификатор
МТСmts
БИЛАЙНbeeline
МЕГАФОНmegafon
TELE2tele2
TАТТЕЛЕКОМtattelecom
ОПЕРАТОР НЕИЗВЕСТЕНunknown

Приложение 3. Идентификаторы платежных систем

ИдентификаторПлатежная система
1Мобильная коммерция
2Банковские карты
©2015-2017 CYPIX