Покупки

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

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

Структура покупки

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

  • Name
    ref
    Type
    string
    Description

    Уникальный (для клиента API) идентификатор покупки.

  • Name
    phone
    Type
    string
    Description

    Номер телефона покупателя.

  • Name
    receipt
    Type
    boolean
    Description

    Флаг для включения регистрации фискальных чеков.

  • Name
    charge
    Type
    object
    Description

    Оплата покупки.

  • Name
    items
    Type
    object array
    Description

    Список товаров, включённых в покупку. Если разбивка на товары не предусмотрена и нет необходимости в регистрации фискальных чеков, в этом списке достаточно передать один товар на всю сумму для оплаты.

    • Name
      name
      Type
      string
      Description

      Название.

    • Name
      marking_code
      Type
      string
      Description

      Код маркировки, необязательный.

    • Name
      spic
      Type
      optional string
      Description

      ИКПУ-код. Обязательный, если receipt: true.

    • Name
      amount
      Type
      integer
      Description

      Количество экземпляров (натуральное число).

    • Name
      price
      Type
      integer
      Description

      Стоимость в тийинах (натуральное число). Суммарная стоимость всех товаров с учётом скидок (discount) должна быть в диапазоне от 50000 до 20000000000 тийин для одного списания средств у покупателя.

    • Name
      discount
      Type
      optional integer
      Description

      Полная сумма скидки для товара в тийинах, если предоставляется.

      Вычитается автоматически из полной стоимости товара и не будет списана через метод оплаты (например, с дебетовой карты). Не должна превышать полную стоимость товара (price ✕ amount).

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

    • Name
      merchant_id
      Type
      optional integer
      Description

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

{
  "ref": "035033da-4065-4c5b-adac",
  "merchant_id": 123,
  "charge": {
    "ref": "ea898fef-6bbc-495e-ad78",
    "amount": 7800000,
    "status": "OTP_REQUIRED",
    "method": {
      "type": "CARD",
      "payload": {
        "pan": "123411******1111"
      }
    },
    "user_action": {
      "phone": "+998*****5564"
    }
  },
  "phone": "998123456789",
  "items": [
    {
      "name": "Mug v556-3.25 (blue)",
      "marking_code": "1545637",
      "spic": "08517001001000000",
      "amount": 2,
      "price": 4000000,
      "discount": 200000
    }
  ]
}

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

  • Name
    ref
    Type
    string
    Description

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

  • Name
    amount
    Type
    integer
    Description

    Сумма в тийинах.

  • Name
    status
    Type
    string
    Description

    Статус.

  • Name
    method
    Type
    string
    Description

    Метод оплаты.

Список статусов

ЗначениеОписание
PENDING В процессе
SUCCEEDED Успешно
INSUFFICIENT_FUNDSНедостаточно средств
INVALID_CARD Невалидная карта
PENDING_REVERSAL В процессе отмены
REVERTED Отменена
OTP_REQUIRED Требуется ввод OTP
UNKNOWN_ERROR Неизвестная ошибка
BLOCKED_CARD Заблокированная карта
EXPIRED_CARD Истек срок действия карты
SMS_NOTIFICATION_IS_OFFОтключено СМС-информирование
INCORRECT_OTP Неправильный OTP
EXPIRED_OTP Просроченный OTP
{
  "ref": "ea898fef-6bbc-495e-ad78",
  "amount": 8800000,
  "status": "OTP_REQUIRED",
  "method": {
    "type": "CARD",
    "payload": {
      "pan": "123411******1111"
    }
  },
  "user_action": {
    "phone": "+998*****5564"
  }
}
POST/purchase

Создание покупки

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

Для подтверждения списания средств используется идентификатор оплаты (charge.ref) из структуры оплаты, содержащейся в ответе при создании покупки.

Параметры

  • Name
    ref
    Type
    string
    Description

    Уникальный (для клиента API) идентификатор покупки.

  • Name
    items
    Type
    array
    Description

    Список товаров, включяемых в покупку.

  • Name
    phone
    Type
    optional string
    Description

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

  • Name
    receipt
    Type
    optional boolean
    Description

    Флаг включения регистрации фискальных чеков.

Способы оплаты

Ниже представлены поля способов оплаты. Одно и только одно из этих полей должно быть заполнено. При заполнении нескольких полей способов оплаты запрос будет провален.

  • Name
    card
    Type
    optional object
    Description

    Реквизиты карты при единоразовой оплате. Производится отправка СМС с кодом подтверждения на номер телефона, для которого подключено СМС-информировани по карте. В этом случае списание производится после подтверждения оплаты.

    • Name
      pan
      Type
      string
      Description

      Номер карты.

    • Name
      exp
      Type
      string
      Description

      Дата истечения срока действия карты в формате MMYY.

  • Name
    bound_card
    Type
    optional object
    Description

    Токен карты при списании с токенизированной карты.

    • Name
      token
      Type
      string
      Description

      Токен карты.

  • Name
    hold
    Type
    optional object
    Description

    Структура, содержащая идентификатор ранее созданного холдирования средств на карте.

    • Name
      id
      Type
      string
      Description

      Идентификатор холдирования.

Ответ

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

Запрос

{
  "ref": "035033da-4065-4c5b-adac",
  "card": {
    "pan": "1234111111111111",
    "exp": "0324"
  },
  "phone": "998123456789",
  "receipt": true,
  "items": [
    {
      "name": "Mug v556-3.25 (blue)",
      "spic": "08517001001000000",
      "amount": 2,
      "price": 4000000,
      "discount": 200000
    }
  ]
}

Ответ

{
  "ref": "035033da-4065-4c5b-adac",
  "merchant_id": 123,
  "charge": {
    "ref": "ea898fef-6bbc-495e-ad78",
    "amount": 7800000,
    "status": "OTP_REQUIRED",
    "method": {
      "type": "CARD",
      "payload": {
        "pan": "123411******1111"
      }
    },
    "user_action": {
      "phone": "********6789"
    }
  },
  "items": [
    {
      "name": "Mug v556-3.25 (blue)",
      "spic": "08517001001000000",
      "amount": 2,
      "price": 4000000,
      "discount": 200000
    }
  ]
}
POST/confirmChargeOTP

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

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

Параметры

  • Name
    ref
    Type
    string
    Description

    Идентификатор оплаты.

  • Name
    otp
    Type
    string
    Description

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

Запрос

POST
/confirmChargeOTP
{
  "ref": "ea898fef-6bbc-495e-ad78",
  "otp": "111111"
}

Ответ

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

Просмотр покупки

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

Параметры

  • Name
    ref
    Type
    string
    Description

    Уникальный (для клиента API) идентификатор покупки.

Запрос

POST
/getPurchase
{
  "ref": "035033da-4065-4c5b-adac"
}

Ответ

{
  "ref": "035033da-4065-4c5b-adac",
  "merchant_id": 123,
  "charge": {
    "ref": "ea898fef-6bbc-495e-ad78",
    "amount": 7800000,
    "status": "OTP_REQUIRED",
    "method": {
      "type": "CARD",
      "payload": {
        "pan": "123411******1111"
      }
    },
    "user_action": {
      "phone": "+998*****5564"
    }
  },
  "phone": "998123456789",
  "items": [
    {
      "name": "Mug v556-3.25 (blue)",
      "marking_code": "1545637",
      "spic": "08517001001000000",
      "amount": 2,
      "price": 4000000,
      "discount": 200000,
      "merchant_id": 372
    }
  ],
  "tax_receipts": [
    {
      "merchant_id": 372,
      "url": "https://ofd.soliq.uz/epi?t=EP000000000001&r=001&c=20060102000000&s=000000000001",
      "refund": false
    }
  ]
}
POST/refundPurchase

Отмена покупки

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

Параметры

  • Name
    ref
    Type
    string
    Description

    Уникальный (для клиента API) идентификатор покупки.

Запрос

POST
/refundPurchase
{
  "ref": "035033da-4065-4c5b-adac"
}

Ответ

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

Вебхуки


Завершение покупки

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

  • Name
    payload
    Type
    object
    Description

    Структура покупки с актуальными данными.

Тело

{
  "type": "purchase",
  "payload": {
    "ref": "035033da-4065-4c5b-adac",
    "merchant_id": 123,
    "phone": "998123456789",
    "charge": { ... },
    "items": [ ... ]
  }
}