Introduction

General information

The universal payment acceptance platform ATMOS allows merchants to integrate their website or mobile application with the payment gateway to enable the acceptance of payments from UzCard and Humo bank cards. Integration with the ATMOS payment platform can be achieved through the following methods:

Initiating the payment widget on the client side;
Making a payment by redirecting to the payment page;
API integration and processing payments on the merchant's external client;

Getting started

The API operates using the REST protocol, with all messages formatted in JSON. To begin working with the API, the merchant needs to obtain the following data from ATMOS:

Consumer key
Consumer secret

Also, before getting started, it is necessary to familiarize yourself with the operating principle of the Callback API.

Test data

The sandbox section provides test data for integration and familiarization with the system's functionality.

Authorization in API

To work with the ATMOS API, you need to obtain an access token, which is set in the headers of each request and serves as a unique identifier when conducting payment operations. Below are the instructions for obtaining the API access token.

Obtaining a token

To get a bearer token:

  curl --location --request POST 'https://apigw.atmos.uz/token?grant_type=client_credentials' \
--header 'Authorization: Basic Base64(consumer-key:consumer-secret)'

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(consumer-key:consumer-secret)
Host: apigw.atmos.uz
Content-Length: 29

//form-data
grant_type=client_credentials

Sample response:

{
  "access_token": "<access_token>",
  "scope": "am_application_scope default",
  "token_type": "Bearer",
  "expires_in": 2525
}

HTTP Request

POST https://apigw.atmos.uz/token

Takes as a parameter an encrypted string in base64 format according to the formula - Base64 (consumer_key + ':' + consumer_secret). The server's response will return an access token, which is valid for 3600 seconds (1 hour).

Token update

To update a bearer token:

  curl --location 'https://apigw.atmos.uz/token' \
--header 'Authorization: Basic Base64(consumer-key:consumer-secret)' \
--header 'Content-Length: 29' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'refresh_token=<access_token>'

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(consumer-key:consumer-secret)
Host: apigw.atmos.uz
Content-Length: 29

//form-data
grant_type=client_credentials
refresh_token=<access_token>

Sample response:

{
  "access_token": "<access_token>",
  "scope": "am_application_scope default",
  "token_type": "Bearer",
  "expires_in": 2525
}

HTTP Request

POST https://apigw.atmos.uz/token

It has similar functionality to the previous method, except that it extends the validity period of an already issued token.

Revoke a token

To revoke a bearer token:

curl --request POST \
  --url https://apigw.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: apigw.atmos.uz
Content-Length: 29

//form-data
token=<access_token>

Sample response:

{
  "access_token": "<access_token>",
  "scope": "am_application_scope default",
  "token_type": "Bearer",
  "expires_in": 2525
}

HTTP Request

POST https://apigw.atmos.uz/revoke

Revokes the previously issued token.

Payments

The ATMOS API allows payments to be processed through the following methods:

By sending a one-time verification code to the cardholder for each payment;
By linking the card to the merchant for future charges without requiring confirmation or re-entering card details.

Each request (for endpoints in the "Payments" section) may contain an optional lang field in its body to select the language of the textual data received from the server.

For the lang field, the following values are permissible: uz, ru, en.

The body of each response (for endpoints in the "Payments" section) contains a result object with fields:

code - "OK" for successful requests, or a string containing the error number (see System Errors);
description - "No errors" for successful requests, or a string containing the error description.

Transaction creating

Request:

curl --request POST \
  --url https://apigw.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: apigw.atmos.uz
Content-Length: 123

{
   "amount": 5000000,
   "account": "12345",
     "terminal_id": "XXXXXXXX",
   "store_id": "XXXX",
   "lang": "ru"
}

Sample response:

{
  "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
  }
}

Creates a draft transaction in the system for subsequent pre-confirmation and final confirmation, and returns the number of the created operation.

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/create

Request parameters

Parameter	Description	Obligation
amount	payment amount in tiyins	yes
account	payment identifier	yes
terminal_id	merchant terminal ID	no
store_id	merchant ID	yes
lang	server response language	no

Response parameters

Parameter	Description
result	object with server response status
transaction_id	number of the transaction created in the system
store_transaction	object with transaction details
- terminal_id	ID of the terminal through which the transaction was created
- account	payment identifier
- amount	transaction amount in tiyns
- confirmed	whether the transaction is confirmed
- prepay_time	transaction pre-confirmation time
- confirm_time	transaction confirmation time
- label	object with invoice number and metadata
- details	transaction details
- commission_value	commission amount in tiyins
- commission_type	service field
- total	total transaction amount
- card_id	in this case null
- status_code	in this case null
- status_message	in this case null

Transaction pre-confirmation

Request:

POST merchant/pay/pre-apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>
Host: apigw.atmos.uz
Content-Length: 102

{
    "card_token": "<card-token>",
    "store_id": 0000,
    "transaction_id": 00000
}

curl --request POST \
  --url https://apigw.atmos.uz/merchant/pay/pre-apply \
  --header 'Authorization: <access_token \
  --header 'Content-Type: application/json' \
  --data '{
    "card_token": "<card-token>",
    "store_id": 0000,
    "transaction_id": 00000
}'

Sample response:

{
  "transaction_id": 202072,
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  }
}

Accepts the number of the created transaction and prepares it for debiting funds. If the card number and expiration date are provided to the method, it sends a one-time SMS code to the cardholder for transaction confirmation.

To process a payment using a one-time SMS confirmation code, use the card_number and expiry fields.
To charge a card previously linked to the service, simply use the card_token field without the card_number and expiry field.

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/pre-apply

Request parameters

Parameters	Description	Obligation
card_token	card token	+/-
card_number	card number	+/-
expiry	card expiration date (YYmm)	+/-
store_id	merchant ID (store)	yes
transaction_id	number of previously created transaction	yes

Response parameters

Parameter	Description
transaction_id	transaction ID
result	object with server response status

Transaction verification

Request:

POST /merchant/pay/apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 63

{
    "transaction_id": 00000,
    "otp": 111111,
    "store_id": 0000
}

curl --request POST \
  --url https://apigw.atmos.uz/merchant/pay/apply \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 00000,
    "otp": 111111,
    "store_id": 0000
}'

Sample response:

{
  "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": "https://ofd2.atmos.uz/api/ofd/bUFLd0Erc2NyTEJMWGFyQlNaRUdRZz09",
  "ofd_url_commission": "https://ofd2.atmos.uz/api/ofd-commission/bUFLd0Erc2NyTEJMWGFyQlNaRUdRZz09"
}

Confirms the transaction and transfers funds from the card to the merchant's terminal.

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/apply

Request parameters

Parameters	Description	Obligation
otp	SMS code	yes
store_id	merchant ID	yes
transaction_id	number of previously created transaction	yes

Response parameters

Parameter	Obligation
result	server response status object
transaction_id	number of the transaction created in the system
store_transaction	object with transaction details
- success_trans_id	permanent number of a successful transaction
- trans_id	transaction number
- store	object with merchant data
- terminal_id	ID of the terminal through which the transaction was created
- account	payment identifier
- amount	transaction amount in tiyins
- confirmed	whether the transaction is confirmed
- prepay_time	transaction pre-confirmation time
- confirm_time	transaction confirmation time
- label	object with invoice number and metadata
- details	transaction details
- commission_value	commission amount in tiyins
- commission_type	service field
- total	total transaction amount
- card_id	card token
- status_code	service field
- status_message	transaction status
ofd_url	link to the fiscal receipt for goods/services
ofd_url_comission	link to the fiscal receipt (commission)

Multitransaction creating

Request:

POST /merchant/bulk/pay/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.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://apigw.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"
        }
    ]
}'

Sample response:

{
  "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
    }
  ]
}

Creates a draft multi-transaction in the system for further pre-confirmation and final confirmation, and returns the number of the created operation. Allows multiple payments (including to different terminals) within a single debit.

HTTP Request

POST https://apigw.atmos.uz/merchant/bulk/pay/create

Request parameter

Parameter	Description	Obligation
amount	Payment amount in tiyns	yes
params	Array of created transaction data	yes
- account	Payment identifier	yes
- terminal_id	Merchant's terminal ID	no
- store_id	Merchant's ID (store)	yes
- lang	Server response language	no

Response parameters

Parameter	Description
result	server response status object
transaction_id	number of the transaction created in the system
store_transaction	array of objects with transaction details
- terminal_id	ID of the terminal through which the transaction was created
- account	payment identifier
- amount	transaction amount in tiyins
- confirmed	whether the transaction is confirmed
- prepay_time	transaction pre-confirmation time
- confirm_time	transaction confirmation time
- label	object with invoice number and metadata
- details	transaction details
- commission_value	commission amount in tiyins
- commission_type	service field
- total	total transaction amount
- card_id	in this case null
- status_code	in this case null
- status_message	in this case null

Pre-confirmation of a multi-transaction

Request:

POST merchant/bulk/pay/pre-apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>
Host: apigw.atmos.uz
Content-Length: 102

{
    "card_token": "<card-token>",
    "store_id": 0000,
    "transaction_id": [00000, 11111]
}

curl --request POST \
  --url https://apigw.atmos.uz/merchant/bulk/pay/pre-apply \
  --header 'Authorization: <access_token \
  --header 'Content-Type: application/json' \
  --data '{
    "card_token": "<card-token>",
    "store_id": 0000,
    "transaction_id": [00000, 11111]
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  }
}

Accepts the number of the created multi-transaction and prepares it for debiting funds. If the card number and expiration date are provided to the method, it sends a one-time SMS code to the cardholder for transaction confirmation.

To process a payment using a one-time SMS confirmation code, use the card_number and expiry fields.
To charge a card previously linked to the service, simply use the card_token field without the card_number and expiry field.

HTTP Request

POST https://apigw.atmos.uz/merchant/bulk/pay/pre-apply

Request parameters

Parameter	Description	Obligation
card_token	Card token	+/-
card_number	Card number	+/-
expiry	Card expiration date	+/-
store_id	Merchant ID (store)	yes
transaction_id	Number of previously created transaction	yes

Response parameters

Parameter	Description
result	server response status object

Request:

curl --request POST \
  --url https://apigw.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"
        }
    ]
}'

Multi-transaction verification

Request:

POST merchant/bulk/pay/apply HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 63

{
  "store_id": 000,
  "otp": "111111",
  "transaction_id": [11111, 22222]
}

curl --request POST \
  --url https://apigw.atmos.uz/merchant/bulk/pay/apply \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "store_id": 000,
  "otp": "111111",
  "transaction_id": [11111, 22222]
}
'

Sample response:

{
  "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"
    }
  ]
}

Confirms the multi-transaction and debits funds from the card to the merchant's (store) terminals.

HTTP Request

POST https://apigw.atmos.uz/merchant/bulk/pay/apply

Request parameters

Parameter	Description	Obligation
otp	SMS code	yes
store_id	merchant ID	yes
transaction_id	previously created transaction number	yes

Response parameters

Parameter	Description
result	Object with server response status
transaction_id	number of the transaction created in the system
store_transaction	array of objects with detailed transaction information
- success_trans_id	permanent number of a successful transaction
- trans_id	transaction number
- store	object with merchant data
- terminal_id	ID of the terminal through which the transaction was created
- account	payment identifier
- amount	transaction amount in tiyins
- confirmed	whether the transaction is confirmed
- prepay_time	transaction pre-confirmation time
- confirm_time	transaction confirmation time
- label	Object with invoice number and metadata
- details	transaction details
- commission_value	commission amount in tiyins
- commission_type	service field
- total	total transaction amount
- card_id	card token
- status_code	service field
- status_message	transaction status

Repeated confirmation code request

Request:

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
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "transaction_id": 10000
}

Resends the SMS confirmation code to the cardholder.

HTTP Request

POST https://api.atmos.uz/merchant/pay/otp-resend

Request parameters

Parameters	Description	Obligation
transaction_id	previously created transaction number	yes

Response parameters

Parameters	Description
transaction_id	transaction number for which the confirmation code was resent

Transaction cancellation

Request:

POST /merchant/pay/reverse HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 54

{
    "transaction_id": 000001,
    "reason": "Something"
}

curl --request POST \
  --url https://apigw.atmos.uz/merchant/pay/reverse \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 000001,
    "reason": "Something"
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "transaction_id": 000001
}

Cancels a previously paid transaction and refunds the money to the card.

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/reverse

Request parameters

Parameter	Description	Obligation
transaction_id	number of the transaction to be canceled	yes
hold_amount	amount held in tiyins	no
reason	reason for transaction cancellation	no

Response parameters

Parameter	Description
transaction_id	cancelled transaction number

Retrieving transaction information

Request:

POST /merchant/pay/get HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 47

{
    "store_id": 0001,
    "transaction_id": 51827
}

curl --request POST \
  --url https://apigw.atmos.uz/merchant/pay/get \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "store_id": 0001,
    "transaction_id": 51827
}'

Sample response:

{
  "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"
  }
}

Request data for a previously created/confirmed/closed transaction. This method is also used if, after the merchant/pay/apply request, the client did not receive the result object in the response body (due to a network interruption, the service not responding within the client-specified timeout, or receiving a bus error). In such cases, it is necessary to check the transaction status using this method.

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/get

Request parameters

Parameter	Description	Obligation
store_id	Merchant ID (store) in the ATMOS system	yes
transaction_id	requested transaction number	yes

Response parameters

Parameter	Description
result	server response status object
store_transaction	object with transaction details
- success_trans_id	permanent successful transaction number
- trans_id	transaction number
- store	object with merchant data
- terminal_id	ID of the terminal through which the transaction was created
- account	payment identifier
- amount	transaction amount in tiyins
- confirmed	whether the transaction is confirmed
- prepay_time	transaction pre-confirmation time
- confirm_time	transaction confirmation time
- label	object with invoice number and metadata
- details	transaction details
- commission_value	commission amount in tiyins
- commission_type	service field
- total	total transaction amount
- card_id	card token
- status_code	service field
- status_message	transaction status

Creating a Partial Reversal

Creates a request for a partial reversal of the amount for a previously confirmed transaction.
Used when it is necessary to return part of the funds to the cardholder. The method creates an operation in the system, which must be confirmed by calling the additional method "Confirm Partial Reversal".

Request:

POST /merchant/pay/create-reverse-partial HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz


{
  "transaction_id": 12764764,
  "store_id": 10370,
  "amount": 100000,
  "reason": "Test",
  "request_id": "test-req",
  "lang": "RU"
}

curl --request POST   --url https://apigw.atmos.uz/merchant/pay/create-reverse-partial   --header 'Authorization: Bearer <access-token>'   --header 'Content-Type: application/json'   --data '{
    "transaction_id": 12764764,
    "store_id": 10370,
    "amount": 100000,
    "reason": "Test",
    "request_id": "test-req",
    "lang": "RU"
}'

Response example:

{
  "transaction_id": 12764764,
  "transaction_partial_reverse_id": 3,
  "result": {
    "code": "OK",
    "description": "No errors"
  },
  "request_id": "test-req"
}

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/create-reverse-partial

Request Parameters

Parameter	Description	Required
transaction_id	transaction number	yes
store_id	merchant (store) ID	yes
amount	partial reversal amount in tiyin	yes
reason	reversal reason	no
request_id	request identifier	no
lang	response language (RU/UZ/EN)	no

Response Parameters

Parameter	Description
transaction_id	transaction number
transaction_partial_reverse_id	created partial reversal number
result	server response status object
request_id	request identifier (if provided)

Confirming a Partial Reversal

Confirms a previously created partial reversal and finalizes the refund.

Request:

POST /merchant/pay/confirm-reverse-partial HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz

{
  "transaction_id": 12764764,
  "transaction_partial_reverse_id": 3,
  "store_id": 10370,
  "ofd_items": [
    {
      "name": "stringName",
      "ofd_code": "stringCode",
      "amount": 100000,
      "details": [
        {
          "key": "stringKey",
          "value": "stringValue",
          "description": "stringDesc",
          "status": 1,
          "type": 0
        }
      ]
    }
  ],
  "request_id": "test-req",
  "lang": "RU"
}

curl --request POST   --url https://apigw.atmos.uz/merchant/pay/confirm-reverse-partial   --header 'Authorization: Bearer <access-token>'   --header 'Content-Type: application/json'   --data '{
    "transaction_id": 12764764,
    "transaction_partial_reverse_id": 3,
    "store_id": 10370,
    "ofd_items": [
      {
        "name": "stringName",
        "ofd_code": "stringCode",
        "amount": 100000,
        "details": [
          {
            "key": "stringKey",
            "value": "stringValue",
            "description": "stringDesc",
            "status": 1,
            "type": 0
          }
        ]
      }
    ],
    "request_id": "test-req",
    "lang": "RU"
}'

Response example:

{
  "transaction_id": 12764764,
  "transaction_partial_reverse_id": 3,
  "transaction_reverted_amount": 100000,
  "transaction_left_amount": 100000,
  "result": {
    "code": "OK",
    "description": "No errors"
  },
  "request_id": "test-req"
}

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/confirm-reverse-partial

Request Parameters

Parameter	Description	Required
transaction_id	transaction number	yes
transaction_partial_reverse_id	partial reversal number	yes
store_id	merchant (store) ID	yes
ofd_items	array of OFD items	yes
- name	item name	yes
- ofd_code	OFD code	yes
- amount	item amount in tiyin	yes
- details	metadata array	no
--- key	metadata key	no
--- value	metadata value	no
--- description	description	no
--- status	status (int)	no
--- type	type (int)	no
request_id	request identifier	no
lang	response language (RU/UZ/EN)	no

Response Parameters

Parameter	Description
transaction_id	transaction number
transaction_partial_reverse_id	partial reversal number
transaction_reverted_amount	successfully reverted amount
transaction_left_amount	remaining amount after reversal
result	server response status object
request_id	request identifier (if provided)

Retrieving Partial Reversal Information

Returns the current status and amounts for the partial reversal.

Request:

POST /merchant/pay/get-reverse-partial HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz

{
  "transaction_id": 12764764,
  "transaction_partial_reverse_id": 3,
  "store_id": 10370,
  "lang": "RU"
}

curl --request POST   --url https://apigw.atmos.uz/merchant/pay/get-reverse-partial   --header 'Authorization: Bearer <access-token>'   --header 'Content-Type: application/json'   --data '{
    "transaction_id": 12764764,
    "transaction_partial_reverse_id": 3,
    "store_id": 10370,
    "lang": "RU"
}'

Response example:

{
  "transaction_id": 12764764,
  "transaction_partial_reverse_id": 3,
  "transaction_reverted_amount": 100000,
  "transaction_left_amount": 100000,
  "result": {
    "code": "OK",
    "description": "No errors"
  },
  "request_id": "test-req"
}

HTTP Request

POST https://apigw.atmos.uz/merchant/pay/get-reverse-partial

Request Parameters

Parameter	Description	Required
transaction_id	transaction number	yes
transaction_partial_reverse_id	partial reversal number	yes
store_id	merchant (store) ID	yes
lang	response language (RU/UZ/EN)	no

Response Parameters

Parameter	Description
transaction_id	transaction number
transaction_partial_reverse_id	partial reversal number
transaction_reverted_amount	successfully reverted amount
transaction_left_amount	remaining amount after reversal
result	server response status object
request_id	request identifier (if provided earlier)

Card linking

Linking cards can be useful in mobile apps, web services, and platforms where regular debiting is required, or where payment is simply needed without verification via an SMS code for each transaction. The card is linked in the following sequence:

Application for card token creation (an SMS confirmation code is sent to the cardholder);
Confirmation of card linking through the ATMOS API using the confirmation code;
Receiving the card token.

Request to link a card

Request:

POST /partner/bind-card/init HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 57

{
    "card_number": "8600490744313347",
    "expiry": "2410"
}

curl --request POST \
  --url https://apigw.atmos.uz/partner/bind-card/init \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "card_number": "8600332914249390",
    "expiry": "2509"
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "transaction_id": 442,
  "phone": "998900222222"
}

Creation of a card linking request. If all data is correct, it returns a value in the transaction_id field for further confirmation of the request and sends an SMS confirmation code to the cardholder.

HTTP Request

POST https://apigw.atmos.uz/partner/bind-card/init

Request parameters

Parameter	Description	Obligation
card_number	16-digit code on the front of the card	yes
expiry	card expiration date (YYmm)	yes

Response parameters

Parameter	Description
result	object with server response status
transaction_id	operation ID
phone	cardholder's phone number

Card linking confirmation

Request:

POST /partner/bind-card/confirm HTTP/1.1
Content-Type: application/json
Authorization: Bearer Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 44

{
    "transaction_id": 383,
    "otp": "111111"
}

curl --request POST \
  --url https://apigw.atmos.uz/partner/bind-card/confirm \
  --header 'Authorization: Bearer Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": 383,
    "otp": "111111"
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "data": {
    "card_id": 1579076,
    "pan": "986009******1840",
    "expiry": "2505",
    "card_holder": "TEST",
    "balance": 1000000000,
    "phone": "998989999999",
    "card_token": "<card-token>"
  },
  "transaction_id": 4789
}

Confirms the previously created operation of linking the card to the merchant's service and issues a token for making payments.

HTTP Request

POST https://apigw.atmos.uz/partner/bind-card/confirm

Request parameters

Parameter	Description	Obligation
transaction_id	number of previously created operation	yes
otp	code received by the cardholder as an SMS	yes

Response parameters

Parameter	Description
result	object with server response status
data	object with card data
transaction_id	transaction ID

List of merchant-linked cards

Request:

POST /partner/list-cards HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 32

{
    "page": 1,
    "page_size": 10
}

curl --request POST \
  --url https://apigw.atmos.uz/partner/list-cards \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "page_size": 10
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "cardDataSmallList": [
    {
      "card_id": 1579076,
      "card_token": "<card-token>",
      "pan": "986009******1840",
      "expiry": "2505"
    }
  ]
}

Returns a list of all cards linked to the merchant's service.

HTTP Request

https://apigw.atmos.uz/partner/list-cards

Request parameters

Parameter	Description	Obligation
page	page number	no
page_size	number of items per page	no

Response parameters

Parameter	Description
result	object with server response status
cardDataSmallList	array of cards linked to the service

Cancel linked card

Request:

POST /partner/remove-card HTTP/1.1
Content-Type: application/json
Authorization: Bearer <bearer-token>
Host: apigw.atmos.uz
Content-Length: 64

{
    "id": 1666711,
    "token": "<card-token>"
}

curl --request POST \
  --url https://apigw.atmos.uz/partner/remove-card \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 1666711,
    "token": "<card-token>"
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "data": {
    "card_id": 1666711,
    "pan": null,
    "expiry": null,
    "card_holder": null,
    "balance": null,
    "phone": null,
    "card_token": null
  }
}

Cancels the token of the card previously linked to the service, making further payments with it impossible.

HTTP Request

https://apigw.atmos.uz/partner/remove-card

Request parameters:

Parameter	Description	Obligation
id	card ID	yes
token	card token	yes

Response parameters:

Parameter	Description
result	server response status object
data	object with nullified data

Holding

Holding is a mechanism for freezing funds on a card for a specified time period without debiting them. The ATMOS API allows merchants to place a hold on a specific amount in the buyer's account and immediately debit it as needed. Additionally, merchants have the option to cancel the hold.

Create a hold request

Request:

POST /hold/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.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://apigw.atmos.uz/hold/create \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "card_token": "<card-token>",
    "store_id": "0001",
    "account": "12345",
    "payment_details": "",
    "amount": "50000",
    "duration": "1"
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "hold_id": 1173,
  "account": null
}

Creates a hold request, sends a confirmation code to the cardholder (if the card is not linked), and returns the operation number for further confirmation.

HTTP Request

POST https://apigw.atmos.uz/hold/create

The method can accept a previously linked card and vice versa. To create a hold without linking a card, use the card_number and card_expiry fields. In the case of a linked card, only the card_token is required.

Request parameters:

Parameter	Description	Obligation
card_token	card token	+/-
card_number	card number	+/-
card_expiry	card expiration date (YYmm)	+/-
store_id	merchant ID (store)	yes
account	payment identifier	yes
payment_details	payment details	no
amount	hold amount in tiyins	yes
duration	hold duration in minutes	yes

Response parameters:

Parameter	Description
result	object with server response status
hold_id	number of the created operation

Confirm holding request

Request:

PUT /hold/apply/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 20

{
    "otp": "111111"
}

curl --request PUT \
  --url https://apigw.atmos.uz/hold/apply/{id} \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "otp": "111111"
}'

Server response sample:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "hold_id": 1173,
  "card_token": "<card-token>",
  "card_pan": "986009******1840",
  "hold_till": "2022-06-30T14:55:19.597"
}

Confirms the hold request and freezes funds on the card.

HTTP Request

PUT https://apigw.atmos.uz/hold/apply/{id}}

In cases where holding is performed using a card token, the otp field must contain the value 111111.

URL parameters:

Parameter	Description	Obligation
id	previously created transaction id	yes

Request parameters:

Parameter	Description	Obligation
otp	SMS code	yes

Response parameters:

Parameter	Description
result	object with server response status
hold_id	confirmed transaction number
hold_till	date of funds unfreezing

Create a request for multiple holding

Request:

POST /hold/multiple/create HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.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://apigw.atmos.uz/hold/multiple/create \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "card_token": "<card-token>",
    "duration": "1",
    "items": [
        {
        "store_id": "<store_id>",
        "account": "<account>",
        "payment_details": "",
        "amount": "1000000"
        },
        {
        "store_id": "<store_id>",
        "account": "<account>",
        "payment_details": "",
        "amount": "1000000"
        }
    ]
}'

Sample response:

{
  "result": {
    "code": "OK",
    "description": "Нет ошибок"
  },
  "parent_id": 261,
  "items": [
    {
      "result": null,
      "hold_id": 1543,
      "account": "255432"
    },
    {
      "result": null,
      "hold_id": 1544,
      "account": "2345645"
    }
  ]
}

Creates a request for multiple transactions (for which funds can be debited separately) within the context of holding the total amount, sends a confirmation code to the cardholder (if the card is not linked), and returns the transaction number for subsequent confirmation.

HTTP Request

POST https://apigw.atmos.uz/hold/multiple/create

Request parameters:

Parameter	Description	Obligation
card_token	card token	+/-
duration	holding period in minutes	yes
items	array of holding requests	yes

Response parameters:

Parameter	Description
result	object with server response status
parent_id	number of the created (main) operation
items	array of accepted hold requests awaiting confirmation

Confirm application for multiple holding

Request:

PUT /hold/multiple/apply/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>
Host: apigw.atmos.uz
Content-Length: 168

{
    "otp": "111111"
}

curl --request PUT \
  --url https://apigw.atmos.uz/hold/multiple/apply/{id} \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
      "otp": "111111"
}'

Sample response:

{
  "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"
    }
  ]
}

Confirms a previously created request for multiple transactions within the context of holding a total amount, enabling the deduction of funds.

HTTP Request

PUT https://apigw.atmos.uz/hold/multiple/apply/{id}

Further debiting of funds or cancellation of multi-holding is performed through the standard endpoints POST https://apigw.atmos.uz/hold/{id} and DELETE https://apigw.atmos.uz/hold/{id}.

Request parameters:

Parameter	Description	Obligation
otp	standard value "111111" if the debit is processed using the card token	yes

Response parameters:

Parameter	Description
result	object with server response status
parent_id	main operation number
items	array of accepted hold requests, with their statuses

Withdraw the held amount

Request:

POST /hold/{id} HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Host: apigw.atmos.uz
Content-Length: 168

{
    "amount": 5000000
}

curl --request POST \
  --url https://apigw.atmos.uz/hold/{id} \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
      "amount": 5000000
  }'

Sample response:

{
  "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"
  },
  "ofd_url": "https://ofd2.atmos.uz/api/ofd/blU3NTZPMGZOZGZyMkZPMWtqN1lGZz09",
  "ofd_url_commission": "https://ofd2.atmos.uz/api/ofd-commission/blU3NTZPMGZOZGZyMkZPMWtqN1lGZz09"
}

Makes payment using the previously held amount. Works on the condition that the hold period has not expired.

HTTP Request

POST https://apigw.atmos.uz/hold/{id}

URL parameters:

Parameter	Description	Obligation
id	transaction ID	yes

Request parameters

Parameter	Description	Required
amount	Modified holding amount (must not exceed the previously held amount)	no

Response parameters:

Parameter	Description
result	object with server response status
transaction_id	number of the transaction created in the system
store_transaction	object with transaction details
- success_trans_id	permanent number of the successful transaction
- trans_id	transaction number
- store	object with merchant data
- terminal_id	ID of the terminal through which the transaction was created
- account	payment identifier
- amount	transaction amount in tiyins
- confirmed	whether the transaction is confirmed
- prepay_time	transaction pre-confirmation time
- confirm_time	transaction confirmation time
- label	object with invoice number and metadata
- details	transaction details
- commission_value	commission amount in tiyins
- commission_type	service field
- total	total transaction amount
- card_id	card token
- status_code	service field
- status_message	transaction status
ofd_url	link to the fiscal receipt for goods/services
ofd_url_comission	link to the fiscal receipt (commission)

Holding cancellation

Request:

DELETE /hold/24888 HTTP/1.1
Host: apigw.atmos.uz
Authorization: Bearer <access-token>
Content-Type: application/json
Content-Length: 26

{
  "send_cancel_sms": true
}

curl --location --request DELETE 'https://apigw.atmos.uz/hold/24888' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "send_cancel_sms": true
}'

Sample response:

{
  "result": {
    "code": "STPIMS-ERR-145",
    "description": "холдирование отменено"
  },
  "status": -242,
  "processing": "UZCARD"
}

Cancels a previously created hold.

HTTP Request

DELETE https://apigw.atmos.uz/hold/{id}

URL parameters:

Parameter	Description	Obligation
id	transaction ID	yes

Request parameters:

Parameter	Description	Obligation
send_cancel_sms	send SMS notifications for hold cancellations	yes

Response parameters:

Parameter	Description
result	server response status object
status	detailed status according to reference guide
processing	card holder's processing center

Request for holding operation data

Request:

GET /hold/{id} HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Host: apigw.atmos.uz

curl --request GET \
  --url https://apigw.atmos.uz/hold/{id} \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json'

Sample response:

{
  "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"
  }
}

Returns data for a previously created hold operation

HTTP Request

GET https://apigw.atmos.uz/hold/{id}

URL parameters:

Parameter	Description	Obligation
id	transaction ID	yes

Response parameters:

Parameter	Description
result	object with server response status
store_transaction	object with transaction details
- success_trans_id	permanent successful transaction number
- trans_id	transaction number
- store	object with merchant data
- terminal_id	ID of the terminal through which the transaction was created
- account	payment identifier
- amount	transaction amount in tiyins
- confirmed	whether the transaction is confirmed
- prepay_time	transaction pre-confirmation time
- confirm_time	transaction confirmation time
- label	object with invoice number and metadata
- details	transaction details
- commission_value	commission amount in tiyins
- commission_type	service field
- total	total transaction amount
- card_id	card token
- status_code	service field
- status_message	transaction status

Withdrawal by TIN(PINFL)

To work with the service, you need to obtain an access token, which is set in the headers of each request and serves as a unique identifier when performing operations. Detailed information about the authorization process can be found in the Authorization in API section.

The following address is provided for working with the service for the endpoints listed below

Base URL: https://apigw.atmos.uz/ppa

Transaction creation (PINFL)

Request:

curl -X POST https://apigw.atmos.uz/ppa/transaction/create \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
  "ext_id": "12345789",
  "first_name": "Ivan",
  "last_name": "Ivanov",
  "middle_name": "Ivanovich",
  "pinfl": "123456789123456789",
  "passport_series": "AA",
  "passport_number": "123456789",
  "contract_number": "123456",
  "amount": 100500,
  "partial_debit": true,
  "ofd_items": {
        "ofd_code": "ofd_code_exm",
        "package_code": "123456",
        "tin" : "100100100"
    },
  "epos": {
        "branch_id": "branch_id",
        "terminal_group_id": "terminal_group_id"
    }
}'

POST /transaction/create HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "ext_id": "12345789",
  "first_name": "Ivan",
  "last_name": "Ivanov",
  "middle_name": "Ivanovich",
  "pinfl": "123456789123456789",
  "passport_series": "AA",
  "passport_number": "123456789",
  "contract_number": "123456",
  "amount": 100500,
  "partial_debit": true,
  "ofd_items": {
        "ofd_code": "ofd_code_exm",
        "package_code": "123456",
        "tin" : "100100100"
    },
  "epos": {
        "branch_id": "branch_id",
        "terminal_group_id": "terminal_group_id"
    }
}

Sample response:

{
  "payload": {
    "available_balance": 123456789,
    "transaction_status": "CREATED",
    "transaction_id": "12345678",
    "ext_id": "12345789",
    "amount": "100500",
    "first_name": "Ivan",
    "middle_name": "Ivanovich",
    "last_name": "Ivanov",
    "date_created": "2023-12-12 00:00:00"
  },
  "code": "200",
  "description": "Transaction confirmed"
}

HTTP Request

POST https://apigw.atmos.uz/ppa/transaction/create

Creation of a transaction on the platform side for further processing

Request parameters

name	description	obligation
ext_id	customer-side unique transaction identifier	yes
first_name	first name	yes
last_name	last name	yes
middle_name	patronymic	yes
pinfl	pinfl	yes
passport_series	passport series	yes
passport_number	passport number	yes
contract_number	customer contract number	yes
amount	withdrawal amount in tiyins	yes
partial_debit	partial debit flag (true/false). default - false	no
ofd_items	OFD data	no
ofd_items.ofd_code	OFD code	no
ofd_items.package_code	marking code	no
ofd_items .tin	TIN	no
epos	epos data and partner branch from which the withdrawal is made	no
epos.branch_id	partner's branch/department id	no
epos.terminal_group_id	partner's terminal group id	no

Response parameters

Name	Description	Obligation
code	response status (ok, progress, error)	yes
description	response status description	no
payload	transaction data object	yes
available_balance	current card balance	yes

Transaction confirmation (PINFL)

Request:

curl -X POST https://apigw.atmos.uz/ppa/transaction/confirm \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
  "ext_id": "12345789",
  "transaction_id": "1113423543"
}'

POST /ppa/transaction/confirm HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "ext_id": "12345789",
  "transaction_id": "1113423543"
}

Sample response:

{
  "payload": {
    "transaction_id": "12345678",
    "ext_id": "12345789",
    "transaction_status": "SUCCESS",
    "details": [
      {
        "pan": "860066******5544",
        "amount": "100",
        "upper_commission": "1",
        "status": "SUCCESS"
      }
    ],
    "ofd_url": "www.ofd_url_example.uz"
  },
  "code": "200",
  "message": null
}

Confirmation of funds withdrawal using unique transaction identifiers

HTTP Request

POST https://apigw.atmos.uz/ppa/transaction/confirm

Request parameters

Name	Description	Obligation
ext_id	unique transaction identifier	yes
transaction_id	transaction ID on the ATMOS side	yes

Response parameters

Name	Description	Obligation
code	response status (ok, progress, error)	yes
message	response status description	no
payload	transaction data object	yes

Transaction data request

Request:

POST /transaction/check HTTP/1.1
Host: apigw.atmos.uz
Authorization: Bearer <access-token>
Content-Type: application/json
{
  "ext_id": 12345789,
  "pinfl": "123456789123456789",
  "passport_series": "AA",
  "passport_number": "123456789",
  "contract_number": "123456",
  "amount": 100500
}

curl -X POST https://apigw.atmos.uz/ppa/transaction/check \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
  "ext_id": 12345789,
  "pinfl": "123456789123456789",
  "passport_series": "AA",
  "passport_number": "123456789",
  "contract_number": "123456",
  "amount": 100500
}'

Sample response:

{
  "payload": {
    "transaction_id": 12345678,
    "ext_id": 12345789,
    "transaction_status": "SUCCESS",
    "details": [
      {
        "pan": "860066******5544",
        "amount": 100,
        "upper_commission": 1,
        "status": "SUCCESS"
      }
    ],
    "ofd_url": "www.ofd_url_example.uz"
  },
  "code": "200",
  "message": null
}

Finds the transaction based on the specified details and returns a breakdown for it

HTTP Request

POST https://apigw.atmos.uz/ppa/transaction/check

Request parameters

Parameter	Description	Obligation
ext_id	unique transaction identifier	yes
pinfl	pinfl	yes
passport_series	passport series	yes
passport_number	passport number	yes

Response parameters

Parameter	Description	Obligation
code	response status (ok, progress, error)	yes
message	response status description	no
payload	transaction data object	yes

Transaction cancellation (PINFL)

Request:

curl -X POST https://apigw.atmos.uz/ppa/transaction/cancel \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
  "ext_id": 12345789,
  "transaction_id": "1113423543"
}'

POST /ppa/transaction/cancel HTTP/1.1
Host: apigw.atmos.uz
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "ext_id": 12345789,
  "transaction_id": "1113423543"
}

Sample response:

{
  "payload": {
    "transaction_id": 12345678,
    "ext_id": 12345789,
    "transaction_status": "CANCELED"
  },
  "code": "200",
  "message": null
}

Cancels a transaction in ATMOS.PAY using a pair of its unique identifiers, before it is confirmed

HTTP Request

POST https://apigw.atmos.uz/ppa/transaction/cancel

Request parameters

Parameter	Description	Obligation
ext_id	unique transaction identifier	yes
transaction_id	transaction ID on the Atmos side	yes

Response parameters

Parameter	Description	Obligation
code	response status (ok, progress, error)	yes
message	response status description	no
payload	transaction data object	yes

Updating cards by PINFL

Request:

curl -X POST https://apigw.atmos.uz/ppa/cards/update-cards-list \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
  "pinfl": "12345678911234",
  "ext_id": "1234567",
  "epos": {
    "branch_id": 546,
    "terminal_group_id": 266
  }
}'

POST /ppa/cards/update-cards-list HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "pinfl": "12345678911234",
  "ext_id": "1234567",
  "epos": {
    "branch_id": 546,
    "terminal_group_id": 266
  }
}

HTTP Request

POST https://apigw.atmos.uz/ppa/cards/update-cards-list

Synchronize/update card data for the requested PINFL

This method is used in the following cases:

If the owner's cards were not found in the system;
It is necessary to update the list of cards to obtain information about new cards recently opened by the PINFL owner.

Request parameters

name	description	obligation
pinfl	PINFL of the requested person	yes
ext_id	Unique request identifier on the client side	no
epos.branch_id	branch id	yes
epos.terminal_group_id	terminal group id	yes

Response parameters

not available

Checking card update status

Request:

curl -X POST https://apigw.atmos.uz/ppa/cards/check/{ext_id} \
-H "Authorization: Bearer <access-token>" \

POST /ppa/cards/check/{ext_id} HTTP/1.1
Host: apigw.atmos.uz
Authorization: Bearer <access-token>

Sample response:

{
  "code": 200,
  "message": null,
  "payload": {
    "ext_id": "example_ext_id",
    "masked_pinfl": "3210xxxxxxx067",
    "status": "SUCCESSFUL",
    "request_date": "2024-11-26 16:11:47"
  }
}

HTTP Request

POST https://apigw.atmos.uz/ppa/cards/check/{ext_id}

Used to determine the status of PINFL card list updates. The payload.status field returns the request status within the system. A SUCCESSFUL value indicates that the individual's cards associated with their PINFL have been successfully updated in the system.

Request parameters

name	description	obligation
ext_id	unique request identifier	yes

Response parameters

Name	Description
code	response status (ok, progress, error)
message	description of response status
payload.ext_id	Unique request identifier
payload.masked_pinfl	Masked user identifier
payload.status	Request execution status
payload.request_date	Date and time of request creation

Status guide

The body of each server response contains a status, field that stores the state of a given operation. By default, when a user's request is successfully processed, this field contains the code 200.

Details of error statuses are provided in the table below.

Error code	Error text	Description
-100	Unexpected exception	Unexpected error. Contact technical support.
-101	Contract registration was unsuccessful	Error during contract registration.
-102	Client registration was unsuccessful	Error during client registration.
-103	Client with PINFL [pin num] is not available	The client registered with the specified [pin num] PINFL is not available for transaction execution.
-105	No cards with sufficient balance were found	No cards with available minimum balance for transaction execution were found.
-106	Not enough balance	Insufficient funds to execute the transaction (only if `"partial_debit": "false"`).
-107	Could not initiate payment in full amount	Insufficient funds to complete the transaction for the specified amount (non-partial debit).
-108	Cards balance is not available	Card balance is not available.
-109	Cards attributable to PINFL [pinfl] not found	Cards belonging to the specified PINFL [pinfl] have not been found. Card list needs to be updated using the `update-cards-list` method.
-200	Unexpected error. Please try again later	Unforeseen error. Try again later or contact technical support.
-202	Transaction with external id: [trans id] failed	Failed transaction [trans id]. Returns only in the `Check` method .
-301	Client or contract or ePOS not found	The specified transaction verification data does not match the data provided when creating the transaction.
-302	External id [external id] is already used	Specified `external_id` has already been used.
-303	Invalid external id	Invalid `external_id` identifier.
-303	Invalid firstname	Invalid client's first name.
-303	Invalid lastname	Invalid client's last name.
-303	Invalid middle name	Invalid client's patronymic.
-303	Invalid PINFL	Invalid PINFL.
-303	Invalid passport series	Invalid passport series.
-303	Invalid passport number	Invalid passport number.
-303	Invalid contract number	Invalid contract number.
-303	Invalid amount	Invalid amount.
-303	Invalid packageCode	Invalid `packageCode`.
-303	Invalid TIN	Invalid TIN.
-303	branch_id must not be null or empty	The `branch_id` field must not be empty.
-303	terminal_group_id must not be null or empty	The `terminal_group_id` field must not be empty.
-306	Requested amount is less than minimum allowed	The specified amount is less than the minimum allowed for withdrawal.
-307	ePOS with branch id: [branch id] not found	ePOS with the specified parameters was not found.
-307	ePOS details were not sent	ePOS details were not sent.
-308	Request with provided external id not found	Request with the specified `external_id` was not found

Visa/Mastercard acquiring

The IPS system is an acquiring platform that enables legal entities operating within the Republic of Uzbekistan to accept payments from Visa and Mastercard cards.

When connecting to the system, partners are issued a unique API key that must be included in any request when working with the platform as an apikey header.

Base URL: https://apigw.atmos.uz/mps

Authorization

Request:

curl --location 'https://apigw.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: apigw.atmos.uz

Sample response:

{
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 1234
}

HTTP Request

POST https://apigw.atmos.uz/token

Accepts as a parameter an encrypted string in base64 format according to the formula: Base64 (consumer_key + ':' + consumer_secret). The server's response will return an access token, which is valid for 3600 seconds (1 hour).

Extension of token validity period

Request:

curl --location 'https://apigw.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: apigw.atmos.uz

Sample response:

{
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 1234
}

HTTP Request

POST https://apigw.atmos.uz/token

It has similar functionality to the previous method, except that it extends the validity period of an already issued token.

Card binding (IPS)

Card linking

Request:

curl --location 'https://apigw.atmos.uz/mps/pay/card/bind' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
    "store_id": 1,
    "pan": "4278310022884134",
    "expiry": "2508",
    "card_name": "TEST",
    "cvc2": "075",
    "client_ip_addr": "192.168.200.01",
    "ext_id": "1"
}'

POST /mps/pay/card/bind HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>

{
    "store_id": 1,
    "pan": "4278310022884134",
    "expiry": "2508",
    "card_name": "TEST",
    "cvc2": "075",
    "client_ip_addr": "192.168.200.01",
    "ext_id": "1"
}

Sample response:

{
  "payload": {
    "id": 144,
    "status": 1,
    "type": "DEFAULT",
    "amount": 10000,
    "card": {
      "id": 67,
      "status": true,
      "masked_pan": "402306********9999",
      "masked_card_holder": "CUSTOMER NAME",
      "card_type": "VISA",
      "date_created": "2024-03-26 14:28:11",
      "date_updated": "2024-03-26 14:28:11",
      "verified_state": "PENDING",
      "card_region": "DOMESTIC"
    },
    "api_id": 1,
    "card_id": 67,
    "external_id": "82b9c105-95f2-45ce-b33a-74ba4ea11ee4",
    "mps_ext_id": "r2PlRV8Y8CjwBAM4gzzFcVJ504c=",
    "status_ps": "Approved",
    "result_code": "Approved",
    "masked_pan": "402306********9327",
    "client_ip_addr": "192.168.200.01",
    "date_created": "2024-03-26 14:28:11",
    "date_updated": "2024-03-26 14:28:11",
    "redirect_uri": "https://ecomm.kapital24.uz:6443/ecomm2/ClientHandler?trans_id=r2PlRV8Y8CjwBAM4gzzFcVJ504c%3D"
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "6602952bd44ca285f56c38255f2c1e15"
  }
}

HTTP Request

POST https://apigw.atmos.uz/mps/pay/card/bind

Allows you to link a card for making future recurring payments

Request parameters

Parameter	Description	Obligation
store_id	Partner ID	yes
pan	Card number	yes
expiry	Card expiry date in MMYY format	yes
card_name	Card name	yes
cvc2	Card security code (CVC2/CVV2)	yes
client_ip_addr	Client IP address	yes
ext_id	External card ID	yes

Response parameters

Parameter	Description
payload	Transaction data object
payload.id	Transaction ID
payload.status	Transaction status
payload.type	Transaction type
payload.amount	Transaction amount in currency
payload.card	Object with card data
payload.card.id	Card ID
payload.card.status	Card status
payload.card.masked_pan	Masked card number
payload.card.masked_card_holder	Masked cardholder name
payload.card.card_type	Card type
payload.card.date_created	Card creation date
payload.card.date_updated	Card update date
payload.card.verified_state	Card verification status
payload.card.card_region	Card region
payload.api_id	API ID
payload.card_id	Card ID
payload.external_id	External transaction ID
payload.mps_ext_id	MPS external transaction ID
payload.status_ps	PS status
payload.result_code	Result code
payload.client_ip_addr	Client's IP address
payload.date_created	Transaction creation date
payload.date_updated	Transaction update date
payload.redirect_uri	Link to redirect client after 3DS
status	Object with operation status data
status.code	Operation status code
status.message	Operation status message
status.trace_id	Operation trace ID

Card linking by the owner

Request:

curl -X POST "https://apigw.atmos.uz/checkout/card-bind/create" \
-H "Host: https://apigw.atmos.uz" \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
  "request_id": "1231312312",
  "store_id": 3,
  "account": "DFSDF",
  "success_url": "https://atmos.uz"
}'

POST https://apigw.atmos.uz/checkout/card-bind/create HTTP/1.1
Host: https://apigw.atmos.uz
Authorization: Bearer <access-token>
Content-Type: application/json
{
  "request_id": "1231312312",
  "store_id": 3,
  "account": "DFSDF",
  "success_url": "https://atmos.uz",
}

Sample response:

{
  "store_id": 3,
  "payment_id": 272,
  "token": "9Y53Bh_hFirZgxxFqBTwtA==",
  "url": "https://checkout.atmos.uz/bind?id=9Y53Bh_hFirZgxxFqBTwtA==",
  "status": {
    "code": "OK",
    "description": "Success",
    "trace_id": "6602952bd44ca285f56c38255f2c1e15"
  }
}

HTTP Request

POST https://apigw.atmos.uz/checkout/card-bind/create

Method for generating a link by linking the card to the cardholder (card owner). After linking, the partner gains access to initiate withdrawals from the card on their end.

Process sequence:

A link is generated by calling the method;
The link is sent to the cardholder. Card details are entered, and the card is linked using a one-time SMS password;
In case of successful linking, the system sends a request to the partner's billing system with the following content: { "api_key" : <API-KEY> "card_id" : 1231 };
The system expects a response from the partner's billing system with the following content: { "status": 1, "message": "Успешно" };
The card has been successfully linked, and the partner can now make charges using the issued card_id.

Request parameters

Parameter	Description	Obligation
request_id	Unique identifier (generated on the partner's side)	yes
store_id	Partner ID in the system	yes
account	Operation identifier (generated on the partner's side)	yes
success_url	User redirection page for successful response	yes

Response parameters

Parameter	Description
store_id	partner id
payment_id	Transaction identifier
token	Transaction token
url	Link for card binding
status	Object with operation status data
status.code	Operation status code
status.message	Operation status message
status.trace_id	Operation trace identifier

Receiving linked card details

Request:

    curl --location 'https://apigw.atmos.uz/mps/pay/card/32' \
    --header 'Authorization: Bearer <access-token>'

    GET /mps/pay/card/32 HTTP/1.1
    Host: apigw.atmos.uz
    Authorization: Bearer <access-token>

Sample response:

{
  "payload": {
    "card": {
      "id": 928,
      "status": true,
      "approved": true,
      "masked_pan": "427831********5430",
      "masked_card_holder": "TEST",
      "card_type": "VISA",
      "date_created": "2024-11-21 10:58:12",
      "date_updated": "2024-11-21 10:58:12",
      "verified_state": "FAILED",
      "status_3ds": "FAILED",
      "card_region": "ONUS",
      "store_id": 1
    },
    "card_id": 928
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "65dd6c72a94bfe3856d7f821e8ac37eb"
  }
}

HTTP Request

GET https://apigw.atmos.uz/mps/pay/card/32

Returns data from a card previously linked to the service

Request parameters

Parameter	Description	Obligation
id	Card id	yes

Response parameters

name	description
payload	Data object
card	Object with card data
card.id	Card ID
card.status	Card linking status
card.masked_pan	Masked card number
card.masked_card_holder	Masked cardholder name
card.card_type	Card type
card.date_created	Card linking creation date
card.date_updated	Card linking update date
card.verified_state	Card verification status
card.status_3ds	3DS status
card.card_region	Card registration region
card.store_id	Partner ID
card_id	Card ID in the system
status	Object with operation status data
status.code	Operation status code
status.message	Operation status message
status.trace_id	Operation trace ID

Creating a transaction draft (bind)

Request:

curl -X POST https://apigw.atmos.uz/mps/pay/transaction/pre-create \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
  "amount": 10000,
  "ext_id": "{{$randomUUID}}",
  "store_id": 3,
  "ofd_items": [],
  "account": "i-203451",
  "invoice_id": "00023213"
}'

POST /mps/pay/transaction/pre-create HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "amount": 10000,
  "ext_id": "{{$randomUUID}}",
  "store_id": 3,
  "ofd_items": [],
  "account": "i-203451",
  "invoice_id": "00023213"
}

Sample response:

{
  "payload": {
    "id": 898,
    "status": 0,
    "type": "DEFAULT",
    "amount": 10000,
    "api_id": 1,
    "external_id": "9f7ab26c-9ddd-47bf-b5ee-c7e04714f162",
    "date_created": "2024-11-20 16:12:38",
    "date_updated": "2024-11-20 16:12:38",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/bVYxRGo5cjQxOFN4RlRpZjRST3hFdz09",
    "store_id": 3,
    "upper_commission": 0,
    "lower_commission": 0
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "673dc426d9e792630a9dec5bb25603a8"
  }
}

HTTP Request

POST https://apigw.atmos.uz/mps/pay/transaction/pre-create

Creating a draft transaction for subsequent debiting from a linked card

Request parameters

Name	Description	Obligation
amount	Transaction amount (in tiyins)	Yes
ext_id	Unique request identifier	Yes
store_id	Partner identifier	Yes
ofd_items	List of OFD objects	Yes
account	Client-side operation ID	Yes
invoice_id	Invoice number	Yes

Response parameters

Field name	Description
id	Unique transaction identifier
status	Transaction status
type	Transaction type
amount	Transaction amount (in tiyins)
api_id	API identifier
external_id	External transaction identifier
date_created	Transaction creation date
date_updated	Date of last transaction update
ofd_redirect_uri	OFD redirection link
store_id	Partner identifier
upper_commission	Upper commission
lower_commission	Lower commission
code	Response status code
message	Response status message
trace_id	Unique request identifier

Создание транзакции из драфта (bind)

Запрос:

curl -X POST https://apigw.atmos.uz/mps/pay/transaction/create/bind \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
  "card_id": 855,
  "amount": 1000,
  "client_ip_addr": "192.168.200.201",
  "transaction_id": 883
}'

POST /mps/pay/transaction/create/bind HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "card_id": 855,
  "amount": 1000,
  "client_ip_addr": "192.168.200.201",
  "transaction_id": 883
}

Sample response:

{
  "payload": {
    "id": 735,
    "status": 1,
    "rrn": "420810227278",
    "type": "DEFAULT",
    "amount": 10000,
    "card": {
      "id": 923,
      "status": true,
      "masked_pan": "419525********1540",
      "masked_card_holder": "NAME TEST",
      "card_type": "VISA",
      "date_created": "2024-11-20 16:20:19",
      "date_updated": "2024-11-20 16:20:19",
      "verified_state": "PENDING",
      "card_region": "DOMESTIC"
    },
    "api_id": 1,
    "card_id": 923,
    "external_id": "fce222d7-2f5a-4052-9170-b68c30bd9890",
    "mps_ext_id": "BhOEry3oY7G5hHtNTFABHiCLsfQ=",
    "status_ps": "Approved",
    "result_code": "Approved",
    "app_code": "249138",
    "masked_pan": "419525********1540",
    "client_ip_addr": "192.168.200.01",
    "date_created": "2024-11-20 16:20:19",
    "date_updated": "2024-11-20 16:20:19",
    "redirect_uri": "https://ecomm.kapital24.uz:2443/ecomm2/ClientHandler?trans_id=BhOEry3oY7G5hHtNTFABHiCLsfQ%3D",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/blBlR3p1RmVlS0pQSHY4QjRlM1k3UT09",
    "store_id": 3,
    "upper_commission": 100,
    "lower_commission": 0,
    "ofd_commission_uri": "https://ofd.atmos.uz/api/ofd/SDRxWDc3ejc0cmZYQmlDT3BGMVFmQT09"
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "673dc5f3080d8074fd3a272cb3d0c365"
  }
}

HTTP Request

POST https://apigw.atmos.uz/mps/pay/transaction/create/bind

Creating a transaction from a draft and linking a payment card to it

Request parameters

Field name	Description	Obligation
card_id	Card ID from which the transaction will be executed	yes
amount	Transaction amount (in tiyins)	yes
client_ip_addr	IP address of the client who initiated the transaction	yes
transaction_id	Transaction ID with which the operation will be associated	yes

Response parameters

Field name	Description
id	Unique transaction ID
status	Transaction status
rrn	Request Reference Number (Retrieval Reference Number)
type	Transaction type
amount	Transaction amount
card.id	Unique card ID
card.status	Card status (true/false)
card.masked_pan	Masked card number
card.masked_card_holder	Masked cardholder name
card.card_type	Card type
api_id	API ID
card_id	Card ID
external_id	External transaction ID
mps_ext_id	External MPS platform ID
status_ps	Processing side status
result_code	Transaction result code
app_code	Application code associated with the transaction
masked_pan	Masked card number
client_ip_addr	Client's IP address
date_created	Date and time of transaction creation
date_updated	Date and time of transaction update
redirect_uri	URI for redirecting after transaction
ofd_redirect_uri	URI for redirecting to the OFD system
store_id	Partner ID
upper_commission	Upper commission
lower_commission	Lower commission
ofd_commission_uri	URI for OFD commission

Transaction confirmation (bind)

Request:

curl -X POST https://apigw.atmos.uz/mps/pay/transaction/apply \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{
  "transaction_id": 59
}'

POST https://apigw.atmos.uz/mps/pay/transaction/apply HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "transaction_id": 59
}

Sample response:

{
  "payload": {
    "id": 735,
    "status": 4,
    "rrn": "420810227278",
    "type": "DEFAULT",
    "amount": 10000,
    "card": {
      "id": 923,
      "status": true,
      "masked_pan": "419525********1540",
      "masked_card_holder": "NAME TEST",
      "card_type": "VISA",
      "date_created": "2024-11-20 16:20:19",
      "date_updated": "2024-11-20 16:20:19",
      "verified_state": "VERIFIED",
      "card_region": "DOMESTIC"
    },
    "api_id": 1,
    "card_id": 923,
    "external_id": "fce222d7-2f5a-4052-9170-b68c30bd9890",
    "mps_ext_id": "BhOEry3oY7G5hHtNTFABHiCLsfQ=",
    "status_ps": "Approved",
    "result_code": "Approved",
    "app_code": "249138",
    "masked_pan": "419525********1540",
    "client_ip_addr": "192.168.200.01",
    "date_created": "2024-11-20 16:20:19",
    "date_updated": "2024-11-20 16:20:19",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/blBlR3p1RmVlS0pQSHY4QjRlM1k3UT09",
    "store_id": 3,
    "upper_commission": 100,
    "lower_commission": 0,
    "ofd_commission_uri": "https://ofd.atmos.uz/api/ofd/SDRxWDc3ejc0cmZYQmlDT3BGMVFmQT09"
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "673dc5f3080d8074fd3a272cb3d0c365"
  }
}

HTTP Request

POST https://apigw.atmos.uz/mps/pay/transaction/apply

Confirmation of a previously created and confirmed transaction

Request parameters

Field name	Description	Obligation
transaction_id	Identifier of the created transaction	yes

Response parameters

Name	Obligation
id	Transaction ID
status	Transaction status
rrn	Transaction reference number
amount	Transaction amount
card.id	Card ID
card.status	Card status
card.masked_pan	Masked card number
card.masked_card_holder	Masked cardholder name
card.card_type	Card type
card.date_created	Card creation date
card.date_updated	Card update date
card.verified_state	Card verification status
card.card_region	Card region
api_id	API ID
card_id	Card ID
external_id	External ID
mps_ext_id	MPS system ID
status_ps	Payment system status
result_code	Result code
app_code	Application code
masked_pan	Masked card number
client_ip_addr	Client's IP address
date_created	Transaction creation date
date_updated	Transaction update date
ofd_redirect_uri	URI for OFD redirect
store_id	Partner ID
upper_commission	Upper commission
lower_commission	Lower commission
ofd_commission_uri	URI for OFD commission
status	Object with request status
code	Status code (0 - successful request)
message	Status message
trace_id	Request tracing ID

Payments (IPS)

Billing (IPS)

Request:

curl -X POST 'https://apigw.atmos.uz/checkout/invoice/create' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "request_id": "1231312312",
    "store_id": 3,
    "expiration_time": 10,
    "expiration_date": "2024-07-11T11:12:12",
    "account": "DFSDF",
    "amount": 100000,
    "success_url": "https://atmos.uz",
    "items": [
        {
            "items_id": "1",
            "name": "book 1",
            "amount": 50000,
            "quantity": 3,
            "details": {
                "name": "some key",
                "values": "some value"
            }
        },
        {
            "items_id": "2",
            "name": "service",
            "amount": 50000,
            "details": {
                "name": "some key 2",
                "values": "some value 2"
            }
        }
    ]
}'

POST https://apigw.atmos.uz/checkout/invoice/create HTTP/1.1
Host: https://apigw.atmos.uz
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "request_id": "1231312312",
    "store_id": 3,
    "expiration_time": 10,
    "expiration_date": "2024-07-11T11:12:12",
    "account": "DFSDF",
    "amount": 100000,
    "success_url": "https://atmos.uz",
    "items": [
        {
            "items_id": "1",
            "name": "book 1",
            "amount": 50000,
            "quantity": 3,
            "details": {
                "name": "some key",
                "values": "some value"
            }
        },
        {
            "items_id": "2",
            "name": "service",
            "amount": 50000,
            "details": {
                "name": "some key 2",
                "values": "some value 2"
            }
        }
    ]
}

Sample response:

{
    "store_id": 3,
    "payment_id": 272,
    "token": "9Y53Bh_hFirZgxxFqBTwtA==",
    "url": "https://checkout.atmos.uz/ru/invoice?id=9Y53Bh_hFirZgxxFqBTwtA==", # ссылка инвойса для открытия в браузере
    "status": {
        "code": "OK",
        "description": "Success"
    }
}

HTTP Request

POST https://apigw.atmos.uz/checkout/invoice/create

Creates a payment in the system with payment through a web interface (payment page). The URL of the payment page will be provided in the server's response.

Request parameters

Parameter	Description	Obligation
request_id	Unique request identifier	yes
store_id	Partner identifier	yes
expiration_time	Time until invoice expiration in minutes	no
expiration_date	Invoice expiration date and time in YYYY-MM-DDTHH:MM:SS format	no
account	Partner payment identifier	yes
amount	Amount (in tiyins)	yes
success_url	Redirect link for successful payment	yes
items	List of items or services	yes
items[].items_id	Item or service identifier	yes
items[].name	Name of item or service	yes
items[].amount	Amount for item or service (in tiyins)	yes
items[].quantity	Quantity of item or service (if applicable)	no
items[].details	Details of item or service	no
items[].details.name	Name of the item or service detail key	no
items[].details.values	Value of the item or service detail key	no

Response parameters

Parameter	Description
store_id	Partner ID
payment_id	Payment ID
token	Invoice token
url	Invoice link for opening in a browser
status	Response status
status.code	Status code
status.description	Status description

Transaction Creation (IPS)

Request:

curl --location 'https://apigw.atmos.uz/mps/pay/transaction/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
    "pan": "4278310021875430",
    "expiry": "2508",
    "amount": 10000,
    "transaction_id": 1,
    "card_name": "TEST",
    "cvc2": "680",
    "client_ip_addr": "192.168.200.01",
    "ext_id": "64bedd41-f21b-4298-aa88-1206107670b8"
}'

POST /mps/pay/transaction/create HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "pan": "4278310021875430",
    "expiry": "2508",
    "amount": 10000,
    "transaction_id": 1,
    "card_name": "TEST",
    "cvc2": "680",
    "client_ip_addr": "192.168.200.01",
    "ext_id": "64bedd41-f21b-4298-aa88-1206107670b8"
}

Sample response:

{
  "payload": {
    "id": 735,
    "status": 1,
    "rrn": "420810227278",
    "type": "DEFAULT",
    "amount": 10000,
    "card": {
      "id": 929,
      "status": true,
      "masked_pan": "419525********1540",
      "masked_card_holder": "ANDREY PAK",
      "card_type": "VISA",
      "date_created": "2024-11-21 16:00:15",
      "date_updated": "2024-11-21 16:00:15",
      "verified_state": "PENDING",
      "card_region": "DOMESTIC"
    },
    "api_id": 1,
    "card_id": 929,
    "external_id": "fce222d7-2f5a-4052-9170-b68c30bd9890",
    "mps_ext_id": "EueYPCDKlXDhyE9chwPzPcHO89s=",
    "status_ps": "Approved",
    "result_code": "Approved",
    "app_code": "249138",
    "masked_pan": "419525********1540",
    "client_ip_addr": "192.168.200.01",
    "date_created": "2024-11-21 16:00:15",
    "date_updated": "2024-11-21 16:00:15",
    "redirect_uri": "https://ecomm.kapital24.uz:2443/ecomm2/ClientHandler?trans_id=EueYPCDKlXDhyE9chwPzPcHO89s%3D",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/blBlR3p1RmVlS0pQSHY4QjRlM1k3UT09",
    "store_id": 3,
    "upper_commission": 100,
    "lower_commission": 0,
    "ofd_commission_uri": "https://ofd.atmos.uz/api/ofd/SDRxWDc3ejc0cmZYQmlDT3BGMVFmQT09"
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "673f12bff4d74919c7fcd40ef4dd24ce"
  }
}

HTTP Request

POST https://apigw.atmos.uz/mps/pay/transaction/create

Creates a transaction in the system that subsequently requires confirmation

Request parameters

Parameter	Description	Obligation
transaction_id	Transaction draft ID	yes
pan	Card number	yes
expiry	Card expiry date in MMYY format	yes
amount	Transaction amount in tiyins	yes
card_name	Card name	yes
cvc2	Card security code (CVC2/CVV2)	yes
client_ip_addr	Client's IP address	yes
ext_id	Unique transaction identifier (UUID) generated on the client side	yes

Response parameters

Parameter	Description
payload	Transaction data object
payload.id	Transaction ID
payload.status	Transaction status
payload.rrn	Transaction return reference number
payload.type	Transaction type
payload.amount	Transaction amount in currency
payload.card	Object with card data
payload.card.id	Card ID
payload.card.status	Card status
payload.card.masked_pan	Masked card number
payload.card.masked_card_holder	Masked cardholder name
payload.card.card_type	Card type (e.g., VISA)
payload.card.date_created	Card creation date
payload.card.date_updated	Card update date
payload.card.verified_state	Card verification status
payload.card.card_region	Card region
payload.api_id	API ID
payload.card_id	Card ID
payload.external_id	External transaction ID
payload.mps_ext_id	IPS external transaction ID
payload.status_ps	PS status
payload.result_code	Result code
payload.app_code	Processing parameters
payload.masked_pan	Masked card number
payload.client_ip_addr	Client's IP address
payload.date_created	Transaction creation date
payload.date_updated	Transaction update date
payload.redirect_uri	Link to redirect client after 3DS
payload.ofd_redirect_uri	Link to redirect to OFD
payload.store_id	Partner ID
payload.upper_commission	Upper commission
payload.lower_commission	Lower commission
payload.ofd_commission_uri	Fiscalization receipt link
status	Object with operation status data
status.code	Operation status code
status.message	Operation status message
status.trace_id	Operation trace ID

Creating a recurring payment (IPS)

Request:

curl --location 'https://apigw.atmos.uz/mps/pay/transaction/create/template' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
    "card_id": 1,
    "amount": 1000,
    "client_ip_addr": "192.168.200.201",
    "ext_id": "12d649ad-38ac-44c5-8f10-3700bfda5efe"
}'

POST /mps/pay/transaction/create/template HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "card_id": 1,
    "amount": 1000,
    "client_ip_addr": "192.168.200.201",
    "ext_id": "12d649ad-38ac-44c5-8f10-3700bfda5efe"
}

Sample response:

{
  "payload": {
    "id": 110,
    "status": 1,
    "type": "TEMPLATE",
    "api_id": 1,
    "card_id": 36,
    "external_id": "c4cea503-4838-440e-aac2-4509e1319f4e",
    "mps_ext_id": "I7cQTxAUXz0LPy75q09sldnOzTk=",
    "status_ps": "Approved",
    "status_3ds": "AUTHENTICATED",
    "result_code": "Approved",
    "masked_pan": "427831********5430",
    "client_ip_addr": "192.168.200.01",
    "date_created": "2024-02-26 17:13:05",
    "date_updated": "2024-02-26 17:13:05",
    "redirect_uri": null
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "65dc805134eb63b90d2e048d1d4fb38a"
  }
}

HTTP Request

POST https://apigw.atmos.uz/mps/pay/transaction/create/template

The method creates a recurring payment in the system. For successful payment creation, the card submitted in the request must have been previously linked to the system, and 3DS verification must have been completed during its addition. The 3DS verification status can be checked using the /card/{id} method.

Request parameters

Parameter	Description	Obligation
card_id	Card ID	yes
amount	Amount of regular payment in tiyins	yes
client_ip_addr	Client's IP address	yes
ext_id	Unique transaction identifier (UUID) generated on the client side	yes

Response parameters

Parameter	Description
payload	Object with regular payment data
id	Regular payment identifier
status	Regular payment status
type	Regular payment type
api_id	API ID
card_id	Card identifier
external_id	External regular payment ID
mps_ext_id	MPS external regular payment ID
status_ps	Regular payment PS status
status_3ds	Regular payment 3DS status
result_code	Regular payment result code
masked_pan	Masked card number
client_ip_addr	Client's IP address
date_created	Regular payment creation date
date_updated	Regular payment update date
redirect_uri	Link to redirect client after 3DS
status	Object with operation status data
code	Operation status code
message	Operation status message
trace_id	Operation tracing identifier

Retrieving transaction details (IPS)

Request:

curl --location 'https://apigw.atmos.uz/mps/pay/transaction/get/52' \
--header 'Authorization: Bearer <access-token>'

GET /mps/pay/transaction/get/52 HTTP/1.1
Host: apigw.atmos.uz
apikey: <api-key>
Authorization: Bearer <access-token>
Content-Type: application/json

Sample response:

{
  "payload": {
    "id": 235,
    "status": 6,
    "rrn": "417310203285",
    "type": "DEFAULT",
    "amount": 100000,
    "api_id": 2,
    "card_id": 220,
    "external_id": "checkout_32157",
    "mps_ext_id": "JEpQ9xa98OhSPPHLRIExPZBlufQ=",
    "status_ps": "Accepted (for reversal)",
    "result_code": "Accepted",
    "app_code": "999284",
    "masked_pan": "419525********1783",
    "client_ip_addr": "10.228.1.26",
    "date_created": "2024-06-21 05:38:25",
    "date_updated": "2024-06-21 05:38:57",
    "redirect_uri": "https://ecomm.kapital24.uz:2443/ecomm2/ClientHandler?trans_id=JEpQ9xa98OhSPPHLRIExPZBlufQ%3D",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/bjhMWnRWaDNxb2NWMHRGL2hLMXlYQT09",
    "store_id": 3,
    "upper_commission": 0,
    "lower_commission": 0
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "673f1773cdc429d9cdb5bc0b0d982291"
  }
}

HTTP Request

GET https://apigw.atmos.uz/mps/pay/transaction/get/${id}

Returns the detailed information available in the system for the requested transaction

Request parameters

Parameter	Description	Obligation
transaction_id	Transaction ID	yes

Response parameters

Parameter	Description
payload	Transaction Data Object
payload.id	Transaction ID
payload.status	Transaction status
payload.rrn	Transaction reference number
payload.type	Transaction type
payload.amount	Transaction amount in currency
payload.api_id	API ID
payload.card_id	Card ID
payload.external_id	External transaction ID
payload.mps_ext_id	MPS external transaction ID
payload.status_ps	PS status
payload.result_code	Result code
payload.app_code	Authorization code
payload.masked_pan	Masked card number
payload.client_ip_addr	Client's IP address
payload.date_created	Transaction creation date
payload.date_updated	Transaction update date
payload.redirect_uri	Link to redirect client after 3DS
payload.ofd_redirect_uri	Link to redirect to OFD
payload.store_id	Partner ID
payload.upper_commission	Upper commission
payload.lower_commission	Lower commission
status	Object with operation status data
status.code	Operation status code
status.message	Operation status message
status.trace_id	Operation trace ID

Retrieving transaction details by external identifier (IPS)

Request:

curl -X POST \
  https://apigw.atmos.uz/mps/pay/get/ext_id \
  -H 'Content-Type: application/json' \
  -d '{
    "ext_id": "<ext-id>"
}'

POST /mps/pay/get/ext_id HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json

{
"ext_id": "<ext-id>"
}

Sample response:

{
  "payload": {
    "id": 131,
    "status": 1,
    "type": "DEFAULT",
    "amount": 10000,
    "card": {
      "id": 55,
      "status": true,
      "masked_pan": "427831********9999",
      "masked_card_holder": "TEST",
      "card_type": "VISA",
      "date_created": "2024-03-18 05:27:54",
      "date_updated": "2024-03-18 05:27:54",
      "verified_state": "PENDING",
      "card_region": "ONUS"
    },
    "api_id": 1,
    "card_id": 55,
    "external_id": "f6d7c050-1927-43d6-a828-6a22235d6f32",
    "mps_ext_id": "E0ZwTIl60PFsSbOz1o8yCwcXEn8=",
    "status_ps": "Approved",
    "result_code": "Approved",
    "masked_pan": "427831********5430",
    "client_ip_addr": "192.168.200.01",
    "date_created": "2024-03-18 05:27:54",
    "date_updated": "2024-03-18 05:27:54"
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "66029622c951aa197d8196bd89d65308"
  }
}

HTTP Request

POST https://apigw.atmos.uz/mps/pay/get/ext_id

returns transaction data using its external key

Request parameters

Parameter	Description	Obligation
ext_id	External transaction identifier	yes

Response parameters

Parameter	Description
payload	Transaction data object
payload.id	Transaction ID
payload.status	Transaction status
payload.type	Transaction type
payload.amount	Transaction amount in currency
payload.card	Object with card data
payload.card.id	Card ID
payload.card.status	Card status
payload.card.masked_pan	Masked card number
payload.card.masked_card_holder	Masked cardholder name
payload.card.card_type	Card type
payload.card.date_created	Card creation date
payload.card.date_updated	Card update date
payload.card.verified_state	Card verification status
payload.card.card_region	Card region
payload.api_id	API ID
payload.card_id	Card ID
payload.external_id	External transaction ID
payload.mps_ext_id	MPS external transaction ID
payload.status_ps	PS status
payload.result_code	Result code
payload.client_ip_addr	Client's IP address
payload.date_created	Transaction creation date
payload.date_updated	Transaction update date
status	Object with operation status data
status.code	Operation status code
status.message	Operation status message
status.trace_id	Operation tracing ID

Holding (IPS)

Creating a hold operation (IPS)

Request:

curl -X POST "https://apigw.atmos.uz/mps-extend/uklon/hold" \
-H "Content-Type: application/json" \
-d '{
  "ext_id": "uklon_001",
  "amount": 12000,
  "store_id": 100002,
  "ofd_items": [
    {
      "items_id": "1",
      "ofd_code": "03402004012000000",
      "name": "105 UMUMIY TOZALASH 1000 ML",
      "amount": 6000,
      "quantity": 1
    },
    {
      "items_id": "1",
      "ofd_code": "10105001001000000",
      "name": "Yetkazib berish",
      "amount": 6000,
      "quantity": 1
    }
  ],
  "account": "user_account",
  "invoice_id": "INV-00001",
  "card_id": 947,
  "client_ip_addr": "192.168.1.1"
}'

POST /mps-extend/uklon/hold HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json

{
  "ext_id": "uklon_001",
  "amount": 12000,
  "store_id": 100002,
  "ofd_items": [
    {
      "items_id": "1",
      "ofd_code": "03402004012000000",
      "name": "105 UMUMIY TOZALASH 1000 ML",
      "amount": 6000,
      "quantity": 1
    },
    {
      "items_id": "1",
      "ofd_code": "10105001001000000",
      "name": "Yetkazib berish",
      "amount": 6000,
      "quantity": 1
    }
  ],
  "account": "user_account",
  "invoice_id": "INV-00001",
  "card_id": 947,
  "client_ip_addr": "192.168.1.1"
}

Sample reponse:

{
  "payload": {
    "id": 925,
    "status": 4,
    "rrn": "435206074577",
    "type": "TEMPLATE",
    "amount": 12000,
    "card": {
      "id": 947,
      "status": true,
      "approved": true,
      "masked_pan": "419525********11111",
      "masked_card_holder": "NAME LASTNAME",
      "card_type": "VISA",
      "date_created": "2024-12-16 12:21:43",
      "date_updated": "2024-12-16 12:21:43",
      "verified_state": "VERIFIED",
      "status_3ds": "AUTHENTICATED",
      "card_region": "DOMESTIC",
      "store_id": 000002
    },
    "card_id": 947,
    "external_id": "PARTNER_001",
    "mps_ext_id": "TrZZ5RRDVRr4GY5FBub5Pjubix8=",
    "status_ps": "Approved",
    "status_3ds": "AUTHENTICATED",
    "result_code": "Approved",
    "masked_pan": "419525********9556",
    "client_ip_addr": "192.168.1.1",
    "date_created": "2024-12-17 06:42:43",
    "date_updated": "2024-12-17 11:42:43",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/T1VXWkVMejFYQVhvS3dNVHNXV1kwZz00",
    "store_id": 100002,
    "upper_commission": 0,
    "lower_commission": 0
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "67611d6344179f211d0ed71bf666e71c"
  }
}

Creation of a funds holding operation on the client's card within the MPS system

HTTP Request

POST https://apigw.atmos.uz/mps-extend/uklon/hold

Request parameters

Parameter	Description	Obligation
ext_id	External ID	yes
amount	Transaction amount	yes
store_id	Partner ID	yes
ofd_items.items_id	Product ID in the OFD list	yes
ofd_items.ofd_code	Product code in the OFD list	yes
ofd_items.name	Product name in the OFD list	yes
ofd_items.amount	Product amount in the OFD list	yes
ofd_items.quantity	Quantity of product in the OFD list	yes
account	Internal ID	yes
invoice_id	Invoice ID	yes
card_id	Card ID	yes
client_ip_addr	Client IP address	yes

Response parameters

Parameter	Description
code	Operation status code
description	Response status description
payload.id	Transaction ID
payload.status	Transaction status
payload.rrn	Transaction number
payload.type	Transaction type
payload.amount	Transaction amount
payload.card.id	Card ID
payload.card.status	Card status
payload.card.approved	Card approval status
payload.card.masked_pan	Masked card number
payload.card.masked_card_holder	Masked cardholder name
payload.card.card_type	Card type
payload.card.date_created	Card creation date
payload.card.date_updated	Date of last card update
payload.card.verified_state	Card verification status
payload.card.status_3ds	3DS card verification status
payload.card.card_region	Card region
payload.card.store_id	Partner ID
payload.card_id	Card ID (corresponds to `payload.card.id`)
payload.external_id	External ID
payload.mps_ext_id	External transaction ID
payload.status_ps	Payment status
payload.status_3ds	3DS transaction status
payload.result_code	Payment result
payload.masked_pan	Masked card number (corresponds to `payload.card.masked_pan`)
payload.client_ip_addr	Client's IP address
payload.date_created	Transaction creation date
payload.date_updated	Date of last transaction update
payload.ofd_redirect_uri	URI for redirection
payload.store_id	Partner ID (corresponds to `payload.card.store_id` и `payload.store_id`)
payload.upper_commission	Upper commission
payload.lower_commission	Lower commission
status.trace_id	Request tracking ID

Withdrawal of the held amount (IPS)

Request:

curl -X POST "https://apigw.atmos.uz/mps-extend/uklon/apply" \
-H "Content-Type: application/json" \
-d '{
  "transaction_id": 925
}'

POST /mps-extend/uklon/apply HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json

{
  "transaction_id": 925
}

Sample response:

{
  "payload": {
    "id": 925,
    "status": 4,
    "rrn": "435206074577",
    "type": "TEMPLATE",
    "amount": 12000,
    "card": {
      "id": 947,
      "status": true,
      "approved": true,
      "masked_pan": "419525********1111",
      "masked_card_holder": "NAME LASTNAME",
      "card_type": "VISA",
      "date_created": "2024-12-16 12:21:43",
      "date_updated": "2024-12-16 12:21:43",
      "verified_state": "VERIFIED",
      "status_3ds": "AUTHENTICATED",
      "card_region": "DOMESTIC",
      "store_id": 100002
    },
    "card_id": 947,
    "external_id": "uklon_001",
    "mps_ext_id": "TrZZ5RRDVRr4GY5FBub5Pjubix8=",
    "status_ps": "Approved",
    "status_3ds": "AUTHENTICATED",
    "result_code": "Approved",
    "masked_pan": "419525********9556",
    "client_ip_addr": "192.168.1.1",
    "date_created": "2024-12-17 06:42:43",
    "date_updated": "2024-12-17 06:42:43",
    "redirect_uri": "https://ecomm.kapital24.uz:2443/ecomm2/ClientHandler?trans_id=TrZZ5RRDVRr4GY5FBub5Pjubix8%30",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/T1VXWkVMejFYQVhvS3dNVHNXV1kwZz00",
    "store_id": 100002,
    "upper_commission": 0,
    "lower_commission": 0
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "67611e3b6b932e56690f31668951dbf2"
  }
}

Performs a deduction of funds based on the previously held amount

HTTP Request

POST https://apigw.atmos.uz/mps-extend/uklon/apply

Request parameters

Parameter	Description	Obligation
transaction_id	Transaction ID	yes

Response parameters

Parameter	Description
code	Operation status code
description	Response status description
payload.id	Transaction ID
payload.status	Transaction status
payload.rrn	Transaction number
payload.type	Transaction type
payload.amount	Transaction amount
payload.card.id	Card ID
payload.card.status	Card status
payload.card.approved	Card approval status
payload.card.masked_pan	Masked card number
payload.card.masked_card_holder	Masked cardholder name
payload.card.card_type	Card type
payload.card.date_created	Card creation date
payload.card.date_updated	Date of last card update
payload.card.verified_state	Card verification status
payload.card.status_3ds	3DS card verification status
payload.card.card_region	Card region
payload.card.store_id	Partner ID
payload.card_id	Card ID (corresponds to `payload.card.id`)
payload.external_id	External ID
payload.mps_ext_id	External transaction ID
payload.status_ps	Payment status
payload.status_3ds	3DS transaction status
payload.result_code	Payment result
payload.masked_pan	Masked card number (corresponds to `payload.card.masked_pan`)
payload.client_ip_addr	Client's IP address
payload.date_created	Transaction creation date
payload.date_updated	Date of last transaction update
payload.redirect_uri	URI for customer redirection
payload.ofd_redirect_uri	URI for redirection to the OFD system
payload.store_id	Partner ID (corresponds to `payload.card.store_id` и `payload.store_id`)
payload.upper_commission	Upper commission
payload.lower_commission	Lower commission
status.trace_id	Request tracking ID

Cancellation of hold operation (IPS)

Request:

curl -X POST "https://apigw.atmos.uz/mps-extend/uklon/cancel" \
-H "Content-Type: application/json" \
-d '{
  "store_id": 100002,
  "transaction_id": 925
}'

POST /mps-extend/uklon/cancel HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json

{
  "store_id": 100002,
  "transaction_id": 925
}

Sample response:

{
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "67611fd176ffefc6b963f36dbe32e582"
  }
}

Cancels a previously created hold operation

HTTP Request

POST https://apigw.atmos.uz/mps-extend/uklon/cancel

Request parameters

Parameter	Description	Obligation
store_id	Partner ID	yes
transaction_id	Transaction ID	yes

Response parameters

Parameter	Description
code	Operation status code
description	Response status description
status.code	Response status code (e.g., 0 - successful request)
status.message	Response status description (e.g., Success)
status.trace_id	Request tracking ID

Refund for a completed holding transaction (IPS)

Request:

curl -X POST "https://apigw.atmos.uz/mps-extend/uklon/return" \
-H "Content-Type: application/json" \
-d '{
  "transaction_id": 923
}'

POST /mps-extend/uklon/return HTTP/1.1
Host: apigw.atmos.uz
Content-Type: application/json

{
  "transaction_id": 923
}

Sample response:

{
  "payload": {
    "id": 923,
    "status": 7,
    "rrn": "000206071000",
    "type": "TEMPLATE",
    "amount": 10000,
    "card_id": 947,
    "external_id": "store_1",
    "mps_ext_id": "AYhQoiCyvfwBOJLqEj24w0ioLHU0",
    "status_ps": "Approved",
    "status_3ds": "AUTHENTICATED",
    "result_code": "Approved",
    "masked_pan": "419525********1111",
    "client_ip_addr": "192.168.1.1",
    "date_created": "2024-12-17 06:17:17",
    "date_updated": "2024-12-17 12:12:17",
    "redirect_uri": "https://ecomm.kapital24.uz:2443/ecomm2/ClientHandler?trans_id=AYhQoiCyvfwBOJLqEj24w0ioLHU%30",
    "ofd_redirect_uri": "https://ofd.atmos.uz/api/ofd/blMxbUNIUEZ0WTNNWGFDVC9VVGQ1dz00",
    "upper_commission": 0,
    "lower_commission": 0
  },
  "status": {
    "code": 0,
    "message": "Success",
    "trace_id": "676124513032520bff53bc5309ac8488"
  }
}

Performs a refund of funds previously deducted based on a hold transaction

HTTP Request

POST https://apigw.atmos.uz/mps-extend/uklon/return

Request parameters

Parameter	Description	Obligation
transaction_id	Transaction ID	yes

Response parameters

Parameter	Description
code	Operation status code
description	Response status description
payload.id	Transaction ID
payload.status	Transaction status
payload.rrn	Transaction number
payload.type	Transaction type
payload.amount	Transaction amount
payload.card_id	Card ID
payload.external_id	External ID
payload.mps_ext_id	External transaction ID
payload.status_ps	Payment status
payload.status_3ds	3DS transaction status
payload.result_code	Payment result
payload.masked_pan	Masked card number
payload.client_ip_addr	Client's IP address
payload.date_created	Transaction creation date
payload.date_updated	Date of last transaction update
payload.redirect_uri	URI for customer redirection
payload.ofd_redirect_uri	URI for redirection to the OFD system
payload.upper_commission	Upper commission
payload.lower_commission	Lower commission
status.trace_id	Request tracking ID

System status and errors

In case of errors, the ATMOS API returns standard status codes, which are listed in the table below:

Answer status	Value
400	Bad Request -- The request contains an error.
401	Unauthorized -- You are not authorized in the system.
403	Forbidden -- Access forbidden.
404	Not Found -- No matching results found.
405	Method Not Allowed -- The method does not exist.
429	Too Many Requests -- Too many requests.
500	Internal Server Error -- An error occurred on the server side. Please try again later.
503	Service Unavailable -- The service is temporarily unavailable.

Transaction errors

Error code	Error description
STPIMS-ERR-001	Internal error
STPIMS-ERR-003	Invalid partner
STPIMS-ERR-004	Card not found
STPIMS-ERR-005	Card not linked to the number
STPIMS-ERR-006	Required parameters not found
STPIMS-ERR-007	Invalid parameter format
STPIMS-ERR-008	Card not registered
STPIMS-ERR-009	Invalid parameters
STPIMS-ERR-010	Account does not exist
STPIMS-ERR-011	Invalid payment options
STPIMS-ERR-012	Invalid transaction ID
STPIMS-ERR-013	Invalid user data
STPIMS-ERR-014	Invalid login attempt
STPIMS-ERR-015	Invalid registration
STPIMS-ERR-016	Invalid payment
STPIMS-ERR-017	Inactive partner
STPIMS-ERR-021	Incorrect phone number
STPIMS-ERR-022	Mobile operator is not functioning
STPIMS-ERR-023	Service not found
STPIMS-ERR-024	No connection with the bank
STPIMS-ERR-025	Bank not found
STPIMS-ERR-026	Please try again later
STPIMS-ERR-027	Contact the administrator
STPIMS-ERR-028	Connection to bank denied
STPIMS-ERR-029	Unregistered bank
STPIMS-ERR-030	Card not found in the bank
STPIMS-ERR-031	Request limit exceeded
STPIMS-ERR-032	Agent not found
STPIMS-ERR-033	Phone number does not match
STPIMS-ERR-034	Transaction failed
STPIMS-ERR-037	Store ID not found
STPIMS-ERR-039	Invalid payment amount
STPIMS-ERR-042	Unauthorized payment amount
STPIMS-ERR-043	Bank card not found
STPIMS-ERR-044	Store with current ID not found
STPIMS-ERR-048	Number already registered
STPIMS-ERR-050	Card cannot be registered
STPIMS-ERR-051	Information not found
STPIMS-ERR-053	Mobile prefix not found
STPIMS-ERR-054	More than two mobile updates
STPIMS-ERR-055	Numbers not found
STPIMS-ERR-056	Authorization problem
STPIMS-ERR-057	Insufficient funds
STPIMS-ERR-058	Card blocked
STPIMS-ERR-060	Unregistered user
STPIMS-ERR-061	Requested transaction not found
STPIMS-ERR-062	Invalid request
STPIMS-ERR-064	Payment cancelled
STPIMS-ERR-065	Payment in progress
STPIMS-ERR-066	You recently made a payment to this account, please try again later
STPIMS-ERR-067	Your card has expired. Please contact your bank.
STPIMS-ERR-068	Contact the issuer. Please contact your bank.
STPIMS-ERR-069	Suspicious card detected. Please contact your bank.
STPIMS-ERR-070	Transaction denied. Please contact your bank.
STPIMS-ERR-072	Your transactions are prohibited. Please contact your bank.
STPIMS-ERR-073	Your card has been reported as lost. Please contact your bank.
STPIMS-ERR-074	There is an issue with your card. Please contact your bank.
STPIMS-ERR-075	There is an issue with your card. Please contact your bank.
STPIMS-ERR-076	Your card is invalid. Please contact your bank.
STPIMS-ERR-077	There is an issue with your card. Please contact your bank.
STPIMS-ERR-078	There is an issue with your card. Please contact your bank.
STPIMS-ERR-079	Your card is blocked (not activated). Please contact your bank.
STPIMS-ERR-080	PIN code entry attempts exceeded. Please contact your bank.
STPIMS-ERR-081	Forced PIN change. Please contact your bank.
STPIMS-ERR-082	Your card is blocked due to outstanding credit debt. Please contact your bank.
STPIMS-ERR-083	Virtual card not activated
STPIMS-ERR-084	Only PIN transactions are available for this card
STPIMS-ERR-085	Your card is not personalized. Please contact your bank.
STPIMS-ERR-086	There is an issue with your card. Please contact your bank.
STPIMS-ERR-087	Temporarily blocked by user
STPIMS-ERR-088	This card has been blocked by the user. Please contact your bank.
STPIMS-ERR-089	SMS notifications not enabled. Please enable SMS notifications.
STPIMS-ERR-090	Card with this number not found. Incorrect card expiration date provided.
STPIMS-ERR-092	Transaction closed
STPIMS-ERR-093	Error in the provider's billing system
STPIMS-ERR-094	No connection to CRPC
STPIMS-ERR-095	User blocked
STPIMS-ERR-097	Card exists
STPIMS-ERR-098	OTP code entered incorrectly
STPIMS-ERR-099	EPOS data not specified
STPIMS-ERR-100	The requested transaction was previously cancelled
STPIMS-ERR-101	Transaction not cancelled
STPIMS-ERR-102	SMS not sent, SMS gateway is likely unavailable
STPIMS-ERR-103	Terminal not found
STPIMS-ERR-104	P2P transfers are disabled for this bank
STPIMS-ERR-105	User and card are not linked
STPIMS-ERR-106	Incorrect SMS format
STPIMS-ERR-107	Installment / Autopayment / Credit not found
STPIMS-ERR-108	Incorrect payment data
STPIMS-ERR-109	EPOS data is incorrect
STPIMS-ERR-111	Sender and recipient cards must not be identical
STPIMS-ERR-112	Insufficient card balance for payment
STPIMS-ERR-113	Payment closed
STPIMS-ERR-114	Payment closed
STPIMS-ERR-116	Error receiving card information
STPIMS-ERR-117	Incorrect card number
STPIMS-ERR-118	Payment status unknown
STPIMS-ERR-120	Payment is temporarily unavailable
STPIMS-ERR-121	Transfer is being processed
STPIMS-ERR-124	User session key not created
STPIMS-ERR-125	User session not deleted
STPIMS-ERR-127	The partner has not added any cards or the card is inactive
STPIMS-ERR-128	The specified account number is not found in the specified transaction
STPIMS-ERR-130	When creating a scheduler, you need to specify the debit card
STPIMS-ERR-134	Sender card not specified
STPIMS-ERR-135	Recipient card not specified
STPIMS-ERR-136	Transfers using corporate cards are prohibited
STPIMS-ERR-137	Transfers using corporate cards are prohibited
STPIMS-ERR-138	Monthly limit exceeded for p2p
STPIMS-ERR-139	One-time limit exceeded for p2p
STPIMS-ERR-140	One-time limit exceeded for p2p
STPIMS-ERR-142	Hold not confirmed
STPIMS-ERR-143	Hold not removed
STPIMS-ERR-144	Hold time expired
INFO-201	Confirmation code sent to SMS notification number
INFO-202	Payment in process

System errors (IPS)

Code	Description	Comment
0	Success	Operation completed successfully
-1	Internal error	Contact administrator, system error occurred
-20	Terminal not found	Terminal not found or not registered. Contact administrator
-11	Transaction in an uncertain state	Transaction cannot be continued. Depends on the operation being performed and the transaction status
-12	Transaction not found	Transaction not found for specified identifier
-100	Processing error	Processing error occurred
-200	Card not found	Card not found
-201	Card not verified	Card failed 3DS verification

System status (IPS)

Status	Description
1	Transaction created
2	Waiting for transaction creation status
3	Waiting for transaction confirmation status
4	Transaction confirmation
5	Transaction ended unsuccessfully
6	Transaction cancellation completed successfully
7	Transaction refund completed successfully
8	Waiting for transaction cancellation status
9	Waiting for transaction refund status

3DS Verification statuses (IPS)

Status	Description
PENDING	Waiting for 3DS card verification
VERIFIED	3DS verification completed successfully
FAILED	3DS verification ended unsuccessfully

Reference guide for statuses and types (IPS - Card Linking)

Error codes

Code	Name	Description
0	OK	Successful request
-1	ERROR	A system error occurred
-2	UNDEFINED	Undefined error
-100	PROCESSING_ERROR	Request processing error
-10	TRANSACTION_UNIQUENESS_ERROR	Transaction already exists
-11	TRANSACTION_INVALID_STATE_ERROR	Transaction in invalid state
-12	TRANSACTION_NOT_FOUND	Transaction not found
-15	TRANSACTION_NOT_CANCELLED	Unable to cancel transaction, try again later
-203	TRANSACTION_DECLINED	Transaction declined by payment provider
-300	INSUFFICIENT_FUNDS	Transaction declined due to insufficient funds
-13	COMMISSION_ERROR	Error calculating commission
-200	CARD_NOT_FOUND	Card not found
-201	CARD_NOT_VERIFIED	3D card authorization expected
-202	CARD_NOT_VALID	The card is not valid
-204	CARD_BIND_NOT_VALID	Card binding is not active
-20	TERMINAL_NOT_FOUND	Terminal not found
-21	TERMINAL_CONFIGURATION_ERROR	Terminal configuration error
-350	STORE_NOT_FOUND	Store not found by identifier
-400	API_KEY_NOT_FOUND	API key not found

Transaction status (status)

Code	Status	Final
0	NEW	no
1	OPEN	no
2	PENDING_OPEN	no
3	PENDING_CONFIRM	no
4	SUCCESS	yes
5	FAILED	yes
6	CANCELLED	yes
7	REVERTED	yes
8	PENDING_CANCELLED	yes
9	PENDING_REVERTED	yes

The final - no feature indicates that the transaction is being processed, and after time has passed, it is necessary to re-request the status

Card verification statuses (verified_state)

Status
OPEN
PENDING
VERIFIED
FAILED

Processing transaction types (card_type)

Type
VISA
MASTERCARD

Sandbox

For testing and integration with the API, it is recommended to use test payment data. All operations performed with the provided cards are for demonstration purposes only and do not involve the deduction of real funds.

Test cards:

PAN: 9860090101014364 Expiry: 02/28
PAN: 9860090101893213 Expiry: 02/28
PAN: 9860090101842392 Expiry: 02/28
PAN: 9860090101469915 Expiry: 02/28

Error debug test cards:

PAN: 8600492986215602 Expiry: 03/20 - card expired

The default OTP for all test cards is - 111111

Callback API

Callback API - a mechanism for reconciling transactions with the merchant. When processing each transaction, ATMOS system communicates with the merchant's billing system and transmits payment data to it in JSON format. The amount will only be deducted after receiving a successful status from the merchant.

For the Service Provider in the ATMOS system, an api_key is provided to verify incoming messages.

The transaction will only be successful if you receive a 200 OK status from the merchant's billing system. The body of the answer must contain the following data, this criterion is also mandatory:

{
   "status": 1,
   "message": "Successfully"
}

The provider's (merchant's) billing should only receive requests from the ATMOS system. To achieve this, the system's IP address must be specified: 185.8.212.47

Sending data

The Callback API sends the following data to the provider's system:

Parameter	Value
store_id	merchant ID
transaction_id	transaction ID
transaction_time	transaction time
amount	amount
invoice	identifier of the paid invoice
sign	unique digital signature

The sign field is generated by hashing according to the formula: store_id+transaction_id+invoice+amount+api_key without separators; Is a unique digital signature for each payment.

{
   "status": 1,
   "message": "Successfully"
}

{
   "status": 0,
   "message": "Invoice number 123 is not available in the system."
}

Examples of provider (merchant) billing response

The Callback API confirms payment only if the merchant's billing response has a status parameter value of 1 and a response code of 200. Example answers are provided in the sidebar

Parameter	Value
status	answer status
message	text message (status details)

Sequence of actions

Based on the information provided, the operating principle of the Callback API mechanism can be described step by step as follows:

On the ATMOS side, the payment is formed and the payment process is initiated;
Before confirming payment, the ATMOS system contacts the merchant's billing system, sending payment data (see sending data);
The merchant confirms or declines the payment (see examples of provider's (merchant's) billing response)
Transaction completed

Alternative payment options

Payment through the widget is a solution for simplified integration with the ATMOS payment service. The payment widget enables accepting payments on the merchant's website through a specially generated payment widget. The payment widget is created using a constructor tool, by specifying the necessary parameters which will be detailed below.

Insertable code:

    <!--  tag head -->
    <script src="https://cdn.pays.uz/checkout/js/v1.0.1/test-checkout.js">
    </script>
    <!--  tag head -->

    <div id="parent-frame">
        <script th:inline="javascript">
            /*<![CDATA[*/
            paymo_open_widget({
                parent_id: "parent-frame",  // id html-element for embedding widget
                store_id: 0,                // unique id of your store
                account: "abc",             // payment identifier
                terminal_id: 0,             // terminal id (if available)
                success_redirect: "url",    // redirect address after successful payment
                fail_redirect: "url",       // redirect address after failed payment
                version: "1.0.0",           // widget version
                amount: 500000,             // payment amount in tiyns
                details: "string",          // payment details (string)
                lang:"ru",                  // widget language (en, ru, uz)
                key:                        // authorization key
                theme: "blue"               // Widget color
            });
            /*]]>*/
        </script>
    <div/>

Insert the HTML tag <script src="url"></script>into your page. In the src attribute of the script tag, specify the URL for retrieving the script:
- for testing: http://cdn.pays.uz/checkout/js/v1.0.1/test-checkout.js
- for accepting real payments: https://cdn.pays.uz/checkout/js/v1.0.1/checkout.js
  It is recommended to place the tag before the closing head tag or before the closing body tag on your page.
Embed the code provided in the side panel into your website's HTML markup;
Specify the necessary parameters for the widget to function;
The widget is now ready for use.

Parameter	Description	Obligatory
parent_id	HTML element ID for embedding the widget	yes
store_id	your store ID	yes
account	payment identifier (arbitrary string)	yes
terminal_id	terminal ID (if applicable)	no
success_redirect	redirect URL after successful payment	yes
fail_redirect	redirect URL for failed payment	yes
version	widget version	no
amount	payment amount in tiyns	yes
details	payment details (arbitrary string)	no
lang	widget language (en, ru, uz)	no
key	authorization key	yes
theme	widget color scheme	no

Payment page

The payment page is the most convenient solution for mobile applications that support webview. It provides secure payment processing on the ATMOS side.

To pay for creation through the payment page, you need:

Call the /merchant/pay/create method and create a draft transaction for payment;
Navigate to the payment page, specifying the following parameters:
- storeId - the unique ID of your store;
- transactionId - the ID of the previously created transaction;
- redirectLink - the URL for redirection after payment (optional).

As a result, the generated link should have a similar appearance:

https://test-checkout.pays.uz/invoice/get?storeId=1111&transactionId=222222&redirectLink=http://site.com

Test page (sandbox): http://test-checkout.pays.uz/invoice/get

Payment page (production): https://checkout.pays.uz/invoice/get