Использование сервисов 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;
     • cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжную систему Visa, и допускающий одно из следующих значений:
       • cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
       • stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
       • native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
       • other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
   • customer — объект, содержащий сведения об отправителе (пользователе):
     • id — идентификатор пользователя в рамках проекта;
     • ip_address — IP-адрес пользователя;
     • country — код страны пользователя в формате ISO 3166-1 alpha-2;
     • address — адрес проживания пользователя, обязательный при использовании карт Visa;
     • city — название города проживания (или иного населённого пункта) пользователя, обязательное при использовании карт Visa;
     • state — код штата или провинции пользователя, обязательный для случаев с последующим зачислением списываемых средств на карту 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 — имя и фамилия держателя карты (в соответствии с указанными на карте);
     • day_of_birth — дата рождения получателя в формате ДД-ММ-ГГГГ, обязательная при использовании карт Visa.
   • При передаче реквизитов карты 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;
     • cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжную систему Visa, и допускающий одно из следующих значений:
       • cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
       • stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
       • native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
       • other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
   • 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",
                    "day_of_birth":"20-08-1304"
                    },
                    "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" 
                        }
                    }