Оповещения

Обзор

Введение

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

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

Оповещение — это техническое сообщение, отправляемое от платёжной платформы ecommpay к веб-сервису мерчанта и содержащее заданную информацию об определённом событии. В этой статье представлена информация об оповещениях, а также о порядке и особенностях работы с ними.

Виды оповещений

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

Оповещения можно условно разделить на предписывающие и уведомительные.

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

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

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

Прим.: Отказ от получения уведомительных оповещений никак не влияет на возможность получения информации о платежах другими способами, в том числе с помощью запросов через Gate API (подробнее) и Data API (подробнее), а также с помощью интерфейса Dashboard и Telegram-бота. Вместе с тем, оповещения являются наиболее оперативным и надёжным способом получения информации (с подтверждением её доставки), и отказываться от их получения следует только в обоснованных случаях, когда это соответствует специфике работы веб-сервиса.

Типовые случаи применения

К типовым случаям применения оповещений можно отнести следующие.

  • Изменение статуса платежа.

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

    Рис.: Пример данных из оповещения о присвоении платежу промежуточного статуса

    {
    "project_id": 42,
    "customer": {
        "id": "17008"
    },
    "payment": {
        "id": "6789101",
        "type": "purchase",
        "status": "awaiting capture",      // промежуточный статус платежа
        "date": "2022-01-11T13:00:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "424242******4243",
        "type": "visa",
        "card_holder": "ELENA KRYLOVA",
        "expiry_month": "05",
        "expiry_year": "2025"
    },
    "operation": {
        "id": 77000002,
        "type": "auth",
        "status": "success",
        "date": "2022-01-11T13:00:40+0000",
        "created_date": "2022-01-11T13:00:37+0000",
        "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
        "sum_initial": {
            "amount": 200000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "RUB"
        },
        "provider": {
            "id": 120,
            "payment_id": "224750650",
            "date": "2022-01-11T13:00:39+0000",
            "result_code": "000",
            "result_message": "Approved",
            "auth_code": "505050",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success",
        "description": "SUCCESS",
        "eci": "00"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}

    Рис.: Пример данных из оповещения о присвоении платежу итогового статуса

    {
    "project_id": 42,
    "payment": {
        "id": "6789102",
        "type": "purchase",
        "status": "success",      // итоговый статус платежа
        "date": "2022-01-11T15:54:40+0000",
        "method": "card",
        "sum": {
            "amount": 200000,
            "currency": "RUB"
        },
        "description": ""
    },
    "account": {
        "number": "424242******4243",
        "type": "visa",
        "card_holder": "ELENA KRYLOVA",
        "expiry_month": "05",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "17008"
    },
    "operation": {
        "id": 7178000006597,
        "type": "capture",
        "status": "success",
        "date": "2022-01-11T15:54:40+0000",
        "created_date": "2022-01-11T15:54:39+0000",
        "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
        "sum_initial": {
            "amount": 200000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "RUB"
        },
        "provider": {
            "id": 120,
            "payment_id": "227307324",
            "date": "2022-01-11T15:54:40+0000",
            "auth_code": "919372",
            "endpoint_id": 120
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
  • Необходимость действий на стороне веб-сервиса.

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

    Рис.: Пример данных из оповещения о необходимости перенаправления пользователя

    "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
  }

    Рис.: Пример данных из оповещения о необходимости отображения пользователю QR-кода

     "display_data": [
            {
                "type": "qr_data",
                "title": "QR code",
                "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG"
            },
            {
                "type": "add_info",
                "title": "QR Code Timeout",
                "data": "600"
            }
        ]
  • Формирование или удаление токена платёжной карты.

    Это оповещения с информацией о событиях, связанных с токенами платёжных карт (таких, как формирование и удаление токенов).

    Рис.: Пример данных из оповещения о формировании токена платёжной карты

    {
    "general":{
    "project_id":42,
    "customer_id":17008,
    "signature":"gmTHcy4ISuWEiV8+AupOYkl9S5eLZ",
        "request": {
			"id": "3c7f53fdbb5b8c96f9707457d75f",
			"action": "tokenize",
			"status": "success"
        },
    "token":"f365bb1729f9b72fd9c0970e35c91d18070d15654",
    "token_created_at":"2022-01-28 13:30:57",
    "token_status":"active"
}

Подключение и настройка

Конфигурирование для проектов

В общем случае отправка оповещений для рабочих проектов мерчанта настраивается при интеграции веб-сервиса с платёжной платформой ecommpay. Вместе с тем, для изменения правил отправки оповещений всегда можно использовать возможности интерфейса Dashboard (подробнее), а также указывать специальные параметры в запросах на проведение платежей (подробнее далее) и при необходимости обращаться к специалистам технической поддержки ecommpay.

Со стороны мерчанта для оповещений можно настраивать следующие свойства:

В общем случае отправка оповещений настраивается при интеграции веб-сервиса с платёжной платформой ecommpay. Вместе с тем, со стороны мерчанта (используя возможности Dashboard и Gate API, а также обращения в техническую поддержку) всегда можно настраивать следующие свойства:

  • Обязательность отправки.

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

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

  • Адреса доставки.

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

    Оповещения по разным событиям могут отправляться на разные адреса веб-сервиса, с учётом типа события, платёжного метода, типа и статуса платежа и операции.

  • Время задержки отправки.

    При необходимости оповещения могут отправляться с задержкой до 600 секунд включительно, например для удобства их обработки на стороне веб-сервиса.

    При необходимости оповещения могут отправляться с задержкой до 600 секунд включительно.

  • Состав параметров.

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

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

    Таким образом, оповещения об одинаковых событиях в разных случаях могут выглядеть по-разному.

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

    Рис.: Пример данных из оповещения о проведении разовой оплаты в типовом формате

    {
    "account": {
        "number": "424242******4243",
        "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
        "type": "visa",
        "card_holder": "ELENA KRYLOVA",
        "expiry_month": "05",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "17008",
        "phone": "79012345678"
    },
    "payment": {
        "date": "2022-11-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 400000,
            "currency": "RUB"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2022-11-11T13:02:42+0000",
        "created_date": "2022-11-11T13:01:45+0000",
        "request_id": "c6eed1eb14c6290088cbc0be4667c",
        "sum_initial": {
            "amount": 400000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 400000,
            "currency": "RUB"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2022-11-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

    Рис.: Пример данных из оповещения о проведении разовой оплаты в индивидуально настроенном формате

    {
    "account": {
        "number": "424242******4243",
        "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
        "type": "visa",
        "card_holder": "ELENA KRYLOVA",
        "id": 45678,
        "expiry_month": "05",
        "expiry_year": "2025"
    },
    "customer": {            // объект с расширенной информацией о пользователе
        "id": "17008",
        "email": "elena@example.com"
        "phone": "79012345678",
        "first_name": "Elena",
        "last_name": "Krylova"
    },
    "payment": {
        "date": "2022-11-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 400000,
            "currency": "RUB"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 91663,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2022-11-11T13:02:42+0000",
        "created_date": "2022-11-11T13:01:45+0000",
        "request_id": "c6eed1e088cbc0be4667c",
        "sum_initial": {
            "amount": 400000,
            "currency": "RUB"
        },
        "sum_converted": {
            "amount": 400000,
            "currency": "RUB"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2022-11-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogVftZ1ZZ5D/aZAeb0VMdeR+CqGrYyilUwSm...=="
}

Управление отправкой для отдельных платежей

При проведении платежей через Gate можно задавать обязательность и время задержки при отправке оповещений. Для этого в объекте callback запросов на проведение платежей используются следующие параметры:

  • delay — задержка отправки оповещений, в секундах (от 0 до 600; например, 42);
  • force_disable — указатель запрета отправки оповещений (со значениями true для запрета отправки оповещений с информацией о данном платеже и false для разрешения их отправки).

Информацию о возможности использования этих параметров при запросах к конкретным конечным точкам можно найти в спецификации Gate API.

Рис.: Пример запроса на проведение оплаты с указанием правил отправки оповещений

{
    "general":{
        "project_id":42,
        "payment_id":"456789",
        "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "customer":{
        "ip_address":"192.0.2.32",
        "id":"17008"
    },
    "payment":{
        "amount":400000,
        "currency":"RUB",
        "callback":{
            "delay":42                // время задержки, равное 42 секундам
        }
    },
    "card":{
        "pan":"4242424242424243",
        "year":2025,
        "month":5,
        "card_holder":"ELENA KRYLOVA",
        "cvv":"123"
    }
}

Использование

Порядок работы

Технически оповещение представляет собой HTTP-POST-сообщение, отправляемое на предоставленный мерчантом URL. Порядок реагирования на каждое поступающее оповещение со стороны веб-сервиса сводится к следующим шагам:

Порядок реагирования на каждое поступающее оповещение со стороны веб-сервиса сводится к следующим шагам:

  1. Принять и проверить оповещение.

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

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

    Оповещения следует принимать только с IP-адресов платёжной платформы, предоставленных ecommpay, и без ограничения времени ожидания. При этом для подтверждения целостности в каждом полученном оповещении необходимо проверять подпись.

  2. Подтвердить получение оповещения.

    Чтобы подтверждать получение оповещений, необходимо отправлять к платёжной платформе синхронные HTTP-сообщения: при приёме оповещений без ошибок — с кодом ответа 200 ОК, в остальных случаях — с кодами ответов, соответствующими ошибкам, например HTTP 400 Bad Request, если не удалось преобразовать строку параметров в массив, или HTTP 500 Internal Server Error, если оповещение поступило на некорректный URL веб-сервиса.

    Чтобы подтверждать получение оповещений, необходимо отправлять к платёжной платформе синхронные HTTP-сообщения: при приёме оповещений без ошибок — с кодом ответа 200 ОК, в остальных случаях — с кодами ответов, соответствующими ошибкам, например HTTP 400 Bad Request.

    Если от веб-сервиса не поступило сообщение с кодом ответа 200 ОК, независимо от характера ошибки оповещение отправляется повторно.

  3. Выполнить необходимые действия.

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

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

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

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

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

  1. 6 попыток с нарастающим интервалом, от 10 до 60 секунд с увеличением на 10 секунд для каждой попытки.
  2. 58 попыток с нарастающим интервалом, от 84 секунд до 2,5 часов с увеличением по формуле 70 + 10 × 1,12n − 4 (в секундах), где n — порядковый номер попытки.
  3. 56 попыток каждые 4 часа до достижения в общей сложности 120 попыток, после чего отправка оповещений по этому событию прекращается.

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

Для изменения этого порядка можно обращаться к специалистам технической поддержки ecommpay.

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

Устранение неисправностей

Оповещения могут не приходить на требуемые адреса по различным причинам. Со стороны мерчанта такие ситуации и способы реагирования на них можно разбить на несколько групп.

  • Не приходят оповещения ни по одному из событий.

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

    В таких ситуациях рекомендуется:

    1. Убедиться, что со стороны веб-сервиса отправлялись корректные запросы (без запрета отправки оповещений) и они были приняты со стороны платформы. При необходимости отправить тестовый запрос, например на формирование токена платёжной карты.
    2. Если запросы принимаются в платформе, но оповещения по-прежнему не приходят — проверить работоспособность URL для приёма оповещений. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки ecommpay.
    3. Если по итогам предыдущих действий проблему не удалось решить — обратиться к специалистам технической поддержки ecommpay.
  • Не приходят оповещения по событиям отдельных типов.

    Это может быть связано с отсутствием событий таких типов, с недействительностью URL веб-сервиса или с отключением отправки оповещений для событий этих типов.

    В таких ситуациях рекомендуется:

    1. Убедиться в наличии событий тех типов, по которым не приходят оповещения, используя карточки платежей в интерфейсе Dashboard.
    2. Если такие события выполнялись, но оповещения по-прежнему не приходят — проверить работоспособность URL для приёма оповещений по событиям соответствующих типов. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки ecommpay.
    3. Если проблему не удалось решить — обратиться к специалистам технической поддержки ecommpay.
  • Не приходит оповещение по конкретной операции.

    Это может быть связано с тем, что в объекте callback запроса на выполнение операции был передан параметр force_disable со значением true.

    В такой ситуации уточнять состояние операции можно через Gate, используя запросы на получение соответствующей информации (подробнее), Dashboard и Telegram-бота.

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

  1. Убедиться, что для используемого проекта или для событий отдельных типов по этому проекту не отключена отправка оповещений.
  2. Убедиться, что со стороны веб-сервиса отправляются корректные запросы (без запрета отправки оповещений) и они принимаются на стороне платформы. При необходимости отправить тестовый запрос.
  3. Проверить работоспособность URL для приёма оповещений. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки ecommpay.
  4. Если проблему не удалось решить — обратиться к специалистам технической поддержки ecommpay.

Передаваемые параметры

Параметры оповещений о платежах и операциях

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

Параметр Описание tree

account
object, optional

 Объект, содержащий информацию о платёжных данных пользователя (например, данных платёжной карты, счёта или электронного кошелька) 10

card_holder
string, optional

Имя держателя платёжной карты.

Пример: ELENA KRYLOVA

 10-10 10

expiry_month
string, optional

Порядковый номер месяца срока действия платёжной карты.

Пример: 05

 10-20 10

expiry_year
string, optional

Год срока действия платёжной карты.

Пример: 2025

 10-30 10

id
integer, optional

Идентификатор сохранённых платёжных данных, используемый в платёжной платформе (подробнее).

Пример: 56789

 10-40 10

number
string, required

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

Пример: 424242***4243

 10-50 10

token
string, optional

Токен платёжной карты, если он был сформирован при выполнении запроса ()

 10-60 10

type
string, optional

Указатель бренда платёжной карты или название оператора мобильной связи, через которых был проведён платёж:

  • Бренды платёжных карт: amex, mastercard, maestro, visa и другие
  • Операторы мобильной связи: mBEELINE, mMEGAFON, mMTS и mTELE2
 10-70 10

acs
object, optional

 Объект, содержащий информацию о результате аутентификации пользователя с применением протокола 3‑D Secure 20

acs_url
string, required

Адрес страницы, на которую перенаправлялся пользователь для его аутентификации с применением протокола 3‑D Secure (ACS-страницы)

 20-10 20

md
string, required

Данные о мерчанте, полученные от международной платёжной системы при аутентификации пользователя с применением протокола 3‑D Secure (Merchant Data)

 20-20 20

pa_req
string, required

 Сообщение PAReq (Payer Authentication Request), полученное при аутентификации пользователя с применением протокола 3‑D Secure 20-30 20

avs_data
object, optional

 Объект, содержащий информацию о результате проверки Address Verification Service (AVS, подробнее) 30

avs_post_code
string, optional

Почтовый индекс пользователя, переданный для выполнения проверки AVS.

Пример: 127018

 30-10 30

avs_street_address
string, optional

Адрес пользователя, переданный для выполнения проверки AVS.

Пример: Москва, улица Профсоюзная, 17

 30-20 30

avs_result
string, optional

Код результата проверки AVS (подробнее).

Пример: F

 40

bank
object, optional

 Объект, содержащий информацию об эмитенте платёжной карты, использованной при проведении платежа 50

name
string, optional

Название эмитента в платёжной платформе.

Пример: SBERBANK of Russia

 50-10 50

customer
object, optional

 Объект, содержащий информацию о пользователе 70

billing
object, optional

 Объект, содержащий информацию о платёжном адресе пользователя, полученном в платёжной платформе при проведении платежа 70-10 70

address
string, optional

Название улицы расчётного адреса пользователя.

Пример: Сущевский вал

 70-10-10 70-10

city
string, optional

Название города платёжного адреса пользователя.

Пример: Москва

 70-10-20 70-10

country
string, optional

Код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2.

Пример: RU

 70-10-30 70-10

postal
string, optional

Индекс платёжного адреса пользователя.

Пример: 127018

 70-10-40 70-10

region
string, optional

Название региона (района, области, края или республики) платёжного адреса пользователя.

Пример: Московская область

 70-10-50 70-10

city
string, optional

 Название города пользователя.

Пример: Москва

 70-20 70

country
string, optional

Код страны пользователя в формате ISO 3166-1 alpha-2.

Пример: RU

 70-30 70

day_of_birth
string, optional

Дата рождения пользователя в формате ДД-ММ-ГГГГ.

Пример: 17-04-1989

 70-40 70

first_name
string, optional

Имя пользователя.

Пример: Елена

 70-50 70

id
string, optional

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

Пример: 17008

 70-60 70

ip_address
string, required

IP-адрес пользователя, актуальный для данной операции.

Пример: 192.0.2.32

 70-70 70

last_name
string, optional

 Фамилия пользователя.

Пример: Крылова

 70-80 70

middle_name
string, optional

 Отчество или среднее имя пользователя.

Пример: Андреевна

 70-90 70

phone
string, optional

Номер телефона пользователя, содержащий от 4 до 24 цифр.

Пример: 79012345678

 70-100 70

decision
string, optional

 Строка, содержащая информацию об оценке допустимости проведения платежа на стороне платёжной платформы 80

decision_message
array, optional

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

Пример: reject.message("RCS reject. Amount less than allowed")

 90

display_data
object, optional

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

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

Пример: Approve the payment request sent to your phone

 100

errors
array, optional

 Массив с сообщениями об ошибках, полученных при выполнении запроса 110

ErrorItem
object, required

 Объект, содержащий информацию об ошибке при выполнении запроса 110-10 110

code
integer, optional

Код ошибки.

Пример: 3287

 110-10-10 110-10

description
string, optional

Сведения о причине ошибки.

Пример: EMPTY_REFUND_CURRENCY

 110-10-10 110-10

field
string, optional

 Название параметра, при указании которого была допущена ошибка (если такой параметр определён) 110-10-20 110-10

message
string, optional

Пояснение к коду ошибки.

Пример: The property currency is required

 110-10-30 110-10

interface_type
object, optional

 Объект, содержащий информацию о способе инициирования платежа 120

id
integer, optional

 Индикатор интерфейса, через который поступил исходный запрос:
  • 1 — запрос поступил через Gate
  • 5 — запрос поступил через Dashboard
  • 6 — запрос поступил через Payment Page, открытой в модальном окне
  • 7 — запрос поступил через Payment Page, открытой в объекте iframe HTML-страницы
 120-10 120

user
string, optional

Сведения об учётной записи пользователя Dashboard, отправившего исходный запрос.

Пример: janedoe@cosmoshop.com

 120-20 120

operation
object, optional

 Объект, содержащий информацию об операциях, относящихся к платежу 130

code
string, optional

Код состояния операции (подробнее).

Пример: 0

 130-10 130

created_date
string, optional

Дата и время создания операции.

Пример: 2022-10-08T18:52:19+0000

 130-20 130

date
string, optional

Дата и время последнего обновления статуса операции в платёжной платформе.

Пример: 2022-10-08T18:52:54+0000

 130-30 130

eci
string, optional

Индикатор результата аутентификации пользователя с применением протокола 3‑D Secure (подробнее).

Пример: 07

 130-40 130

id
integer, optional

Идентификатор операции в платёжной платформе.

Пример: 17007255

 130-50 130

message
string, optional

Пояснительное описание к коду состояния операции (подробнее).

Пример: Success

 130-60 130

provider
object, optional

 Объект, содержащий информацию о результате выполнения платежа, полученную от провайдера или платёжной системы 130-70 130

auth_code
string, optional

Код авторизации, полученный от провайдера или платёжной системы.

Пример: 331040

 130-70-10 130-70

date
string, optional

Дата и время завершения обработки платежа на стороне провайдера или платёжной системы.

Пример: 2022-10-08T18:52:53+0000

 130-70-20 130-70

endpoint_id
string (integer), optional

CRC32-идентификатор провайдера или платёжной системы.

Пример: 2

 130-70-30 130-70

id
integer, optional

Идентификатор провайдера или платёжной системы в платёжной платформе.

Пример: 2

 130-70-40 130-70

payment_id
string, optional

Идентификатор платежа на стороне провайдера или платёжной системы.

Пример: 603458

 130-70-50 130-70

request_id
string, required

Идентификатор последнего запроса, относящегося к данной операции, в платёжной платформе

 130-80 130

status
string, required

Статус операции (в соответствии c моделью проведения платежей).

Пример: success

 130-90 130

sum_converted
object, optional

 Объект, содержащий информацию о сумме и валюте операции после конвертации (подробнее о конвертации) 130-100 130

amount
integer, optional

Сумма операции. В дробных единицах валюты, если они применимы, или в целых единицах.

Пример: 8726

 130-100-10 130-100

currency
string, optional

Код валюты операции в формате ISO 4217 alpha-3.

Пример: EUR

 130-100-20 130-100

sum_initial
object, optional

 Объект, содержащий информацию о сумме и валюте операции, переданных в запросе 130-110 130

amount
integer, required

Исходная сумма операции в дробных единицах валюты.

Пример: 9055

 130-110-10 130-110

currency
string, required

Код исходной валюты операции в формате ISO 4217 alpha-3.

Пример: USD

 130-110-20 130-110

type
string, required

Тип операции (в соответствии c моделью проведения платежей).

Пример: sale

 130-120 130

payment
object, required

 Объект, содержащий основные сведения о платеже 140

cascading_with_redirect
boolean, optional

 Индикатор необходимости получить подтверждение пользователя на дополнительную попытку проведения оплаты в случае получения отказа при выполнении аутентификации 3‑D Secure (подробнее):
  • true — подтверждение требуется
  • false — подтверждение не требуется
 140-10 140

date
string, optional

Дата и время последнего обновления статуса платежа в платёжной платформе.

Пример: 2022-10-08T18:52:54+0000

 140-20 140

description
string, optional

Описание платежа, переданное в исходном запросе.

Пример: Радиоуправляемая модель летающей тарелки Nano Size с доставкой

 140-30 140

id
string, required

Идентификатор платежа, переданный в исходном запросе.

Пример: 18641868

 140-40 140

is_new_attempts_available
boolean, optional

 Индикатор возможности выполнить повторную попытку оплаты (подробнее):
  • true — повторная попытка доступна
  • false — повторная попытка недоступна
 140-50 140 е

method
string, optional

Код платёжного метода (подробнее).

Пример: card

 140-60 140

merchant_refund_id
string, optional

Идентификатор, полученный при инициировании возврата со стороны веб-сервиса.

Пример: refund_143

 140-61 140

OperationFee
object, optional

 Объект, содержащий информацию о сумме комиссии 140-70 140

amount
string, optional

 Сумма комиссии в дробных единицах валюты, если эта сумма включена в общую сумму операции 140-70-10 140-70

currency
string, optional

 Код валюты, в которой начислена комиссия, в формате ISO 4217 alpha-3 140-70-20 140-70

sum_with_surcharge
string, optional

 Общая сумма операции и надбавленной комиссии в дробных единицах валюты 140-70-30 140-70

surcharge_amount
string, optional

 Сумма комиссии, надбавленной к сумме платежа, в дробных единицах валюты (применяется для микрофинансовых организаций, МФО) 140-70-40 140-70

surcharge_currency
string, optional

 Код валюты, в которой начислена сумма комиссии, надбавленная к сумме платежа, в формате ISO 4217 alpha-3 140-70-50 140-70

region
string, optional

Код региона выполнения операции (подробнее).

Пример: eea

 140-80 140

status
string, required

Cтатус платежа (в соответствии c моделью проведения платежей).

Пример: partially refunded

 140-90 140

sum
object, optional

 Объект, содержащий информацию о сумме и валюте платежа 140-100 140

amount
integer, required

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

Пример: 8855

 140-100-10 140-100

currency
string, required

Код валюты платежа, переданный в исходном запросе, в формате ISO 4217 alpha-3.

Пример: USD

 140-100-20 140-100

timeout_attempts
string, optional

Время, в течение которого возможно выполнение повторных попыток оплаты (подробнее), в секундах.

Пример: 360

 140-110 140

type  
string, required

Тип платежа (в соответствии c моделью проведения платежей).

Пример: purchase

 140-120 140

project_id
integer, required

Идентификатор проекта мерчанта в платёжной платформе.

Пример: 42

 150

provider_extra_fields
object, optional

 Объект, содержащий информацию, поступившую от провайдера или платёжной системы 160

recurring
object, optional

 Объект, содержащий информацию о повторяемой оплате (подробнее) 170

currency
string, optional

Код валюты повторяемой оплаты в формате ISO 4217 alpha-3.

Пример: USD

 170-10 170

id
integer, optional

Идентификатор записи о серии списаний (подробнее) в платёжной платформе.

Пример: 1001648

 170-20 170

register_payment_id
string, optional

Идентификатор записи о серии списаний (подробнее) в веб-сервисе мерчанта.

Пример: 18641865

 170-30 170

status
string, optional

 Статус записи о серии списаний (подробнее):
  • active — запись о серии списаний действительна
  • canceled — запись о серии списаний недействительна (например, если повторяемая оплата отменена по запросу мерчанта)
 170-40 170

type
string, optional

 Тип повторяемой оплаты (подробнее):
  • C — экспресс-оплата (OneClick)
  • U — автооплата
  • R — регулярная оплата
 170-50 170

valid_thru
string, optional

Дата, до наступления которой возможно выполнение списаний (подробнее).

Пример: 2023-05-20T00:00:00+0000

 170-60 170

redirect_data
object, optional

 Объект, содержащий данные для перенаправления пользователя 180

body
object, optional

 Данные для перенаправления пользователя 180-10 180

method
string, optional

 Требуемый HTTP-метод отправки запроса на перенаправление: POST или GET 180-20 180

url
string, optional

 URL, на который требуется направить пользователя 180-30 180

signature
string, required

 Подпись оповещения (подробнее) 190

Параметры оповещений о токенах

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

general
object, required

 Объект с основными идентификационными сведениями из исходного запроса на формирование токена 1

project_id
string, required

Идентификатор проекта мерчанта в платёжной платформе.

Пример: 42

 1-11

customer_id
string, optional

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

Пример: 17008

 1-21

signature
string, required

 Подпись оповещения 1-31

request
object, required

 Объект со сведениями об исходном запросе 2

id
integer, required

Идентификатор исходного запроса

 2-12

action
string, optional

 Тип исходного запроса:
  • tokenize — запрос на формирование токена;
  • token_revoke — запрос на удаление токена;

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

 2-22

status
string, required

 Статус запроса:
  • success — запрос выполнен
  • error — запрос не выполнен из-за возникновения ошибок, сведения о которых указаны в массиве errors
 2-32

errors
array, optional

 Массив с информацией об ошибках, возникших при выполнении запроса.

Этот массив не передаётся в случаях, когда запрос выполнен без ошибок

 2-42

ErrorItem
object, required

 Объект с информацией об ошибке, возникшей при выполнении запроса 2-4-12-4

code
string, optional

Код ошибки, возникшей при выполнении запроса.

Пример: 3021

 2-4-1-12-4-1

message
string, optional

Поясняющее описание к коду ошибки.

Пример: Card expired

 2-4-1-22-4-1

field
string, optional

 Название параметра исходного запроса, в котором допущена ошибка, если этот параметр определён 2-4-1-32-4-1

token
string, optional

Токен платёжной карты

 3

token_created_at
string, optional

Дата и время формирования токена карты.

Пример: 2022-07-22T03:31:24+0000

 4

token_status
string, optional

 Статус токена:
  • active — токен действителен и может использоваться при проведении платежей;
  • expiry — токен недействителен, так как срок его действия истёк;
  • revoke — токен недействителен, так как был удалён по запросу со стороны веб-сервиса мерчанта
 5