Alipay | Документация ECOMMPAY

Обзор

Введение

Alipay — метод, позволяющий проводить платежи в разных валютах с использованием электронного кошелька в Китае. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и возвраты.

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

Характеристика

Тип платёжного метода	платежи с использованием электронных кошельков
Платёжные инструменты	электронные кошельки
Регионы использования	CN
Валюты платежей	AUD, CAD, CNY, EUR, GBP, HKD, JPY, SGD, USD *
Конвертация валют	–
Разовые оплаты	+
Повторяемые оплаты	–
Полные возвраты*	+
Частичные возвраты*	+
Выплаты	–
Опротестования	–
Особенности	в рамках платёжного метода Alipay доступны оплаты с веб и мобильной версий приложения: web, mobile при помощи QR-кода в некоторых случаях есть ограничение на время жизни платежа — 30 минут, информацию необходимо уточнять у курирующего менеджера ecommpay
Организация и стоимость подключения	по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommshop

Прим.:

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

Схема работы

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

Основные операции

Для проведения платежей и выполнения операций с использованием метода Alipay могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.

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

	Суммы		Время ¹
	Минимум	Максимум	Базовое	Предельное
Оплаты	10,00 CNY или 1,00 USD	5 000,00 CNY или неограниченно USD	до 1 часа	*
Возвраты	–	–	*	*

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

Прим.:

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

Сценарии использования

Проведение оплат с использованием метода Alipay осуществляется с перенаправлением пользователей к сервису Alipay, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса.

Рис.: Оплата через Payment Page

Рис.: Оплата через Gate

Рис.: Возврат через Gate

Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом Alipay соответствуют специфике этих возможностей.

Оплаты через Payment Page

Общая информация

Для проведения оплаты через Payment Page с использованием метода Alipay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.

Рис.: Проведение оплаты через Payment Page. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
Запрос на проведение оплаты поступает в платёжную платформу.
В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
Пользователю отображается платёжная форма.
Пользователь выбирает для оплаты метод Alipay.
В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Alipay.
В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Alipay.
В сервисе Alipay выполняется обработка запроса на оплату.
От сервиса Alipay к платёжной платформе передаются данные для перенаправления пользователя к сервису Alipay.
Данные для перенаправления пользователя передаются к Payment Page.
Пользователь перенаправляется к сервису Alipay.
Пользователь выполняет необходимые действия для оплаты.
В сервисе Alipay выполняется обработка платежа.
От сервиса Alipay к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
От платёжной платформы к Payment Page направляется информация о результате оплаты.
Информация о результате оплаты отображается пользователю на Payment Page.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом Alipay через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода Alipay необходимо учитывать следующее:

Должен использоваться базовый минимум параметров, обязательный для любого платежа:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в дробных единицах валюты;
- customer_id — идентификатор пользователя в рамках проекта.
Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
Доступные валюты платежа уточняйте у курирующего менеджера ecommpay.
Дополнительно должен использоваться параметр language_code — код языка Payment Page в формате ISO 639-1 alpha-2; необходимо указать код zh.
Для предварительного выбора метода Alipay необходимо указывать код этого метода в параметре force_payment_method — alipay.
Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "CNY",
   "customer_id": "customer1",
   "language_code": "zh",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "CNY",
   "customer_id": "customer1",
   "language_code": "zh",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Формат оповещений

Для оповещений о результатах оплат с применением метода Alipay используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 201 для пользователя 125 была проведена оплата в размере 10,00 CNY.

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

 {
        "project_id": 201,
        "payment": {
            "id": "ECT_TEST_155125514200636",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-27T16:01:25+0000",
            "method": "alipay",
            "sum": {
                "amount": 1000,
                "currency": "CNY"
            },
            "description": "ECT_TEST_1551255142006"
        },
        "customer": {
            "id": "125"
        },
        "operation": {
            "id": 20891000000045,
            "type": "sale",
            "status": "success",
            "date": "2019-02-27T16:01:25+0000",
            "created_date": "2019-02-27T15:46:21+0000",
            "request_id": "85d4801f8fa9dead54d315ae19ecb4550201cdcafab",
            "sum_initial": {
                "amount": 1000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1189,
                "payment_id": "Abe9VAEokJyIqyRcX10TLkz30XQbmK3f",
                "date": "2019-02-27T16:01:24+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "T/v8rquB+C0K7TR7sz1vvOrpCsV1/hr9LhIh27fY9PF7Q=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

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

 {
            "id": "ECT_TEST_1551103453746538344",
            "type": "purchase",
            "status": "decline",
            "date": "2019-02-27T14:41:30+0000",
            "method": "alipay",
            "sum": {
                "amount": 10000,
                "currency": "CNY"
            },
            "description": ""
        },
        "operation": {
            "id": 20370000000023,
            "type": "sale",
            "status": "decline",
            "date": "2019-02-27T14:41:30+0000",
            "created_date": "2019-02-26T13:39:44+0000",
            "request_id": "36e07e85504ec76924432b3d6e59e5d5066ebb",
            "sum_initial": {
                "amount": 10000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1189,
                "payment_id": "g4Ld5b6iSuzTmukZUj1RVkXNMuYSj07I",
                "date": "2019-02-27T14:41:29+0000",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "EezTcWDrcp8RW2Wb+bLmytXRRWctzaanCrzhw=="
    }

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

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

Оплаты через Gate

Общая информация

Для проведения оплаты через Gate с использованием метода Alipay со стороны веб-сервиса необходимо:

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

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

Рис.: Проведение оплаты через Gate. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Alipay.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис Alipay.
В сервисе Alipay выполняется обработка запроса на оплату.
От сервиса Alipay к платёжной платформе передаются данные для перенаправления пользователя к сервису Alipay.
От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису Alipay.
Пользователь перенаправляется к сервису Alipay.
Пользователь выполняет необходимые действия для оплаты.
В сервисе Alipay выполняется обработка платежа.
От сервиса Alipay к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом Alipay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на оплаты с применением метода Alipay необходимо учитывать следующее:

Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/alipay/sale. Эта точка относится к группе /v2/payment/wallet/{payment_method}/sale.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  - payment_id — идентификатор платежа, уникальный в рамках проекта;,
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
- payment — объект, содержащий сведения о платеже:
  - amount — сумма платежа в дробных единицах валюты;,
  - currency — код валюты платежа в формате ISO-4217 alpha-3;,
  - description * — описание или комментарий к платежу;,
- customer — объект, содержащий сведения о пользователе:
  - id — идентификатор пользователя, уникальный в рамках проекта;,
  - ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
  - first_name * — имя пользователя;,
  - last_name * — фамилия пользователя;,
  - phone * — номер телефона пользователя без знака +;,
  - email * — адрес электронной почты пользователя;,
  - zip * — почтовый индекс пользователя;,
  - country * — страна в формате ISO 3166-1 alpha-2 пользователя;,
  - city * — город на китайском пользователя;,
  - street * — адрес на китайском пользователя;,
- return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
  - success * — URL для перенаправления пользователя после проведения оплаты,
  - return — URL для перенаправления пользователя любом шаге оплаты.
Прим.: * Необходимость использования этих параметров следует уточнять у курирующего менеджера ecommpay. Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение (подробнее — в статье Дополнение информации о платеже).
Доступные валюты платежа уточняйте у курирующего менеджера ecommpay.
Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода Alipay должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, URL для перенаправления и подпись.

{
  "general": {
    "project_id": 201,
    "payment_id": "ECT_TEST_155125514400636",
    "signature": "cMlzFj8zqZJbum1w62aewWX7xcG+Ttb0fhuenWNptFZg=="
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0",
    "first_name": "之的",
    "last_name": "张",
    "phone": "13632264148",
    "email": "2524243674@example.com",
    "street":"street",
    "city": "city",
    "zip": "123045608",
    "country": "CH"
  },
  "payment": {
    "amount": 1000,
    "currency": "CNY",
    "description": "test payment"
  },
   "return_url": {
    "return": "http://example.com/return",
    "success": "http://example.com/success"
    }
}

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

{
  "general": {
    "project_id": 201,
    "payment_id": "ECT_TEST_155125514400636",
    "signature": "cMlzFj8zqZJbum1w62aewWX7xcG+Ttb0fhuenWNptFZg=="
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0",
    "first_name": "之的",
    "last_name": "张",
    "phone": "13632264148",
    "email": "2524243674@example.com",
    "street":"street",
    "city": "city",
    "zip": "123045608",
    "country": "CH"
  },
  "payment": {
    "amount": 1000,
    "currency": "CNY",
    "description": "test payment"
  },
   "return_url": {
    "return": "http://example.com/return",
    "success": "http://example.com/success"
    }
}

Формат промежуточных оповещений для перенаправления пользователей

Для перенаправления пользователя от веб-сервиса к сервису Alipay со стороны платёжной платформы к веб-сервису отправляется оповещение с данными для перенаправления. В зависимости от провайдера, обрабатывающего платёж, для перенаправления могут использоваться URL или QR-код:

URL — в этом случае в оповещении содержится объект redirect_data.
QR-код — в этом случае в оповещении содержится массив display_data.

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

Объект redirect_data

Для перенаправления пользователей от веб-сервиса мерчанта к сервису Alipay при проведении каждого платежа с использованием метода Alipay необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

body — объект с данными для отправки в теле запроса;
method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
url — параметр со ссылкой для перенаправления.

Рис.: Пример объекта redirect_data

"redirect_data": {
            "method": "POST",
            "body": {
                "order_no": "29895000000582",
                "amount": "13.00",
                "payment_channel": "ALIPAY",
                "sign": "****************",
                "return_url": "https://example.com/process/wsid=njf2h9cd3",
                "signType": "RSA",
                "currency": "CNY",
                "body": "ECT_TEST_1552972940011",
                "app_id": "4391"
            },
            "encrypted": [],
            "url": "https://example.com:443/payment/otoSoft/v3/h5.html"
        }

Массив display_data

Для перенаправления пользователя от веб-сервиса к сервису Alipay необходимо использовать данные из массива display_data, который передаётся в оповещении от платёжной платформы. Этот массив может содержать один или несколько объектов со следующими параметрами:

type — тип объекта,
title — название объекта,
data — данные, соответствующие указанному типу объекта.

Массив display_data формируется с учётом следующих условий:

Обязательным является объект с указанием данных для передачи QR-кода. Значение параметра data в таком объекте соответствует значению параметра type, который может принимать следующие значения:
- qr_url — при передаче QR-кода как ссылки на изображение. В этом случае в параметре data передаётся URL.
- qr_img — при передаче QR-кода как изображения. В этом случае в параметре data передаётся строка, закодированная с использованием схемы Base64.
- qr_data — при передаче QR-кода как строки. В этом случае в параметре data передаётся строка, на основании которой на стороне веб-сервиса должен быть создан QR-код.
В дополнение к обязательному объекту с указанием данных для передачи QR-кода могут передаваться один или несколько объектов c дополнительной информацией. Параметр type таких объектов принимает значение add_info, а в параметре data может передаваться разнообразная информация.
Если в массиве присутствуют один или несколько объектов с дополнительной информацией, то в такой массив включается объект с информацией о сроке действия QR-кода с момента его создания на стороне сервиса Alipay. Параметру title такого объекта присваивается значение QR Code Timeout, а срок действия указывается в секундах в параметре data.

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

 "display_data": [
            {
                "type": "qr_data",
                "title": "QR code",
                "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG"
            },
            {
                "type": "add_info",
                "title": "QR Code Timeout",
                "data": "600"
            }
        ]

Формат итоговых оповещений

Для оповещений о результатах оплат с применением метода Alipay используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 201 для пользователя 125 была проведена оплата в размере 10,00 CNY.

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

 {
        "project_id": 201,
        "payment": {
            "id": "ECT_TEST_155125514200636",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-27T16:01:25+0000",
            "method": "alipay",
            "sum": {
                "amount": 1000,
                "currency": "CNY"
            },
            "description": "ECT_TEST_1551255142006"
        },
        "customer": {
            "id": "125"
        },
        "operation": {
            "id": 20891000000045,
            "type": "sale",
            "status": "success",
            "date": "2019-02-27T16:01:25+0000",
            "created_date": "2019-02-27T15:46:21+0000",
            "request_id": "85d4801f8fa9dead54d315ae19ecb4550201cdcafab",
            "sum_initial": {
                "amount": 1000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1189,
                "payment_id": "Abe9VAEokJyIqyRcX10TLkz30XQbmK3f",
                "date": "2019-02-27T16:01:24+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "T/v8rquB+C0K7TR7sz1vvOrpCsV1/hr9LhIh27fY9PF7Q=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

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

 {
            "id": "ECT_TEST_1551103453746538344",
            "type": "purchase",
            "status": "decline",
            "date": "2019-02-27T14:41:30+0000",
            "method": "alipay",
            "sum": {
                "amount": 10000,
                "currency": "CNY"
            },
            "description": ""
        },
        "operation": {
            "id": 20370000000023,
            "type": "sale",
            "status": "decline",
            "date": "2019-02-27T14:41:30+0000",
            "created_date": "2019-02-26T13:39:44+0000",
            "request_id": "36e07e85504ec76924432b3d6e59e5d5066ebb",
            "sum_initial": {
                "amount": 10000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1189,
                "payment_id": "g4Ld5b6iSuzTmukZUj1RVkXNMuYSj07I",
                "date": "2019-02-27T14:41:29+0000",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "EezTcWDrcp8RW2Wb+bLmytXRRWctzaanCrzhw=="
    }

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

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

Возвраты через Gate

Общая информация

Для выполнения возврата через Gate с использованием метода Alipay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема выполнения возврата выглядит следующим образом.

Рис.: Выполнение возврата через Gate. Описание шагов

Пользователь инициирует возврат.
От веб-сервиса на заданный URL ecommpay передаётся запрос на выполнение возврата.
Запрос на выполнение возврата поступает в платёжную платформу ecommpay.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис Alipay.
В сервисе Alipay выполняется обработка возврата.
От сервиса Alipay к платёжной платформе направляется информация о результате возврата.
От платёжной платформы к веб-сервису направляется оповещение о результате возврата.
На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата.

Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Alipay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на возвраты с применением метода Alipay необходимо учитывать следующее:

Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/alipay/refund. Эта точка относится к группе /v2/payment/wallet/{payment_method}/refund.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  - payment_id — идентификатор платежа, для которого необходимо выполнить возврат;,
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее)),
- payment — объект, содержащий сведения о возврате:
  - description — комментарий к возврату или его описание;,
  - amount — сумма возврата в дробных единицах валюты (является обязательной при частичном возврате);,
- customer — объект, содержащий сведения о пользователе:
  - ip_address — IP-адрес пользователя, актуальный для инициируемого возврата.
Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на возврат с применением метода Alipay должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, подпись, а также, при необходимости, сумму возврата.

  "general": {    
    "project_id": 239,    
    "payment_id": "refund_02",   
    "signature": "of8k9xerKSK40CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },  
   "customer": {    
     "ip_address": "192.0.2.0" 
 },  
  "payment": {    
    "amount": 10000,    
    "description": "refund_02"
}

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

  "general": {    
    "project_id": 239,    
    "payment_id": "refund_02",   
    "signature": "of8k9xerKSK40CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },  
   "customer": {    
     "ip_address": "192.0.2.0" 
 },  
  "payment": {    
    "amount": 10000,    
    "description": "refund_02"
}

Формат оповещений

Для оповещений о результатах возврата с применением метода Alipay используется типовой формат, описание которого представлено в разделе Оповещения.

Дополнительные материалы

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

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

Тестирование

Общая информация

Для метода Alipay доступно тестирование оплат через Payment Page и Gate, а также возвратов через Gate. Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности следует обращаться к специалистам технической поддержки ecommpay.

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

Статусы тестовых платежей

При тестировании оплат их итоговые статусы определяются исходя из сумм, указанных в запросах:

decline — при указании суммы 40000 или 40400,
success — при указании любой другой суммы.

При тестировании возвратов их итоговые статусы определяются исходя из сумм, указанный в запросах:

decline — при указании суммы 50000 или 50500,
success — при указании любой другой суммы.

Оплаты через Payment Page

Для проведения тестовой оплаты через Payment Page необходимо:

Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
Если в запросе не был указан метод alipay — выбрать метод Alipay на странице эмулятора.
Убедиться в отображении инструкции и щёлкнуть кнопку Оплатить.
Указать в поле ввода произвольную фамилию.
Щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы).
Принять итоговое оповещение с информацией о результате оплаты.

Более подробная информация о проведении оплат с использованием метода Alipay через Payment Page представлена в разделе Оплаты через Payment Page этой статьи.

Оплаты через Gate

Для проведения тестовой оплаты через Gate необходимо:

Отправить в платёжную платформу корректный тестовый запрос на оплату.
Принять промежуточное оповещение с данными для перенаправления.
Перейти по полученному URL и щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы) — на странице эмулятора.
Принять итоговое оповещение с информацией о результате оплаты.

Более подробная информация о проведении оплат с использованием метода Alipay через Gate представлена в разделе Оплаты через Gate этой статьи.

Возвраты через Gate

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

Анализ результатов проведения платежей

Для анализа информации о платежах и операциях, как в отдельности по методу Alipay, так и в совокупности с другими методами, можно использовать:

инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.