Apple Pay

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

Схема работы

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

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

* Дополнительную информацию необходимо уточнять у курирующего менеджера ecommpay.

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

Для проведения оплат с помощью Apple Pay пользователю достаточно один раз зарегистрировать свою карту на устройстве Apple Pay и после использовать Touch ID, Face ID, пароль или двойное нажатие на боковую кнопку (Apple Watch) для подтверждения оплаты.

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

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

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

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

Для оплаты через Payment Page с использованием метода Apple Pay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате оплаты. При этом метод Apple Pay можно сделать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты представлена далее.

Информация о формате запросов и параметрах вызова Payment Page при работе с Apple Pay, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API см. в разделе Описание Payment Page API.

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

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

1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах,
   • customer_id — идентификатор пользователя, уникальный в рамках проекта.
2. Для предварительного выбора метода Apple Pay необходимо указывать код платёжного метода в параметре force_payment_method:
   • apple_pay_core — для открытия Payment Page с предварительно выбранным платёжным методом Apple Pay;
   • card — для открытия Payment Page с возможностью выбрать оплату с использованием платёжной карты, подключенной к сервису Apple Pay. В данном случае оба платёжных метода доступны пользователю.
3. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
4. После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

Таким образом, корректный запрос на открытие платёжной формы с применением метода Apple Pay должен содержать идентификаторы проекта, платежа и пользователя, а также валюту и сумму платежа и подпись:

EPayWidget.run(
    { 
      payment_id: 'X03936', 
      payment_amount: 100000, 
      payment_currency: 'RUB', 
      project_id: 247, 
      customer_id: '123',
      signature: "mcsgn6KHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOc
                                                                ZzUCwX6R\/ekpZhkIQg=="
    }
)

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 580 была успешно проведена оплата в размере 1 000,00 RUB с использованием карты 480099******9286.

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15671726468667687",
            "type": "purchase",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "method": "etoken",
            "sum": {
                "amount": 100000,
                "currency": "RUB"
            },
            "description": "ECT_TEST_1567172646866"
        },
        "account": {
            "number": "480099******9286"
        },
        "operation": {
            "id": 47478000001698,
            "type": "sale",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "created_date": "2019-08-30T13:58:06+0000",
            "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3",
            "sum_initial": {
                "amount": 100000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "24fb3f30-000f-5000-8000-1c329d900c68",
                "date": "2019-08-30T13:58:09+0000",
                "auth_code": "591748"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67MbzypSxU2KS33RFCKlyphMTlWSNEuhc06gW
                                                       Q7IZpU6i9siv7+WD1u7AyIYdQ=="
    }
}

В следующем примере оплата была отклонена из-за недостатка средств на счёте карты.

 {
        "account": {
            "number": "480623******2326"
        },
        "customer": {
            "id": "964282"
        },
        "payment": {
            "date": "2019-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "RU",
        "product_name": "Visa Rewards",
        "issuer_name": "Tinkoff Bank",
        "operation": {
            "id": 45047000000055,
            "type": "sale",
            "status": "decline",
            "date": "2019-08-06T12:57:03+0000",
            "created_date": "2019-08-06T12:57:00+0000",
            "request_id": "f92c3dfdf76133d5e1a9d26279b3b77b7da32e",
            "sum_initial": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVAyjRoWsamH6wOqYCdXre8kY9rpDixPlNKv8yVTP
                                                     5U5SRo8YNjIxHPjEEQSmLAtClQ=="
    }
}

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

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

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

1. Отправить запрос на создание платёжной сессии, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
2. Принять данные платёжной сессии и пользователя.
3. Отправить запрос оплату, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
4. Принять оповещение о результате оплаты.

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

Информация о формате запросов и параметрах инициализации оплат методом Apple Pay через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

Формат запросов на создание платёжной сессии

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

1. Должен использоваться запрос /v2/session/applepay, отправляемый методом POST.
2. В запросе должны использоваться следующие параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • validation_url — URL для проверки;
     • domain_name — доменное имя веб-сервиса мерчанта;
     • display_name — название проекта для отображения, должен содержать не более 64 символов;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным).

Пример корректного запроса на создание платёжной сессии с Apple Pay представлен далее.

{
  "general" : {
    "project_id": 175,
    "signature": "VJ/h5ogVuQ6oMNLLxvvKe3Ef6Jw7wV8bt1cPYZcSQduYBT6o+Se5mDLXHChlDZrjJX...==",
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain_name": "appay.eu.ngrok.io",
    "display_name": "test payment"
  }
}

Формат запросов на проведение оплаты

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

1. Должен использоваться запрос, отправляемый методом POST:
   • /v2/payment/applepay/sale для проведения оплаты в одну стадию,
   • /v2/payment/applepay/auth для проведения оплаты в две стадии.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — основные идентификационные сведения запроса:
     • project_id — идентификатор проекта,
     • payment_id — идентификатор платежа, уникальный в рамках проекта,
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — сведения о пользователе:
     • id — идентификатор в рамках проекта,
     • ip_address — IP-адрес;
   • payment — сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3;
   • etoken — сведения о токене от Apple Pay:
     • token — токен, полученный от Apple Pay в формате JSON после идентификации пользователя и указываемый в виде строки. В значении этого параметра могут приводиться такие сведения, как идентификатор платежа на стороне Apple Pay, тип международной платёжной системы и различные служебные данные.

       Рис.: Пример JSON-структуры токена, который должен передаваться в виде строки

       {
          "paymentData":{
             "version":"EC_v1",
             "data":"perkYfGgfMXL/lTG DCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==",
             "header":{
                "ephemeralPublicKey":"MWnwEQ==",
                "publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=",
                "transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"
             }
          },
          "paymentMethod":{
             "displayName":"Visa 1005",
             "network":"Visa",
             "type":"debit"
          },
          "transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"
       }

       Рис.: Пример значения параметра token в виде строки

       "token": "{"paymentData":{"version":"EC_v1","data":"perkYfGgfMXL/lTGDCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==","header":{"ephemeralPublicKey":"MWnwEQ==","publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=","transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"}},"paymentMethod":{"displayName":"Visa 1005","network":"Visa","type":"debit"},"transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"}"

3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, IP-адрес пользователя, валюту и сумму платежа, а также токен от Apple Pay:

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "customer": {
    "ip_address": "83.220.236.84",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "etoken": {
        "token": "..."
    }
}

Формат запросов на подтверждение оплаты в две стадии

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

1. Должен использоваться запрос, отправляемый методом POST на /v2/payment/applepay/capture для подтверждения списания оплаты в две стадии.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — основные идентификационные сведения запроса:
     • project_id — идентификатор проекта,
     • payment_id — идентификатор платежа, по которому необходимо подтвердить списание,
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • payment — сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3;
3. Валюта и сумма платежа должны совпадать со значениями, переданными в запросе на авторизацию.
4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, валюту и сумму платежа:

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  }

Формат запросов на отмену оплаты в две стадии

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

1. Должен использоваться запрос, отправляемый методом POST на /v2/payment/applepay/cancel для отмены проведения оплаты в две стадии.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — основные идентификационные сведения запроса:
     • project_id — идентификатор проекта,
     • payment_id — идентификатор платежа, по которому необходимо отменить списание,
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на отмену оплаты с применением метода Apple Pay должен содержать идентификаторы проекта и платежа и подпись:

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  }

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 580 была успешно проведена оплата в размере 1 000,00 RUB с использованием карты 480099******9286.

{
        "project_id": 580,
        "payment": {
            "id": "TEST_15671726468667687",
            "type": "purchase",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "method": "etoken",
            "sum": {
                "amount": 100000,
                "currency": "RUB"
            },
            "description": "ECT_TEST_1567172646866"
        },
        "account": {
            "number": "480099******9286"
        },
        "operation": {
            "id": 47478000001698,
            "type": "sale",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "created_date": "2019-08-30T13:58:06+0000",
            "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3",
            "sum_initial": {
                "amount": 100000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "24fb3f30-000f-5000-8000-1c329d900c68",
                "date": "2019-08-30T13:58:09+0000",
                "auth_code": "591748"                
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67MbzypSxU2KS33RFCKlyphMTlWSNEuhc06gW
                                                       Q7IZpU6i9siv7+WD1u7AyIYdQ=="
    }
}

В следующем примере оплата была отклонена из-за недостатка средств на счёте карты.

 {
        "account": {
            "number": "480623******2326"
        },
        "customer": {
            "id": "964282"
        },
        "payment": {
            "date": "2019-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "RU",
        "product_name": "Visa Rewards",
        "issuer_name": "Tinkoff Bank",
        "operation": {
            "id": 45047000000055,
            "type": "sale",
            "status": "decline",
            "date": "2019-08-06T12:57:03+0000",
            "created_date": "2019-08-06T12:57:00+0000",
            "request_id": "f92c3dfdf76133d5e1a9d26279b3b77b7da32e",
            "sum_initial": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVAyjRoWsamH6wOqYCdXre8kY9rpDixPlNKv8yVTP
                                                     5U5SRo8YNjIxHPjEEQSmLAtClQ=="
    }
}

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

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

• Схемы взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация об операциях

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

Платёжный метод Apple Pay предоставляет возможность проводить повторяемые оплаты — регулярные оплаты со списаниями по запросу. Подробная информация представлена в разделе Повторяемая оплата со списаниями по запросам. Через Payment Page доступна регистрация повторяемой оплаты, для этого со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, а также данные для регистрации повторяемой оплаты в объекте recurring, на рабочий URL ecommpay и принять оповещение о результате. В оповещении о регистрации повторяемой оплаты вы получите её идентификатор, который нужно использовать для проведения или отмены регулярной оплаты через Gate. Подробная информация об этом представлена в разделе Повторяемые оплаты через Gate.

Информация о формате запросов и параметрах вызова Payment Page при работе с Apple Pay, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API см. в разделе Описание Payment Page API.

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

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

1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Для регистрации повторяемой оплаты необходимо передать объект recurring, содержащий признак регистрации и необходимую информацию. Для регистрации регулярной оплаты в запросе необходимо передать информацию о периодичности, сумме, начале и конце совершения регулярной оплаты. Полный список параметров, которые можно передать в объекте recurring представлен в разделе Регистрация повторяемых оплат.
3. Для предварительного выбора метода Apple Pay необходимо указывать код платёжного метода в параметре force_payment_method:
   • apple_pay_core — для открытия Payment Page с предварительно выбранным платёжным методом Apple Pay;
   • card — для открытия Payment Page с возможностью выбрать оплату с использованием платёжной карты, подключенной к сервису Apple Pay. В данном случае оба платёжных метода доступны пользователю.
4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
5. После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

Таким образом, корректный запрос на открытие платёжной формы для регистрации повторяемой оплаты с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, признак регистрации и информацию повторяемой оплаты, валюту и сумму платежа и подпись:

EPayWidget.run(
    { 
      payment_id: 'X03936', 
      payment_amount: 100000, 
      payment_currency: 'RUB', 
      project_id: 208, 
      customer_id: '123',
      force_payment_method: 'apple_pay_core',
      recurring={"register":true,"type":"R","expiry_year":2025,"expiry_month":"01","period":"D","time":"10:00:00","start_date":"15-11-2020","scheduled_payment_id":"A2323"},
      signature: "mcsgn6KHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO...=="
    }
)

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

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

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

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "purchase",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken",
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "account": {
            "number": "489537******3478"
        },
        "recurring": {
            "id": 1000030038,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

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

Платёжный метод Apple Pay предоставляет возможность проводить повторяемые оплаты — регулярные оплаты со списаниями по запросу. Подробная информация представлена в разделе Повторяемая оплата со списаниями по запросам.

Регистрация повторяемой оплаты через Gate

Для регистрации повторяемых оплат со стороны веб-сервиса необходимо отправить запрос на оплату, содержащий требуемые параметры и подпись, а также признак регистрации повторяемой оплаты recurring.register: true, на рабочий URL ecommpay и принять оповещение о результате. В оповещении о регистрации повторяемой оплаты вы получите её идентификатор, который можно использовать для проведения или отмены регулярных оплат.

Подробнее о проведении оплаты через Gate с помощью метода Apple Pay см. в разделе Оплаты через Gate.

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

При работе с запросами на регистрацию повторяемой оплаты с применением метода Apple Pay необходимо учитывать следующее:

1. Должны использоваться запросы, отправляемые методом POST на следующие URL: /v2/payment/applepay/sale или /v2/payment/applepay/auth.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные сведения:
     • project_id — идентификатор проекта,
     • payment_id — идентификатор платежа,
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор в рамках проекта,
     • ip_address — используемый IP-адрес;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3.
   • recurring — объект, содержащий сведения о повторяемой оплате (условия проведения регулярной оплаты хранятся на стороне мерчанта):
     • register — признак регистрации платежа как повторяемой оплаты,
     • type—тип повторяемой оплаты: R (для регулярной оплаты), C (для экспресс-оплаты), или U (для автооплаты), подробную информацию см. в разделе Общая информация,
     • scheduled_payment_id—идентификатор следующей повторяемой оплаты,
     • start_date — дата начала регулярной оплаты, в формате ДД-ММ-ГГГГ (должна быть как минимум на один день позже, чем дата регистрации),
     • amount — сумма платежа,
     • period — период выполнения регулярной оплаты,
     • interval — интервал выполнения регулярной оплаты,
     • time — время выполнения регулярной оплаты в формате hh:mm:ss (UTC0).
3. Для регистрации регулярных оплат в запросе необходимо также передать информацию о периодичности, сумме, начале и конце совершения регулярных оплат.
4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Корректный запрос на регистрацию повторяемой оплаты с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, валюту и сумму платежа, а также признак регистрации и условия проведения списаний при регулярной оплате.

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "1.1.1.1",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

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

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

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

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

1. Должен использоваться запрос, отправляемый методом POST на следующие URL: /v2/payment/applepay/recurring.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные сведения:
     • project_id — идентификатор проекта,
     • payment_id — идентификатор платежа,
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — используемый IP-адрес;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма,
     • currency — валюта платежа в формате ISO-4217 alpha-3.
   • recurring — объект, содержащий сведения о повторяемой оплате:
     • id — идентификатор зарегистрированной повторяемой оплаты.
3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Корректный запрос на проведение повторяемой оплаты с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, валюту и сумму платежа, а также идентификатор зарегистрированной регулярной оплаты.

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "1.1.1.1"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "recurring": {
    "id": 1234567890
  }
}

Отмена проведения повторяемой оплаты

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

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

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

1. Должен использоваться запрос, отправляемый методом POST на следующие URL: /v2/payment/applepay/recurring/cancel
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные сведения:
     • project_id — идентификатор проекта,
     • payment_id — идентификатор платежа,
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • recurring — объект, содержащий сведения о повторяемой оплате:
     • id — идентификатор зарегистрированной повторяемой оплаты;
3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Корректный запрос на отмену проведения регулярной оплаты с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, подпись, а также идентификатор зарегистрированной повторяемой оплаты.

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}

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

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

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

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken",
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "account": {
            "number": "489537******3478"
        },
        "recurring": {
            "id": 1000030038,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация об операциях

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

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

Информация о формате запросов и параметрах инициализации возвратов методом Apple Pay через Gate, а также о формате оповещений о результатах возвратов приведена далее, общая информация о работе с API см. в разделе Работа с API.

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

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

1. Должен использоваться запрос, отправляемый методом POST на /v2/payment/applepay/refund.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения о запросе:
     • project_id — идентификатор проекта;
     • payment_id — идентификатор платежа;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — используемый IP-адрес;
   • payment — объект, содержащий сведения о возврате :
     • description — комментарий или описание возврата,
     • amount — сумма возврата в дробных единицах валюты (обязательный при частичном возврате),
     • currency — валюта возврата в формате ISO-4217 alpha-3 (обязательный при частичном возврате).
3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на частичный возврат с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, подпись, сумму и валюту платежа, описание возврата и IP-адрес пользователя:

{
   "general": {    
    "project_id": 239,    
    "payment_id": "refund_02",   
    "signature": "of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },  
   "customer": {    
     "ip_address": "1.2.3.4" 
  },  
   "payment": {    
     "amount": 50000,    
     "currency": "RUB",
     "description": "refund_02"
 }
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 260 для пользователя был успешно проведён возврат в размере 10,00 RUB на карту 480114******3791.

{
        "project_id": 260,
        "payment": {
            "id": "TEST_15792507735",
            "type": "purchase",
            "status": "refunded",
            "date": "2020-01-20T08:31:36+0000",
            "method": "etoken",
            "sum": {
                "amount": 1000,
                "currency": "RUB"
            },
            "description": ""
        },
        "customer": {
            "id": "1888"
        },
        "account": {
            "number": "480114******3791"
        },
        "operation": {
            "id": 69512000019571,
            "type": "refund",
            "status": "success",
            "date": "2020-01-20T08:31:36+0000",
            "created_date": "2020-01-20T08:31:35+0000",
            "request_id": "e0069513"
            "sum_initial": {
                "amount": 1000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RUB"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1911,
                "payment_id": "0000438583",
                "auth_code": ""
                }
            },
        "signature": "beJ1deUiEDd+7zuo6YrfSRxbOn8BYDLI9RR3yliH3B91LcBan4+2VkRrxn2NYOexr7goJzgEQj34sKAStuW8Fg=="
    }

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

{
        "project_id": 260,
        "payment": {
            "id": "TEST_1579250773501",
            "type": "purchase",
            "status": "success",
            "date": "2020-01-20T08:31:36+0000",
            "method": "etoken",
            "sum": {
                "amount": 100,
                "currency": "RUB"
            },
            "description": ""
        },
        "customer": {
            "id": "1888"
        },
        "account": {
            "number": "480114******3791"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RUB"
            },
            "code": "3283",
            "message": "Refund amount more than init amount",
            "provider": {
                "id": 1911,
                "payment_id": "0000438582",
                "auth_code": ""
            },
            "id": 69512000019571,
            "type": "refund",
            "status": "decline",
            "date": "2020-01-20T08:31:36+0000",
            "created_date": "2020-01-20T08:31:35+0000",
            "request_id": "e0069142"
        },
        "signature": "beJ1deUiEDd+7zuo6YrfSRxbOn8BYDLI9RR3yliH3B91LcBan4+2VkRrxn2NYOexr7goJzgEQj34sKAStuW8Fg=="
    }
}

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация об операциях

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

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

Формат запросов на проверку действительности карты

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

1. Должен использоваться запрос, отправляемый методом POST на /v2/payment/applepay/account_verification.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — основные идентификационные сведения запроса:
     • project_id — идентификатор проекта,
     • payment_id — идентификатор платежа
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — сведения о пользователе:
     • ip_address — IP-адрес;
   • payment — сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3;
   • etoken — сведения о токене от Apple Pay:
     • token — токен, полученный от Apple Pay в формате JSON после идентификации пользователя и указываемый в виде строки. В значении этого параметра могут приводиться такие сведения, как идентификатор платежа на стороне Apple Pay, тип международной платёжной системы и различные служебные данные.

       Рис.: Пример JSON-структуры токена, который должен передаваться в виде строки

       {
          "paymentData":{
             "version":"EC_v1",
             "data":"perkYfGgfMXL/lTG DCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==",
             "header":{
                "ephemeralPublicKey":"MWnwEQ==",
                "publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=",
                "transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"
             }
          },
          "paymentMethod":{
             "displayName":"Visa 1005",
             "network":"Visa",
             "type":"debit"
          },
          "transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"
       }

       Рис.: Пример значения параметра token в виде строки

       "token": "{"paymentData":{"version":"EC_v1","data":"perkYfGgfMXL/lTGDCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==","header":{"ephemeralPublicKey":"MWnwEQ==","publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=","transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"}},"paymentMethod":{"displayName":"Visa 1005","network":"Visa","type":"debit"},"transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"}"

3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на проверку действительности карты с применением метода Apple Pay должен содержать идентификаторы проекта и платежа, IP-адрес пользователя, валюту и сумму платежа, а также токен от Apple Pay:

{
  "general": {
    "project_id": 238,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "customer": {
    "ip_address": "83.220.236.84"
  },
  "payment": {
    "amount": 0,
    "currency": "RUB"
  },
  "etoken": {
        "token": "..."
    }
}

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

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

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация об операциях

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

Для метода Apple Pay доступно тестирование оплат в одну и две стадии через Payment Page и Gate. Также доступно тестирование проверки действительности карты через Gate. При тестировании оплат через Gate веб-сервис мерчанта должен соответствовать следующим условиям:

• Домен сайта зарегистрирован в сервисах Apple. Для регистрации домена необходимо обратиться в службу технической поддержки ecommpay support@ecommpay.com
• Сайт поддерживает функциональность запуска скрипта для начала сессии Apple согласно документации.

Также при тестировании следует учитывать другие особенности работы с методом Apple Pay, указанные в таблице Характеристика

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

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

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

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

• success — при указании суммы 1000;
• decline — при указании суммы 2000, 5000 или 10001.

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

• success — при указании суммы 0;
• decline — при указании любой другой суммы.

Оплата в одну стадию через Payment Page

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

1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
2. Если в запросе не был указан метод apple_pay_core — выбрать метод Apple Pay на странице эмулятора.
3. Подтвердить оплату.
4. Принять оповещение с информацией о результате оплаты.

Подробная информация о проведении оплат с использованием метода Apple Pay через Payment Page представлена в пункте Оплаты через Payment Page.

Оплата в одну стадию через Gate

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

1. Отправить в платёжную платформу корректный тестовый запрос на создание платёжной сессии.
2. Принять данные платёжной сессии и пользователя.
3. Подтвердить оплату.
4. Отправить в платёжную платформу корректный тестовый запрос на оплату.
5. Принять оповещение с информацией о результате оплаты.

Подробная информация о проведении оплат с использованием метода Apple Pay через Gate представлена в пункте Оплаты через Gate.

Оплата в две стадии с блокировкой средств через Payment Page и подтверждением или отменой через Gate

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

1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
2. Если в запросе не был указан код предварительного выбора метода card или apple_pay_core — выбрать оплату методом Apple Pay на странице эмулятора.
3. Подтвердить оплату.
4. Принять оповещение с информацией о результате блокировки.
5. Отправить запрос на подтверждение или отмену оплаты.
6. Принять оповещение с информацией о результате оплаты.

Подробная информация о проведении оплат с использованием метода Apple Pay через Payment Page и Gate представлена в пунктах Оплаты через Payment Page и Оплаты через Gate.

Оплата в две стадии с блокировкой средств и подтверждением или отменой через Gate

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

1. Отправить в платёжную платформу корректный тестовый запрос на создание платёжной сессии.
2. Принять данные платёжной сессии и пользователя.
3. Отправить в платёжную платформу корректный тестовый запрос на оплату.
4. Подтвердить оплату.
5. Принять оповещение с информацией о результате блокировки.
6. Отправить запрос на подтверждение или отмену оплаты.
7. Принять оповещение с информацией о результате оплаты.

Подробная информация о проведении оплат с использованием метода Apple Pay через Gate представлена в пункте Оплаты через Gate.

Проверка действительности карты через Gate

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

Подробная информация о проведении проверки действительности карты с использованием метода Apple Pay через Gate представлена в пункте Проверка действительности карты.

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

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

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

• Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
• Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

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