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

Общая информация

В рамках платёжной платформы оплаты в одну стадию проводятся в соответствии с моделью проведения платежей (Разовая оплата в одну стадию).

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

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

Схема проведения

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

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

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

Рис.: Проведение оплаты в одну стадию в базовом случае

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

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

Формат запросов

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

  1. POST-запрос должен отправляться к одной из следующих конечных точек:
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта мерчанта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
    • customer — объект, содержащий сведения о пользователе:
      • ip_address — IP-адрес пользователя;
      • id — идентификатор пользователя в рамках проекта мерчанта;
    • 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. В зависимости от специфических региональных требований, а также от требований провайдеров и платёжных систем, в запросе может понадобиться указать дополнительные сведения о пользователе:
    • first_name — имя пользователя;
    • last_name — фамилия;
    • middle_name — отчество или среднее имя;
    • day_of_birth — дата рождения;
    • phone — номер телефона с кодом страны;
    • email — адрес электронной почты;
    • zip — почтовый индекс адреса проживания;
    • address — адрес проживания (улица, номер дома);
    • city — город проживания (или иной населенный пункт);
    • district — округ (район, область и т.д.) проживания;
    • state — регион проживания (штат, графство, кантон и т.д.);
    • avs_post_code — почтовый индекс, зафиксированный эмитентом как актуальный для пользователя;
    • avs_street_address — улица и номер дома, зафиксированные эмитентом как актуальные для пользователя.

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

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

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

{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "ip_address": "248.121.176.220"
  }
    "payment": {
      "amount": 400000,
      "currency": "USD"
  },
//при передаче реквизитов карты в явном виде:
    "card": {
      "pan": "4242424242424243",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

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

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

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

В зависимости от платёжной системы, обрабатывающей платёж, для завершения оплаты может потребоваться перенаправление пользователя от веб-сервиса на сайт платёжной системы. Для этого необходимо принять оповещение от платёжной платформы 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..."
                    }

Формат оповещений

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

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

Рис.: Пример данных о проведённой оплате в одну стадию

{
    "account": {
        "number": "424242******4243",
        "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...=="
}

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

Рис.: Пример данных об отказе в проведении оплаты в одну стадию

{
    "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": "424242******4243",
        "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...=="
}