Оплата в одну стадию

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

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

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

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

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

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

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

1. POST-запрос должен отправляться к одной из следующих конечных точек:
   • при передаче реквизитов карты в явном виде — к /v2/payment/card/sale;
   • при передаче идентификатора вместо реквизитов — к /v2/payment/card/sale/saved;
   • при передаче токена вместо реквизитов — к /v2/payment/card/sale/token.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта мерчанта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью);
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя;
     • id — идентификатор пользователя в рамках проекта мерчанта;
     • screen_res — разрешение экрана устройства пользователя, в пикселях и с символом x в качестве разделителя (например, 360x640);
     • email — адрес электронной почты пользователя;
     • phone — номер телефона пользователя;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;
     • currency — валюта платежа в формате ISO-4217 alpha-3.
3. В запросе должны содержаться сведения о платёжной карте пользователя:
   • при передаче реквизитов карты в явном виде — следующие данные в объекте card:
     • pan — номер карты,
     • year — год окончания срока действия карты,
     • month — месяц окончания срока действия карты,
     • card_holder — имя держателя карты (в соответствии с указанным на карте),
     • cvv — код проверки подлинности карты (в соответствии с указанным на карте); при проведении MO/TO оплат данный параметр необязателен, подробнее — в разделе Проведение оплат MO/TO;
   • при передаче идентификатора — идентификатор, ассоциированный с реквизитами карты в платёжной платформе, и код проверки подлинности карты в параметрах 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. Если необходимые сведения не были переданы в запросе, со стороны веб-сервиса потребуется выполнить процедуру дополнения информации о платеже.

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

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

{
  "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"   
}