Илтимос, маълумоти заруриро пешниҳод намоед
Мо дар муддати кӯтоҳтарин бо Шумо ба тамос мебароем
Добро пожаловать в ImconPay!
Наша платежная платформа позволяет подключить на ваш веб-сайт прием платежей с пластиковых карт в интернете в виде готовой платежной формы или с возможностью использования платежной формы на стороне мерчанта по API. С нами вы можете организовать прием платежей в интернете быстро и гибко так, как это нужно именно вам. Мы создаем продукт, который удобен не только для бизнеса, но и для разработчиков.
Взаимодействие с API
Запуск процесса оплаты посредством сервиса ImconPay со стороны мерчанта состоит из этих этапов:
- Первый этап, подключение к API ImconPay посредством клиентского сертификата выданный на основе CSR который был предоставлен со стороны мерчанта (все запросы в API должны быть аутентифицированы по клиентскому сертификату). Используется протокол не ниже TLSv1.2
- Второй этап, запрос на получение JWT токена который используется для аутентификации запросов мерчанта к API
- Третий этап, запрос на создание заказа и получение подписи по заказу и формированной платежной ссылки
- Четвертый этап, перенаправление клиента в платежную ссылку.
- Пятый этап, получение оповещения об изменение статуса заказа, и инициирование мерчантом запроса на получение статуса заказа
В личном кабинете мерчанта в Мерчант > Интеграция Магазина находиться информация по ключам для взаимодействия с сервисом ImconPay. Ниже предоставлена таблица с наименованием данных ключей.
| Имя | Описание |
|---|---|
| Client Code | Код мерчанта в системе ImconPay |
| Merchant Api Key | Секретный ключ мерчанта в системе ImconPay |
| Root Api Key | Секретный ключ сервиса ImconPay |
| Private Key | Закрытый ключ мерчанта для формирования подписи по алгоритму RS256 |
| KID | KID (Идентификатор ключа) мерчанта в системе ImconPay |
Запрос на получение токена доступа
Данный шаг рекомендуется соверщать в закрытой части (бэкэнд) приложения мерчанта. Чтобы отправить запрос на сервис ImconPay для получения токена, сначала требуется формировать JWT token который будет отправляться в Authorization header-е запроса. Формируем JWT token (RFC 7519) по алгоритму RS256 с нижеследующими параметрами:
| Параметр | Описание | Обяз. | |
|---|---|---|---|
| Private key: | |||
| privateKey | Закрытый ключ мерчанта для формирования подписи по алгоритму RS256 | да | |
| KID: | |||
| kid | KID (Идентификатор ключа) мерчанта в системе ImconPay | да | |
| Payload: | |||
| iss | URL сайта мерчанта | да | |
| client_code | Код мерчанта в системе ImconPay | да | |
| prv | Захешериваное значение по алгоритму SHA256 конкатенацией строки: iss + client_code |
да |
Далее отправляем POST запрос с заголовком Authorization: Bearer {JWT token}
POST https://api.mtm.tj/api/auth/acquire_access_token
При успешном запросе предоставляется ответ от сервиса ImconPay как в примере ниже.
{
"status": true,
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJpc3MiOiJodHRwczovL3BheS5tdG0udGovYXBpL2F1dGgvbG9naW4iLCJpYXQiOjE3MDAwMjM0OTgsImV4cCI6MTcwMDAyNTI5OCwiY2xpZW50X2NvZGUiOiIzOGZlODJiNiIsInBydiI6ImU4YmEzMjI3NzM0ZWIzMzJjYzgwZjVmOGVhMGI1NGEzNzQ2NWU2MmIwZDM5MTZlMTBkZTgzMTRhOWJmYzUxMWIifQ.dl0XssA2qKTjMXAZnNBKlOLheIX_UngEebnTda1LGZhfd_dkmZlO6tg3sriG7-NqxiEkN5ud_-kmQYrSihDoEkvCqpLzr5ac8GDDhkiFhJfNlbbLiEDZq0T5x1YdfGC9wYJEwDHf14YhJVLpEYoHwD_Uask1uMCQwlFysztvr-OIodSKlr4h4xeBFplpOjf2Suu-itjgpZ1sCqTL25f4UpirAPCo0_dyjsMZnYBDpCF7-bIyqmHNJmS6AtvcLxG0xE_QEvukFcn67inopmJL4sYAg7d6jF-AjFdBAsHJSlVO3mlW2YtV314d2q5HAu2TEQsXp2kqK1KmZb6IylyEAQ"
}
После успешного получения токена доступа в API вызовах по api.mtm.tj, нужно отправлять выданный ранее токен доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
Запрос на создание заказа
Данный шаг рекомендуется соверщать в закрытой части (бэкэнд) приложения мерчанта. Чтобы отправить запрос на сервис ImconPay для получения подписи заказа, сначала требуется формировать hash который будет отправляться в числе параметров запроса. Перечень параметров запроса отображен в нижеследующей таблице. Параметр hash это захешериваное значение по алгоритму SHA256 текстовой строки которая составляется конкатенацией некоторых параметров. Ниже параметры которые должны конкатенировать.
order_id + amount + MerchantApiKey
Далее отправляем POST запрос с параметрами перечисленными в таблице.
POST https://api.mtm.tj/api/pay/create_quote
Передача токена доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| client_code | String | Код мерчанта в системе ImconPay | да |
| order_id | String | Идентификатор заказа на стороне мерчанта | да |
| amount | Number(8, 2) | Стоимость покупки (заказа), разделитель точка | да |
| currency | Integer | Код валюты по стандарту ISO 4217 | да |
| description_cart | String | Содержимое корзины | нет |
| order_type | String | Тип заказа | да |
| hash | String | Рассчитанный хэш | да |
Поле order_type может иметь 2 ввида значений mpi_url, custom_url. При интеграции с платежной формой ImconPay надо отправлять значение mpi_url
При успешном запросе предоставляется ответ от сервиса ImconPay в данном ввиде.
{
"success": true,
"signature": "a833440eec33d195ae27638eaa08ac10613c9bc2ad9a02be209f255838245eed",
"uuid_order": "f798db9e-72cd-4fa9-acd4-d551ce910439"
}
Перенаправление клиента на платежный шлюз ImconPay
В указанных в примере местах вместо фигурных скобок надо подставить параметры. Параметры указаны в таблице.
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| signature | String | Подпись заказа | да |
| uuid_order | String | Идентификатор заказа в системе ImconPay | да |
| client_code | String | Код мерчанта в системе ImconPay | да |
Пример:
GET https://api.mtm.tj/pay/gateway/{signature}/{uuid_order}/{client_code}
Ответ от сервиса ImconPay
Во время регистрации со стороны мерчанта предоставляется merchant_notify_url. При прохождение операции сервис ImconPay отправляет запрос на предоставлений merchant_notify_url.
Пример:
GET {merchant_notify_url}?uuid_order={uuid_order}
Это будет означать, что статус заказа изменился, и мерчант в этот момент должен начинать делать запрос на получение статуса оплаты заказа.
Для получения статуса заказа необходимо отправить POST-запрос с параметрами, перечисленными в таблице:
POST https://api.mtm.tj/api/pay/get_order_status
Передача токена доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| client_code | String | Код мерчанта в системе ImconPay | да |
| uuid_order | UUID | Идентификатор заказа в системе ImconPay | да |
Добро пожаловать в ImconPay!
Наша платежная платформа позволяет подключить на ваш веб-сайт прием платежей с пластиковых карт в интернете в виде готовой платежной формы или с возможностью использования платежной формы на стороне мерчанта по API. С нами вы можете организовать прием платежей в интернете быстро и гибко так, как это нужно именно вам. Мы создаем продукт, который удобен не только для бизнеса, но и для разработчиков.
Взаимодействие с API
Запуск процесса оплаты посредством сервиса ImconPay со стороны мерчанта состоит из этих этапов:
- Первый этап, подключение к API ImconPay посредством клиентского сертификата выданный на основе CSR который был предоставлен со стороны мерчанта (все запросы в API должны быть аутентифицированы по клиентскому сертификату). Используется протокол не ниже TLSv1.2
- Второй этап, запрос на получение JWT токена который используется для аутентификации запросов мерчанта к API
- Третий этап, запрос на создание заказа и получение подписи и идентификатора заказа
- Четвертый этап, перенаправление клиента в платежную ссылку. Для мерчантов которые используют свою платежную страницу, надо проверить вовлеченность карты к 3DSv2, реализовать сбор данных браузера по предоставленной ссылке по API и отправить данные карты плательщика по API
- Пятый этап, получение оповещения об изменение статуса заказа, и инициирование мерчантом запроса на получение статуса заказа
В личном кабинете мерчанта в Мерчант > Интеграция Магазина находиться информация по ключам для взаимодействия с сервисом ImconPay. Ниже предоставлена таблица с наименованием данных ключей.
| Имя | Описание |
|---|---|
| Client Code | Код мерчанта в системе ImconPay |
| Merchant Api Key | Секретный ключ мерчанта в системе ImconPay |
| Root Api Key | Секретный ключ сервиса ImconPay |
| Private Key | Закрытый ключ мерчанта для формирования подписи по алгоритму RS256 |
| KID | KID (Идентификатор ключа) мерчанта в системе ImconPay |
Запрос на получение токена доступа
Данный шаг рекомендуется соверщать в закрытой части (бэкэнд) приложения мерчанта. Чтобы отправить запрос на сервис ImconPay для получения токена, сначала требуется формировать JWT token который будет отправляться в Authorization header-е запроса. Формируем JWT token (RFC 7519) по алгоритму RS256 с нижеследующими параметрами:
| Параметр | Описание | Обяз. | |
|---|---|---|---|
| Private key: | |||
| privateKey | Закрытый ключ мерчанта для формирования подписи по алгоритму RS256 | да | |
| KID: | |||
| kid | KID (Идентификатор ключа) мерчанта в системе ImconPay | да | |
| Payload: | |||
| iss | URL сайта мерчанта | да | |
| client_code | Код мерчанта в системе ImconPay | да | |
| prv | Захешериваное значение по алгоритму SHA256 конкатенацией строки: iss + client_code |
да |
Далее отправляем POST запрос с заголовком Authorization: Bearer {JWT token}
POST https://api.mtm.tj/api/auth/acquire_access_token
При успешном запросе предоставляется ответ от сервиса ImconPay как в примере ниже.
{
"status": true,
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJpc3MiOiJodHRwczovL3BheS5tdG0udGovYXBpL2F1dGgvbG9naW4iLCJpYXQiOjE3MDAwMjM0OTgsImV4cCI6MTcwMDAyNTI5OCwiY2xpZW50X2NvZGUiOiIzOGZlODJiNiIsInBydiI6ImU4YmEzMjI3NzM0ZWIzMzJjYzgwZjVmOGVhMGI1NGEzNzQ2NWU2MmIwZDM5MTZlMTBkZTgzMTRhOWJmYzUxMWIifQ.dl0XssA2qKTjMXAZnNBKlOLheIX_UngEebnTda1LGZhfd_dkmZlO6tg3sriG7-NqxiEkN5ud_-kmQYrSihDoEkvCqpLzr5ac8GDDhkiFhJfNlbbLiEDZq0T5x1YdfGC9wYJEwDHf14YhJVLpEYoHwD_Uask1uMCQwlFysztvr-OIodSKlr4h4xeBFplpOjf2Suu-itjgpZ1sCqTL25f4UpirAPCo0_dyjsMZnYBDpCF7-bIyqmHNJmS6AtvcLxG0xE_QEvukFcn67inopmJL4sYAg7d6jF-AjFdBAsHJSlVO3mlW2YtV314d2q5HAu2TEQsXp2kqK1KmZb6IylyEAQ"
}
После успешного получения токена доступа в API вызовах по api.mtm.tj, нужно отправлять выданный ранее токен доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
Запрос на создание заказа
Данный шаг рекомендуется соверщать в закрытой части (бэкэнд) приложения мерчанта. Чтобы отправить запрос на сервис ImconPay для получения подписи заказа, сначала требуется формировать hash который будет отправляться в числе параметров запроса. Перечень параметров запроса отображен в нижеследующей таблице. Параметр hash это захешериваное значение по алгоритму SHA256 текстовой строки которая составляется конкатенацией некоторых параметров. Ниже параметры которые должны конкатенировать.
order_id + amount + MerchantApiKey
Далее отправляем POST запрос с параметрами перечисленными в таблице.
POST https://api.mtm.tj/api/pay/create_quote
Передача токена доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| client_code | String | Код мерчанта в системе ImconPay | да |
| order_id | String | Идентификатор заказа на стороне мерчанта | да |
| amount | Number(8, 2) | Стоимость покупки (заказа), разделитель точка | да |
| currency | Integer | Код валюты по стандарту ISO 4217 | да |
| description_cart | String | Содержимое корзины | нет |
| order_type | String | Тип заказа | да |
| hash | String | Рассчитанный хэш | да |
Поле order_type может иметь 2 ввида значений mpi_url, custom_url. При интеграции собственной платежной формы мерчанта надо отправлять значение custom_url
При успешном запросе предоставляется ответ от сервиса ImconPay в данном ввиде.
{
"success": true,
"signature": "a833440eec33d195ae27638eaa08ac10613c9bc2ad9a02be209f255838245eed",
"uuid_order": "f798db9e-72cd-4fa9-acd4-d551ce910439"
}
Перенаправление клиента на платежный шлюз ImconPay
В указанных в примере местах вместо фигурных скобок надо подставить параметры. Параметры указаны в таблице.
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| signature | String | Подпись заказа | да |
| uuid_order | String | Идентификатор заказа в системе ImconPay | да |
| client_code | String | Код мерчанта в системе ImconPay | да |
Пример:
GET https://api.mtm.tj/pay/gateway/{signature}/{uuid_order}/{client_code}
Запрос на проверку вовлеченности карты к 3DS2
Данный шаг надо выполнять только для мерчантов которые используют свою платёжную страницу.
Данный шаг рекомендуется соверщать в закрытой части (бэкэнд) приложения мерчанта.
Отправляем POST запрос с параметрами перечисленнемы в таблице.
POST https://api.mtm.tj/api/pay/3ds2/check
Передача токена доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| client_code | String | Код мерчанта в системе ImconPay | да |
| uuid_order | UUID | Идентификатор заказа в системе ImconPay | да |
| pan | Количество цифр от 8 до 19 включительно | Полный номер карты | да |
При успешном запросе предоставляется ответ от сервиса ImconPay в данном ввиде.
{
"success": true,
"threeDSProtocolVersion": "3DSv2",
"threeDSServerTransID": "366b4dcd-cef6-47d8-8c29-68c9bc4e06f0",
"gatherUrl": "https://3dstest.mtm.tj:8443/api/v1/client/gather"
}
Поле threeDSProtocolVersion может иметь 3 ввида значений None, 3DSv1 и 3DSv2. Поле threeDSServerTransID имеет не пустое значение только при 3DSv2
После получения ответа со стороны ImconPay отправьте POST запрос на gatherUrl с параметрами формы (Content-Type: application/x-www-form-urlencoded):
threeDSServerTransID: {threeDSServerTransID}Запрос на оплату
Данный шаг надо выполнять только для мерчантов которые используют свою платёжную страницу.
Данный шаг рекомендуется соверщать в закрытой части (бэкэнд) приложения мерчанта.
Отправляем POST запрос с параметрами перечисленнемы в таблице.
POST https://api.mtm.tj/api/pay/payment
Передача токена доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| client_code | String | Код мерчанта в системе ImconPay | да |
| uuid_order | UUID | Идентификатор заказа в системе ImconPay | да |
| pan | Количество цифр от 8 до 19 включительно | Полный номер карты | да |
| cvc | Число (длина 3) | Проверочный код карты | да |
| exp_month | Число (длина 2) | Месяц, в течение которого карта истекает | да |
| exp_year | Число (длина 4) | Год, когда истекает срок действия карты | да |
| cardholder | String | Имя владельца карты | нет |
При успешном запросе предоставляется ответ от сервиса ImconPay в данном ввиде.
{
"success": true,
"threeDSProtocolVersion": "3DSv2",
"PaReq": "eJxVUu1ugkAQfBXDf7wvEDDrNbXa1LQYo/gAwG0VK6jH2dg+fe/8aOu/nWEzMzcLPJzqbecTdVvtmoHHutTrYFPuVNWsBt4ye/Zj70FCttaIowWWR40SUmzbfIWdSg289zwOFVeBn1OFfsAF+jFViZ/0hFBFwoqiEJ6E2eMcDxKuRtL6dDmQG7SKulznjZGQl4fhZCoDHvUoBXKFUKOejCTjIgh7UZwAuRDQ5DXKDFtzU2BAzhyUu2Nj9JfsBQLIDcBRb+XamH3bJ6Q2dddsgDgOyF+E2dFNrdU4VUqmmzGfZsvvNBuLdDQJp5slnWbjMB19DIC4DVC5QckpF4yzpEPDfhj1hQ1y5iGvnblklIrAPuiCYO9MHu8+/afANq3tIb5kEtmifhHgab9r0G5Y9ncG8pf56cWVWJpzXbGIaMBE+NqK2Ux/vuniVPD5YjN0SS5LTrGy1fCAsbOkA0CcDLlejVwPbqe7H+EHkb25WQ==",
"cReq": "eJxVUu1ugkAQfBXDf7wvEDDrNbXa1LQYo/gAwG0VK6jH2dg+fe/8aOu/nWEzMzcLPJzqbecTdVvtmoHHutTrYFPuVNWsBt4ye/Zj70FCttaIowWWR40SUmzbfIWdSg289zwOFVeBn1OFfsAF+jFViZ/0hFBFwoqiEJ6E2eMcDxKuRtL6dDmQG7SKulznjZGQl4fhZCoDHvUoBXKFUKOejCTjIgh7UZwAuRDQ5DXKDFtzU2BAzhyUu2Nj9JfsBQLIDcBRb+XamH3bJ6Q2dddsgDgOyF+E2dFNrdU4VUqmmzGfZsvvNBuLdDQJp5slnWbjMB19DIC4DVC5QckpF4yzpEPDfhj1hQ1y5iGvnblklIrAPuiCYO9MHu8+/afANq3tIb5kEtmifhHgab9r0G5Y9ncG8pf56cWVWJpzXbGIaMBE+NqK2Ux/vuniVPD5YjN0SS5LTrGy1fCAsbOkA0CcDLlejVwPbqe7H+EHkb25WQ==",
"TermUrl": "https://3dstest.mtm.tj:8443/payments/rest/finish3ds.do",
"MD": "607b4d63-ac5d-4667-b3c9-b0986aef4bf1",
"acsUrl": "https://3dstest.mtm.tj:8443/acs/pareq/f98150d35dbb4598a6c56b9e4296cbdb"
}
После получения ответа со стороны ImconPay отправьте POST запрос на acsUrl с параметрами формы (Content-Type: application/x-www-form-urlencoded):
Когда threeDSProtocolVersion None, переход на страницу acsUrl не нужен
Когда threeDSProtocolVersion 3DSv1:
PaReq: {PaReq}TermUrl: {TermUrl}
MD: {MD}
Когда threeDSProtocolVersion 3DSv2:
creq: {сReq}Ответ от сервиса ImconPay
Во время регистрации со стороны мерчанта предоставляется merchant_notify_url. При прохождение операции сервис ImconPay отправляет запрос на предоставлений merchant_notify_url.
Пример:
GET {merchant_notify_url}?uuid_order={uuid_order}
Это будет означать, что статус заказа изменился, и мерчант в этот момент должен начинать делать запрос на получение статуса оплаты заказа.
Для получения статуса заказа необходимо отправить POST-запрос с параметрами, перечисленными в таблице:
POST https://api.mtm.tj/api/pay/get_order_status
Передача токена доступа accessToken в заголовке авторизации:
Authorization: Bearer {accessToken}
| Атрибут/Параметр | Тип данных | Описание | Обяз. |
|---|---|---|---|
| client_code | String | Код мерчанта в системе ImconPay | да |
| uuid_order | UUID | Идентификатор заказа в системе ImconPay | да |