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

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

Схемы работы с отдельными операциями списаний и зачислений при работе через 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-запрос должен отправляться к одной из следующих конечных точек:
   • при передаче реквизитов карты в явном виде — к /v2/payment/card/sale;
   • при передаче идентификаторов сохранённых данных — к /v2/payment/card/sale/saved;
   • при передаче токенов сохранённых данных — к /v2/payment/card/sale/token;
   • при использовании методов Apple Pay и Google Pay — к /v2/payment/applepay/sale и /v2/payment/googlepay/sale cоответственно.
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-запрос должен отправляться к одной из следующих конечных точек:
   • при передаче реквизитов карты в явном виде — к /v2/payment/card/payout;
   • при передаче токенов сохранённых данных — к /v2/payment/card/payout/token.
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" 
  }
}