Apple Pay

Введение

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

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

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

Схема работы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

К особенностям оповещений в случае с Apple Pay можно отнести то, что в параметре token объекта account указывается значение токена карты, которое можно использовать только при запросах на выплаты.

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

{
        "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": "USD"
            },
            "description": "ECT_TEST_1567172646866"
        },
        "account": {
            "number": "431422******0056",
            "token": :"a989f5ef7ab159dd5c3016eee7563736fa6608ce50413260e4201d13dbfcdc75"
        },
        "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": "USD"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "USD"
            },
            "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+dMGZZnm3Owjgw9ly67Mb9siv7+WD1u7AyIYdQ=="
    }
}

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

 {
        "account": {
            "number": "431422******0056"
        },
        "customer": {
            "id": "964282"
        },
        "payment": {
            "date": "2019-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "RU",
        "product_name": "Visa Rewards",
        "issuer_name": "Example 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": "USD"
            },
            "sum_converted": {
                "amount": 1030000,
                "currency": "USD"
            },
            "provider": {
                "id": 1187,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVSRo8YNjIxHPjEEQSmLAtClQ=="
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к одной из следующих конечных точек:
   • /v2/payment/applepay/sale для проведения оплаты в одну стадию,
   • /v2/payment/applepay/auth для проведения оплаты в две стадии.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
   • 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": "USD"
  },
  "etoken": {
        "token": "..."
    }
}

{
  "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": "USD"
  },
  "etoken": {
        "token": "..."
    }
}

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

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

1. Для подтверждения каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/applepay/capture.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • 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": "USD"
  }

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

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

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

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

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

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

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

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

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

К особенностям оповещений в случае с Apple Pay можно отнести то, что в параметре token объекта account указывается значение токена карты, которое можно использовать только при запросах на выплаты.

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

{
        "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": "USD"
            },
            "description": "ECT_TEST_1567172646866"
        },
        "account": {
            "number": "431422******0056",
            "token":"a989f5ef7ab159dd5c3016eee7563736fa6608ce50413260e4201d13dbfcdc75"
        },
        "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": "USD"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "USD"
            },
            "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+dMGZZnm3Owjgw9ly67Mb9siv7+WD1u7AyIYdQ=="
    }
}

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

 {
        "account": {
            "number": "431422******0056"
        },
        "customer": {
            "id": "964282"
        },
        "payment": {
            "date": "2019-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "RU",
        "product_name": "Visa Rewards",
        "issuer_name": "Example 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": "USD"
            },
            "sum_converted": {
                "amount": 1030000,
                "currency": "USD"
            },
            "provider": {
                "id": 1187,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVSRo8YNjIxHPjEEQSmLAtClQ=="
    }
}

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

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

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

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

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

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

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

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

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

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "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": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "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": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

Для оповещений о результатах регистрации повторяемой оплаты с применением метода 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": "431422******0056"
        },
        "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 также могут быть полезны следующие материалы:

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

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

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

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

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

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

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

Формат запросов на регистрацию повторяемой оплаты

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

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

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytOqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytOqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

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

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

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

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

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6wx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "recurring": {
    "id": 1234567890
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6wx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "recurring": {
    "id": 1234567890
  }
}

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

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

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

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

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "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": "431422******0056"
        },
        "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": "x2tsnvLCRXZMXr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

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

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

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

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

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

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

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

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

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

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

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

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

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

{
        "project_id": 260,
        "payment": {
            "id": "TEST_15792507735",
            "type": "purchase",
            "status": "refunded",
            "date": "2020-01-20T08:31:36+0000",
            "method": "etoken",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "1888"
        },
        "account": {
            "number": "431422******0056"
        },
        "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": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1911,
                "payment_id": "0000438583",
                "auth_code": ""
                }
            },
        "signature": "beJ1deUiEDd+7zuo6YrfSRzgEQj34sKAStuW8Fg=="
    }

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

{
        "project_id": 260,
        "payment": {
            "id": "TEST_1579250773501",
            "type": "purchase",
            "status": "success",
            "date": "2020-01-20T08:31:36+0000",
            "method": "etoken",
            "sum": {
                "amount": 100,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "1888"
        },
        "account": {
            "number": "431422******0056"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "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+7zuooJzgEQj34sKAStuW8Fg=="
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/card/payout/token.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма выплаты в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемой выплаты;,
     • first_name — имя пользователя;,
     • middle_name — отчество или среднее имя пользователя;,
     • last_name — фамилия пользователя;,
   • card — объект, содержащий сведения о платёжной карте пользователя:
     • card_holder — полное имя держателя карты;,
   • token — токен, полученный от ecommpay, в параметре token, включённым в оповещение о проведённой оплате.
3. В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, в запросе необходимо передавать объект recipient, содержащий сведения о местонахождении получателя выплаты:
   • country — код страны получателя в формате ISO 3166-1 alpha-2;
   • city — город получателя;
   • address — адрес получателя;
   • если код страны соответствует CA или US, дополнительно следует передать параметр state — штат, провинция или другой регион получателя выплаты.
4. В случае проведения выплаты в рамках программы Money Transfer платёжной системы Visa на карту, выпущенную в Бразилии или Катаре, в запросе необходимо передавать номер телефона отправителя в параметре phone объекта sender.
5. В случае проведения выплаты в рамках программ сервиса MoneySend платёжной системы Mastercard, в которой отправителем является физическое лицо, в запросе необходимо передавать информацию об имени и фамилии получателя в параметрах first_name и last_name объекта recipient, а также информацию об отправителе выплаты в объекте sender:
   • номер платёжного инструмента отправителя — pan для карты или wallet_id для электронного кошелька;
   • first_name — имя отправителя;
   • last_name — фамилия отправителя;
   • address — адрес отправителя;
   • city — город отправителя;
   • zip — почтовый индекс отправителя;
   • country — код страны отправителя в формате ISO 3166-1 alpha-2;
   • если код страны соответствует CA или US, дополнительно следует передать параметр state — штат, провинция или другой регион отправителя выплаты.
6. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "first_name": "John",
    "middle_name": "Jr",
    "last_name": "Jonson",
    "ip_address": "192.0.2.0"
  },
  "card": {
    "card_holder": "John Johnson",
  "token": "a989f5ef7ab159dd5c3016eee7563736f"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "first_name": "John",
    "middle_name": "Jr",
    "last_name": "Jonson",
    "ip_address": "192.0.2.0"
  },
  "card": {
    "card_holder": "John Johnson",
  "token": "a989f5ef7ab159dd5c3016eee7563736f"
  }
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 123 была проведена выплата в размере 1,00 EUR.

{
        "payment": {
            "method": "card",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "id": "test_id",
            "type": "payout",
            "status": "success",
            "date": "2023-11-07T07:37:27+0000",
            "description": "Test payout"
        },
        "customer": {
            "id": "Test",
            "ip": "192.0.2.0",
            "first_name": "Test",
            "last_name": "Test"
        },
        "account": {
            "number": "1234******4567",
            "token": "a9608ce50413260e4201d13dbfcdc75",
            "type": "visa",
            "card_holder": "TEST TEST",
            "expiry_month": "01",
            "expiry_year": "2031"
        },
        "project_id": 123,
        "rrn": "331140338636",
        "testdebet": "credit",
        "opeation": {
            "last_processor_message": "Success"
        },
        "operation": {
            "created_date": "2023-11-07T07:37:22+0000",
            "request_id": "d22a4c02f61ed9a82140045-00049491",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 414,
                "payment_id": "0040000018267721",
                "auth_code": "408112",
                "endpoint_id": 414,
                "date": "2023-11-07T07:37:24+0000"
            },
            "id": 49490010084733,
            "type": "payout",
            "status": "success",
            "date": "2023-11-07T07:37:27+0000"
        },
        "signature": "TL2BLpOE/xAVCmYf8SIUXYqmlF1WHtaHQ=="
    }

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

{
        "payment": {
            "method": "card",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "id": "test_id",
            "type": "payout",
            "status": "decline",
            "date": "2023-11-07T07:38:27+0000",
            "description": "Test payout"
        },
        "customer": {
            "id": "Test",
            "ip": "192.0.2.0",
            "first_name": "Test",
            "last_name": "Test"
        },
        "account": {
            "number": "1234******4567",
            "token": "a9608ce50413260e4201d13dbfcdc75",
            "type": "visa",
            "card_holder": "TEST TEST",
            "expiry_month": "01",
            "expiry_year": "2031"
        },
        "project_id": 123,
        "rrn": "",
        "testdebet": "credit",
        "opeation": {
            "last_processor_message": "Decline"
        },
        "operation": {
            "created_date": "2023-11-07T07:38:22+0000",
            "request_id": "d22a4c02f61ed9a82140045-00049492",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 414,
                "payment_id": "0040000018267721",
                "auth_code": "",
                "endpoint_id": 414,
                "date": "2023-11-07T07:38:24+0000"
            },
            "id": 49490010084733,
            "type": "payout",
            "status": "decline",
            "date": "2023-11-07T07:38:27+0000"
        },
        "signature": "TL2BLpOE/xAVCmYf8SIUXYqmlF1WHtaHA=="
    }

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

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

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

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

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

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

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

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

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

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

• 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 представлена в пункте Проверка действительности карты этой статьи.