Введение
Общая информация
Универсальная платформа приема платежей 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 |
Пред-подтверждение транзакции
Запрос:
POST /merchant/pay/pre-confirm 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-confirm \
--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-confirm
Параметры запроса
Параметр | Описание | Обязательность |
---|---|---|
card_token | Токен карты | +/- |
card_number | Номер карты | +/- |
expiry | срок действия карты (ггММ) | +/- |
store_id | id мерчанта(store) | да |
transaction_id | номер созданной прежде транзакции | да |
Параметры ответа
Параметр | Описание |
---|---|
result | объект со статусом ответа сервера |
Подтверждение транзакции
Запрос:
POST /merchant/pay/confirm 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/confirm \
--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/confirm
Параметры запроса
Параметр | Описание | Обязательность |
---|---|---|
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-confirm 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-confirm \
--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-confirm
Параметры запроса
Параметр | Описание | Обязательность |
---|---|---|
card_token | Токен карты | +/- |
card_number | Номер карты | +/- |
expiry | срок действия карты (ггММ) | +/- |
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/confirm 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/confirm \
--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/confirm
Параметры запроса
Параметр | Описание | Обязательность |
---|---|---|
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/confirm-with-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/confirm-with-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/confirm-with-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/confirm
клиент не получил в теле ответа объект 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/confirm
клиент не получил в теле ответа объект 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/create 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/create \
--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/create
Параметры запроса
Параметр | Описание | Обязательность |
---|---|---|
card_number | 16-значный код на лицевой стороне карты | да |
expiry | дата действительности карты (ггММ) | да |
Параметры ответа
Параметр | Описание |
---|---|
result | объект со статусом ответа сервера |
transaction_id | id операции |
phone | номер телефона держателя карты |
Подтверждение привязки карты
Запрос:
POST /partner/bind-card/apply 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/apply \
--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/apply
Параметры запроса
Параметр | Описание | Обязательность |
---|---|---|
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/ 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/ \
--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/
Параметры запроса:
Параметр | Описание | Обязательность |
---|---|---|
card_token | токен карты | +/- |
card_number | номер карты | +/- |
card_expiry | срок действия карты | +/- |
store_id | id мерчанта(store) | да |
account | идентификатор платежа | да |
payment_details | детали платежа | нет |
amount | сумма холдирования в тиинах | да |
duration | срок холдирования в минутах | да |
Параметры ответа:
Параметр | Описание |
---|---|
result | объект со статусом ответа сервера |
hold_id | номер созданной операции |
Подтвердить заявку на холдирование
Запрос:
PUT /hold/{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/{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/{id}}
Параметры URL:
Параметр | Описание | Обязательность |
---|---|---|
id | id созданной ранее транзакции | да |
Параметры запроса:
Параметр | Описание | Обязательность |
---|---|---|
otp | код из sms | да |
Параметры ответа:
Параметр | Описание |
---|---|
result | объект со статусом ответа сервера |
hold_id | номер подтвержденной операции |
hold_till | дата разморозки средств |
Создать заявку на множественное холдирование
Запрос:
POST /hold/multiple 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 \
--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
Параметры запроса:
Параметр | Описание | Обязательность |
---|---|---|
card_token | токен карты | +/- |
duration | срок холдирования в минутах | да |
items | массив заявок на холдирование | да |
Параметры ответа:
Параметр | Описание |
---|---|
result | объект со статусом ответа сервера |
parent_id | номер созданной(главной) операции |
items | массив принятых заявок на холдирование, ожидающих подтверждения |
Подтвердить заявку на множественное холдирование
Запрос:
PUT /hold/multiple/{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 | объект со статусом ответа сервера |
Системные ошибки
В случае ошибок 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 | Платеж в обработке |
Песочница
Для тестирования и интеграции с API рекомендуется использование тестовых платежных данных. Все операции, проводимые с приведенными картами имеют демонстративный характер, и не подразумевают списание настоящих денежных средств.
Тестовые карты:
PAN:
8600490744313347
Expiry:10/24
PAN:
8600332914249390
Expiry:09/25
PAN:
8600492993407481
Expiry:10/24
PAN:
8600312990314318
Expiry:08/23
PAN:
9860090101431907
Expiry:05/25
Тестовые карты для отладки ошибок:
PAN:
8600312987000557
Expiry:12/22
- ошибка на стороне процессингаPAN:
8600493214116133
Expiry:10/24
- не подключено SMS информированиеPAN:
8600492986215602
Expiry:03/20
- истек срок действия картыPAN:
8600312998546358
Expiry:10/23
- недостаточно средств на балансе
Callback API
Callback API - механизм согласования с мерчантом проводимых транзакций. При проведении каждой транзакции система ATMOS обращается в биллинговую систему мерчанта, и передает ей данные платежа в формате JSON. Только после получения успешного статуса со стороны мерчанта сумма будет списана.
Для Поставщика услуг в системе ATMOS предоставляется api_key для проверки входящих сообщений.
Отправляемые данные
Callback API отправляет в систему поставщика следующие данные:
Параметр | Значение |
---|---|
store_id | ID мерчанта |
transaction_id | ID транзакции |
transaction_time | время оплаты |
amount | сумма оплаты |
sign | уникальная цифровая подпись |
Альтернативные виды оплаты
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