Схема интеграции
- Выставляем счёт
- Либо с помощью метода API
CreateInvoice - Либо можно сформировать ссылку, при переходе покупателя на которую счёт выставится автоматически
- Либо с помощью метода API
- Покупатель оплачивает счёт
- Либо на нашей платежной странице
- Либо в нашем виджете
- Либо на вашем сайте, с помощью метода
BankCardPayment(у вашей организации должна быть сертификация PCI DSS)
- Получаем статус оплаты
- Либо ждем HTTP POST запроса об изменении статуса от IntellectMoney
- Либо периодически вызываем метод API
GetBankCardPaymentState
Авторизация в API
Для авторизации в запросе нужно передать 3 строки: ваш Bearer токен и два хеша.
HTTP заголовок Authorization
В заголовке Authorization нужно передать Bearer токен в формате Bearer 92022dd8245a56d8a73446b43ebb3590. Bearer token (с секретным ключом) можно запросить в личном кабинете.
HTTP заголовок Sign
В заголовке Sign нужно передать хеш, сформированный из остальных параметров. Хеш формируется по шаблону, которой уникален для каждого метода. Для примера, вот шаблон из метода CreateInvoice:
eshopId::orderId::serviceName::recipientAmount::recipientCurrency::userName::email::successUrl::failUrl::backUrl::resultUrl::expireDate::holdMode::preference::signSecretKey
В нем signSecretKey - секретный ключ, полученный вместе с Bearer токеном на странице https://lk.intellectmoney.ru/profile/security/api, остальное - параметры передаваемые в метод.
Скажем, что вы вызываете метод CreateInvoice со следующими параметрами:
eshopId: 462539 orderId: myorder recipientAmount: 10.00 recipientCurrency: RUB email: e@e.ru
Для рассчета хеша нужно:
Заменить имена параметров в шаблоне их значениями, и подставить секретный ключ вместо
signSecretKey. Получаем строку:462539::myorder::::10.00::RUB::::e@e.ru::::::::::::::::21baff51c1a342f3ac059e61e0894583
Эту строку нужно закодировать в UTF-8 и посчитать от нее хеш SHA256. Получаем хеш:
1c4e379396faee212c676d500ee12a21354d8f68b1acbc40b64065cd7dcd50fa
Полученный хеш записываем в заголовок Sign.
Параметр hash
У каждого метода API имеется параметр hash. В него нужно передать хеш, формируемый подобно хешу из заголовка Sign. Чтобы рассчитать этот хеш, нужно использовать шаблон, уникальный для каждого метода. К примеру, вот шаблон из метода CreateInvoice:
eshopId::orderId::serviceName::recipientAmount::recipientCurrency::userName::email::successUrl::failUrl::backUrl::resultUrl::expireDate::holdMode::preference::secretKey
Здесь secretKey - ключ, заданный в личном кабинете в настройках магазина. Это ключ, как и весь шаблон, не связаны с ключем и шаблоном из заголовка Sign.
Возьмем такие параметры для примера:
eshopId: 462539 orderId: myorder recipientAmount: 10.00 recipientCurrency: RUB email: e@e.ru
Для расчета параметра hash нужно:
Заменить имя каждого параметра его значением, и подставить секретный ключ вашего магазина вместо
secretKey:462539::myorder::::10.00::RUB::::e@e.ru::::::::::::::::my_very_secret_key
Закодировать полученную строку в UTF-8 и расчитать её MD5 хеш:
7a97ff0cda3d7593c1a69a04d0a78a13
Полученный хеш нужно передать в параметре hash.
Методы API
CreateInvoice - ВЫСТАВЛЕНИЕ СЧЁТА К ОПЛАТЕ
POST https://api.intellectmoney.ru/merchant/createInvoice
Authorization: Bearer <ваш токен> Sign: <хеш рассчитанный по шаблону ниже> Content-Type: application/json или application/x-www-form-urlencoded Accept: application/json или application/xml
eshopId::orderId::serviceName::recipientAmount::recipientCurrency::userName::email::successUrl::failUrl::backUrl::resultUrl::expireDate::holdMode::preference::signSecretKey
eshopId::orderId::serviceName::recipientAmount::recipientCurrency::userName::email::successUrl::failUrl::backUrl::resultUrl::expireDate::holdMode::preference::secretKey
Параметры
| Имя параметра | Описание |
|---|---|
| eshopId Обязательный | ID магазина |
| orderId Обязательный | Уникальный идентификатор покупки из вашей системы. до 50 символов |
| recipientAmount Обязательный | Сумма платежа, разделенная точкой. Минимальное значение - 10.00.До 13 символов, до 2 цифр после точки. |
| recipientCurrency Обязательный | Валюта платежа. Допустимые значения - TST (тестовая валюта) - RUB - USD - EUR |
| email Обязательный | E-mail покупателя. До 100 символов. |
| hash Обязательный | Контрольная подпись запроса |
| serviceName | Назначение платежа - описание товара или услуги. До 1024 символов. |
| userName | Имя покупателя, До 255 символов. |
| successUrl | Адрес, на который происходит перенаправление плательщика с платежной страницы после успешной оплаты До 512 символов. |
| failUrl | Адрес, на который происходит перенаправление плательщика с платежной страницы в случае неуспешной оплаты До 512 символов. |
| backUrl | Адрес ссылки "Вернуться в магазин" на платежной странице До 512 символов. |
| resultUrl | Адрес, на который система IntellectMoney посылает HTTP/S POST запросы об изменении состояния cчёта До 512 символов. |
| expireDate | Срок существования счёта - дата и время, по достижению которых оплатить счёт станет невозможно. Формат: yyyy-MM-dd HH:mm:ss. |
| preference | Возможные способы оплаты счёта. Если не передавать, счет можно будет оплатить любым из подключенных способов. Допустимые значения - BankCard - YandexPay - Sbp Можно перечислить несколько значений через запятую, например "BankCard,YandexPay,Sbp". |
В этой таблице опущена часть параметров, например параметры связанные с холдированием, онлайн кассой, и рекаррингом. См. полный список параметров здесь: СЮДА НАДО ССЫЛКУ НА Merchant API
GetBankCardPaymentState - СОСТОЯНИЕ ПЛАТЕЖА
POST https://api.intellectmoney.ru/merchant/getbankcardpaymentstate
Authorization: Bearer <ваш токен> Sign: <хеш рассчитанный по шаблону ниже> Content-Type: application/json или application/x-www-form-urlencoded Accept: application/json или application/xml
eshopId::invoiceId::signSecretKey
eshopId::invoiceId::secretKey
Параметры
| Имя параметра | Описание |
|---|---|
| eshopId Обязательный | ID магазина, в котором был выставлен счёт |
| invoiceId Обязательный | Номер счёта |
| hash Обязательный | Контрольная подпись запроса |
Пример ответа
Чтобы получить ответ в формате JSON, нужно добавить в запрос заголовок Accept: application/json
{
"OperationState": {
"Code": 0,
"Desc": "Успешно обработана"
},
"EshopId": 465932,
"Result": {
"PaymentStep": "InProcess",
"State": {
"Code": 0,
"Desc": "Успешно обработан"
}
}
}
BankCardPayment - ОПЛАТА БАНКОВСКОЙ КАРТОЙ
POST https://api.intellectmoney.ru/merchant/bankcardpayment
Authorization: Bearer <ваш токен> Sign: <хеш рассчитанный по шаблону ниже> Content-Type: application/json или application/x-www-form-urlencoded Accept: application/json или application/xml
eshopId::invoiceId::pan::cardHolder::expiredMonth::expiredYear::cvv::returnUrl::ipAddress::signSecretKey
eshopId::invoiceId::pan::cardHolder::expiredMonth::expiredYear::cvv::returnUrl::ipAddress::secretKey
Используется для передачи реквизитов банковской карты и дальнейшей оплаты счета.
Для использования этого метода у вашей организации должна быть сертификация PCI DSS. Если у вас её нет, то оплату можно реализовать перенаправлением покупателя на нашу платежную страницу, либо внедрением нашего платежного виджета на сайт.
Параметры
| Имя параметра | Описание |
|---|---|
| eshopId Обязательный | ID магазина, где был выставлен счёт |
| invoiceId Обязательный | Номер счёта к оплате |
| ipAddress Обязательный | IP адрес сайта, с которого выставляется платеж. |
| returnUrl Обязательный | Адрес, на который перенаправляет плательщика после завершения 3DS. |
| cardHolder | Имя и фамилия с карты |
| pan Обязательный | Номер карты плательщика |
| cvv Обязательный для карт имеющих CVV2 (CVC2) | Секретный код CVV2 (CVC2), как правило написан на обороте карты (последние три цифры на полосе для подписи). Параметр не нужно передавать, если карта не имеет кода. |
| expiredYear Обязательный | Год, до которого действует карта |
| expiredMonth Обязательный | Месяц, до которого действует карта |
| hash Обязательный | Контрольная подпись запроса |
Пример ответа
Чтобы получить ответ в формате JSON, нужно добавить в запрос заголовок Accept: application/json
{
"OperationState": {
"Code": 0,
"Desc": "Успешно обработана"
},
"EshopId": 465932,
"Result": {
"State": {
"Code": 0,
"Desc": "Успешно обработан"
}
}
}