# Оплата в одну стадию {#ru_gate_payment_sale}

статья о порядке проведения через Gate разовых одностадийных оплат с незамедлительными списаниями

**Прим.:** Эта статья посвящена тому, как проводить разовые оплаты в одну стадию через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт.

Помимо этой статьи для работы с разовыми оплатами в одну стадию могут быть полезны:

-   статья [Разовая оплата в одну стадию](ru_platform_sms_model.md) модели проведения платежей с описанием того, как в целом проводятся разовые оплаты в одну стадию в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций;
-   статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводить разовые оплаты в одну стадию через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом.

**На уровень выше:**[Разовые оплаты](ru_Gate_purchase.md)

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

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

-   *Реквизиты \(в явном виде\)*. Это базовая форма, при использовании которой необходимо обеспечить предоставление реквизитов пользователем, а затем передать эти реквизиты в платёжную платформу в запросе на проведение платежа.Это касается и так называемых оплат Mail Order/Telephone Order \(MO/TO\), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. Подробная информация об оплатах MO/TO представлена в разделе [Проведение оплат MO/TO](ru_Gate_moto.md).
-   *Идентификатор реквизитов*. В этом случае со стороны веб-сервиса передаётся идентификатор, однозначно ассоциированный с реквизитами платёжного инструмента на стороне платёжной платформы \(подробнее — в разделе [Сохранение платёжных данных](ru_gate_saved_data.md)\).
-   *Токен реквизитов*. В отличие от базового способа, вместо полных реквизитов передаётся токен. Для использования этого способа необходимо провести первоначальный платёж. Подробная информация об использовании токена представлена в разделе [Использование токенов](ru_Gate_Token.md).

## Схема проведения {#ru_gate_payment_sale_workflow}

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

1.  Отправить запрос к конечной точке `/v2/payment/\{название метода\}/sale[/форма указания реквизитов платёжного инструмента]`.
2.  При необходимости выполнить вспомогательные процедуры, инициируемые со стороны платёжной платформы. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже.
    -   *Аутентификация 3‑D Secure*. Такая аутентификация предназначена для обеспечения безопасности проведения оплаты с использованием платёжных карт через интернет. Подробная информация об этой процедуре представлена в разделе [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md#).
    -   *Аутентификация по инициативе мерчанта*. Такая аутентификация предназначена для обеспечения дополнительной безопасности оплаты с использованием платёжных карт. Подробная информация об этой процедуре представлена в разделе [Аутентификация по инициативе мерчанта](ru_gate_payment_merch_auth.md).
    -   *Дополнение информации о платеже*. Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md).
3.  Принять от платёжной платформы оповещение о результате оплаты.
4.  При необходимости для проведённых оплат использовать дополнительную возможность — возврат средств по проведённой оплате. Возврат используется в ситуациях, когда в рамках проведённой оплаты необходимо частично или полностью вернуть средства пользователю. Подробная информация о возвратах представлена в разделе [Возвраты средств после оплат](ru_Gate_Refund.md).

Схема проведения оплаты в одну стадию в базовом случае — без выполнения дополнительных процедур — представлена далее.

![](images/purchase_schemes/ru_gate_schema_sale.svg)

1.  Пользователь на стороне веб-сервиса инициирует оплату.
2.  От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты в одну стадию.
3.  Запрос на проведение оплаты в одну стадию поступает в платёжную платформу.
4.  В платёжной платформе выполняется приём запроса с проверкой его корректности.
5.  От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
6.  В платёжной платформе выполняется обработка этого запроса, его преобразование и отправка в платёжную систему в соответствии с протоколом взаимодействия с ней.
7.  В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту.
8.  На стороне эмитента выполняется обработка платежа и списание средств пользователя.
9.  От эмитента к платёжной системе направляется уведомление о результате оплаты.
10. От платёжной системы к платёжной платформе направляется уведомление о результате оплаты.
11. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
12. От веб-сервиса пользователю направляется результат оплаты.

Далее приведена информация о формате запросов и параметрах инициирования оплаты в одну стадию с использованием платёжных карт, а также о формате оповещений с результатами оплаты. Информацию о возможных статусах такой оплаты можно найти [в соответствующей статье](ru_platform_sms_model.md).

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

Формат запросов в этом разделе представлен для проведения оплат в одну стадию с использованием *платёжных карт*. При формировании запросов необходимо учитывать следующее:

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).
2.  В запросе должны использоваться следующие объекты и параметры:

    -   `general` — объект, содержащий основные идентификационные сведения запроса:
        -   `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции;
        -   `payment_id` — идентификатор платежа, уникальный в рамках проекта мерчанта;
        -   `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\);
    -   `customer` — объект, содержащий сведения о пользователе:
        -   `ip_address` — IP-адрес пользователя;
        -   `id` — идентификатор пользователя в рамках проекта мерчанта;
        -   `screen_res` — разрешение экрана устройства пользователя, в пикселях и с символом `x` в качестве разделителя \(например, `360x640`\);
        -   `email` — адрес электронной почты пользователя;
        -   `phone` — номер телефона пользователя;
    -   `payment` — объект, содержащий сведения о платеже:
        -   `amount` — сумма платежа в дробных единицах валюты;
        -   `currency` — валюта платежа в формате ISO-4217 alpha-3.
    **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача объекта `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_gate_additional_data.md#)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md#)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922.

3.  В запросе должны содержаться сведения о платёжной карте пользователя:
    -   при передаче реквизитов карты в явном виде — следующие данные в объекте `card`:
        -   `pan` — номер карты;
        -   `year` — порядковый номер года, в котором заканчивается срок действия карты \(в четырёхзначном формате `YYYY` по григорианскому календарю\);
        -   `month` — порядковый номер месяца, в котором заканчивается срок действия карты \(в виде числа, без ведущего нуля\);
        -   `card_holder` — имя держателя карты, если этот параметр обязателен для используемого проекта \(это имя должно указываться в соответствии с написанием на карте, а исключить его из числа обязательных параметров можно только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков\);
        -   `cvv` — код проверки подлинности карты \(в соответствии с указанным на карте\); при проведении MO/TO оплат данный параметр необязателен, подробнее — в разделе [Проведение оплат MO/TO](ru_Gate_moto.md);
    -   при передаче идентификатора — идентификатор, ассоциированный с реквизитами карты в платёжной платформе, и код проверки подлинности карты в параметрах `saved_account_id` и `cvv`;
    -   при передаче токена — токен и код проверки подлинности карты в параметрах `token` и `cvv`.
4.  В запросе должен содержаться объект `return_url` с адресами для перенаправления пользователя к веб-сервису:
    -   `success` — URL для перенаправления после завершения платежа;
    -   `decline` — URL для перенаправления после отклонения платежа.
5.  В зависимости от специфических региональных требований, а также от требований провайдеров и платёжных систем, в запросе может понадобиться указать дополнительные сведения о пользователе:

    -   `first_name` — имя пользователя;
    -   `last_name` — фамилия;
    -   `middle_name` — отчество или среднее имя;
    -   `day_of_birth` — дата рождения;
    -   `phone` — номер телефона с кодом страны;
    -   `email` — адрес электронной почты;
    -   `zip` — почтовый индекс адреса проживания;
    -   `address` — адрес проживания \(улица, номер дома\);
    -   `city` — город проживания \(или иной населенный пункт\);
    -   `district` — округ \(район, область и т.д.\) проживания;
    -   `state` — регион проживания \(штат, графство, кантон и т.д.\);
    -   `avs_post_code` — почтовый индекс, зафиксированный эмитентом как актуальный для пользователя;
    -   `avs_street_address` — улица и номер дома, зафиксированные эмитентом как актуальные для пользователя.
    Для получения информации о наборе сведений, требуемом в каждом конкретном случае, следует обращаться к курирующему менеджеру Ecommpay. Если необходимые сведения не были переданы в запросе, со стороны веб-сервиса потребуется выполнить процедуру [дополнения информации о платеже](ru_Gate_Clarification.md).

6.  Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

```language-json
{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "ip_address": "248.121.176.220",
      "id": "customer_12",
      "screen\_res": "360x640",
      "phone": "44991234567",
      "email": "john\_smith@email.com"
  },
    "payment": {
      "amount": 400000,
      "currency": "USD"
  },
    "return_url": {
      "success": "https://example.com/success",
      "decline": "https://example.com/decline"
  },

//при передаче реквизитов карты в явном виде:
    "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

//при передаче идентификатора ранее сохранённой платёжной карты:
    "saved_account_id": 2345678,
    "cvv": "123"

//при передаче токена ранее сохранённой платёжной карты:
    "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
    "cvv": "123"   
}
```

## Формат данных для перенаправления пользователей {#ru_gate_payment_sale_redirect_form}

В зависимости от платёжной системы, обрабатывающей платёж, для завершения оплаты может потребоваться перенаправление пользователя от веб-сервиса на сайт платёжной системы. Для этого необходимо принять оповещение от платёжной платформы Ecommpay, содержащее объект `redirect_data` с параметрами:

-   `redirect_data.url` — ссылка для перенаправления пользователя,
-   `redirect_data.body` — данные для отправки запроса \(может быть пустым\),
-   `redirect_data.method` — метод отправки запроса.

Далее приведён пример оповещения, содержащего данные для перенаправления. Данное оповещение отправляется от платёжной платформы Ecommpay на URL, указанный в настройках проекта мерчанта. В таком случае платеж находится в статусе `awaiting redirect result` до момента завершения оплаты со стороны пользователя.

```
    "type": "redirect",
                "code": "0",
                "operation_id": 64897000022161,
                "request_type": "purchase",
                "redirect_data": {
                    "body": {
                    },
                    "method": "POST",
                    "url": "https://payment.asiapaygateway.com/payment/DirectInterface",
                    "encrypted": {
                        "key": 3,
                        "message": "d4d9aa52891d0a59c40069bae69b57e872d0e946b70c67860e9c3e3b182cf240033a..."
                    }
```

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

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

В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_12` была проведена оплата в одну стадию в размере `4 000,00 USD` с платёжной карты `№424242******4243`.

```language-json
{
    "account": {
        "number": "431422******0056",
        "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "id": 45678,
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "payment": {
        "date": "2019-01-11T13:02:42+0000",
        "id": "456789",
        "method": "card",
        "status": "success",
        "sum": {
            "amount": 400000,
            "currency": "USD"
        },
        "type": "purchase",
        "description": ""
    },
    "project_id": 42,
    "operation": {
        "id": 969000002636,
        "type": "sale",
        "status": "success",
        "date": "2019-01-11T13:02:42+0000",
        "created_date": "2019-01-11T13:01:45+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 400000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 400000,
            "currency": "USD"
        },
        "provider": {
            "id": 408,
            "payment_id": "330157196",
            "date": "2019-01-11T13:02:32+0000",
            "auth_code": "",
            "endpoint_id": "612266625"
        },
        "code": "0",
        "message": "Success",
        "eci": "07"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```

Далее представлен пример данных из оповещения с информацией об отказе в проведении оплаты. Оплата отклонена из-за ввода некорректных данных карты.

```language-json
{
    "project_id": 42,
    "payment": {
        "id": "456789",
        "type": "purchase",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "method": "card",
        "sum": {
            "amount": 400000,
            "currency": "USD"
        },
        "description": ""
    },
    "account": {
        "number": "431422******0056",
        "type": "visa",
        "card_holder": "JOHN SMITH",
        "expiry_month": "08",
        "expiry_year": "2025"
    },
    "customer": {
        "id": "customer_12",
        "phone": "44991234567"
    },
    "operation": {
        "id": 13300000004505,
        "type": "sale",
        "status": "decline",
        "date": "2019-01-11T14:11:33+0000",
        "created_date": "2019-01-11T14:11:00+0000",
        "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
        "sum_initial": {
            "amount": 400000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 400000,
            "currency": "USD"
        },
        "provider": {
            "id": 12,
            "payment_id": "48219213050",
            "auth_code": "",
            "endpoint_id": 12
        },
        "code": "10102",
        "message": "Incorrect data entered",
        "eci": "05"
    },
    "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```