NAV
HTTP cURL

Введение

Общая информация

Универсальная платформа приема платежей ATMOS позволяет мерчантам интегрировать свой сайт или мобильное приложение к платежнему шлюзу в целях организации приема платежей с банковских карт UzCard и Humo. Интеграция с платежной платформой ATMOS возможна следующими путями:

Начало работы

API работает по протоколу REST, формат всех сообщений - JSON. Для начала работы с API, мерчанту необходимо получить от ATMOS следующие данные:

Также, перед началом работы, необходимо ознакомиться с принципом действия 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 позволяет проводить оплаты следующими путями:

  1. Путем отправки одноразового кода подтверждения при каждом платеже держателю карты;
  2. Через привязку карты к мерчанту, для дальнейших списаний без надобности подтверждения и ввода реквизитов.

Каждый запрос(для эндпоинтов раздела "Оплаты") может содержать в своем теле необязательное поле lang, для выбора языка получаемых текстовых данных от сервера.

Для поля lang являются допустимыми значения: uz, ru, en.

В теле каждого ответа(для эндпоинтов раздела "Оплаты") содержится объект result с полями:

Создание транзакции

Запрос:

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-код для подтверждения транзакции держателю карты.

  1. Для списания по одноразовому SMS-коду подтверждения используйте поля card_number и expiry.

  2. Для списания по ранее привязанной к сервису карте, достаточно использовать поле 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-код для подтверждения транзакции держателю карты.

  1. Для списания по одноразовому SMS-коду подтверждения используйте поля card_number и expiry.

  2. Для списания по ранее привязанной к сервису карте, достаточно использовать поле 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-код каждой транзакции. Привязка карты проводится в приведенной последовательности:

  1. Заявка на создание токена карты (держателю карты высылается sms-код подтверждения);
  2. Подтверждение привязки карты через сообщение API ATMOS кода подтверждения;
  3. Получение токена карты.

Запрос на привязку карты

Запрос:

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 идентификатор платежа да

Примечания:

  1. Login - номер телефона, к которому привязана карта, можно запросить через метод https://partner.atmos.uz/card/1/check-card-token;

  2. 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 идентификатор платежа нет

Примечания:

  1. Login - номер телефона, к которому привязана карта, можно запросить через метод https://partner.atmos.uz/card/1/check-card-token;

  2. 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 рекомендуется использование тестовых платежных данных. Все операции, проводимые с приведенными картами имеют демонстративный характер, и не подразумевают списание настоящих денежных средств.

Тестовые карты:

  1. PAN: 8600490744313347 Expiry: 10/24

  2. PAN: 8600332914249390 Expiry: 09/25

  3. PAN: 8600492993407481 Expiry: 10/24

  4. PAN: 8600312990314318 Expiry: 08/23

  5. PAN: 9860090101431907 Expiry: 05/25

Тестовые карты для отладки ошибок:

  1. PAN: 8600312987000557 Expiry: 12/22 - ошибка на стороне процессинга

  2. PAN: 8600493214116133 Expiry: 10/24 - не подключено SMS информирование

  3. PAN: 8600492986215602 Expiry: 03/20 - истек срок действия карты

  4. 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/>

  1. Встройте на Вашу страницу 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

  2. Встройте в html разметку Вашего сайта приведенный в боковой панели код;

  3. Укажите параметры, необходимые для работы виджета;

  4. Виджет готов к использованию.

Параметры виджета

Параметр Описание Обязательность
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.

Для оплаты создания через платежную страницу требутся:

  1. вызвать метод /merchant/pay/create и создать драфт транзакции для оплаты;
  2. перейти на страницу оплаты, с указанием следующих параметров:
    • 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

HTTP cURL