Введение
Общая информация
Универсальная платформа приема платежей ATMOS позволяет мерчантам интегрировать свой сайт или мобильное приложение к платежнему шлюзу в целях организации приема платежей с банковских карт UzCard и Humo. Интеграция с платежной платформой ATMOS возможна следующими путями:
- Вызов платежного виджета на стороне клиента;
- Оплата посредством перехода на платежную страницу;
- Интеграция с API и прием оплат на внешнем клиенте мерчанта;
Начало работы
API работает по протоколу REST, формат всех сообщений - JSON. Для начала работы с API, мерчанту необходимо получить от ATMOS следующие данные:
- Consumer key
- Consumer secret
Также, перед началом работы, необходимо ознакомиться с принципом действия Callback API.
Тестовые данные
В разделе песочница приведены тестовые данные для интеграции и ознакомления с работой системы.
Авторизация в API
Для работы с ATMOS API необходимо получить токен доступа, который устанавливается в заголовки каждого запроса и служит уникальным идентификатором при проведении платежных операций. Ниже приведены инструкции по получению токена доступа к API.
Получение токена
Для получения bearer-токена:
curl --request POST \
--url https://partner.atmos.uz/token \
--header 'Authorization: Basic Base64(consumer-key:consumer-secret) \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials
POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(consumer-key:consumer-secret)
Host: partner.atmos.uz
Content-Length: 29
//form-data
grant_type=client_credentials
Пример ответа:
{
"access_token": "<access_token>",
"scope": "am_application_scope default",
"token_type": "Bearer",
"expires_in": 2525
}
HTTP Request
POST https://partner.atmos.uz/token
Принимает в качестве параметра зашифрованную строку в формате base64 по формуле - Base64(consumer_key + ':' + consumer_secret). В ответе сервера будет возвращен токен доступа, который действителен в течение 3600 секунд(1ч.).
Обновление токена
Для обновления bearer-токена:
curl --request POST \
--url https://partner.atmos.uz/token \
--header 'Authorization: Basic Base64(consumer-key:consumer-secret) \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials
--data refresh_token=<access_token>
POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(consumer-key:consumer-secret)
Host: partner.atmos.uz
Content-Length: 29
//form-data
grant_type=client_credentials
refresh_token=<access_token>
Пример ответа:
{
"access_token": "<access_token>",
"scope": "am_application_scope default",
"token_type": "Bearer",
"expires_in": 2525
}
HTTP Request
POST https://partner.atmos.uz/token
Имеет аналогичный функционал с преждним методом, за исключением того, что продлевает срок действия уже выданного токена.
Отзыв токена
Для отзыва bearer-токена:
curl --request POST \
--url https://partner.atmos.uz/revoke \
--header 'Authorization: Basic Base64(consumer-key:consumer-secret) \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data token=<access_token>
POST /revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(consumer-key:consumer-secret)
Host: partner.atmos.uz
Content-Length: 29
//form-data
token=<access_token>
Пример ответа:
{
"access_token": "<access_token>",
"scope": "am_application_scope default",
"token_type": "Bearer",
"expires_in": 2525
}
HTTP Request
POST https://partner.atmos.uz/revoke
Отменяет действие уже выданного токена.
Оплаты
API ATMOS позволяет проводить оплаты следующими путями:
- Путем отправки одноразового кода подтверждения при каждом платеже держателю карты;
- Через привязку карты к мерчанту, для дальнейших списаний без надобности подтверждения и ввода реквизитов.
Каждый запрос(для эндпоинтов раздела "Оплаты") может содержать в своем теле необязательное поле lang, для выбора языка получаемых текстовых данных от сервера.
Для поля lang являются допустимыми значения: uz, ru, en.
В теле каждого ответа(для эндпоинтов раздела "Оплаты") содержится объект result с полями:
- code - "OK" для успешных запросов, или строка с номером ошибки (см. Системные ошибки);
- description - "Нет ошибок" для успешных запросов, или строка с описанием ошибки.
Создание транзакции
Запрос:
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/create \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"amount": 5000000,
"account": "12345",
"terminal_id": "XXXXXXXX",
"store_id": "XXXX",
"lang": "ru"
}'
POST /merchant/pay/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 123
{
"amount": 5000000,
"account": "12345",
"terminal_id": "XXXXXXXX",
"store_id": "XXXX",
"lang": "ru"
}
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"transaction_id": 111111,
"store_transaction": {
"success_trans_id": null,
"trans_id": 222222,
"store": {
"id": 0000,
"name": "Store name",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "00000000",
"account": "000000000",
"amount": 5000000,
"confirmed": false,
"prepay_time": null,
"confirm_time": null,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": null,
"commission_value": "0",
"commission_type": "0",
"total": 5000000,
"card_id": null,
"status_code": null,
"status_message": null
}
}
Создает в системе черновик транзакции для дальнейшего пред-подтверждения и финального подтверждения, и возвращает номер созданной операции.
HTTP Request
POST https://partner.atmos.uz/merchant/pay/create
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| amount | Сумма платежа в тиинах | да |
| account | Идентификатор платежа | да |
| terminal_id | id терминала мерчанта | нет |
| store_id | id мерчанта | да |
| lang | язык для ответа сервера | нет |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | объект с детализацией по транзакции |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | в данном случае null |
| - status_code | в данном случае null |
| - status_message | в данном случае null |
(OFD) Создание транзакции
Запрос:
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/create/checkout-ofd \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"amount": 5000000,
"account": "12345",
"terminal_id": "XXXXXXXX",
"store_id": "XXXX",
"lang": "ru",
"ofd_items" : [
{
"ofd_code" : "XXXXXXXXX",
"name" : "product name 1",
"amount" : 300000
},
{
"ofd_code" : "XXXXXXXXX",
"name" : "product name 2",
"amount" : 200000
}
]
}'
POST /merchant/pay/create/checkout-ofd HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 123
{
"amount": 5000000,
"account": "12345",
"terminal_id": "XXXXXXXX",
"store_id": "XXXX",
"lang": "ru",
"ofd_items" : [
{
"ofd_code" : "XXXXXXXXX",
"name" : "product name 1",
"amount" : 300000
},
{
"ofd_code" : "XXXXXXXXX",
"name" : "product name 2",
"amount" : 200000
}
]
}
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"transaction_id": 111111,
"store_transaction": {
"success_trans_id": null,
"trans_id": 222222,
"store": {
"id": 0000,
"name": "Store name",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "00000000",
"account": "000000000",
"amount": 5000000,
"confirmed": false,
"prepay_time": null,
"confirm_time": null,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": null,
"commission_value": "0",
"commission_type": "0",
"total": 5000000,
"card_id": null,
"status_code": null,
"status_message": null
}
}
Является расширением предыдущего метода /merchant/pay/create (Создание транзакции). Используется, когда необходимо создать транзакцию с детализацией OFD и сформировать инвойс для оплаты на платежной странице (см. раздел "Альтернативные виды оплаты").
HTTP Request
POST https://partner.atmos.uz/merchant/pay/create/checkout-ofd
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| amount | Сумма платежа в тиинах | да |
| account | Идентификатор платежа | да |
| terminal_id | id терминала мерчанта | нет |
| store_id | id мерчанта | да |
| lang | язык для ответа сервера | нет |
| ofd_items | массив объектов Ofd item | да |
| -ofd_code | ИКПУ код товара | да |
| -name | Название товара | да |
| -amount | Стоимость товара в тиинах | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | объект с детализацией по транзакции |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | в данном случае null |
| - status_code | в данном случае null |
| - status_message | в данном случае null |
Пред-подтверждение транзакции
Запрос:
POST merchant/pay/pre-apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>
Host: partner.atmos.uz
Content-Length: 102
{
"card_token": "<card-token>",
"store_id": 0000,
"transaction_id": 00000
}
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/pre-apply \
--header 'Authorization: <access_token \
--header 'Content-Type: application/json' \
--data '{
"card_token": "<card-token>",
"store_id": 0000,
"transaction_id": 00000
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
}
}
Принимает номер созданной транзакции и подготавливает ее к списанию средств. В случае передачи в метод номера и срока действия карты, высылает одноразовый sms-код для подтверждения транзакции держателю карты.
Для списания по одноразовому SMS-коду подтверждения используйте поля
card_numberиexpiry.Для списания по ранее привязанной к сервису карте, достаточно использовать поле
card_tokenбезcard_numberиexpiry.
HTTP Request
POST https://partner.atmos.uz/merchant/pay/pre-apply
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| card_token | Токен карты | +/- |
| card_number | Номер карты | +/- |
| expiry | срок действия карты (YYmm) | +/- |
| store_id | id мерчанта(store) | да |
| transaction_id | номер созданной прежде транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
Подтверждение транзакции
Запрос:
POST /merchant/pay/apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 63
{
"transaction_id": 00000,
"otp": 111111,
"store_id": 0000
}
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/apply \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"transaction_id": 00000,
"otp": 111111,
"store_id": 0000
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"store_transaction": {
"success_trans_id": 0000000,
"trans_id": 11111,
"store": {
"id": 0000,
"name": "XXXXX",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "00000000",
"account": "0001",
"amount": 5000000,
"confirmed": true,
"prepay_time": 1656326498000,
"confirm_time": 1656326529324,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": null,
"commission_value": "0",
"commission_type": "0",
"total": 5000000,
"card_id": "XXXXXX",
"status_code": "0",
"status_message": "Success"
}
}
Подтверждает транзакцию и списыввет средства с карты на терминал мерчанта.
HTTP Request
POST https://partner.atmos.uz/merchant/pay/apply
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| otp | Код из sms | да |
| store_id | id мерчанта | да |
| transaction_id | номер созданной прежде транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | объект с детализацией по транзакции |
| - success_trans_id | постоянный номер успешной транзакции |
| - trans_id | номер транзакции |
| - store | объект с данными мерчанта |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | токен карты |
| - status_code | сервисное поле |
| - status_message | статус транзакции |
Создание мультитранзакции
Запрос:
POST /merchant/bulk/pay/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 208
{
"store_id": <store-id>,
"params": [
{
"account": "user_1",
"amount": 50000,
"details": "Для услуги 1"
},
{
"account": "user_1",
"amount": 100000,
"details": "Для услуги 1"
}
]
}
curl --request POST \
--url https://partner.atmos.uz/merchant/bulk/pay/create \
--header 'Authorization: <access_token \
--header 'Content-Type: application/json' \
--data '{
"store_id": <store-id>,
"params": [
{
"account": "user_1",
"amount": 50000,
"details": "Для услуги 1"
},
{
"account": "user_1",
"amount": 100000,
"details": "Для услуги 1"
}
]
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"transaction_id": [111111, 222222],
"store_transactions": [
{
"success_trans_id": null,
"trans_id": 111111,
"store": {
"id": 0000,
"name": "Store name",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "00000000",
"account": "000000000",
"amount": 50000,
"confirmed": false,
"prepay_time": null,
"confirm_time": null,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": "Для услуги 1",
"commission_value": "0",
"commission_type": "0",
"total": 50000,
"card_id": null,
"status_code": null,
"status_message": null
},
{
"success_trans_id": null,
"trans_id": 222222,
"store": {
"id": 0000,
"name": "Store name",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "00000000",
"account": "000000000",
"amount": 50000,
"confirmed": false,
"prepay_time": null,
"confirm_time": null,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": "Для услуги 2",
"commission_value": "0",
"commission_type": "0",
"total": 100000,
"card_id": null,
"status_code": null,
"status_message": null
}
]
}
Создает в системе черновик мультитранзакции для дальнейшего пред-подтверждения и финального подтверждения, и возвращает номер созданной операции. Позволяет произвести несколько оплат(в т.ч. на разные терминалы) в рамках одного списания.
HTTP Request
POST https://partner.atmos.uz/merchant/bulk/pay/create
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| amount | Сумма платежа в тиинах | да |
| params | Массив данных создаваемых транзакций | да |
| - account | Идентификатор платежа | да |
| - terminal_id | id терминала мерчанта | нет |
| - store_id | id мерчанта(store) | да |
| - lang | язык для ответа сервера | нет |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | массив объектов с детализацией по транзакции |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | в данном случае null |
| - status_code | в данном случае null |
| - status_message | в данном случае null |
Пред-подтверждение мультитранзакции
Запрос:
POST merchant/bulk/pay/pre-apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>
Host: partner.atmos.uz
Content-Length: 102
{
"card_token": "<card-token>",
"store_id": 0000,
"transaction_id": [00000, 11111]
}
curl --request POST \
--url https://partner.atmos.uz/merchant/bulk/pay/pre-apply \
--header 'Authorization: <access_token \
--header 'Content-Type: application/json' \
--data '{
"card_token": "<card-token>",
"store_id": 0000,
"transaction_id": [00000, 11111]
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
}
}
Принимает номер созданной мультитранзакции и подготавливает ее к списанию средств. В случае передачи в метод номера и срока действия карты, высылает одноразовый sms-код для подтверждения транзакции держателю карты.
Для списания по одноразовому SMS-коду подтверждения используйте поля
card_numberиexpiry.Для списания по ранее привязанной к сервису карте, достаточно использовать поле
card_tokenбезcard_numberиexpiry.
HTTP Request
POST https://partner.atmos.uz/merchant/bulk/pay/pre-apply
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| card_token | Токен карты | +/- |
| card_number | Номер карты | +/- |
| expiry | срок действия карты (YYmm) | +/- |
| store_id | id мерчанта(store) | да |
| transaction_id | номер созданной прежде транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
Запрос:
curl --request POST \
--url https://partner.atmos.uz/merchant/bulk/pay/create \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"store_id": <store-id>,
"params": [
{
"account": "user_1",
"amount": 50000,
"details": "Для услуги 1"
},
{
"account": "user_1",
"amount": 100000,
"details": "Для услуги 1"
}
]
}'
Подтверждение мультитранзакции
Запрос:
POST merchant/bulk/pay/apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 63
{
"store_id": 000,
"otp": "111111",
"transaction_id": [11111, 22222]
}
curl --request POST \
--url https://partner.atmos.uz/merchant/bulk/pay/apply \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"store_id": 000,
"otp": "111111",
"transaction_id": [11111, 22222]
}
'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"store_transaction": [
{
"success_trans_id": 2728805,
"trans_id": 45702,
"store": {
"id": 000,
"name": "Store name",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "7777777",
"account": "user_1",
"amount": 50000,
"confirmed": true,
"prepay_time": 1635828973000,
"confirm_time": 1635829043427,
"label": {
"type_id": 49,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Invoice number"
},
"details": "Для услуги 1",
"commission_value": "0",
"commission_type": "0",
"total": 50000,
"card_id": "<card-id>",
"status_code": "0",
"status_message": "Success"
},
{
"success_trans_id": 2728806,
"trans_id": 45703,
"store": {
"id": 271,
"name": "Store name",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "7777777",
"account": "user_1",
"amount": 100000,
"confirmed": true,
"prepay_time": 1635828973000,
"confirm_time": 1635829043432,
"label": {
"type_id": 49,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Invoice number"
},
"details": "Для услуги 2",
"commission_value": "0",
"commission_type": "0",
"total": 100000,
"card_id": "<card-id>",
"status_code": "0",
"status_message": "Success"
}
]
}
Подтверждает мультитранзакцию и списыввет средства с карты на терминалы мерчанта(store).
HTTP Request
POST https://partner.atmos.uz/merchant/bulk/pay/apply
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| otp | Код из sms | да |
| store_id | id мерчанта | да |
| transaction_id | номер созданной прежде транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | массив объектов с детализацией по транзакциям |
| - success_trans_id | постоянный номер успешной транзакции |
| - trans_id | номер транзакции |
| - store | объект с данными мерчанта |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | токен карты |
| - status_code | сервисное поле |
| - status_message | статус транзакции |
(OFD) Подтверждение транзакции с отправкой данных ИКПУ товаров
Запрос:
POST /merchant/pay/confirm-with-ofd-list HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
x-jwt-assertion: ---
Content-Length: 359
{
"store_id": 7659,
"transaction_id": 67665,
"otp": "111111",
"ofd_items": [
{
"ofdCode": "222222",
"amount": 100000
},
{
"ofdCode": "33333",
"amount": 40000
}
]
}
curl --location 'https://partner.atmos.uz/merchant/pay/confirm-with-ofd-list' \
--header 'x-jwt-assertion: ---' \
--header 'Content-Type: application/json' \
--data '{
"store_id": 7659,
"transaction_id": 67665,
"otp": "111111",
"ofd_items": [
{
"ofdCode": "222222",
"amount": 100000
},
{
"ofdCode": "33333",
"amount": 40000
}
]
}'
Пример ответа сервера:
{
"result": {
"code": "STPIMS-ERR-092",
"description": "Транзакция закрыта"
},
"store_transaction": {
"success_trans_id": 0123456,
"trans_id": 67665,
"store": {
"id": 1111,
"name": "<Store name>",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "00000000",
"account": "9989999999999",
"amount": 140000,
"confirmed": true,
"prepay_time": 1677588413000,
"confirm_time": 1677588425000,
"label": {
"type_id": 49,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Invoice number"
},
"details": null,
"commission_value": "0",
"commission_type": "0",
"total": 100000,
"card_id": null,
"status_code": "0",
"status_message": "Success",
"ofd_url": "https://ofd.atmos.uz/api/ofd/eEw5UE5EK2N0L3ZzbkpjMk11RGYzdz08"
}
}
Подтверждает созданную ранее транзакцию и списывает средства с карты на терминал мерчанта, отличается от родительского метода тем, что в теле запроса принимает данные о товарах с их стоимостью и ИКПУ в объекте ofd_items. По итогу возвращает фискальный чек к транзакции.
HTTP Request
POST https://partner.atmos.uz/merchant/pay/confirm-with-ofd-list
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| store_id | id мерчанта | да |
| transaction_id | номер созданной прежде транзакции | да |
| otp | код подтверждения транзакции | да |
| ofd_items | массив объектов по товарам | |
| - ofdCode | ИКПУ товара | |
| - amount | стоимость товара(тийин) |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | массив с детализацией по транзакциям |
| - success_trans_id | постоянный номер успешной транзакции |
| - trans_id | номер транзакции |
| - store | объект с данными мерчанта |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | токен карты |
| - status_code | сервисное поле |
| - status_message | статус транзакции |
| - ofd_url | ссылка на фискальный чек |
(OFD) Подтверждение транзакции с генерацией фискального чека
Запрос:
POST /merchant/pay/apply-ofd HTTP/1.1
Content-Type: application/json
Authorization: Bearer Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 63
{
"transaction_id": 00000,
"otp": 111111,
"store_id": 0000
}
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/apply-ofd \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"transaction_id": 00000,
"otp": 111111,
"store_id": 0000
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"store_transaction": {
"success_trans_id": 0000000,
"trans_id": 11111,
"store": {
"id": 0000,
"name": "XXXXX",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "00000000",
"account": "0001",
"amount": 5000000,
"confirmed": true,
"prepay_time": 1656326498000,
"confirm_time": 1656326529324,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": null,
"commission_value": "0",
"commission_type": "0",
"total": 5000000,
"card_id": "XXXXXX",
"status_code": "0",
"status_message": "Success"
},
"ofd_url": "http://test.ofd.atmos.uz/api/ofd/0000000"
}
Подтверждает транзакцию и списывает средства с карты на терминал мерчанта, отличается от родительского метода тем, что по итогу генерирует возвращает ссылку на фискальный чек(OFD)
HTTP Request
POST https://partner.atmos.uz/merchant/pay/apply-ofd
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| otp | Код из sms | да |
| store_id | id мерчанта | да |
| transaction_id | номер созданной прежде транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | объект с детализацией по транзакции |
| - success_trans_id | постоянный номер успешной транзакции |
| - trans_id | номер транзакции |
| - store | объект с данными мерчанта |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | токен карты |
| - status_code | сервисное поле |
| - status_message | статус транзакции |
| - ofd_url | ссылка на фискальный чек |
Повторный запрос кода подтверждения
Запрос:
POST /merchant/pay/otp-resend HTTP/1.1
Content-Type: application/json
Authorization: Bearer 9281a6ab-c963-3c1c-9d95-dbed95db955c
Host: api.atmos.uz
Content-Length: 28
{
"transaction_id": 00001
}
curl --request POST \
--url https://api.atmos.uz/merchant/pay/otp-resend \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data '{
"transaction_id": 10000
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"transaction_id": 10000
}
Переотправляет SMS-код подтверждения держателю карты.
HTTP Request
POST https://api.atmos.uz/merchant/pay/otp-resend
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | номер созданной прежде транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| transaction_id | номер транзакции для которой был переотправлен код подтверждения |
Отмена транзакции
Запрос:
POST /merchant/pay/reverse HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 54
{
"transaction_id": 000001,
"reason": "Something"
}
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/reverse \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"transaction_id": 000001,
"reason": "Something"
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"transaction_id": 000001
}
Отменяет ранее оплаченную транзакцию и возвращает средства на карту.
HTTP Request
POST https://partner.atmos.uz/merchant/pay/reverse
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | номер отменяемой транзакции | да |
| hold_amount | удерживаемая сумма в тиинах | нет |
| reason | причина отмены транзакции | нет |
Параметры ответа
| Параметр | Описание |
|---|---|
| transaction_id | номер отмененной транзакции |
Получение информации о транзакции
Запрос:
POST /merchant/pay/get HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 47
{
"store_id": 0001,
"transaction_id": 51827
}
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/get \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"store_id": 0001,
"transaction_id": 51827
}'
Пример ответа сервера:
{
"result": {
"code": "STPIMS-ERR-092",
"description": "Транзакция закрыта"
},
"store_transaction": {
"success_trans_id": 2730590,
"trans_id": 51827,
"store": {
"id": 0001,
"name": "XXXXX",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "000001",
"account": "XXXXXX",
"amount": 5000000,
"confirmed": true,
"prepay_time": 1656326498000,
"confirm_time": 1656326529000,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": null,
"commission_value": "0",
"commission_type": "0",
"total": 5000000,
"card_id": null,
"status_code": "0",
"status_message": "Success"
}
}
Запрос данных о ранее созданной/подтвержденной/закрытой транзакции. Данный метод также используется, если после запроса merchant/pay/apply клиент не получил в теле ответа объект result (случился обрыв связи в сети, или сервис не ответил в рамках заданного клиентом срока (time out), или получили ошибку от шины) необходимо проверить статус транзакции через данный метод.
HTTP Request
POST https://partner.atmos.uz/merchant/pay/get
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| store_id | id мерчанта(store) в системе ATMOS | да |
| transaction_id | номер запрашиваемой транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| store_transaction | объект с детализацией по транзакции |
| - success_trans_id | постоянный номер успешной транзакции |
| - trans_id | номер транзакции |
| - store | объект с данными мерчанта |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | токен карты |
| - status_code | сервисное поле |
| - status_message | статус транзакции |
(OFD) Получение информации о транзакции с фискальным чеком
Запрос:
POST /merchant/pay/get-with-ofd HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 47
{
"store_id": 0001,
"transaction_id": 51827
}
curl --request POST \
--url https://partner.atmos.uz/merchant/pay/get-with-ofd \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"store_id": 0001,
"transaction_id": 51827
}'
Пример ответа сервера:
{
"result": {
"code": "STPIMS-ERR-092",
"description": "Транзакция закрыта"
},
"store_transaction": {
"success_trans_id": 2730590,
"trans_id": 51827,
"store": {
"id": 0001,
"name": "XXXXX",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "000001",
"account": "XXXXXX",
"amount": 5000000,
"confirmed": true,
"prepay_time": 1656326498000,
"confirm_time": 1656326529000,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": null,
"commission_value": "0",
"commission_type": "0",
"total": 5000000,
"card_id": null,
"status_code": "0",
"status_message": "Success"
},
"ofd_url": "https://ofd.atmos.uz/api/ofd/eEw5UE5EK2N0L3ZzbkpjMk11RGYzdz09"
}
Запрос данных о ранее созданной/подтвержденной/закрытой транзакции, с незначительым отличием от исходного метода. В теле ответа возвращает ссылку на фискальный чек в поле ofd_url Данный метод также используется, если после запроса merchant/pay/apply клиент не получил в теле ответа объект result (случился обрыв связи в сети, или сервис не ответил в рамках заданного клиентом срока (time out), или получили ошибку от шины) необходимо проверить статус транзакции через данный метод.
HTTP Request
POST https://partner.atmos.uz/merchant/pay/get-with-ofd
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| store_id | id мерчанта(store) в системе ATMOS | да |
| transaction_id | номер запрашиваемой транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| store_transaction | объект с детализацией по транзакции |
| - success_trans_id | постоянный номер успешной транзакции |
| - trans_id | номер транзакции |
| - store | объект с данными мерчанта |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | токен карты |
| - status_code | сервисное поле |
| - status_message | статус транзакции |
| ofd_url | ссылка на фискальный чек |
(OFD) Получение данных о прикрепленных к транзакции товарах
Запрос:
curl --location 'https://partner.atmos.uz/merchant/pay/ofd-list' \
--header 'x-jwt-assertion: ---' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"store_id": 7659,
"success_transaction_id": 2741154
}'
POST /merchant/pay/ofd-list HTTP/1.1
Host: partner.atmos.uz
Authorization: Bearer <access-token>
x-jwt-assertion: ---
Content-Type: application/json
Content-Length: 62
{
"store_id": 7659,
"success_transaction_id": 2741154
}
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"store_id": 7659,
"transaction_id": 2741154,
"ofd_items": [
{
"id": 6,
"amount": 1000,
"init_time": "2023-02-28 17:47:05.000",
"ofd_code": "SADADD#D"
}
]
}
Используется для получения детализации о прикрепленных к транзакции товарах, зарегистрированных для фискализации
HTTP Request
POST https://partner.atmos.uz/merchant/pay/ofd-list
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| store_id | id мерчанта | да |
| success_stransaction_id | id запрашиваемой транзакции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| store_id | id мерчанта |
| transaction_id | id операции |
| ofd_items | массив с данными о товарах, прикрепленных к транзакции |
Привязка карт
Привязка карт может быть полезна в мобильных приложениях, веб-сервисах, платформах, где требуется регулярное списание средств, или просто требуется оплата без подтверждения через sms-код каждой транзакции. Привязка карты проводится в приведенной последовательности:
- Заявка на создание токена карты (держателю карты высылается sms-код подтверждения);
- Подтверждение привязки карты через сообщение API ATMOS кода подтверждения;
- Получение токена карты.
Запрос на привязку карты
Запрос:
POST /partner/bind-card/init HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 57
{
"card_number": "8600490744313347",
"expiry": "2410"
}
curl --request POST \
--url https://partner.atmos.uz/partner/bind-card/init \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"card_number": "8600332914249390",
"expiry": "2509"
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"transaction_id": 442,
"phone": "998900222222"
}
Создание заявки на привязку карты. Если все данные верны, возвращает в поле transaction_id значение для дальнейшего подтверждения заявки и высылает sms-код подтверждения держателю карты.
HTTP Request
POST https://partner.atmos.uz/partner/bind-card/init
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| card_number | 16-значный код на лицевой стороне карты | да |
| expiry | дата действительности карты (YYmm) | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | id операции |
| phone | номер телефона держателя карты |
Подтверждение привязки карты
Запрос:
POST /partner/bind-card/confirm HTTP/1.1
Content-Type: application/json
Authorization: Bearer Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 44
{
"transaction_id": 383,
"otp": "111111"
}
curl --request POST \
--url https://partner.atmos.uz/partner/bind-card/confirm \
--header 'Authorization: Bearer Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"transaction_id": 383,
"otp": "111111"
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"data": {
"card_id": 1579076,
"pan": "986009******1840",
"expiry": "2505",
"card_holder": "TEST",
"balance": 1000000000,
"phone": "998989999999",
"card_token": "<card-token>"
}
}
Подтверждает созданную ранее операцию по привязке карты к сервису мерчанта и выдает токен для совершения платежей.
HTTP Request
POST https://partner.atmos.uz/partner/bind-card/confirm
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | номер созданной ранее операции | да |
| otp | код, полученный держателем карты в виде sms | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| data | объект с данными карты |
Запрос звонка для получения кода
Запрос:
PUT /partner/bind-card/dial HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 26
{
"transaction_id": 442
}
curl --request PUT \
--url https://partner.atmos.uz/partner/bind-card/dial \
--header 'Authorization: Bearer <access-token> \
--header 'Content-Type: application/json' \
--data '{
"transaction_id": 442
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
}
}
Звонит держателю карты и сообщает код подтверждения в автоматическом порядке.
HTTP Request
https://partner.atmos.uz/partner/bind-card/dial
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | номер созданной ранее операции | да |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
Список привязанных к мерчанту карт
Запрос:
POST /partner/list-cards HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 32
{
"page": 1,
"page_size": 10
}
curl --request POST \
--url https://partner.atmos.uz/partner/list-cards \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"page": 1,
"page_size": 10
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"card_list": [
{
"card_id": 1579076,
"card_token": "<card-token>",
"pan": "986009******1840",
"expiry": "2505"
}
]
}
Возвращает список всех привязанных к сервису мерчанта карточек.
HTTP Request
https://partner.atmos.uz/partner/list-cards
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| page | номер страницы | нет |
| page_size | кол-во элементов на страницк | нет |
Параметры ответа
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| card_list | массив привязанных к сервису карт |
Аннулировать привязанную карту
Запрос:
POST /partner/remove-card HTTP/1.1
Content-Type: application/json
Authorization: Bearer <bearer-token>
Host: partner.atmos.uz
Content-Length: 64
{
"id": 1666711,
"token": "<card-token>"
}
curl --request POST \
--url https://partner.atmos.uz/partner/remove-card \
--header 'Authorization: Bearer <bearer-token>' \
--header 'Content-Type: application/json' \
--data '{
"id": 1666711,
"token": "<card-token>"
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"data": {
"card_id": 1666711,
"pan": null,
"expiry": null,
"card_holder": null,
"balance": null,
"phone": null,
"card_token": null
}
}
Аннулирует токен ранее привязанной к сервису карты, и дальнейшая оплата по ней становится невозможной.
HTTP Request
https://partner.atmos.uz/partner/remove-card
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| id | id карты | да |
| token | токен карты | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| data | объект с аннулированными данными |
Реккурентные платежи
Поставщики услуг, которые интегрируется к системе ATMOS по API (глубокая интеграция) имеют возможность настроить рекуррентные платежи. Рекуррентные платежи представляют из себя периодическое автосписание определенной суммы в счет оплаты услуг Поставщика.
Внимание! Для пользования API реккурентных платежей, карта должна быть предварительно привязана к сервису.
Подробнее: привязка карт
Создать планировщик
Запрос:
POST /pay-scheduler/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 256
{
"payment": {
"date_start": "2022-12-13",
"date_finish": "2023-12-13",
"login": "998991234567",
"pay_day": 16,
"pay_time": "10:22",
"repeat_interval":2,
"repeat_times":2,
"ext_id": "2410",
"repeat_low_balance": true,
"amount": 751240000,
"cards": "[1666741]",
"store_id": 7777,
"account": "998974445566"
}
}
curl --request POST \
--url https://partner.atmos.uz/pay-scheduler/create \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"payment": {
"date_start": "2022-12-13",
"date_finish": "2023-12-13",
"login": "998991234567",
"pay_day": 16,
"pay_time": "10:22",
"repeat_interval":2,
"repeat_times":2,
"ext_id": "2410",
"repeat_low_balance": true,
"amount": 751240000,
"cards": "[1666741]",
"store_id": 7777,
"account": "998974445566"
}
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"scheduler_id": "12345"
}
Создает планировщик для карты, с возможностью указания суммы, дня списания для каждого месяца, времени дня для списания. При условии нехватки денег на карте, может списывать средства с дополнительно указанных карт. После создания планировщик должен быть подтвержден вызовом следующего метода.
HTTP Request
https://partner.atmos.uz/pay-scheduler/create
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| payment | объект с данными о планировщике | да |
| - date_start | дата создания планировщика | да |
| - date_finish | дата завершения работы планировщика | да |
| - login | номер телефона, к которому привязана карта* | да |
| - pay_day | день месяца для списаний (1-28, last)* | да |
| - pay_time | время оплаты в заданный день. Формат HH24:MI. | да |
| - repeat_interval | интервал повторных попыткок в минутах | да |
| - repeat_times | кол-во повторных попыток списания | да |
| - ext_id | персональный счет клиента в биллинге поставщика | да |
| - repeat_low_balance | повторять ли, в случае, если на балансе недостаточно средств | да |
| - amount | сумма списания в тиинах | да |
| - cards | id карт, с которых произведется списание, если на основной не хватает средств | да |
| - store_id | id мерчанта(store) в системе ATMOS | да |
| - account | идентификатор платежа | да |
Примечания:
Login - номер телефона, к которому привязана карта, можно запросить через метод
https://partner.atmos.uz/card/1/check-card-token;Pay_day - значение last указывает на последний день месяца.
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| scheduler_id | id созданного планировщика |
Подтвердить создание планировщика
Запрос:
POST /pay-scheduler/confirm HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 43
{
"sсheduler_id": 12345,
"otp": "111111"
}
curl --request POST \
--url https://partner.atmos.uz/pay-scheduler/confirm \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"sheduler_id": 12345,
"otp": "111111"
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
}
}
Метод подтверждает и активирует созданный планировщик.
HTTP Request
https://partner.atmos.uz/pay-scheduler/confirm
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| scheduler_id | id созданного ранее планировщика | да |
| otp | код из sms, высланный владельцу карты | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
Удалить или изменить планировщик
Запрос:
POST /pay-scheduler/change HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 256
{
"sсheduler_id": 75127,
"delete": false,
"payment": {
"date_start": "2022-12-13",
"date_finish": "2023-12-13",
"login": "9989881234567",
"pay_day": 16,
"pay_time": "14:14",
"repeat_interval":2,
"repeat_times":10,
"ext_id": "2410",
"repeat_low_balance": true,
"amount": 111110000,
"cards": "[1666741]",
"store_id": 7777,
"account": "998974445566"
}
}
curl --request POST \
--url https://partner.atmos.uz/pay-scheduler/change \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"sсheduler_id": 75127,
"delete": false,
"payment": {
"date_start": "2022-12-13",
"date_finish": "2023-12-13",
"login": "9989881234567",
"pay_day": 16,
"pay_time": "14:14",
"repeat_interval":2,
"repeat_times":10,
"ext_id": "2410",
"repeat_low_balance": true,
"amount": 111110000,
"cards": "[1666741]",
"store_id": 7777,
"account": "998974445566"
}
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"scheduler_id": 12345
}
Метод удаляет или вносит изменения в созданный ранее планировщик.
HTTP Request
https://partner.atmos.uz/pay-scheduler/change
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| scheduler_id | id созданного ранее планировщика | да |
| delete | boolean - если true, планировщик удаляется | да |
| payment | объект с данными о планировщике | да |
| - date_start | дата создания планировщика | нет |
| - date_finish | дата завершения работы планировщика | нет |
| - login | номер телефона, к которому привязана карта* | нет |
| - pay_day | день месяца для списаний (1-28, last)* | нет |
| - pay_time | время оплаты в заданный день. Формат HH24:MI. | нет |
| - repeat_interval | интервал повторных попыткок в минутах | нет |
| - repeat_times | кол-во повторных попыток списания | нет |
| - ext_id | персональный счет клиента в биллинге поставщика | нет |
| - repeat_low_balance | повторять ли, в случае, если на балансе недостаточно средств | нет |
| - amount | сумма списания в тиинах | нет |
| - cards | id карт, с которых произведется списание, если на основной не хватает средств | нет |
| - store_id | id мерчанта(store) в системе ATMOS | нет |
| - account | идентификатор платежа | нет |
Примечания:
Login - номер телефона, к которому привязана карта, можно запросить через метод
https://partner.atmos.uz/card/1/check-card-token;Pay_day - значение last указывает на последний день месяца.
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| scheduler_id | id созданного планировщика |
Холдирование
Холдирование - инструмент по заморозке денежных средств на карте на определенный временной промежуток без списания. ATMOS API позволяет холдировать сумму на счету покупателя и сразу производить списание по мере необходимости. Также, мерчантам доступна отмена холдирования.
Создать заявку на холдирование
Запрос:
POST /hold/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 168
{
"card_token": "<card-token>",
"store_id": "0001",
"account": "12345",
"payment_details": "",
"amount": "50000",
"duration": "1"
}
curl --request POST \
--url https://partner.atmos.uz/hold/create \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"card_token": "<card-token>",
"store_id": "0001",
"account": "12345",
"payment_details": "",
"amount": "50000",
"duration": "1"
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"hold_id": 1173,
"account": null
}
Создает заявку на холдирование, высылает код подтверждения держателю карты(если карта не привязана) и возвращает номер операции, для дальнейшего ее подтверждения.
HTTP Request
POST https://partner.atmos.uz/hold/create
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| card_token | токен карты | +/- |
| card_number | номер карты | +/- |
| card_expiry | срок действия карты(YYmm) | +/- |
| store_id | id мерчанта(store) | да |
| account | идентификатор платежа | да |
| payment_details | детали платежа | нет |
| amount | сумма холдирования в тиинах | да |
| duration | срок холдирования в минутах | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| hold_id | номер созданной операции |
Подтвердить заявку на холдирование
Запрос:
PUT /hold/apply/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 20
{
"otp": "111111"
}
curl --request PUT \
--url https://partner.atmos.uz/hold/apply/{id} \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"otp": "111111"
}'
Пример ответа от сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"hold_id": 1173,
"card_token": "<card-token>",
"card_pan": "986009******1840",
"hold_till": "2022-06-30T14:55:19.597"
}
Подтверждает запрос на холдирование и замораживает средства на карте.
HTTP Request
PUT https://partner.atmos.uz/hold/apply/{id}}
Параметры URL:
| Параметр | Описание | Обязательность |
|---|---|---|
| id | id созданной ранее транзакции | да |
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| otp | код из sms | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| hold_id | номер подтвержденной операции |
| hold_till | дата разморозки средств |
Создать заявку на множественное холдирование
Запрос:
POST /hold/multiple/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 168
{
"card_token": "<card-token>",
"duration": "1",
"items": [
{
"store_id": "<store_id>",
"account": "<account>",
"payment_details": "",
"amount": "1000000"
},
{
"store_id": "<store_id>",
"account": "<account>",
"payment_details": "",
"amount": "1000000"
}
]
}
curl --request POST \
--url https://partner.atmos.uz/hold/multiple/create \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"card_token": "<card-token>",
"duration": "1",
"items": [
{
"store_id": "<store_id>",
"account": "<account>",
"payment_details": "",
"amount": "1000000"
},
{
"store_id": "<store_id>",
"account": "<account>",
"payment_details": "",
"amount": "1000000"
}
]
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"parent_id": 261,
"items": [
{
"result": null,
"hold_id": 1543,
"account": "255432"
},
{
"result": null,
"hold_id": 1544,
"account": "2345645"
}
]
}
Создает заявку на несколько операций(средства за которые могут быть списаны по отдельности) в контексте холдирования общей суммы, высылает код подтверждения держателю карты(если карта не привязана) и возвращает номер операции, для дальнейшего ее подтверждения.
HTTP Request
POST https://partner.atmos.uz/hold/multiple/create
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| card_token | токен карты | +/- |
| duration | срок холдирования в минутах | да |
| items | массив заявок на холдирование | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| parent_id | номер созданной(главной) операции |
| items | массив принятых заявок на холдирование, ожидающих подтверждения |
Подтвердить заявку на множественное холдирование
Запрос:
PUT /hold/multiple/apply/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: partner.atmos.uz
Content-Length: 168
{
"otp": "111111"
}
curl --request PUT \
--url https://partner.atmos.uz/hold/multiple/{id} \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
"otp": "111111"
}'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"parent_id": 260,
"items": [
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"hold_id": 1541,
"card_token": "<card-token>",
"card_pan": "XXXXXXXXXXXXXXXX",
"hold_till": "2022-09-28T16:46:22.762"
},
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"hold_id": 1542,
"card_token": "<card-token>",
"card_pan": "XXXXXXXXXXXXXXXX",
"hold_till": "2022-09-28T16:46:23.118"
}
]
}
Подтверждает ранее созданную заявку на несколько операций в контексте холдирования общей суммы, делая доступным списание средств.
HTTP Request
PUT https://partner.atmos.uz/hold/multiple/{id}
Параметры запроса:
| Параметр | Описание | Обязательность |
|---|---|---|
| otp | стандартное значение "111111", если списание идет по токену карты | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| parent_id | номер главной операции |
| items | массив принятых заявок на холдирование, с их статусами |
Произвести списание захолдированной суммы
Запрос:
POST /hold/{id} HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Host: partner.atmos.uz
curl --request POST \
--url https://partner.atmos.uz/hold/{id} \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
},
"store_transaction": {
"success_trans_id": 000001,
"trans_id": 12345,
"store": {
"id": 0001,
"name": "XXXXX",
"desc": "",
"logo": null,
"ga_id": null
},
"terminal_id": "0000001",
"account": "12345",
"amount": 5000000,
"confirmed": true,
"prepay_time": 1656325395000,
"confirm_time": 1656325681944,
"label": {
"type_id": 64,
"label_ru": "Номер инвойса",
"label_uz": "Invoys raqami",
"label_en": "Number of Invoice"
},
"details": "",
"commission_value": "0",
"commission_type": "0",
"total": 5000000,
"card_id": "<card-token>",
"status_code": "0",
"status_message": "Success"
}
}
Производит оплату за счет захолдированной ранее суммы. Работает при условии того, что время действия холда не истекло.
HTTP Request
POST https://partner.atmos.uz/hold/{id}
Параметры URL:
| Параметр | Описание | Обязательность |
|---|---|---|
| id | id транзакции | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
| transaction_id | номер созданной в системе транзакции |
| store_transaction | объект с детализацией по транзакции |
| - success_trans_id | постоянный номер успешной транзакции |
| - trans_id | номер транзакции |
| - store | объект с данными мерчанта |
| - terminal_id | id терминала через который была создана транзакция |
| - account | идентификатор платежа |
| - amount | сумма транзакции в тиинах |
| - confirmed | подтверждена ли транзакция |
| - prepay_time | время пред-подтверждения транзакции |
| - confirm_time | время подтверждения транзакции |
| - label | Объект с номером и мета-данными инвойса |
| - details | детали транзакции |
| - commission_value | размер комиссии в тиинах |
| - commission_type | сервисное поле |
| - total | итоговая сумма транзакции |
| - card_id | токен карты |
| - status_code | сервисное поле |
| - status_message | статус транзакции |
Отмена холдирования
Запрос:
DELETE /hold/{id} HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Host: partner.atmos.uz
curl --request DELETE \
--url https://partner.atmos.uz/hold/{id} \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json'
Пример ответа сервера:
{
"result": {
"code": "OK",
"description": "Нет ошибок"
}
}
Отменяет ранее созданный холд.
HTTP Request
https://partner.atmos.uz/hold/{id}
Параметры URL:
| Параметр | Описание | Обязательность |
|---|---|---|
| id | id транзакции | да |
Параметры ответа:
| Параметр | Описание |
|---|---|
| result | объект со статусом ответа сервера |
Списание по ПИНФЛ
Для работы с сервисом необходимо получить токен доступа, который устанавливается в заголовки каждого запроса и служит уникальным идентификатором при проведении операций. Подробная информация о процессе авторизации содержится в разделе Авторизация в API
Для нижеперечисленных эндпоинтов, предусмотрен следующий адрес для работы с сервисом
Base URL: https://apigw.atmos.uz/ppa
Создание транзакции (ПИНФЛ)
Запрос:
curl -X POST https://apigw.atmos.uz/ppa/transaction/create \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
"ext_id": "12345789",
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"pinfl": "123456789123456789",
"passport_series": "AA",
"passport_number": "123456789",
"contract_number": "123456",
"amount": 100500,
"partial_debit": true
}'
POST /transaction/create HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>
{
"ext_id": "12345789",
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"pinfl": "123456789123456789",
"passport_series": "AA",
"passport_number": "123456789",
"contract_number": "123456",
"amount": 100500,
"partial_debit": true
}
Пример ответа:
{
"payload": {
"transaction_status": "CREATED",
"transaction_id": "12345678",
"ext_id": "12345789",
"amount": "100500",
"first_name": "Ivan",
"middle_name": "Ivanovich",
"last_name": "Ivanov",
"date_created": "2023-12-12 00:00:00"
},
"code": "200",
"description": "Transaction confirmed"
}
HTTP Request
POST https://apigw.atmos.uz/ppa/transaction/create
Создание транзакции на стороне платформы для дальнейшей работы
Параметры запроса
| название | описание | обязательность |
|---|---|---|
| ext_id | уникальный идентификатор транзакции на стороне клиента | да |
| first_name | имя | да |
| last_name | фамилия | да |
| middle_name | отчество | да |
| pinfl | пинфл | да |
| passport_series | серия паспорта | да |
| passport_number | номер паспорта | да |
| contract_number | номер договора с клиентом | да |
| amount | сумма списания в тиинах | да |
| partial_debit | флаг частичного списания (true/false). по умолчанию - false | нет |
Параметры ответа
| Название | Описание | Обязательность |
|---|---|---|
| code | статус ответа (ok, progress, error) | да |
| description | описание статуса ответа | нет |
| payload | объект с данными о созданной транзакции | да |
Подтверждение транзакции (ПИНФЛ)
Запрос:
curl -X POST https://apigw.atmos.uz/ppa/transaction/confirm \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
"ext_id": "12345789",
"transaction_id": "1113423543"
}'
POST /ppa/transaction/confirm HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>
{
"ext_id": "12345789",
"transaction_id": "1113423543"
}
Пример ответа сервера:
{
"payload": {
"transaction_id": "12345678",
"ext_id": "12345789",
"transaction_status": "SUCCESS",
"details": [
{
"pan": "860066******5544",
"amount": "100",
"upper_commission": "1",
"status": "SUCCESS"
}
]
},
"code": "200",
"description": "Transaction confirmed"
}
Подтверждение списания средств по уникальным идентификаторам транзакции
HTTP Request
POST https://apigw.atmos.uz/ppa/transaction/confirm
Параметры запроса
| Название | Описание | Обязательность |
|---|---|---|
| ext_id | уникальный идентификатор транзакции | да |
| transaction_id | id транзакции на стороне atmos | да |
Параметры ответа
| Название | Описание | Обязательность |
|---|---|---|
| code | статус ответа (ok, progress, error) | да |
| description | описание статуса ответа | нет |
| payload | объект с данными о созданной транзакции | да |
Запрос данных о транзакции
Запрос:
POST /transaction/check HTTP/1.1
Host: apigw.atmos.uz
Authorization: Bearer <access-token>
Content-Type: application/json
{
"ext_id": 12345789,
"pinfl": "123456789123456789",
"passport_series": "AA",
"passport_number": "123456789",
"contract_number": "123456",
"amount": 100500
}
curl -X POST https://apigw.atmos.uz/ppa/transaction/check \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
"ext_id": 12345789,
"pinfl": "123456789123456789",
"passport_series": "AA",
"passport_number": "123456789",
"contract_number": "123456",
"amount": 100500
}'
Пример ответа сервера:
{
"payload": {
"transaction_id": 12345678,
"ext_id": 12345789,
"transaction_status": "SUCCESS",
"details": [
{
"pan": "860066******5544",
"amount": 100,
"upper_commission": 1,
"status": "SUCCESS"
}
]
},
"code": "200",
"description": "Transaction confirmed"
}
Находит транзакцию по указанным реквизитам, и возвращает по ней детализацию
HTTP Request
POST https://apigw.atmos.uz/ppa/transaction/check
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| ext_id | уникальный идентификатор транзакции | да |
| pinfl | пинфл | да |
| passport_series | серия паспорта | да |
| passport_number | номер паспорта | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| code | статус ответа (ok, progress, error) | да |
| description | описание статуса ответа | нет |
| payload | объект с данными о созданной транзакции | да |
Отмена транзакции (ПИНФЛ)
Запрос:
curl -X POST https://apigw.atmos.uz/ppa/transaction/cancel \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
"ext_id": 12345789,
"transaction_id": "1113423543"
}'
POST /ppa/transaction/cancel HTTP/1.1
Host: apigw.atmos.uz
Authorization: Bearer <access-token>
Content-Type: application/json
{
"ext_id": 12345789,
"transaction_id": "1113423543"
}
Пример ответа сервера:
{
"payload": {
"transaction_id": 12345678,
"ext_id": 12345789,
"transaction_status": "CANCELED"
},
"code": "200",
"description": "Transaction Canceled"
}
Отменяет транзакцию в ATMOS.PAY по паре ее уникальных идентификаторов, до того, как она будет подтверждена
HTTP Request
POST https://apigw.atmos.uz/ppa/transaction/cancel
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| ext_id | уникальный идентификатор транзакции | да |
| transaction_id | id транзакции на стороне atmos | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| code | статус ответа (ok, progress, error) | да |
| description | описание статуса ответа | нет |
| payload | объект с данными о созданной транзакции | да |
Эквайринг Visa/Mastercard
Система МПС - это эквайринг платформа, позволяющая юридическим лицам, осуществляющим свою деятельность на территории Республики Узбекистан, принимать платежи с карт Visa и Mastercard.
При подключении к системе, партнеру выдается уникальный API ключ, который должен быть включен в любой запрос, при работе с платформой, в виде заголовка apikey
Base URL: https://apigw.atmos.uz/mps
Авторизация
Запрос:
curl --location 'https://apigw.atmos.uz/mps/auth' \
--header 'apikey: <spi-key>' \
--header 'Content-Type: application/json' \
--data '{
"api_key" : <api-key>
}'
POST /mps/auth HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Content-Type: application/json
{
"api_key": <api-key
}
Пример ответа сервера:
{
"access_token": "string",
"refresh_token": "string",
"expires_in": 1234
}
HTTP Request
POST https://apigw.atmos.uz/mps/auth
Выдает токен доступа при передаче API ключа
Продление срока действия токена
Запрос:
curl -X POST https://apigw.atmos.uz/mps/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "string"
}'
POST /mps/auth/refresh HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
{"refresh_token": "string"}
Пример ответа сервера:
{
"access_token": "string",
"refresh_token": "string",
"expires_in": 1234
}
HTTP Request
POST https://apigw.atmos.uz/mps/auth/refresh
Принимает в теле запроса параметр refresh_token c значением, полученным при авторизации в аналогичном поле ответа сервера, и выдает в результате новый токен, с новым сроком действительности
Привязка карты
Запрос:
curl --location 'https://apigw.atmos.uz/mps/card/bind' \
--header 'apikey: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
"pan": "4278310022884134",
"expiry": "2508",
"card_name": "TEST",
"cvc2": "075",
"client_ip_addr": "192.168.200.01",
"ext_id": "1"
}'
POST /mps/card/bind HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>
apikey: <api-key>
{
"pan": "4278310022884134",
"expiry": "2508",
"card_name": "TEST",
"cvc2": "075",
"client_ip_addr": "192.168.200.01",
"ext_id": "1"
}
Пример ответа сервера:
{
"payload": {
"id": 144,
"status": 1,
"type": "DEFAULT",
"amount": 10000,
"card": {
"id": 67,
"status": true,
"masked_pan": "402306********9999",
"masked_card_holder": "CUSTOMER NAME",
"card_type": "VISA",
"date_created": "2024-03-26 14:28:11",
"date_updated": "2024-03-26 14:28:11",
"verified_state": "PENDING",
"card_region": "DOMESTIC"
},
"api_id": 1,
"card_id": 67,
"external_id": "82b9c105-95f2-45ce-b33a-74ba4ea11ee4",
"mps_ext_id": "r2PlRV8Y8CjwBAM4gzzFcVJ504c=",
"status_ps": "Approved",
"result_code": "Approved",
"masked_pan": "402306********9327",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-03-26 14:28:11",
"date_updated": "2024-03-26 14:28:11",
"redirect_uri": "https://ecomm.kapital24.uz:6443/ecomm2/ClientHandler?trans_id=r2PlRV8Y8CjwBAM4gzzFcVJ504c%3D"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "6602952bd44ca285f56c38255f2c1e15"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/card/bind
Позволяет привязать карту для совершения дальнейших регулярных платежей
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| pan | Номер карты | да |
| expiry | Срок действия карты в формате MMYY | да |
| card_name | Название карты | да |
| cvc2 | Код безопасности карты (CVC2/CVV2) | да |
| client_ip_addr | IP-адрес клиента | да |
| ext_id | Внешний id карты | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о транзакции | да |
| payload.id | Идентификатор транзакции | да |
| payload.status | Статус транзакции | да |
| payload.type | Тип транзакции | да |
| payload.amount | Сумма транзакции в валюте | да |
| payload.card | Объект с данными о карте | да |
| payload.card.id | Идентификатор карты | да |
| payload.card.status | Статус карты | да |
| payload.card.masked_pan | Маскированный номер карты | да |
| payload.card.masked_card_holder | Маскированное имя владельца карты | да |
| payload.card.card_type | Тип карты | да |
| payload.card.date_created | Дата создания карты | да |
| payload.card.date_updated | Дата обновления карты | да |
| payload.card.verified_state | Состояние верификации карты | да |
| payload.card.card_region | Регион карты | да |
| payload.api_id | ID API | да |
| payload.card_id | Идентификатор карты | да |
| payload.external_id | Внешний ID транзакции | да |
| payload.mps_ext_id | MPS внешний ID транзакции | да |
| payload.status_ps | Статус PS | да |
| payload.result_code | Код результата | да |
| payload.client_ip_addr | IP-адрес клиента | да |
| payload.date_created | Дата создания транзакции | да |
| payload.date_updated | Дата обновления транзакции | да |
| payload.redirect_uri | Ссылка для перенаправления клиента после 3DS | да |
| status | Объект с данными о статусе операции | да |
| status.code | Код статуса операции | да |
| status.message | Сообщение статуса операции | да |
| status.trace_id | Идентификатор трассировки операции | да |
Получение деталей привязанной карты
Запрос:
curl --location 'https://apigw.atmos.uz/mps/card/32' \
--header 'apikey: <api-key>' \
--header 'Authorization: Bearer <access-token>'
GET /mps/card/32 HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Пример ответа сервера:
{
"payload": {
"id": 32,
"status": true,
"masked_pan": "427831********4134",
"masked_card_holder": "TEST",
"card_type": "VISA",
"date_created": "2024-02-19T12:37:45.385173Z",
"date_updated": "2024-02-19T12:37:45.385192Z",
"verified_state": "PENDING",
"status_3ds": "FAILED"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "65dd6c72a94bfe3856d7f821e8ac37eb"
}
}
HTTP Request
GET https://apigw.atmos.uz/mps/card/32
Возвращает данные по ранее привязанной к сервису карте
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| id | Идентификатор карты | да |
Параметры ответа
| название | описание | обязательность |
|---|---|---|
| payload | Объект с данными о карте | да |
| id | Идентификатор карты | да |
| status | Статус привязки карты | да |
| masked_pan | Замаскированный номер карты | да |
| masked_card_holder | Замаскированное имя владельца карты | да |
| card_type | Тип карты | да |
| date_created | Дата создания привязки карты | да |
| date_updated | Дата обновления привязки карты | да |
| verified_state | Состояние верификации карты | да |
| status_3ds | Статус 3DS | да |
| status | Объект с данными о статусе операции | да |
| code | Код статуса операции | да |
| message | Сообщение статуса операции | нет |
| trace_id | Идентификатор трассировки операции | да |
Выставление счета
Запрос:
curl -X POST 'https://apigw.atmos.uz/mps/checkout/invoice/create' \
--header 'jAuthorization: <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"request_id": "1231312312",
"store_id": 3,
"expiration_time": 10,
"expiration_date": "2024-07-11T11:12:12",
"account": "DFSDF",
"amount": 100000,
"success_url": "https://atmos.uz",
"items": [
{
"items_id": "1",
"name": "book 1",
"amount": 50000,
"quantity": 3,
"details": {
"name": "some key",
"values": "some value"
}
},
{
"items_id": "2",
"name": "service",
"amount": 50000,
"details": {
"name": "some key 2",
"values": "some value 2"
}
}
]
}'
POST https://apigw.atmos.uz/mps/checkout/invoice/create HTTP/1.1
Host: https://apigw.atmos.uz
jAuthorization: <ACCESS_TOKEN>
Content-Type: application/json
{
"request_id": "1231312312",
"store_id": 3,
"expiration_time": 10,
"expiration_date": "2024-07-11T11:12:12",
"account": "DFSDF",
"amount": 100000,
"success_url": "https://atmos.uz",
"items": [
{
"items_id": "1",
"name": "book 1",
"amount": 50000,
"quantity": 3,
"details": {
"name": "some key",
"values": "some value"
}
},
{
"items_id": "2",
"name": "service",
"amount": 50000,
"details": {
"name": "some key 2",
"values": "some value 2"
}
}
]
}
Пример ответа сервера:
{
"store_id": 3,
"payment_id": 272,
"token": "9Y53Bh_hFirZgxxFqBTwtA==",
"url": "https://checkout.atmos.uz/ru/invoice?id=9Y53Bh_hFirZgxxFqBTwtA==", # ссылка инвойса для открытия в браузере
"status": {
"code": "OK",
"description": "Success"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/checkout/invoice/create
Создает платеж в системе с оплатой через веб-интерфейс (платежная страница). URL платежной страницы будет передан в ответе сервера.
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| request_id | Уникальный идентификатор запроса | да |
| store_id | Идентификатор магазина | да |
| expiration_time | Время до истечения инвойса в минутах | нет |
| expiration_date | Дата и время истечения инвойса в формате YYYY-MM-DDTHH:MM:SS | нет |
| account | Партнерский идентификатор платежа | да |
| amount | Сумма (тийины) | да |
| success_url | Ссылка для редиректа при успешной оплате | да |
| items | Список товаров или услуг | да |
| items[].items_id | Идентификатор товара или услуги | да |
| items[].name | Наименование товара или услуги | да |
| items[].amount | Сумма для товара или услуги (тийины) | да |
| items[].quantity | Количество товара или услуги (если применимо) | нет |
| items[].details | Детали товара или услуги | нет |
| items[].details.name | Название ключа детали товара или услуги | нет |
| items[].details.values | Значение ключа детали товара или услуги | нет |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| store_id | Идентификатор магазина | да |
| payment_id | Идентификатор платежа | да |
| token | Токен инвойса | да |
| url | Ссылка на инвойс для открытия в браузере | да |
| status | Статус ответа | да |
| status.code | Код статуса | да |
| status.description | Описание статуса | да |
Создание транзакции (МПС)
Запрос:
curl --location 'https://apigw.atmos.uz/mps/transaction/create' \
--header 'apikey: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
"pan": "4278310021875430",
"expiry": "2508",
"amount": 10000,
"card_name": "TEST",
"cvc2": "680",
"client_ip_addr": "192.168.200.01",
"ext_id": "64bedd41-f21b-4298-aa88-1206107670b8"
}'
POST /mps/transaction/create HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json
{
"pan": "4278310021875430",
"expiry": "2508",
"amount": 10000,
"card_name": "TEST",
"cvc2": "680",
"client_ip_addr": "192.168.200.01",
"ext_id": "64bedd41-f21b-4298-aa88-1206107670b8"
}
Пример ответа сервера:
{
"payload": {
"id": 144,
"status": 1,
"type": "DEFAULT",
"amount": 10000,
"card": {
"id": 67,
"status": true,
"masked_pan": "402306********9999",
"masked_card_holder": "CUSTOMER NAME",
"card_type": "VISA",
"date_created": "2024-03-26 14:28:11",
"date_updated": "2024-03-26 14:28:11",
"verified_state": "PENDING",
"card_region": "DOMESTIC"
},
"api_id": 1,
"card_id": 67,
"external_id": "82b9c105-95f2-45ce-b33a-74ba4ea11ee4",
"mps_ext_id": "r2PlRV8Y8CjwBAM4gzzFcVJ504c=",
"status_ps": "Approved",
"result_code": "Approved",
"masked_pan": "402306********9327",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-03-26 14:28:11",
"date_updated": "2024-03-26 14:28:11",
"redirect_uri": "https://ecomm.kapital24.uz:6443/ecomm2/ClientHandler?trans_id=r2PlRV8Y8CjwBAM4gzzFcVJ504c%3D"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "6602952bd44ca285f56c38255f2c1e15"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/transaction/create
Создает транзакцию в системе, которая в дальнейшем подлежит подтверждению
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| pan | Номер карты | да |
| expiry | Срок действия карты в формате MMYY | да |
| amount | Сумма транзакции в тиинах | да |
| card_name | Название карты | да |
| cvc2 | Код безопасности карты (CVC2/CVV2) | да |
| client_ip_addr | IP-адрес клиента | да |
| ext_id | Уникальный идентификатор (UUID) транзакции, сгенерированный на стороне клиента | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о транзакции | да |
| payload.id | Идентификатор транзакции | да |
| payload.status | Статус транзакции | да |
| payload.type | Тип транзакции | да |
| payload.amount | Сумма транзакции в валюте | да |
| payload.card | Объект с данными о карте | да |
| payload.api_id | ID API | да |
| payload.card_id | Идентификатор карты | да |
| payload.external_id | Внешний ID транзакции | да |
| payload.mps_ext_id | MPS внешний ID транзакции | да |
| payload.status_ps | Статус PS | да |
| payload.result_code | Код результата | да |
| payload.masked_pan | Маскированный номер карты | да |
| payload.client_ip_addr | IP-адрес клиента | да |
| payload.date_created | Дата создания транзакции | да |
| payload.date_updated | Дата обновления транзакции | да |
| payload.redirect_uri | Ссылка для перенаправления клиента после 3DS | да |
| status | Объект с данными о статусе операции | да |
| status.code | Код статуса операции | да |
| status.message | Сообщение статуса операции | нет |
| status.trace_id | Идентификатор трассировки операции | да |
Подтверждение транзакции (МПС)
Запрос:
curl --location 'https://apigw.atmos.uz/mps/transaction/apply' \
--header 'apikey: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
"transaction_id": 59
}'
POST /mps/transaction/apply HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json
{
"transaction_id": 59
}
Пример ответа сервера:
{
"payload": {
"id": 110,
"status": 4,
"type": "DEFAULT",
"api_id": 1,
"card_id": 36,
"external_id": "c4cea503-4838-440e-aac2-4509e1319f4e",
"mps_ext_id": "I7cQTxAUXz0LPy75q09sldnOzTk=",
"status_ps": "AUTHENTICATED",
"status_3ds": "AUTHENTICATED",
"result_code": "APPROVED",
"masked_pan": "427831********5430",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-02-26 12:13:05",
"date_updated": "2024-02-26 17:13:17"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "65dc805d720e28c6b9194e7fd26fdda7"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/transaction/apply
Подтверждает транзакцию и выполняет оплату. Используется для подтверждения как стандартных транзакций, так и для рекуррентных платежей
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | Идентификатор транзакции | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о транзакции | да |
| id | Идентификатор транзакции | да |
| status | Статус транзакции | да |
| type | Тип транзакции | да |
| api_id | ID API | да |
| card_id | Идентификатор карты | да |
| external_id | Внешний ID транзакции | да |
| mps_ext_id | MPS внешний ID транзакции | да |
| status_ps | Статус PS | да |
| status_3ds | Статус 3DS | да |
| result_code | Код результата | да |
| masked_pan | Маскированный номер карты | да |
| client_ip_addr | IP-адрес клиента | да |
| date_created | Дата создания транзакции | да |
| date_updated | Дата обновления транзакции | да |
| status | Объект с данными о статусе операции | да |
| code | Код статуса операции | да |
| message | Сообщение статуса операции | нет |
| trace_id | Идентификатор трассировки операции | да |
Создание рекуррентного платежа
Запрос:
curl --location 'https://apigw.atmos.uz/mps/transaction/create/template' \
--header 'apikey: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
"card_id": 1,
"amount": 1000,
"client_ip_addr": "192.168.200.201",
"ext_id": "12d649ad-38ac-44c5-8f10-3700bfda5efe"
}'
POST /mps/transaction/create/template HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json
{
"card_id": 1,
"amount": 1000,
"client_ip_addr": "192.168.200.201",
"ext_id": "12d649ad-38ac-44c5-8f10-3700bfda5efe"
}
Пример ответа сервера:
{
"payload": {
"id": 110,
"status": 1,
"type": "TEMPLATE",
"api_id": 1,
"card_id": 36,
"external_id": "c4cea503-4838-440e-aac2-4509e1319f4e",
"mps_ext_id": "I7cQTxAUXz0LPy75q09sldnOzTk=",
"status_ps": "Approved",
"status_3ds": "AUTHENTICATED",
"result_code": "Approved",
"masked_pan": "427831********5430",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-02-26 17:13:05",
"date_updated": "2024-02-26 17:13:05",
"redirect_uri": null
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "65dc805134eb63b90d2e048d1d4fb38a"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/transaction/create/template
Метод создает регулярный платеж в системе. Для успешного создания платежа, передаваемая в запросе карта должна быть ранее привязана к системе, и проведена 3DS верификация при добавлении. Статус 3DS верификации можно проверить методом /card/{id}
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| card_id | Идентификатор карты | да |
| amount | Сумма регулярного платежа в тиинах | да |
| client_ip_addr | IP-адрес клиента | да |
| ext_id | Уникальный идентификатор (UUID) транзакции, сгенерированный на стороне клиента | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о регулярном платеже | да |
| id | Идентификатор регулярного платежа | да |
| status | Статус регулярного платежа | да |
| type | Тип регулярного платежа | да |
| api_id | ID API | да |
| card_id | Идентификатор карты | да |
| external_id | Внешний ID регулярного платежа | да |
| mps_ext_id | MPS внешний ID регулярного платежа | да |
| status_ps | Статус PS регулярного платежа | да |
| status_3ds | Статус 3DS регулярного платежа | да |
| result_code | Код результата регулярного платежа | да |
| masked_pan | Маскированный номер карты | да |
| client_ip_addr | IP-адрес клиента | да |
| date_created | Дата создания регулярного платежа | да |
| date_updated | Дата обновления регулярного платежа | да |
| redirect_uri | Ссылка для перенаправления клиента после 3DS | нет |
| status | Объект с данными о статусе операции | да |
| code | Код статуса операции | да |
| message | Сообщение статуса операции | нет |
| trace_id | Идентификатор трассировки операции | да |
Получение деталей транзакции
Запрос:
curl --location 'https://apigw.atmos.uz/mps/transaction/get/52' \
--header 'apikey: <api-key>' \
--header 'Authorization: Bearer <access-token>'
GET /mps/transaction/get/52 HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json
Пример ответа сервера:
{
"payload": {
"id": 110,
"status": 5,
"type": "DEFAULT",
"api_id": 1,
"card_id": 36,
"external_id": "c4cea503-4838-440e-aac2-4509e1319f4e",
"mps_ext_id": "I7cQTxAUXz0LPy75q09sldnOzTk=",
"status_ps": "Missing mandatory parameters\n",
"status_3ds": "AUTHENTICATED",
"result_code": "Decline",
"masked_pan": "427831********5430",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-02-26 12:13:05",
"date_updated": "2024-02-26 12:13:17"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "65dd6baa145542eebadc9ba6a8f10291"
}
}
HTTP Request
GET https://apigw.atmos.uz/mps/transaction/get/${id}
Возвращает имеющуюся в системе детализацию по запрошенной транзакции
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | Идентификатор транзакции | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о транзакции | да |
| id | Идентификатор транзакции | да |
| status | Статус транзакции | да |
| type | Тип транзакции | да |
| api_id | ID API | да |
| card_id | Идентификатор карты | да |
| external_id | Внешний ID транзакции | да |
| mps_ext_id | MPS внешний ID транзакции | да |
| status_ps | Статус PS транзакции | да |
| status_3ds | Статус 3DS транзакции | да |
| result_code | Код результата транзакции | да |
| masked_pan | Маскированный номер карты | да |
| client_ip_addr | IP-адрес клиента | да |
| date_created | Дата создания транзакции | да |
| date_updated | Дата обновления транзакции | да |
| status | Объект с данными о статусе операции | да |
| code | Код статуса операции | да |
| message | Сообщение статуса операции | нет |
| trace_id | Идентификатор трассировки операции | да |
Получение деталей транзакции по внешнему идентификатору
Запрос:
curl -X POST \
https://apigw.atmos.uz/mps/get/ext_id \
-H 'Content-Type: application/json' \
-d '{
"ext_id": "<ext-id>"
}'
``http POST /mps/get/ext_id HTTP/1.1 Host: apigw.atmos.uz Content-Type: application/json
{
"ext_id": "
> Пример ответа сервера:
```json
{
"payload": {
"id": 131,
"status": 1,
"type": "DEFAULT",
"amount": 10000,
"card": {
"id": 55,
"status": true,
"masked_pan": "427831********9999",
"masked_card_holder": "TEST",
"card_type": "VISA",
"date_created": "2024-03-18 05:27:54",
"date_updated": "2024-03-18 05:27:54",
"verified_state": "PENDING",
"card_region": "ONUS"
},
"api_id": 1,
"card_id": 55,
"external_id": "f6d7c050-1927-43d6-a828-6a22235d6f32",
"mps_ext_id": "E0ZwTIl60PFsSbOz1o8yCwcXEn8=",
"status_ps": "Approved",
"result_code": "Approved",
"masked_pan": "427831********5430",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-03-18 05:27:54",
"date_updated": "2024-03-18 05:27:54"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "66029622c951aa197d8196bd89d65308"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/get/ext_id
возвращает данные транзакции по ее внешнему ключу
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| ext_id | Внешний идентификатор транзакции | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о транзакции | да |
| payload.id | Идентификатор транзакции | да |
| payload.status | Статус транзакции | да |
| payload.type | Тип транзакции | да |
| payload.amount | Сумма транзакции в валюте | да |
| payload.card | Объект с данными о карте | да |
| payload.card.id | Идентификатор карты | да |
| payload.card.status | Статус карты | да |
| payload.card.masked_pan | Маскированный номер карты | да |
| payload.card.masked_card_holder | Маскированное имя владельца карты | да |
| payload.card.card_type | Тип карты | да |
| payload.card.date_created | Дата создания карты | да |
| payload.card.date_updated | Дата обновления карты | да |
| payload.card.verified_state | Состояние верификации карты | да |
| payload.card.card_region | Регион карты | да |
| payload.api_id | ID API | да |
| payload.card_id | Идентификатор карты | да |
| payload.external_id | Внешний ID транзакции | да |
| payload.mps_ext_id | MPS внешний ID транзакции | да |
| payload.status_ps | Статус PS | да |
| payload.result_code | Код результата | да |
| payload.client_ip_addr | IP-адрес клиента | да |
| payload.date_created | Дата создания транзакции | да |
| payload.date_updated | Дата обновления транзакции | да |
| status | Объект с данными о статусе операции | да |
| status.code | Код статуса операции | да |
| status.message | Сообщение статуса операции | да |
| status.trace_id | Идентификатор трассировки операции | да |
Отмена платежа (МПС)
Запрос:
curl --location 'https://apigw.atmos.uz/mps/transaction/cancel' \
--header 'apikey: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
"transaction_id": 52
}'
POST /mps/transaction/cancel HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json
{
"transaction_id": 52
}
Пример ответа сервера:
{
"payload": {
"id": 110,
"status": 5,
"type": "DEFAULT",
"api_id": 1,
"card_id": 36,
"external_id": "c4cea503-4838-440e-aac2-4509e1319f4e",
"mps_ext_id": "I7cQTxAUXz0LPy75q09sldnOzTk=",
"status_ps": "Missing mandatory parameters\n",
"status_3ds": "AUTHENTICATED",
"result_code": "Decline",
"masked_pan": "427831********5430",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-02-26 12:13:05",
"date_updated": "2024-02-26 12:13:17"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "65dd6baa145542eebadc9ba6a8f10291"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/transaction/cancel
Отменяет совершенный ранее платеж без удержаний из суммы платежа.
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | Идентификатор транзакции для отмены | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о результирующей транзакции | да |
| id | Идентификатор транзакции | да |
| status | Статус транзакции | да |
| type | Тип транзакции | да |
| api_id | ID API | да |
| card_id | Идентификатор карты | да |
| external_id | Внешний ID транзакции | да |
| mps_ext_id | Внешний ID MPS транзакции | да |
| status_ps | Статус платежной системы | да |
| status_3ds | Статус 3DS | да |
| result_code | Код результата | да |
| masked_pan | Маскированный номер карты | да |
| client_ip_addr | IP-адрес клиента | да |
| date_created | Дата создания транзакции | да |
| date_updated | Дата обновления транзакции | да |
| status | Объект с данными о статусе операции | да |
| code | Код статуса операции | да |
| message | Сообщение статуса операции | нет |
| trace_id | Идентификатор трассировки операции | да |
Возврат платежа (МПС)
Запрос:
curl --location 'https://apigw.atmos.uz/mps/transaction/revert' \
--header 'apikey: <api-key>' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"transaction_id": 52
}'
POST /mps/transaction/revert HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json
{
"transaction_id": 52
}
Пример ответа сервера:
{
"payload": {
"id": 110,
"status": 5,
"type": "DEFAULT",
"api_id": 1,
"card_id": 36,
"external_id": "c4cea503-4838-440e-aac2-4509e1319f4e",
"mps_ext_id": "I7cQTxAUXz0LPy75q09sldnOzTk=",
"status_ps": "Missing mandatory parameters\n",
"status_3ds": "AUTHENTICATED",
"result_code": "Decline",
"masked_pan": "427831********5430",
"client_ip_addr": "192.168.200.01",
"date_created": "2024-02-26 12:13:05",
"date_updated": "2024-02-26 12:13:17"
},
"status": {
"code": 0,
"message": "Success",
"trace_id": "65dd6baa145542eebadc9ba6a8f10291"
}
}
HTTP Request
POST https://apigw.atmos.uz/mps/transaction/revert
Возвращает совершенный ранее платеж.
Параметры запроса
| Параметр | Описание | Обязательность |
|---|---|---|
| transaction_id | Идентификатор транзакции для возврата | да |
Параметры ответа
| Параметр | Описание | Обязательность |
|---|---|---|
| payload | Объект с данными о результирующей транзакции | да |
| id | Идентификатор транзакции | да |
| status | Статус транзакции | да |
| type | Тип транзакции | да |
| api_id | ID API | да |
| card_id | Идентификатор карты | да |
| external_id | Внешний ID транзакции | да |
| mps_ext_id | Внешний ID MPS транзакции | да |
| status_ps | Статус платежной системы | да |
| status_3ds | Статус 3DS | да |
| result_code | Код результата | да |
| masked_pan | Маскированный номер карты | да |
| client_ip_addr | IP-адрес клиента | да |
| date_created | Дата создания транзакции | да |
| date_updated | Дата обновления транзакции | да |
| status | Объект с данными о статусе операции | да |
| code | Код статуса операции | да |
| message | Сообщение статуса операции | нет |
| trace_id | Идентификатор трассировки операции | да |
Системные статусы и ошибки
В случае ошибок ATMOS API возвращает общепринятые статусы, которые приведены в таблице ниже:
| Статус ответа | Значение |
|---|---|
| 400 | Bad Request -- Запрос содержит ошибку. |
| 401 | Unauthorized -- Вы не авторизованы в системе. |
| 403 | Forbidden -- Доступ запрещен. |
| 404 | Not Found -- Удовлетворяющих результатов не найдено. |
| 405 | Method Not Allowed -- Метода не существует. |
| 429 | Too Many Requests -- Слишком много запросов. |
| 500 | Internal Server Error -- На стороне сервера произошла ошибка. Попробуйте позже. |
| 503 | Service Unavailable -- Сервис временно недоступен. |
Ошибки при совершении транзакций
| Код ошибки | Описание ошибки |
|---|---|
| STPIMS-ERR-001 | Внутренняя ошибка |
| STPIMS-ERR-003 | Неправильный партнер |
| STPIMS-ERR-004 | Карта не найдена |
| STPIMS-ERR-005 | Карта не подключена к номеру |
| STPIMS-ERR-006 | Требуемые параметры не найдены |
| STPIMS-ERR-007 | Неправильный формат параметра |
| STPIMS-ERR-008 | Карта не зарегистрирована |
| STPIMS-ERR-009 | Неправильные параметры |
| STPIMS-ERR-010 | Учетная запись не существует |
| STPIMS-ERR-011 | Неправильные опции для платежа |
| STPIMS-ERR-012 | Неправильный id транзакции |
| STPIMS-ERR-013 | Неправильные данные пользователя |
| STPIMS-ERR-014 | Неправильная попытка входа |
| STPIMS-ERR-015 | Неправильная регистрация |
| STPIMS-ERR-016 | Неправильный платеж |
| STPIMS-ERR-017 | Неактивный партнер |
| STPIMS-ERR-021 | Неправильный номер телефона |
| STPIMS-ERR-022 | Мобильный оператор не работает |
| STPIMS-ERR-023 | Сервис не найден |
| STPIMS-ERR-024 | Нет соединения с банком |
| STPIMS-ERR-025 | Банк не найден |
| STPIMS-ERR-026 | Попробуйте позже |
| STPIMS-ERR-027 | Соединитесь с администратором |
| STPIMS-ERR-028 | Отказ в соединении с банком |
| STPIMS-ERR-029 | Незарегистрированный банк |
| STPIMS-ERR-030 | Карта не найдена в банке |
| STPIMS-ERR-031 | Превышен лимит запросов |
| STPIMS-ERR-032 | Агент не найден |
| STPIMS-ERR-033 | Телефонный номер не соответствует |
| STPIMS-ERR-034 | Транзакция не прошла |
| STPIMS-ERR-037 | Не найден ID магазина |
| STPIMS-ERR-039 | Неверная сумма для платежа |
| STPIMS-ERR-042 | Не разрешенная сумма платежа |
| STPIMS-ERR-043 | Банковская Карта не найдена |
| STPIMS-ERR-044 | Магазин с текущим ID не найден |
| STPIMS-ERR-048 | Номер уже зарегистрирован |
| STPIMS-ERR-050 | Карта не может быть зарегистрирована |
| STPIMS-ERR-051 | Информация не найдена |
| STPIMS-ERR-053 | Мобильный префикс не найден |
| STPIMS-ERR-054 | Больше двух мобильных обновлений |
| STPIMS-ERR-055 | Номера не найдены |
| STPIMS-ERR-056 | Проблема при авторизации |
| STPIMS-ERR-057 | Недостаточно средств |
| STPIMS-ERR-058 | Карта заблокирована |
| STPIMS-ERR-060 | Не зарегистрированный пользователь |
| STPIMS-ERR-061 | Запрашиваемая транзакция не найдена |
| STPIMS-ERR-062 | Неправильный запрос |
| STPIMS-ERR-064 | Оплата отменена |
| STPIMS-ERR-065 | Оплата в процессе |
| STPIMS-ERR-066 | Вы недавно оплатили на этот лицевой счет, попробуйте позже |
| STPIMS-ERR-067 | Срок действия вашей карты истек. Просим обратиться в банк. |
| STPIMS-ERR-068 | Свяжитесь с эмитентом. Просим обратиться в банк. |
| STPIMS-ERR-069 | Обнаружена подозрительная карта. Просим обратиться в банк. |
| STPIMS-ERR-070 | Отказано в транзакции. Просим обратиться в банк. |
| STPIMS-ERR-072 | Ваши операции запрещены. Просим обратиться в банк. |
| STPIMS-ERR-073 | Ваша карта является утерянной. Просим обратиться в банк. |
| STPIMS-ERR-074 | Что-то не так с вашей картой. Просим обратиться в банк. |
| STPIMS-ERR-075 | Что-то не так с вашей картой. Просим обратиться в банк. |
| STPIMS-ERR-076 | Карта недействительна. Просим обратиться в банк. |
| STPIMS-ERR-077 | Что-то не так с вашей картой. Просим обратиться в банк. |
| STPIMS-ERR-078 | Что-то не так с вашей картой. Просим обратиться в банк. |
| STPIMS-ERR-079 | Ваша карта заблокирована (не активированная). Просим обратиться в банк. |
| STPIMS-ERR-080 | Превышено количество попыток ввода PIN кода. Просим обратиться в банк. |
| STPIMS-ERR-081 | Принудительная смена PIN-кода. Просим обратиться в банк. |
| STPIMS-ERR-082 | Ваша карта заблокирована по причине задолженности по кредиту. Просим обратиться в банк. |
| STPIMS-ERR-083 | Виртуальная карта не активирована |
| STPIMS-ERR-084 | По данной карте доступны только PIN-транзакции |
| STPIMS-ERR-085 | Ваша карта не персонифицирована. Просим обратиться в банк. |
| STPIMS-ERR-086 | Что-то не так с вашей картой. Просим обратиться в банк. |
| STPIMS-ERR-087 | Временно заблокировано пользователем |
| STPIMS-ERR-088 | Данная карта заблокирована пользователем. Просим обратиться в банк. |
| STPIMS-ERR-089 | Не подключено SMS-информирование. Просим подключить SMS-информирование |
| STPIMS-ERR-090 | Карта с данным номером не найдена. Неверно указана дата истечения срока вашей карты. |
| STPIMS-ERR-092 | Транзакция закрыта |
| STPIMS-ERR-093 | Ошибка в системе биллинга поставщика |
| STPIMS-ERR-094 | Нет связи с ЕОПЦ |
| STPIMS-ERR-095 | Пользователь заблокирован |
| STPIMS-ERR-097 | Карта существует |
| STPIMS-ERR-098 | OTP код указан неверно |
| STPIMS-ERR-099 | Данные EPOS не указаны |
| STPIMS-ERR-100 | Запрашиваемая транзакция ранее была отменена |
| STPIMS-ERR-101 | Транзакция не отменилась |
| STPIMS-ERR-102 | СМС не отправилось, скорее всего СМС шлюз не доступен |
| STPIMS-ERR-103 | Терминал не найден |
| STPIMS-ERR-104 | P2P переводы отключены для данного банка |
| STPIMS-ERR-105 | Пользователь и карта не взаимосвязанны |
| STPIMS-ERR-106 | Некорректный формат СМС |
| STPIMS-ERR-107 | Рассрочка / Автоплатеж / Кредит не найден |
| STPIMS-ERR-108 | Некорретные данные платежа |
| STPIMS-ERR-109 | Данные EPOS некорректы |
| STPIMS-ERR-111 | Карты отправителя и получателя не должны быть идентичными |
| STPIMS-ERR-112 | Недостаточно средств на балансе карты для проведения платежа |
| STPIMS-ERR-113 | Платеж закрыт |
| STPIMS-ERR-114 | Платеж закрыт |
| STPIMS-ERR-116 | Ошибка при получении информации по карте |
| STPIMS-ERR-117 | Неправильный номер карты |
| STPIMS-ERR-118 | Статус платежа неизвестен |
| STPIMS-ERR-120 | Оплата временно невозможна |
| STPIMS-ERR-121 | Перевод в обработке |
| STPIMS-ERR-124 | Ключ сессии пользователя не создан |
| STPIMS-ERR-125 | Сессия пользователя не удалена |
| STPIMS-ERR-127 | У партнера не добавлено ни одной карты, либо карта неактивна |
| STPIMS-ERR-128 | Указанный номер счета не найден в указанной транзакции |
| STPIMS-ERR-130 | При создании планировщика необходимо указать карту для списания |
| STPIMS-ERR-134 | Не указана карта отправителя |
| STPIMS-ERR-135 | Не указана карта получателя |
| STPIMS-ERR-136 | Переводы с использованием корпоративных карт запрещены |
| STPIMS-ERR-137 | Переводы с использованием корпоративных карт запрещены |
| STPIMS-ERR-138 | Ежемесячный лимит превышен для p2p |
| STPIMS-ERR-139 | Одноразовый лимит превышен для p2p |
| STPIMS-ERR-140 | Одноразовый лимит превышен для p2p |
| STPIMS-ERR-142 | Холдирование не подтверждено |
| STPIMS-ERR-143 | Холдирование не снято |
| STPIMS-ERR-144 | Время холдирования истекло |
| INFO-201 | Код подтверждения отправлен на номер СМС-информирования |
| INFO-202 | Платеж в обработке |
Эквайринг VISA/MASTERCARD(МПС) - системные ошибки
| Код | Описание | Комментарий |
|---|---|---|
| 0 | Успех | Операция завершилась успешно |
| -1 | Внутренняя ошибка | Обратитесь к администратору, произошла системная ошибка |
| -20 | Терминал не найден | Терминал не найден или не зарегистрирован. Обратитесь к администратору |
| -11 | Транзакция находится в неопределенном состоянии | Транзакция не может быть продолжена. Зависит от выполняемой операции и состояния транзакции |
| -12 | Транзакция не найден | Транзакция не найдена по заданному идентификатору |
| -100 | В процессинге произошла ошибка | В процессинге произошла ошибка |
| -200 | Карта не найдена | Карта не найдена |
| -201 | Карта неверифицирована | Карта не прошла 3DS верификацию |
Эквайринг VISA/MASTERCARD(МПС) - системные статусы
| Статус | Описание |
|---|---|
| 1 | Транзакция создана |
| 2 | Ожидание статуса создания транзакции |
| 3 | Ожидание статуса подтверждения транзакции |
| 4 | Подтверждение транзакции |
| 5 | Транзакция завершилась неуспешно |
| 6 | Отмена транзакции завершилась успешно |
| 7 | Возврат транзакции завершился успешно |
| 8 | Ожидание статуса отмены транзакции |
| 9 | Ожидание статуса возврата транзакции |
Эквайринг VISA/MASTERCARD(МПС) - состояния 3DS верификации
| Статус | Описание |
|---|---|
| PENDING | Ожидание 3DS верификации карты |
| VERIFIED | 3DS верификация прошла успешно |
| FAILED | 3DS верификация завершилась неуспешно |
Песочница
Для тестирования и интеграции с API рекомендуется использование тестовых платежных данных. Все операции, проводимые с приведенными картами имеют демонстративный характер, и не подразумевают списание настоящих денежных средств.
Тестовые карты:
PAN:
8600490744313347Expiry:10/24PAN:
8600332914249390Expiry:09/25PAN:
8600492993407481Expiry:10/24PAN:
8600312990314318Expiry:08/23PAN:
9860090101431907Expiry:05/25
Тестовые карты для отладки ошибок:
PAN:
8600312987000557Expiry:12/22- ошибка на стороне процессингаPAN:
8600493214116133Expiry:10/24- не подключено SMS информированиеPAN:
8600492986215602Expiry:03/20- истек срок действия картыPAN:
8600312998546358Expiry:10/23- недостаточно средств на балансе
Callback API
Callback API - механизм согласования с мерчантом проводимых транзакций. При проведении каждой транзакции система ATMOS обращается в биллинговую систему мерчанта, и передает ей данные платежа в формате JSON. Только после получения успешного статуса со стороны мерчанта сумма будет списана.
Для Поставщика услуг в системе ATMOS предоставляется api_key для проверки входящих сообщений.
Отправляемые данные
Callback API отправляет в систему поставщика следующие данные:
| Параметр | Значение |
|---|---|
| store_id | ID мерчанта |
| transaction_id | ID транзакции |
| transaction_time | время оплаты |
| amount | сумма оплаты |
| invoice | идентификатор оплаченного инвойса |
| sign | уникальная цифровая подпись |
{
"status": 1,
"message": "Успешно"
}
{
"status": 0,
"message": "Инвойс с номером 123 отсутствует в системе"
}
Примеры ответа биллинга поставщика(мерчанта)
Callback API подтверждает оплату только в том случае, если ответ от биллинга мерчанта имеет значение параметра status 1 и код ответа 200. Примеры ответов приведены в области сбоку
| Параметр | Значение |
|---|---|
| status | статус ответа |
| message | текстовое сообщение(детали статуса) |
Последовательность действий
Следуя изложенной информации, можно пошагово описать приницип работы механизма Callback API следующим образом:
- На стороне ATMOS формируется платеж и запускается процесс оплаты;
- Перед подтверждением оплаты система ATMOS обращается к биллингу мерчанта, отправляя данные платежа(см. отправляемые данные);
- Мерчант подтверждает или отклоняет оплату (см. примеры ответа биллинга поставщика(мерчанта))
- Транзакция завершена
Альтернативные виды оплаты
HTML-виджет
Оплата через виджет - решение для упрощенной интеграции с платежным сервисом ATMOS. Платежный виджет предоставляет возможность принимать оплаты на стороне сайта мерчанта, через сгенерированный специальный виджет оплаты. Виджет оплаты создается через конструктор, с указанием необходимых параметров, которые будут приведены ниже.
Инструкция по установке виджета на сайт
Встраиваемый код:
<!-- тег head -->
<script src="https://cdn.pays.uz/checkout/js/v1.0.1/test-checkout.js">
</script>
<!-- тег head -->
<div id="parent-frame">
<script th:inline="javascript">
/*<![CDATA[*/
paymo_open_widget({
parent_id: "parent-frame", // id html-элемента для встраивания виджета
store_id: 0, // уникальный id вашего store
account: "abc", // идентификатор платежа
terminal_id: 0, // id терминала(если есть)
success_redirect: "url", // адрес перенаправления после успешной оплаты
fail_redirect: "url", // адрес перенаправления после неудачной оплаты
version: "1.0.0", // версия виджета
amount: 500000, //сумма платежа в тиинах
details: "string", // детали платежа (строка)
lang:"ru", // язык виджета (en, ru, uz)
key: // ключ авторизации,
theme: "blue" // Цвет виджета
});
/*]]>*/
</script>
<div/>
Встройте на Вашу страницу html-тег
<script src="url"></script>. В атрибуте src тега script укажите url получения скрипта:- на время тестирования:
http://cdn.pays.uz/checkout/js/v1.0.1/test-checkout.js - на принятие реальных оплат:
https://cdn.pays.uz/checkout/js/v1.0.1/checkout.js
- на время тестирования:
Встройте в html разметку Вашего сайта приведенный в боковой панели код;
Укажите параметры, необходимые для работы виджета;
Виджет готов к использованию.
Параметры виджета
| Параметр | Описание | Обязательность |
|---|---|---|
| parent_id | id html-элемента для встраивания виджета | да |
| store_id | id вашего store | да |
| account | идентификатор платежа(прозизв.строка) | да |
| terminal_id | id терминала(если есть) | нет |
| success_redirect | url адрес перенаправления после успешной оплаты | да |
| fail_redirect | url адрес перенаправления при неудачной оплате | да |
| version | версия виджета | нет |
| amount | сумма платежа в тиинах | да |
| details | детали платежа (прозизв.строка) | нет |
| lang | язык виджета (en, ru, uz) | нет |
| key | ключ авторизации | да |
| theme | цветовое оформление виджета | нет |
Платежная странца
Платежная странца - наиболее удобное решение для мобильных приложений, поддерживающих webview. Представляет из себя безопасную оплату на стороне ATMOS.
Для оплаты создания через платежную страницу требутся:
- вызвать метод
/merchant/pay/createи создать драфт транзакции для оплаты; - перейти на страницу оплаты, с указанием следующих параметров:
- storeId - уникальный id вашего store;
- transactionId - id созданной ранее транзакции;
- redirectLink - url для перенаправления после оплаты(необязательно).
В итоге, сгенерированная ссылка должна иметь подобный вид:
https://test-checkout.pays.uz/invoice/get?storeId=1111&transactionId=222222&redirectLink=http://site.com
Тестовая страница(песочница): http://test-checkout.pays.uz/invoice/get
Платежная страница(production): https://checkout.pays.uz/invoice/get