ERP Platform Docs

02-platezhi

время чтения ~5 мин.

2. Платежи

Источник: https://docs.paykeeper.ru/dokumentatsiya-json-api/platezhi/

Раздел «Платежи» позволяет работать с платежами: получать информацию, выгружать реестры с фильтрами по датам/статусам/платёжным системам, искать платежи, делать полные и частичные возвраты.

Инициализация платежей выполняется через выставление счетов, HTML-формы, iframe-формы или прямые платёжные ссылки.

Диаграмма статусов

Статусы получен, совершён без оповещения и совершён — равнозначны в части получения средств (держатель карты списан, деньги зачислены или будут зачислены мерчанту). Статусы отменён и не состоялся — провал платежа.

Список запросов

#URIНазначение
2.1/info/payments/bydate/Реестр платежей за период с фильтрами
2.2/info/payments/bydatecount/Количество платежей за период по статусам и ПС
2.3/info/payments/byid/Информация о платеже по ID
2.4/info/options/byid/Дополнительные параметры платежа
2.5/info/params/byid/Необязательные параметры платежа
2.6/info/httplog/byid/HTTP-лог для платежа
2.7/info/refunds/bypaymentid/Информация о возвратах по платежу
2.8/change/payment/reverse/Полный или частичный возврат
2.9/change/payment/repeatcnt/Сбросить счётчик оповещений
2.10—Инициализация платежа — не поддерживается
2.11/info/payments/search/Поиск платежей
2.12/change/payment/capture/Подтверждение списания по предавторизации
2.13/change/payment/post-sale-receipt/Чек окончательного расчёта

2.1 Реестр платежей /info/payments/bydate/

Тип: GET
Формат: /info/payments/bydate/?limit=100&from=0&start=2016-04-14&end=2017-03-14&status[]=success&status[]=canceled&status[]=failed&payment_system_id[]=9&payment_system_id[]=1

Параметры:

ПараметрНазначение
startДата начала (YYYY-MM-DD)
endДата конца (YYYY-MM-DD)
payment_system_id[]ID платёжных систем для фильтра (обязателен)
status[]Статусы: pending, obtained, canceled, success, failed, stuck, refunded, refunding, partially_refunded (обязателен)
fromПропустить N значений (обязателен)
limitКоличество возвращаемых значений (обязателен)

Параметры ответа:

ПараметрНазначение
idИдентификатор платежа
pay_amountСумма платежа
refund_amountВозвращённая часть
clientidИдентификатор клиента
orderidНомер заказа
payment_system_idID платёжной системы
unique_idУникальный ID транзакции
statusСтатус
repeat_counterКоличество попыток оповещения
pending_datetimeДата создания
obtain_datetimeДата обработки
success_datetimeДата успешного оповещения

Пример ответа:

[
  {
    "id": "136641",
    "pay_amount": "1000.00",
    "refund_amount": "0.00",
    "clientid": null,
    "orderid": null,
    "payment_system_id": "6",
    "unique_id": "Rj5er56P5ItOLxi0uuptDER7NM=",
    "status": "canceled",
    "repeat_counter": "0",
    "pending_datetime": "2017-03-17 16:44:30",
    "obtain_datetime": null,
    "success_datetime": null
  },
  {
    "id": "136640",
    "pay_amount": "2150.00",
    "refund_amount": "0.00",
    "clientid": "Оплата за кресло-качалку",
    "orderid": "Петров Иван Сергеевич",
    "payment_system_id": "6",
    "unique_id": "xONlvdy91aB+N3I21n1WE5/5ZqEg=",
    "status": "success",
    "repeat_counter": "0",
    "pending_datetime": "2017-03-15 16:54:49",
    "obtain_datetime": "2017-03-15 16:56:26",
    "success_datetime": "2017-03-15 16:56:30"
  }
]

2.2 Количество платежей /info/payments/bydatecount/

Тип: GET
Формат: /info/payments/bydatecount/?start=2014-04-14&end=2014-05-14&status[]=success&status[]=canceled&status[]=failed&payment_system_id[]=6&payment_system_id[]=1

Параметры аналогичны 2.1 (без from/limit).

Параметры ответа:

ПараметрНазначение
statusesМассив [status, count]
payment_systemsМассив [payment_system_id, count]
fullcountОбщее число платежей

Пример:

[
  {
    "statuses": [
      {"status": "canceled", "count": "14"},
      {"status": "success", "count": "71"},
      {"status": "failed", "count": "3"}
    ]
  },
  {
    "payment_systems": [
      {"payment_system_id": "1", "count": "47"},
      {"payment_system_id": "6", "count": "41"}
    ]
  },
  {
    "fullcount": [{"count": "88"}]
  }
]

2.3 Информация по ID /info/payments/byid/

Тип: GET
Формат: /info/payments/byid/?id=11186

Параметры:

ПараметрНазначение
idID платежа в PayKeeper
advancedФлаг получения дополнительных данных (true)

Параметры ответа: аналогично 2.1 + site_description, system_description.

При advanced=true добавляются:

ПараметрНазначение
APPROVAL_CODEКод авторизации
CARD_NUMBERМаскированный номер карты
RESULTРезультат операции
RESULT_CODEКод результата
3DSECUREИспользовалась ли 3D Secure
RRNRRN успешного платежа

Пример ответа:

[
  {
    "id": "11186",
    "pay_amount": "12000.00",
    "refund_amount": "0.00",
    "clientid": "ivan.petrov@mail.ru",
    "orderid": "7916",
    "payment_system_id": "40",
    "site_description": "Сбербанк",
    "system_description": "SberBank",
    "unique_id": "8613d9ab-1234-4678-9014-0f3489dcaba4",
    "status": "success",
    "repeat_counter": "0",
    "pending_datetime": "2017-03-21 14:25:33",
    "obtain_datetime": "2017-03-21 14:29:48",
    "success_datetime": "2017-03-21 14:30:02",
    "APPROVAL_CODE": "933921",
    "CARD_NUMBER": "400011xxxxxx1111",
    "RESULT": null,
    "RESULT_CODE": null,
    "3DSECURE": "Y",
    "RRN": "16560565471"
  }
]

2.4 Дополнительные параметры /info/options/byid/

Тип: GET
Формат: /info/options/byid/?id=11186

Ответ зависит от платёжной системы и статуса.

Пример:

[
  {
    "orderid": "7916",
    "client_ip": "109.252.85.68",
    "service_name": "Uslugi po perevodu",
    "client_email": "info@example.com",
    "client_phone": "+79112511000",
    "qiwi_phone": "",
    "msgtype": "Visa",
    "RRN": "304756189111",
    "APPROVAL_CODE": "186111",
    "CARD_NUMBER": "472732**2524",
    "actionCode": "0",
    "actionCodeDescription": "",
    "orderStatus": "2",
    "preauth": "false"
  }
]

2.5 Необязательные параметры /info/params/byid/

Тип: GET
Формат: /info/params/byid/?id=11186

Параметры ответа:

ПараметрНазначение
idID
payment_idID платежа
fieldКлюч
valueЗначение

Пример:

[
  {"id": "282", "payment_id": "11186", "field": "0/value", "value": "86ead1ab-111d-4aa6-8daf-01119bbaaa1"},
  {"id": "287", "payment_id": "11186", "field": "cardAuthInfo/expiration", "value": "202109"},
  {"id": "288", "payment_id": "11186", "field": "cardAuthInfo/cardholderName", "value": "Ivan Petrov"}
]

2.6 HTTP-лог /info/httplog/byid/

Тип: GET
Формат: /info/httplog/byid/?id=11186

Параметры ответа:

ПараметрНазначение
idID
payment_idID платежа
request_methodМетод
request_uriURI
ipIP-адрес
bodyТело запроса
datetimeДата/время

Пример:

[
  {
    "id": "176325",
    "payment_id": "11186",
    "request_method": "POST",
    "request_uri": "/order/inline/",
    "ip": "187.145.22.11",
    "body": "orderid=7916&clientid=ivanivanov%40mail.ru&sum=120000&phone=891112345678",
    "datetime": "2017-03-21 14:25:20"
  }
]

2.7 Возвраты по платежу /info/refunds/bypaymentid/

Тип: GET
Формат: /info/refunds/bypaymentid/?id=124076

По одному платежу может быть несколько возвратов.

Параметры ответа:

ПараметрНазначение
idID возврата
payment_idID платежа
refund_numberПорядковый номер возврата
userКто инициировал
amountСумма возврата
remainderОстаток после возврата
datetimeДата выполнения
statusСтатус: started, done, failed

Пример:

[
  {
    "id": "1",
    "payment_id": "124076",
    "refund_number": "1",
    "user": "admin",
    "amount": "9730.00",
    "remainder": "0.00",
    "datetime": "2017-02-10 10:58:36",
    "status": "done"
  }
]

2.8 Возврат /change/payment/reverse/

Тип: POST
Формат: /change/payment/reverse/

Метод сам определяет, какой тип операции применить (полный возврат, отмена, частичный возврат, частичное списание) в зависимости от состояния платежа и возможностей банка-эквайера.

При работе в режиме автоматической фискализации (54-ФЗ) при возвратах можно передавать информацию о товарах. Для полного возврата с корзиной товары можно не передавать; для частичных — обязательна корзина возврата для корректной генерации чека.

Параметры:

ПараметрНазначение
idID платежа
amountСумма возврата (точка как разделитель)
partialФлаг частичного возврата (true/false, не 1/0)
sbp_refund_toИспользуется только в особых случаях; обычно не передавать
tokenТокен безопасности
refund_cartJSON-строка с корзиной возврата (формат — как при инициализации счёта)

Успех:

{"result": "success"}

Ошибка:

{
  "result": "fail",
  "msg": "Нельзя сделать возврат по платежу, статус которого не \"совершён\", \"получен\" или \"превышено число повторов\""
}

Возврат выполняется асинхронно — инициализация не гарантирует успешного исполнения. Контроль: запрос 2.1 с фильтром по refunding, либо запрос 2.7 по конкретному платежу. Результат обычно приходит через несколько минут; проверять рекомендуется через 3 минуты. PayKeeper может слать callback при завершении возврата.

2.9 Сброс счётчика оповещений /change/payment/repeatcnt/

Тип: POST
Формат: /change/payment/repeatcnt/

Сбрасывает счётчик попыток оповещения и запускает информатор.

Параметры: id, token.

Ответ:

[{"result": "success"}]

2.10 Инициализация платежа

Не поддерживается.

2.11 Поиск платежей /info/payments/search/

Тип: GET
Формат: /info/payments/search/?query=4038*9682&beg_date=2016-01-01&end_date=2017-04-04

Возвращает платежи, в номерах/параметрах/номерах карт/кодах авторизации которых содержится искомая подстрока.

Параметры:

ПараметрНазначение
queryПодстрока. Ищется в payment.id, payment.clientid, options.orderid, options.service_name, options.client_email, options.client_phone, options.CARD_NUMBER, options.APPROVAL_CODE. Поддерживает MySQL LIKE-синтаксис; * = %
beg_dateНачало периода (YYYY-MM-DD)
end_dateКонец периода (YYYY-MM-DD)
user_ids[]Массив ID пользователей (из метода 4.7)

Пример ответа:

[
  {
    "id": "124134",
    "pay_amount": "1.00",
    "clientid": "Иванов Петр Семенович",
    "orderid": "325009",
    "payment_system_id": "6",
    "unique_id": "Nhf+fl3l8Rz/rvCEtMNCVm12Ew=",
    "status": "success",
    "repeat_counter": "0",
    "pending_datetime": "2017-03-30 13:20:59",
    "obtain_datetime": "2017-03-30 13:21:43",
    "success_datetime": "2017-03-30 13:21:47"
  }
]

2.12 Подтверждение списания /change/payment/capture/

Тип: POST
Формат: /change/payment/capture/

Досрочное списание средств при предавторизации (без ожидания автосписания). Для частичного — использовать 2.8.

Параметры: id, token.

Ответ:

[{"result": "success"}]

Для Промсвязьбанка status=queued означает принятие банком, но ещё не выполнение. Проверять через 2.4 через несколько минут.

2.13 Чек окончательного расчёта /change/payment/post-sale-receipt/

Тип: POST
Формат: /change/payment/post-sale-receipt/

По 54-ФЗ при доставке предоплаченного товара онлайн необходимо выдать чек. Метод упрощает выдачу чека в момент доставки.

Параметры: id — номер платежа.

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

Нельзя использовать для аванса — окончательный расчёт должен содержать точные позиции. В «зачёте аванса» используется сумма «электронно» из исходного чека. Для частично возвращённых платежей учитываются оставшиеся товары. Формирование асинхронное — при успехе вернётся receipt_id, результат проверять через запрос 8.4.

Вид графа

Обратные ссылки