Оплаты

Раздел описывает методы для взаимодействия с оплатами. Методы позволяют мерчантам проводить оплаты (списывать средства) и регистрировать фискальные чеки.

API также предоставляет возможность для мерчантов-агрегаторов (например, для маркетплейсов или агрегаторов такси) проводить оплату в пользу других мерчантов (например, продавцов и таксопарков).

Структура оплаты

Сущность оплаты включает информацию о фискальных чеках, статусе и методе оплаты, а также список товаров.

Name
id
Type
string
Description
Уникальный (для клиента API) идентификатор оплаты.
Name
amount
Type
integer
Description
Сумма оплаты для списания (в тийинах) в диапазоне от 50000 до 20000000000 тийин для одного списания средств у покупателя. Не включает в себя сумму скидки.
Name
status
Type
string
Description
Статус списания.
Name
method
Type
string
Description
Метод оплаты.
Name
receipt
Type
object
Description
Информация о фискальном чеке.
Показать атрибуты
Name
type
Type
integer
Description
Тип чека в налоговой: 0 — покупка, 1 — аванс, 2 — кредит. По умолчанию 0.
Name
phone
Type
string
Description
Номер телефона покупателя.
Name
items
Type
array
Description
Список товаров, включённых в оплату. Необходим для регистрации фискальных чеков.
Показать атрибуты
Name
name
Type
string
Description
Название.
Name
amount
Type
integer
Description
Количество экземпляров (натуральное число).
Name
price
Type
integer
Description
Стоимость в тийинах (натуральное число). Суммарная стоимость всех товаров с учётом скидок (discount) должна быть в диапазоне от 50000 до 20000000000 тийин для одного списания средств у покупателя.
Name
spic
Type
string
Description
ИКПУ-код, обязательный.
Name
discount
Type
integer
Description
Полная сумма скидки для товара в тийинах, если предоставляется. Не должна превышать полную стоимость товара (price ✕ amount).
При регистрации фискального чека скидка отражается на соответствующем параметре в чеке.
Name
marking_code
Type
string
Description
Код маркировки, необязательный.
Name
vat_percent
Type
integer
Description
Процент НДС для товара (сумма НДС вычисляется после вычета скидки).
Name
tin
Type
string
Description
ИНН комитента для регистрации чека. Состоит из 9 цифр. Указывается, только если не указан ПИНФЛ.
Name
pin
Type
string
Description
ПИНФЛ комитента для регистрации чека. Состоит из 14 цифр. Указывается, только если не указан ИНН.
Name
payment_id
Type
string
Description
Идентификатор PaymentId для Soliq. Используется кассами для регистрации чека налоговой.
Name
results
Type
array of objects
Description
Список фискальных чеков после регистрации.
Показать атрибуты
Name
merchant_id
Type
integer
Description
Идентификатор мерчанта, для которого зарегистрирован чек.
Name
url
Type
string
Description
Ссылка на фискальный чек.
Name
refund
Type
boolean
Description
true для чека возврата. Иначе false.
Name
payouts
Type
array
Description
Параметры для распределения списанных средств в пользу других мерчантов, если распределение требуется. Общая сумма распределения не должна превышать сумму счёта.
Оставшаяся после распределения сумма средств направляется мерчанту, создавшему счёт.
Необходимо указать один из идентификаторов мерчанта.
Показать атрибуты
Name
amount
Type
integer
Description
Сумма, предназначенная для мерчанта.
Name
tin
Type
string
Description
ИНН мерчанта (9 цифр).
Name
pin
Type
string
Description
ПИНФЛ мерчанта (14 цифр).

Статусы списания

Значение	Описание
`SUCCEEDED`	Успешно
`INSUFFICIENT_FUNDS`	Недостаточно средств
`INVALID_CARD`	Невалидная карта
`REVERTED`	Отменена
`OTP_REQUIRED`	Требуется ввод кода подтверждения
`BLOCKED_CARD`	Заблокированная карта
`EXPIRED_CARD`	Истек срок действия карты
`SMS_NOTIFICATION_IS_OFF`	Отключено СМС-информирование
`INCORRECT_OTP`	Неправильный код подтверждения
`EXPIRED_OTP`	Просроченный код подтверждения
`PENDING`	В процессе обработки
`PENDING_REVERSAL`	Отмена в процессе обработки
`DECLINED`	Платеж отклонен
`UNKNOWN_ERROR`	Неизвестная ошибка

{
  "id": "035033da-4065-4c5b-adac",
  "amount": 7800000,
  "status": "OTP_REQUIRED",
  "method": {
    "type": "CARD",
    "payload": {
      "pan": "123411******1111",
      "phone": "+998*****5564"
    }
  },
  "receipt": {
    "type": 0,
    "phone": "998123456789",
    "items": [
      {
        "name": "Mug v556-3.25 (blue)",
        "marking_code": "1545637",
        "spic": "08517001001000000",
        "amount": 2,
        "price": 4000000,
        "discount": 200000,
        "vat_percent": 12
      }
    ],
    "payment_id": "e897-4ab3-abff-136a48b9e437",
    "results": [
      {
        "merchant_id": 105,
        "url": "https://ofd.soliq.uz/epi?t=EP000000000001&r=001&c=20060102000000&s=000000000001",
        "refund": false
      }
    ]
  },
  "payouts": [
    {
      "amount": 3000000,
      "pin": "31001732720040"
    },
    {
      "amount": 50000,
      "tin": "306781762"
    }
  ]
}

POST/pay

Оплата

Инициирует оплату: списывает средства по указанному методу оплаты, регистрирует фискальные чеки, распределяет списанные средства продавцам.

При оплате дебетовой картой для подтверждения списания средств используется идентификатор оплаты id.

Параметры

Name
id
Type
string обязательный
Description
Уникальный (для клиента API) идентификатор оплаты.
Name
amount
Type
integer обязательный
Description
Сумма оплаты для списания (в тийинах). Должна быть в диапазоне от 50000 до 20000000000 тийин для одного списания средств у покупателя. Не должна включать в себя сумму скидки.
Name
method
Type
object обязательный
Description
Метод оплаты. Имеет динамический набор параметров, который определяется указанным типом (type).
Показать атрибуты
Name
type
Type
string обязательный
Description
Одно из значений: CARD, TOKEN, HOLD, MOBI_SHOW_QR.
Тип CARD:
Показать атрибуты
Единоразовая оплата картой. Производится отправка СМС с кодом подтверждения на номер телефона, для которого подключено СМС-информировани по карте. В этом случае списание производится после подтверждения оплаты.
Name
pan
Type
string обязательный
Description
Номер карты.
Name
exp
Type
string обязательный
Description
Дата истечения срока действия карты в формате MMYY.
Тип TOKEN:
Показать атрибуты
Оплата токенизированной картой.
Name
token
Type
string обязательный
Description
Токен карты, полученный токенизацией.
Name
force
Type
boolean
Description
Если true, с карты списываются все доступные средства (от 1000 сум), когда на балансе карты недостаточно средств для списания изначально указанной суммы amount. Итоговая сумма списания указана в ответе при оплате и в ответе метода получения оплаты.
В некоторых случаях по-прежнему может вернуться статус INSUFFICIENT_FUNDS.
Эта опция недоступна при использовании параметра payouts.
Тип HOLD:
Показать атрибуты
Name
id
Type
string обязательный
Description
Идентификатор холдирования.
Тип MOBI_SHOW_QR:
Показать атрибуты
Name
token
Type
string обязательный
Description
Идентификатор источника средств для списания.
Name
receipt
Type
object
Description
Параметры фискального чека.
Показать атрибуты
Name
type
Type
integer
Description
Тип чека в налоговой: 0 — покупка, 1 — аванс, 2 — кредит. По умолчанию 0.
Name
phone
Type
string
Description
Номер телефона покупателя. Используется для регистрации фискального чека.
Name
items
Type
array обязательный
Description
Список товаров, включяемых в оплату/покупку для формирования чека.
Показать атрибуты
Name
name
Type
string обязательный
Description
Название.
Name
amount
Type
integer обязательный
Description
Количество экземпляров (натуральное число).
Name
price
Type
integer обязательный
Description
Стоимость в тийинах (натуральное число). Суммарная стоимость всех товаров с учётом скидок (discount) должна быть в диапазоне от 50000 до 20000000000 тийин для одного списания средств у покупателя.
Name
spic
Type
string обязательный
Description
ИКПУ-код.
Name
discount
Type
integer
Description
Полная сумма скидки для товара в тийинах, если предоставляется. Не должна превышать полную стоимость товара (price ✕ amount).
При регистрации фискального чека скидка отражается на соответствующем параметре в чеке.
Name
marking_code
Type
string
Description
Код маркировки.
Name
vat_percent
Type
integer
Description
Процент НДС для товара (сумма НДС вычисляется после вычета скидки).
Name
tin
Type
string
Description
ИНН комитента для регистрации чека. Состоит из 9 цифр. Указывается, только если не указан ПИНФЛ.
Name
pin
Type
string
Description
ПИНФЛ комитента для регистрации чека. Состоит из 14 цифр. Указывается, только если не указан ИНН.
Name
payouts
Type
array
Description
Параметры для распределения списанных средств в пользу других мерчантов, если распределение требуется. Общая сумма распределения не должна превышать сумму оплаты.
Оставшаяся после распределения сумма средств направляется мерчанту, совершившему запрос на оплату.
Необходимо указать один из идентификаторов мерчанта.
Показать атрибуты
Name
amount
Type
integer обязательный
Description
Сумма, предназначенная для мерчанта.
Name
tin
Type
string
Description
ИНН мерчанта (9 цифр).
Name
pin
Type
string
Description
ПИНФЛ мерчанта (14 цифр).

Ответ

В ответе возвращается объект оплаты.

Запрос

POST

/pay

{
  "id": "035033da-4065-4c5b-adac",
  "amount": 7800000,
  "method": {
    "type": "CARD",
    "pan": "1234111111111111",
    "exp": "0324"
  },
  "receipt": {
    "type": 0,
    "phone": "998123456789",
    "items": [
      {
        "name": "Mug v556-3.25 (blue)",
        "spic": "08517001001000000",
        "amount": 2,
        "price": 4000000,
        "discount": 200000,
        "tin": "306781762",
        "vat_percent": 12
      }
    ]
  },
  "payouts": [
    {
      "amount": 3000000,
      "pin": "31001732720040"
    },
    {
      "amount": 50000,
      "tin": "306781762"
    }
  ]
}

Ответ

{
  "id": "035033da-4065-4c5b-adac",
  "amount": 7800000,
  "status": "OTP_REQUIRED",
  "method": {
    "type": "CARD",
    "payload": {
      "pan": "123411******1111",
      "phone": "********6789"
    }
  },
  "receipt": {
    "type": 0,
    "phone": "998123456789",
    "items": [
      {
        "name": "Mug v556-3.25 (blue)",
        "spic": "08517001001000000",
        "amount": 2,
        "price": 4000000,
        "discount": 200000,
        "tin": "306781762",
        "vat_percent": 12
      }
    ],
    "payment_id": "e897-4ab3-abff-136a48b9e437"
  },
  "payouts": [
    {
      "amount": 3000000,
      "pin": "31001732720040"
    },
    {
      "amount": 50000,
      "tin": "306781762"
    }
  ]
}

POST/confirmPayment

Подтверждение оплаты

Подтверждает единоразовую оплату (без токенизации) с помощью идентификатора оплаты и одноразового кода подтверждения.

Параметры

Name
id
Type
string обязательный
Description
Идентификатор оплаты.
Name
otp
Type
string обязательный
Description
Одноразовый код подтверждения (one-time password), отправленный на номер телефона, для которого включено СМС-информирование для используемого метода оплаты (например, банковской карты).

Запрос

POST

/confirmPayment

{
  "id": "ea898fef-6bbc-495e-ad78",
  "otp": "111111"
}

Ответ

{
  "id": "ea898fef-6bbc-495e-ad78",
  "amount": 7800000,
  "status": "SUCCEEDED",
  "method": {
    "type": "CARD",
    "payload": {
      "pan": "123411******1111"
    }
  }
}

POST/getPayment

Просмотр оплаты

Позволяет просмотреть оплату по идентификатору.

Параметры

Name
id
Type
string обязательный
Description
Уникальный (для клиента API) идентификатор оплаты.

Запрос

POST

/getPayment

{
  "id": "035033da-4065-4c5b-adac"
}

Ответ

{
  "id": "035033da-4065-4c5b-adac",
  "amount": 7800000,
  "status": "OTP_REQUIRED",
  "method": {
    "type": "CARD",
    "payload": {
      "pan": "123411******1111",
      "phone": "+998*****5564"
    }
  },
  "receipt": {
    "type": 0,
    "phone": "998123456789",
    "items": [
      {
        "name": "Mug v556-3.25 (blue)",
        "spic": "08517001001000000",
        "amount": 2,
        "price": 4000000,
        "discount": 200000,
        "tin": "306781762",
        "vat_percent": 12
      }
    ],
    "payment_id": "e897-4ab3-abff-136a48b9e437",
    "results": [
      {
        "url": "https://ofd.soliq.uz/epi?t=EP000000000001&r=001&c=20060102000000&s=000000000001",
        "merchant_id": 14,
        "refund": false
      }
    ]
  },
  "payouts": [
    {
      "amount": 3000000,
      "pin": "31001732720040"
    },
    {
      "amount": 50000,
      "tin": "306781762"
    }
  ]
}

POST/refundPayment

Отмена оплаты

Позволяет отменить оплату. Возвращает средства покупателю и регистрирует фискальный чек возврата, если ранее был зарегистрирован соответствующий чек оплаты.

Параметры

Name
id
Type
string обязательный
Description
Уникальный (для клиента API) идентификатор оплаты.

Атрибуты ответа

Name
id
Type
string
Description
Идентификатор оплаты (тот же, что и в запросе).

Запрос

POST

/refundPayment

{
  "id": "035033da-4065-4c5b-adac"
}

Ответ

{
  "id": "035033da-4065-4c5b-adac"
}

POST/refundPaymentPartial

Частичная отмена оплаты

Позволяет отменить оплату частично. Возможен только для оплат в рассрочку. Создаёт заявку на отмену и в случае одобрения возвращает средства на лимит покупателя.

Параметры

Name
id
Type
string обязательный
Description
Уникальный (для клиента API) идентификатор возврата.
Name
payment_id
Type
string обязательный
Description
Идентификатор оплаты.
Name
amount
Type
integer обязательный
Description
Сумма отмены в тийинах.
Name
webhook_url
Type
string
Description
URL вебхука.

Атрибуты ответа

Name
id
Type
string
Description
Уникальный (для клиента API) идентификатор возврата.
Name
status
Type
string
Description
Статус возврата, один из: DONE, PENDING, FAILED. Статус PENDING означает, что возврат находится на рассмотрении.
При каких-либо ошибках при возврате может вернуться статус FAILED без пояснения причины ошибки.
Name
amount
Type
integer
Description
Сумма возврата в тийинах.
Name
webhook_url
Type
string
Description
URL вебхука.

Запрос

POST

/refundPaymentPartial

{
  "id": "92f1b03a-acfc-41bb-91bc",
  "payment_id": "035033da-4065-4c5b-adac",
  "amount": 1150000
}

Ответ

{
  "id": "92f1b03a-acfc-41bb-91bc",
  "status": "PENDING",
  "amount": 1150000
}

POST/getRefund

Просмотр отмены

Возвращает информацию об отмене по идентификатору.

Параметры

Name
id
Type
string обязательный
Description
Уникальный (для клиента API) идентификатор отмены.

Атрибуты ответа

Name
id
Type
string
Description
Уникальный (для клиента API) идентификатор отмены.
Name
status
Type
string
Description
Статус отмены, один из: DONE, PENDING, FAILED. Статус PENDING означает, что отмена находится на рассмотрении.
При каких-либо ошибках при отмене может вернуться статус FAILED без пояснения причины ошибки.
Статус DONE означает, что отмена осуществлена успешно или одобрена.
Name
amount
Type
integer
Description
Сумма возврата в тийинах.

Запрос

POST

/getRefund

{
  "id": "92f1b03a-acfc-41bb-91bc",
}

Ответ

{
  "id": "92f1b03a-acfc-41bb-91bc",
  "status": "PENDING",
  "amount": 1150000
}

Имитация завершения отмены бета-версия

Позволяет имитировать успешное или проваленное завершение отмены. Доступен только в тестовой среде.

Параметры

Name
refund_id
Type
string обязательный
Description
Идентификатор отмены, использовавшийся в инициализации отмены.
Name
approve
Type
bool
Description
Флаг, указывающий завершить ли отмену успешно. При указании true отмена будет завершена со статусом DONE, иначе со статусом FAILED.

Атрибуты ответа

Name
ok
Type
bool
Description
Всегда имеет значение true.

Запрос

POST

/_completeInstallmentRefund

{
  "id": "92f1b03a-acfc-41bb-91bc",
}

Ответ

{
  "message": "success"
}

Вебхуки

Завершение оплаты

Отправляется при успешном или проваленном завершении оплаты.

Name
payload
Type
object
Description
Структура оплаты с актуальными данными.

Тело

{
  "id": "035033da-4065-4c5b-adac",
  "amount": 7800000,
  "status": "SUCCEEDED",
  "method": {
    "type": "CARD",
    "payload": {
      "pan": "123411******1111"
    }
  },
  "receipt": {
    "type": 0,
    "phone": "998123456789",
    "items": [
      {
        "name": "Mug v556-3.25 (blue)",
        "marking_code": "1545637",
        "spic": "08517001001000000",
        "amount": 2,
        "price": 4000000,
        "discount": 200000,
        "vat_percent": 12
      }
    ]
  },
  "payouts": [
    {
      "amount": 3000000,
      "pin": "31001732720040"
    },
    {
      "amount": 50000,
      "tin": "306781762"
    }
  ]
}

POST/registerReceipt

Регистрация чека

Позволяет зарегистрировать фискальный чек и привязать его к оплате в пользу партнера, инициировавшего запрос.

Параметры

Name
id
Type
string обязательный
Description
Идентификатор оплаты.
Name
fiscal_data
Type
object обязательный
Description
Структура фискального чека.
Показать атрибуты
Name
qr_code_url
Type
string обязательный
Description
URL чека.
Name
is_refund
Type
boolean
Description
Чек продажи или возврата.
Name
phone_number
Type
string
Description
Номер телефона профиля, на который будет начислен кешбэк.
Name
location
Type
object
Description
Структура информации о геолокации.
Показать атрибуты
Name
latitude
Type
number
Description
Долгота геолокации, где прошла оплата.
Name
longitude
Type
number
Description
Широта геолокации, где прошла оплата.
Name
tin
Type
string
Description
ИНН продавца. Это поле не нужно заполнять, если поле ПИНФЛ было заполнено.
Name
pinfl
Type
string
Description
ПИНФЛ продавца. Это поле не нужно заполнять, если поле ИНН было заполнено.
Name
sale_point_address
Type
string
Description
Адрес места, где была совершена оплата.

Атрибуты ответа

Name
ok
Type
boolean
Description
Флаг, сигнализирующий об успехе операции.

Запрос

POST

/registerReceipt

{
  "id": "035033da-4065-4c5b-adac",
  "fiscal_data": {
    "qr_code_url": "https://ofd.soliq.uz/epi?t=EP000000000001&r=001&c=20060102000000&s=000000000001",
    "phone_number": "998123456789",
    "is_refund": false,
  },
  "location": {
    "latitude": -50.000,
    "longitude": 100.00
  },
  "tin": "123456789",
  "pinfl": "01234567890123",
  "sale_point_address": "Узбекистан, город Ташкент"
}

Ответ

{
  "ok": true
}