Использование сервисов Mastercard MoneySend и Visa Direct

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

В платёжной платформе ecommpay поддерживается возможность использования сервисов Mastercard MoneySend и Visa Direct, которые упрощают проведение денежных переводов между пользователями и мерчантами. В рамках этих сервисов доступны операции, позволяющие списывать средства с пользователей-„отправителей“ и зачислять средства пользователям-„получателям“. Такие списания и зачисления могут выполняться по отдельности и в различных комбинациях, при этом поступление средств на целевые счета согласно требованиям платёжных систем должно занимать не более 30 минут, что обеспечивает довольно высокую скорость переводов и удобство пользователей.

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

  Списание Зачисление
Операция в сервисе Mastercard MoneySend Funding transaction (FT) Payment transaction (PT)
Операция в сервисе Visa Direct Account Funding Transaction (AFT) Original Credit Transaction (OCT)
Техническая операция в платформе ecommpay sale payout
Допустимые платёжные методы
  • Карточные платежи
  • Apple Pay
  • Google Pay

Карточные платежи

Допустимые платёжные инструменты пользователей Платёжные карты Mastercard или Visa Платёжные карты Mastercard или Visa
Возможность отмены операции после её выполнения +

(с ограничениями по времени)

Примеры использования
  • Пополнение пользовательского счёта в сервисе мерчанта
  • Первая часть перевода с карты на карту (со списанием средств со счёта отправителя)
  • Выплата средств пользователю
  • Вторая часть перевода с карты на карту (с зачислением средств на счёт получателя)

Поскольку в платформе ecommpay эти операции выполняются как sale и payout (с определённым набором параметров), для их инициирования могут использоваться любые подходящие интерфейсы: для оплат не только Gate, но и Payment Page и SDK для мобильных приложений, а для выплат Gate и Dashboard.

По вопросам, касающимся ограничений в применении сервисов Mastercard MoneySend и Visa Direct и подключения к ним, можно обращаться к курирующему менеджеру ecommpay.

Схемы выполнения операций

Общий порядок работы

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

Способы указания платёжных реквизитов

Как и с другими видами оплат и выплат в платёжной платформе ecommpay, при При работе со списаниями и зачислениями в рамках сервисов Mastercard MoneySend и Visa Direct можно использовать разные способы указания реквизитов платёжных карт. Это:

  • Реквизиты (в явном виде) — с указанием номера карты, срока её действия, держателя и кода проверки подлинности;
  • Произвольный идентификатор реквизитов — с указанием идентификатора, ранее ассоциированного в платёжной платформе с реквизитами используемой карты (подробнее);
  • Стандартизированный токен реквизитов — с указанием токена, ранее ассоциированного в платёжной платформе с реквизитами используемой карты (подробнее).

Списания

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

  1. Отправить запрос к конечной точке /v2/payment/{название метода}/sale[/форма указания реквизитов платёжного инструмента].
  2. При необходимости выполнить аутентификацию пользователя с использованием протокола 3-D Secure (подробнее).
  3. Принять от платёжной платформы оповещение о результате списания.

Формат запроса на списание описан далее, в разделе Форматы запросов этой статьи.

Отмены списаний

В некоторых случаях может быть актуальной отмена списания. Технически в платформе такая отмена выполняется как возврат и инициируется через запрос к конечной точке /v2/payment/{указатель метода}/refund. При этом следует учитывать, что согласно требованиям платёжных систем отменить списание можно только на полную сумму и только в установленные сроки.

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

Зачисления

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

  1. Отправить запрос к конечной точке /v2/payment/card/payout[/token].
  2. Принять от платёжной платформы оповещение о результате зачисления.

Формат запроса на зачисление описан далее, в разделе Форматы запросов этой статьи.

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

Запрос на списание

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

  1. POST-запрос должен отправляться к одной из следующих конечных точек:
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным);
    • payment — объект, содержащий сведения о списании:
      • amount — сумма списания с платёжной карты отправителя (пользователя), в дробных единицах валюты;
      • currency — код валюты списания в формате ISO-4217 alpha-3;
    • customer — объект, содержащий сведения об отправителе (пользователе):
      • id — идентификатор пользователя в рамках проекта;
      • ip_address — IP-адрес пользователя;
      • country — код страны пользователя в формате ISO 3166-1 alpha-2;
      • address — адрес проживания пользователя, обязательный при использовании карт Visa;
      • city — название города проживания (или иного населённого пункта) пользователя, обязательное при использовании карт Visa;
      • state_code — код штата или провинции пользователя, обязательный для случаев с последующим зачислением списываемых средств на карту Visa, выпущенную в США или Канаде;
      • phone — номер телефона пользователя, обязательный для случаев с последующим зачислением списываемых средств на карту Visa, выпущенную в Бразилии или Катаре;
      • account_id — номер кошелька получателя, обязательный при использовании карт Mastercard;
      • first_name — имя пользователя, обязательное при использовании методов Apple Pay и Google Pay;
      • last_name — фамилия пользователя, обязательное при использовании методов Apple Pay и Google Pay.
  3. В запросе должны содержаться сведения о платёжной карте отправителя (пользователя):
    • При передаче реквизитов в явном виде — следующие данные в объекте card:
      • pan — номер карты;
      • year — год окончания срока действия карты;
      • month — порядковый номер месяца срока действия карты;
      • card_holder — имя и фамилия держателя карты (в соответствии с указанными на карте);
      • cvv — код проверки подлинности карты.
    • При передаче идентификатора реквизитов — следующие данные в объекте card:
      • saved_account_id — идентификатор, ассоциированный в платёжной платформе с реквизитами используемой карты;
      • cvv — код проверки подлинности карты.
    • При передаче токена реквизитов — следующие данные:
      • token — токен, ассоциированный в платёжной платформе с реквизитами используемой карты;
      • cvv — код проверки подлинности карты.
  4. В запросе должны содержаться сведения о платёжном инструменте получателя:
    • При передаче сведений о кошельке получателя — следующие данные в объекте recipient:
      • wallet_id — номер кошелька;
      • wallet_owner — имя и фамилия владельца кошелька;
      • country — код страны владельца кошелька в формате ISO 3166-1 alpha-2, обязательный для случаев, когда кошелёк связан с картой Mastercard.
    • При передаче реквизитов карты — следующие данные в объекте recipient:
      • pan — номер платёжной карты получателя;
      • card_holder — имя и фамилия держателя карты (в соответствии с указанными на карте).
    • При передаче реквизитов карты Visa, выпущенной в Канаде — следующие данные (в дополнение к реквизитам):
      • country — код страны получателя в формате ISO 3166-1 alpha-2;
      • address — адрес проживания получателя;
      • city — название города проживания (или иного населённого пункта) получателя;
      • state_code — код штата или провинции получателя.
  5. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

В следующем примере представлены данные тела запроса на списание с карты Visa c последующим зачислением списываемых средств на карту Mastercard.

Рис.: Пример тела запроса на списание

{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "payment":{
    "amount":1000,
    "currency":"EUR"
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225,
    "country":"IT",
    "city":"Florence",
    "address":"Via Certaldo 18"
  },
//при передаче реквизитов карты отправителя в явном виде:
  "card":{
    "pan":"4314220000000056",
    "year":2024,
    "month":10,
    "card_holder":"Gio Boccaccio",
    "cvv":"334"
  },
//при передаче идентификатора реквизитов:
  "card":{
    "saved_account_id": 21121375,
    "cvv": "334"
  },
//при передаче токена реквизитов:
    "token":"f365bb1729f9b72fd9c09703a751c979f3becc67",
    "cvv":"334",
//при передаче реквизитов карты получателя:
"recipient":{
    "pan":"5413330000000019",
    "card_holder":"Fran Petrarca"
  }
//при передаче сведений о кошельке получателя:
"recipient":{
    "wallet_id":"WID20071304",
    "wallet_owner":"Fran Petrarca",
    "country":"IT"
  }
}

Запрос на зачисление

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

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

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

В следующем примере представлены данные тела запроса на зачисление средств на карту Mastercard, при этом списание было осуществлено с карты Visa.

Рис.: Пример тела запроса на зачисление

{
  "general":{
    "project_id":91348,
    "payment_id":"135113521354",
    "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer":{
    "id":"16061313",
    "ip_address":"93.47.230.225"
  },
  "payment":{
    "amount":1000,
    "currency":"EUR"
  },
  "recipient":{
    "first_name":"Fran",
    "last_name":"Petrarca"
  },
  "sender":{
    "country":"IT",
    "city":"Florence",
    "address":"Via Certaldo 18",
    "first_name":"Gio",
    "last_name":"Boccaccio",
    "day_of_birth":"16-06-1313"
  },
//при передаче реквизитов карты получателя:
  "card":{
    "pan":"5413330000000019",
    "card_holder":"Fran Petrarca"
  },
//при передаче токена:
    "token": 1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713,
//при передаче реквизитов карты отправителя:
"sender":{
    "pan":"4314220000000056"
  }
//при передаче сведений о кошельке отправителя:
"sender":{
    "wallet_id":"WID16061313" 
  }
}

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

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

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

    {
        "project_id": 91348,
        "payment": {
            "id": "135113521354",
            "type": "purchase",
            "status": "success",
            "date": "2022-02-22T19:52:14+0000",
            "method": "card",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "431422******0056",
            "type": "visa",
            "token": "f365bb1729f9b72fd9c09703a751c979f3becc67",
            "country": "IT",
            "bank": "Intesa Sanpaolo SpA",
            "product": "debit"
        },
        "customer": {
            "id": "16061313"
        },
        "operations": [
            {
                "provider": {
                    "result_message": "Success",
                    "result_code": "00",
                    "id": 2,
                    "payment_id": "135113521354",
                    "auth_code": "661786",
                    "endpoint_id": 3651,
                    "date": "2022-02-22T19:52:14+0000"
                },
                "rrn": "305440290856",
                "region": "domestic",
                "code": "0",
                "message": "Success",
                "eci": "05",
                "id": 52901540107953,
                "type": "sale",
                "status": "success",
                "date": "2022-02-22T19:52:14+0000",
                "created_date": "2022-02-22T19:51:18+0000",
                "request_id": "a51091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-d7bc0c44525",
                "sum_initial": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "sum_converted": {
                    "amount": 1000,
                    "currency": "EUR"
                }
            }
        ],
        "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
    }

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

    {
        "project_id": 91348,
        "payment": {
            "id": "135113521355",
            "type": "payout",
            "status": "success",
            "date": "2022-02-22T20:01:36+0000",
            "method": "card",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "account": {
            "number": "541333******0019",
            "type": "mastercard",
            "token": "1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713"
        },
        "customer": {
            "id": "16061313"
        },
        "issuer_name": "UniCredit SpA",
        "product_name": "World Mastercard",
        "country": "IT",
        "card_product_type": "debit",
        "card_holder": "Fran Petrarca",
        "operations": [
            {
                "type": "payout",
                "provider": {
                    "result_message": "Success",
                    "result_code": "00",
                    "id": 2,
                    "payment_id": "135113521355",
                    "auth_code": "309410",
                    "endpoint_id": 3651,
                    "date": "2022-02-22T20:01:35+0000"
                },
                "status": "success",
                "date": "2022-02-22T20:01:36+0000",
                "rrn": "301360291143",
                "created_date": "2022-02-22T20:01:34+0000",
                "region": "domestic",
                "request_id": "fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001711",
                "code": "0",
                "sum_initial": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "message": "Success",
                "sum_converted": {
                    "amount": 1000,
                    "currency": "EUR"
                },
                "id": 5013600010130727
            }
        ],
        "signature": "hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g=="
    }