4.6. mPOS API Ru

Закрытие дня

Описание закрытия дня

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

Если по какой-либо причине не удается провести закрытие дня, используя «Удаленное закрытие дня», необходимо провести операцию закрытия дня вручную через личный кабинет или обратиться за помощью в службу поддержки.

Данная операция доступна не для всех эквайеров, за информацией обращайтесь в службу поддержки.

Для закрытия дня доступны следующие способы:

Принудительное закрытие дня

Автоматическое закрытие дня

Автоматическое закрытие дня по заранее установленному времени

Удаленное закрытие дня

Принудительное закрытие дня

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

pic1 close_day

pic2 close_day

На странице шлюза нажмите кнопку “Закрыть день” и подтвердите закрытие дня на всплывающем окне. На странице начнет отображаться окно “Закрытие дня для ‘имя шлюза’”, дождитесь завершения операции.

pic3 close_day

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

pic4 close_day

Warning

Во время закрытия дня шлюз блокируется и транзакции по нему проходить не будут.

Автоматическое закрытие дня

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

pic1 close_day

pic2 close_day

На странице шлюза нажмите кнопку “Редактировать”, поставьте галочку напротив пункта “Автоматическое закрытия дня” и нажмите “Сохранить”.

pic5 close_day
При автоматическом закрытии дня оптимальное время закрытия выбирается системой автоматически (ближе к концу рабочего дня по МСК).

Warning

Во время автоматического закрытия дня шлюз блокируется и транзакции по нему проходить не будут.

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

pic4 close_day

Автоматическое закрытие дня по заранее установленному времени

Для автоматического закрытия дня по заданному времени менеджеру или его сотруднику в личном кабинете системы надо перейти в настройки шлюза, для которого требуется закрывать день автоматически в установленное время.
pic1 close_day

pic2 close_day
На странице шлюза нажмите кнопку “Редактировать”, поставьте галочку напротив пункта “Закрывать день автоматически”, появится пункт “Время закрытия дня”, нужно выставить время закрытия дня, затем нажать “Сохранить”.
Обратите внимание, что пункт “Автоматическое закрытия дня” должен быть выключен, иначе время закрытия дня будет выбрано автоматически системой.
pic6 close_day

Закрытие дня будет выполняться в заданное время, после успешного закрытия дня на странице шлюза будет отображена информация о дате закрытия и сумме транзакций с момента последнего закрытия дня для данного шлюза до текущего закрытия дня.

pic6 close_day

Warning

Во время автоматического закрытия дня по заданному времени шлюз блокируется и транзакции по нему проходить не будут.

Удаленное закрытие дня

Удаленное закрытие дня позволяет закрыть день сразу на всех шлюзах определенного терминала. Для этого необходимо для ВСЕХ шлюзов ассоциированных с терминалом установить в настройках “Удаленное закрытие дня”.
Для удаленного закрытия дня менеджеру или его сотруднику в личном кабинете системы надо перейти в настройки шлюза, для которого требуется включить удаленное закрытие дня.
pic1 close_day

pic2 close_day
На странице шлюза нажмите кнопку “Редактировать”, поставьте галочку напротив пункта “Удаленное закрытие дня”, при необходимости, задайте число дней через которое будет срабатывать автоматическое закрытие дня, начиная с последнего успешного удаленного закрытия дня - пункт “Максимальная задержка закрытия дня (дн.)”, автоматически устанавливается 3 дня, затем нажмите “Сохранить”.
pic8 close_day

Warning

Во время удаленного закрытия дня шлюзы блокируются и транзакции по ним проходить не будут.

Для инициации Удаленного закрытия дня необходимо отправить HTTP запрос следующего вида:
POST https://${hostname}/paynet/api/v2/close-day/{endpointId}
Аутентификация пользователя происходит по OAuth 1.0, описание: oauth

Тело запроса

В теле запроса укажите данные со следующей структурой:
{
  "day_close_request_id": {string},
  "sale_approved_count": {string},
  "sale_approved_sum": {string},
  "reversal_approved_count": {string},
  "reversal_approved_sum": {string}
}

Имя свойства

Тип(длина)

Описание

Обязательные параметры

day_close_request_id

string(8-32)

Уникальный идентификатор запроса. Может содержать буквы и цифры

Необязательные параметры

sale_approved_count

string

Число подтвержденных sale транзакций

sale_approved_sum

string

Сумма по подтвержденным sale транзакциям

reversal_approved_count

string

Число подтвержденных reversal транзакций

reversal_approved_sum

string

Сумма по подтвержденным reversal транзакциям

Тело ответа

Пользователь генерирует идентификатор запроса и посылает запрос на закрытие дня. Если этот идентификатор используется впервые - начинается инициализация закрытия дня для гейта(ов), ассоциированного(ых) с переданным идентификатором терминала. Пользователю возвращается асинхронный ответ со статусом ‘starting’.
Пример структуры ответа следующий:
{
  "response": {
    "status": "starting",
    "gates": [ {
      "gateId": 193,
      "isDayClosing": true,
      "epntId": 1
      }, {
      "gateId": 82,
      "isDayClosing": true,
      "epntId": 1
      }, {
      "gateId": 317,
      "isDayClosing": true,
      "epntId": 1
    }
    ]
  },
  "theRequestSerialNumber": "00000000-0000-0000-0000-00000000001c"
}

Имя свойства

Тип

Описание

status

string

Статус операции закрытия дня

gateId

long

Идентификатор шлюза по которому происходит закрытие дня

isDayClosing

boolean

Флаг закрытия дня, при значении true - шлюз заблокирован

epntId

long

Свойство, присваемое банком терминалу при его настройке в системе банка

theRequestSerialNumber

string

Серийный номер запроса закрытия дня
Запрос с идентификатором day_close_request_id, уже использованным ранее, выполняет функцию статус-запроса. После первичного (инициирующего запроса) пользователь может продолжать посылать запросы по тому же адресу с тем же самым идентификатором запроса. В данном случае, этот идентификатор всегда будет ассоциирован с процедурой закрытия дня, которую он инициировал. Пока операция по закрытию дня в процессе выполнения - пользователю будет возвращаться асинхронный ответ со статусом ‘processing’.
Пример структуры ответа следущий:
{
  "response": {
    "status": "processing",
    "gates": [ {
      "gateId": 193,
      "isDayClosing": true,
      "epntId": 1
      }, {
      "gateId": 82,
      "isDayClosing": true,
      "epntId": 1
      }, {
      "gateId": 317,
      "isDayClosing": true,
      "epntId": 1
    }
    ]
  },
  "theRequestSerialNumber": "00000000-0000-0000-0000-00000000001e"
}

Имя свойства

Тип

Описание

status

string

Статус операции закрытия дня

gateId

long

Идентификатор шлюза по которому происходит закрытие дня

isDayClosing

boolean

Флаг закрытия дня, при значении true - шлюз заблокирован

epntId

long

Свойство, присваемое банком терминалу при его настройке в системе банка

theRequestSerialNumber

string

Серийный номер запроса закрытия дня
Информация о закрытом дне появится в ответе от сервера по мере ее поступления от процессоров (в случае одновременного закрытия нескольких гейтов). После закрытия дня гейта(ов) статус ответа примет значение ‘finished’, вне зависимости от того, завершилось ли закрытие дня на всех гейтах успешно, или часть гейтов (или все) закрылись с ошибкой.

Warning

Если во время удаленного закрытия дня шлюз(ы) останутся в заблокированном состоянии (в теле ответа при “status”: “finished” для шлюза - “isDayClosing”: true), воспользуйтесь инструментом снятия блокировки в личном кабинете системы, который описан далее в этом разделе.

Пример структуры ответа следующий:
{
  "response": {
    "status": "finished",
        "gates": [ {
              "gateId": 193,
              "isDayClosing": false,
              "gateCloseDate": "Mon Dec 10 14:44:21 MSK 2018",
              "epntId": 1,
              "saleApprovedCount": "2334",
              "saleAmount": "87328428482.00",
              "reversalApprovedCount": "123",
              "reversalAmount": "12393423.00",
              "code39": "000",
              "RRN": "2034829434"
              }, {
              "gateId": 82,
              "isDayClosing": false,
              "gateCloseDate": "Mon Dec 10 14:44:21 MSK 2018",
              "epntId": 1,
              "saleApprovedCount": "2334",
              "saleAmount": "87328428482.00",
              "reversalApprovedCount": "123",
              "reversalAmount": "12393423.00",
              "code39": "000",
              "RRN": "2034829434"
              }, {
              "gateId": 317,
              "isDayClosing": false,
              "gateCloseDate": "Mon Dec 10 14:44:21 MSK 2018",
              "epntId": 1,
              "saleApprovedCount": "2334",
              "saleAmount": "87328428482.00",
              "reversalApprovedCount": "123",
              "reversalAmount": "12393423.00",
              "code39": "000",
              "RRN": "2034829434"
        }
        ]
      },
      "theRequestSerialNumber": "00000000-0000-0000-0000-00000000002c"
}

Имя свойства

Тип

Описание

status

string

Статус операции закрытия дня

gateId

long

Идентификатор шлюза по которому происходит закрытие дня

isDayClosing

boolean

Флаг закрытия дня, при значении true - шлюз заблокирован

gateCloseDate

string

Дата закрытия дня шлюза

epntId

long

Свойство, присваемое банком терминалу при его настройке в системе банка

saleApprovedCount

string

Число подтвержденных sale транзакций

saleAmount

string

Сумма по подтвержденным sale транзакциям

reversalApprovedCount

string

Число подтвержденных reversal транзакций

reversalAmount

string

Сумма по подтвержденным reversal транзакциям

code39

string

Результат закрытия, ответ банка на вызов процедуры закрытия гейта

RRN

string

Номер закрытия дня сгруппированный по ID терминала

theRequestSerialNumber

string

Серийный номер запроса закрытия дня
Если во время выполнения процедуры закрытия дня пользователь посылает повторный запрос на закрытие дня с новым идентификатором запроса - сервер вернет ответ со статусом ‘error’ и с описанием ошибки. Использовать повторно идентификатор этого запроса для дальнейшего инициирования закрытия дня бессмысленно, т.к. статус ошибки - это финальный статус и идентификатор запроса всегда будет ассоциирован с этим запросом.
Пример структуры ответа следующий:
{
      "response": {
        "status": "error",
        "errorCode": "99",
        "errorMessage": "gate is closing already"
      },
      "theRequestSerialNumber": "00000000-0000-0000-0000-000000000020"
}

Имя свойства

Тип

Описание

status

string

Статус операции закрытия дня

errorCode

string

Код ошибки

errorMessage

string

Описание ошибки

theRequestSerialNumber

string

Серийный номер запроса закрытия дня
Если пользователь инициирует запрос с новым идентификатором запроса на терминал, по которому уже было закрытие дня, и часть ассоциированных с терминалом гейтов закрылись с ошибкой (и находятся в закрытом состоянии) - сервер пришлет ответ со статусом ‘error’ и соответствующим описанием ошибки.

Warning

Для разрешения этой проблемы проведите операцию закрытия дня вручную в личном кабинете системы.

Инструмент снятия блокировки для шлюза

Если во время проведения удаленного закрытия дня, один или несколько шлюзов остались в заблокированном состоянии (в теле ответа при “status”: “finished” для шлюза - “isDayClosing”: true), Вы можете снять блокировку в личном кабинете системы и, при необходимости, закрыть день вручную.

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

pic1 close_day

pic2 close_day

На странице шлюза нажмите кнопку “Locks”, для вызова инструмента снятия блокировки.

pic9 close_day

pic10 close_day

В меню “Current locks” отображена текущая информация о блокировке шлюза:

  • Lock session ID - идентификатор сессии блокировки.

  • Start day closing date - дата начала закрытия дня.

  • Bank terminal lock status - блокировка терминала для проведения траназкций (Blocked/Free).

  • Initial gate job status - статус задачи по инициализации шлюза.

  • Close day job status - статус задачи по закрытию шлюза.

  • Is day closing - шлюз в стадии закрытия, т.е. находится ли в заблокированном состоянии (Y/N). Y - шлюз заблокирован, N - блокировки нет.

Доступны следующие команды снятия блокировки:

  • CLEAR_TRANSACTION_LOCK - сбросить сессию из-за которой произошла блокировка.

  • CLEAR_INIT_ATTEMPT - сбросить статус задачи по инициализации шлюза.

  • CLEAR_CLOSING_DAY_ATTEMPTS - сбросить статус задачи по закрытию шлюза.

  • CLEAR_CLOSING_DAY_FLAG - сбросить задачу по закрытию шлюза, снять блокировку.

Отметьте галочкой нужный пункт меню и нажмите кнопку “Update”.

После выполнения команды сброса, повторно откройте инструмент снятия блокировки и проверьте, что в меню “Current locks” изменился статус сбрасываемого параметра. Например, если шлюз был заблокирован, то после снятия блокировки параметр “Is day closing” = N.

Инструмент отладки для удаленного закрытия дня

Чтобы воспроизвести вызов API, введите все данные из исходного запроса, включая маркеры проверки подлинности. Не забудьте установить nonce и timestamp значения, которые Вы использовали. Запрос, подписанный с помощью OAuth, должен совпадать со значением в инструменте отладки ниже, вне зависимости от используемой библиотеки и языка программирования. Если подписи отличаются, значит в Вашем коде подписи OAuth есть ошибка.
HTTP method
URL
parameters
version
consumer key
consumer secret
timestamp

nonce

signature method

normalized parameters
signature base string
signature
authorization header