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

статья о возможности проводить денежные переводы между пользователями и мерчантами в рамках сервисов Mastercard MoneySend и Visa Direct при работе через Gate

**На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md)

## Общая информация {#ru_gate_money_transfer_services_overview}

В платёжной платформе 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.

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

### Общий порядок работы {#section_odv_vwj_5wb .section}

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

### Способы указания платёжных реквизитов {#section_t3p_2xj_5wb .section}

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

-   *Реквизиты* \(в явном виде\)— с указанием номера карты, срока её действия, держателя и кода проверки подлинности;
-   *Произвольный идентификатор реквизитов*— с указанием идентификатора, ранее ассоциированного в платёжной платформе с реквизитами используемой карты \([подробнее](ru_gate_saved_data.md)\);
-   *Стандартизированный токен реквизитов*— с указанием токена, ранее ассоциированного в платёжной платформе с реквизитами используемой карты \([подробнее](ru_Gate_Token.md)\).

### Списания {#section_ywd_pxj_5wb .section}

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

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

Формат запроса на списание описан [далее](ru_gate_money_transfer_services.md#section_s1y_31k_5wb), в разделе [Форматы запросов](ru_gate_money_transfer_services.md#) этой статьи.

### Отмены списаний {#section_apg_czj_5wb .section}

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

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

### Зачисления {#section_xgb_szj_5wb .section}

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

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

Формат запроса на зачисление описан [далее](ru_gate_money_transfer_services.md#section_fcv_3vk_5wb), в разделе [Форматы запросов](ru_gate_money_transfer_services.md#) этой статьи.

## Форматы запросов {#ru_gate_money_transfer_services_format_request}

### Запрос на списание {#section_s1y_31k_5wb .section}

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

1.  POST-запрос должен отправляться к одной из следующих конечных точек:
    -   при передаче реквизитов карты в явном виде — к [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale);
    -   при передаче идентификаторов сохранённых данных — к [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved);
    -   при передаче токенов сохранённых данных — к [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token);
    -   при использовании методов Apple Pay и Google Pay — к [/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale) и [/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale) cоответственно.
2.  В запросе должны использоваться следующие объекты и параметры:
    -   `general` — объект, содержащий основные идентификационные сведения запроса:
        -   `project_id` — идентификатор проекта, полученный от Ecommpay;
        -   `payment_id` — идентификатор платежа, уникальный в рамках проекта;
        -   `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\);
    -   `payment` — объект, содержащий сведения о списании:
        -   `amount` — сумма списания с платёжной карты отправителя \(пользователя\), в дробных единицах валюты;
        -   `currency` — код валюты списания в формате ISO-4217 alpha-3;
        -   `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и 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.
5.  В отдельных случаях должны указываться дополнительные сведения о получателе в объекте `recipient` \(в дополнение к реквизитам\):
    -   При передаче реквизитов карты Visa, выпущенной в Канаде:
        -   `country` — код страны получателя в формате ISO 3166-1 alpha-2;
        -   `city` — название города проживания \(или иного населённого пункта\) получателя;
        -   `state_code` — код штата или провинции получателя.
    -   При передаче реквизитов карты Visa, выпущенной в Австралии, Канаде или Новой Зеландии — адрес проживания получателя в параметре `address`.
6.  Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

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

```language-json
{
                    "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"
                        \}
                    }
```

### Запрос на зачисление {#section_fcv_3vk_5wb .section}

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

1.  POST-запрос должен отправляться к одной из следующих конечных точек:
    -   при передаче реквизитов карты в явном виде — к [/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout);
    -   при передаче токенов сохранённых данных — к [/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token).
2.  В запросе должны использоваться следующие объекты и параметры:
    -   `general` — объект, содержащий основные идентификационные сведения запроса:
        -   `project_id` — идентификатор проекта, полученный от Ecommpay;
        -   `payment_id` — идентификатор платежа, уникальный в рамках проекта;
        -   `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\);
    -   `payment` — объект, содержащий сведения о зачислении:
        -   `amount` — сумма зачисления на платёжную карту получателя в дробных единицах валюты;
        -   `currency` — код валюты зачисления в формате ISO-4217 alpha-3;
        -   `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и 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.

```language-json
{
                    "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" 
                        \}
                    }
```

## Формат оповещений {#ru_gate_money_transfer_services_format_callback}

Для оповещений о результате выполнения операций списания и зачисления в рамках использования сервисов Mastercard MoneySend и Visa Direct используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#).

```language-json
    {
        "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=="
    }
```

```language-json
    {
        "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=="
    }
```