Запрос на взимание платы

Банки-эквайеры могут применять различные сценарии и типы транзакций при проведении оплаты по сохраненным картам для вашей схемы расчета. Это означает, что вам необходимо было бы внедрять разные типы запросов при работе с несколькими эквайерами или при смене одного эквайера на другого.

Overpay предлагает использовать единый запрос на взимание платы, который позволяет унифицировать процесс по привязке карт и списанию платы с них в дальнейшем.

Когда система Overpay получает запрос на взимание платы, она автоматически преобразовывает такой запрос в платеж или авторизацию в зависимости от типа операции, поддерживаемого тем вашим эквайером, который будет обрабатывать транзакцию. Более того, если запрос на взимание платы был преобразован в запрос авторизации, система Overpay самостоятельно отправит запрос на списание средств.

В личном кабинете запрос на взимание платы будет отображен транзакцией того типа, в которую этот запрос был преобразован, т.е. либо оплатой, либо авторизацией и списанием.

Запрос

Отправьте POST запрос на https://gateway.overpay.io/services/credit_cards/charges со следующими параметрами:

Параметр	Тип	Описание
request	object
amount * обязательный	integer	Стоимость в минимальных денежных единицах (например, $32.45 должна быть отправлена как 3245).
currency * обязательный	string	Валюта в формате ISO-4217 (например USD).
description * обязательный	string(255)	Описание заказа.
tracking_id	string(255)	ID транзакции или заказа в вашей системе. Пожалуйста, используйте уникальное значение, чтобы получить актуальную информацию при запросе статуса транзакции. В противном случае вы получите массив данных по 10 последним транзакциям, найденным по указанному `tracking_id`.
expired_at	string	Время в формате ISO 8601, до которого должна быть завершена операция. По умолчанию - бессрочно. Формат: `YYYY-MM-DDThh:mm:ssTZD`, где YYYY – год (например 2019), MM – месяц (например 02), DD – день (например 09), hh – часы (например 18), mm – минуты (например 20), ss – секунды (например 45), TZD – часовой пояс (+hh:mm или –hh:mm), например +03:00 для Минска. Если в указанный момент платёж всё ещё не будет оплачен, он будет переведён в статус `expired`.
duplicate_check	boolean	`true` или `false`. Параметр управляет процессом проверки входящего запроса на уникальность. По умолчанию этот параметр имеет значение `true`, поэтому, если в течение 30 секунд придет запрос на оплату с одинаковыми значениями `amount` и `number` или `token`, то запрос будет отклонен.
dynamic_billing_descriptor	string	Динамический идентификатор платежа.
language	string	Язык вашей страницы оформления заказа. Также является языком текста уведомления покупателя о транзакции по электронной почте, если оно настроено. По умолчанию - `en`. Доступные значения параметра `language`.
notification_url	string	URL, на который будут приходить уведомления. Формат запроса уведомления аналогичен формату ответа транзакции.
verification_url	string	URL, на который будет приходить запрос на подтверждение транзакции. Формат запроса на подтверждение аналогичен формату ответа транзакции.
return_url * условно обязательный	string	URL на стороне торговца, на который Overpay будет перенаправлять клиента после завершения 3-D Secure проверки. Параметр обязателен, если 3-D Secure включен. Обратитесь к менеджеру за дополнительной информацией.
test	boolean	`true` или `false`. Транзакция будет тестовой, если установлено значение `true`.
credit_card	object	Секция реквизитов карты.
number * обязательный	string	Номер карты, длина - от 12 до 19 цифр.
verification_value	string	3-х или 4-х цифровой код безопасности (CVC2, CVV2 или CID в зависимости от бренда карты). Может быть отправлен вместе с параметром `token`, и Overpay передаст банку-эквайеру данные карты с CVC2/CVV2/CID.
holder * обязательный	string	Имя держателя карты. Максимальная длина - 32 символа.
exp_month * обязательный	integer	Месяц окончания срока действия карты, представленный двумя цифрами (например, 01).
exp_year * обязательный	integer	Год срока окончания действия карты, представленный четырьмя цифрами (например, 2027).
token * условно обязательный	string	Токен карты, полученный ранее. Обязателен, если не передаете реквизиты карты. Если используется токен карты, то необходимо обязательно указывать параметр `additional_data.contract`.
skip_three_d_secure_verification	boolean	Параметр используется, если вы хотите, чтобы клиент не проходил авторизацию по протоколу 3-D Secure. Уточните у службы технической поддержки, можете ли вы использовать этот параметр. Если значение параметра - `true`, Overpay не применяет 3-D Secure проверку к запросу на взимание платы, когда передан токен карты. По умолчанию, установлено значение `false`. Параметр `force_three_d_secure_verification` имеет больший приоритет, чем параметр `skip_three_d_secure_verification`, когда оба переданы со значением `true`.
force_three_d_secure_verification	boolean	Параметр используется, если вы хотите, чтобы клиент проходил авторизацию по протоколу 3-D Secure. Уточните у службы технической поддержки, можете ли вы использовать этот параметр. Если значение параметра - `true`, Overpay принудительно применяет 3-D Secure проверку к запросу на взимание платы, когда передан токен карты. По умолчанию, установлено значение `false`. Параметр `force_three_d_secure_verification` имеет больший приоритет, чем параметр `skip_three_d_secure_verification`, когда оба переданы со значением `true`.
additional_data	object	Секция, содержащая дополнительную информацию о платеже. Уточните у службы поддержки, требуется ли вам передавать эти данные.
referer	string	URL ресурса, с которого осуществляется запрос на проведение транзакции.
p2p	object	Секция для работы с AFT операциями.
service_id * условно обязательный	string	Значение параметра уточните у вашего менеджера.
service_extension * условно обязательный	string	Значение параметра уточните у вашего менеджера.
excluded_gateways	array	Массив для работы с каскадными платежами.
masterpass	object	Секция для работы с сервисом Masterpass.
params	object	Секция для параметров Masterpass.
session	string	ID пользовательской сессии.
receipt_text	array	Текст, который будет добавлен в письмо клиенту. Должен быть представлен как массив строк, например `["Первая строка", "Вторая строка"]`.
contract	array	Массив, элементами которого могут быть параметры: `recurring` - Overpay вернет токен карты для осуществления последующих платежей без повторного ввода реквизитов карты. Клиент указывает полные данные карты, включая проверочный код карты CVC/CVV, и проходит авторизацию по протоколу 3-D Secure только при проведении первоначального платежа; `oneclick` - Overpay вернет токен карты для осуществления последующих платежей по схеме oneclick, когда на странице оплаты будут уже частично заполнены реквизиты карты, а клиенту для завершения оплаты достаточно ввести проверочный код CVC/CVV и пройти авторизацию по протоколу 3-D Secure; `credit` - Overpay вернет токен карты для осуществления операций выплаты средств; `card_on_file` - Overpay вернет токен карты, чтобы сохранить его в учетной записи клиента на вашем сайте или в приложении и использовать этот токен для последующих платежей. Ознакомьтесь ниже с секцией `card_on_file`, чтобы узнать сценарии использования данного значения. Внимание! Опция `card_on_file` поддерживается не всеми эквайерами. Если вы хотите ее использовать, свяжитесь со своим аккаунт менеджером.
avs_cvc_verification	object	AVS/CVC проверка.
card_on_file	object	Секция атрибутов операции, которые будут отправлены в дальнейшем в платёжную систему. Если секция не передана, то для параметров `initiator` и `type` будут использованы значения по умолчанию.
initiator	string	Возможные значения: `merchant` (по умолчанию) - операция инициирована вашей системой или приложением, от клиента не требуется дополнительных действий (например, автоматическое списание с карты клиента стоимости поездки в такси после ее завершения); `customer` - операция инициирована клиентом, клиенту необходимо подтвердить проведение платежа (например, при размещении заказа клиент выбирает опцию оплаты сохраненной картой).
type	string	Используется, только если параметр `additional_data.card_on_file.initiator` имеет значение `merchant`. `delayed_charge` (по умолчанию) - отложенная оплата (например, за оказанную услугу); `increment` - досписание суммы (например, при допродаже товара или замене на более дорогой товар); `resubmission` - повторная попытка списать деньги из-за предыдущего отказа в операции (например, не было денег на карте); `reauthorization` - обновление авторизации (например, нужно повторно зарезервировать средства на карте в связи с истечением срока авторизации предыдущей операции); `no_show` - проведение штрафного списания, если клиент не воспользовался услугой или товаром (например, не заехал в отель).
browser	object	Секция параметров браузера клиента. Параметры из секции передаются только при использовании протокола 3-D Secure 2.0.
accept_header	integer	Содержание HTTP-заголовка `Accept` запроса от браузера клиента.
screen_width	integer	Ширина экрана в пикселях. Соответствует параметру `screen.width` из JavaScript
screen_height	integer	Высота экрана в пикселях. Соответствует параметру `screen.height` из JavaScript
screen_color_depth	integer	Глубина цвета экрана в битах на пиксель. Соответствует параметру `screen.colorDepth` из JavaScript. Возможные значения: `1` - 1 bit `4` - 4 bits `8` - 8 bits `15` - 15 bits `16` - 16 bits `24` - 24 bits `32` - 32 bits `48` - 48 bits
window_width	integer	Размер окна браузера по горизонтали в пикселях. Соответствует параметру `document.body.clientWidth` из JavaScript.
window_height	integer	Размер окна браузера по вертикали в пикселях. Соответствует параметру `document.body.clientHeight` из JavaScript.
language	string	Язык навигатора. Соответствует параметру `navigator.language` из JavaScript.
java_enabled	boolean	Параметр показывает, включен ли java в текущем браузере или нет. Соответствует параметру `navigator.javaEnabled()` из JavaScript.
user_agent	string	Строка агента пользователя текущего браузера. Соответствует параметру `navigator.userAgent` из JavaScript.
time_zone	integer	Смещение часового пояса относительно часового пояса UTC в минутах для текущей локали. Соответствует параметру `new Date().getTimezoneOffset()` из JavaScript.
time_zone_name	string	Название часового пояса. Соответствует параметру `Intl.DateTimeFormat().resolvedOptions().timeZone` из JavaScript.
customer * условно обязательный	object	Секция информации о покупателе. Уточните у Службы технической поддержки, необходимо ли передавать параметры данной секции.
ip	string	IP-адрес клиента, производящего оплату на вашем сайте или в приложении.
email	string	Электронная почта клиента, производящего оплату на вашем сайте или в приложении.
device_id	string	ID устройства клиента, производящего оплату на вашем сайте или в приложении.
birth_date	string	Дата рождения клиента в формате ISO 8601 `YYYY-MM-DD`.
taxpayer_id	string	Идентификационный номер налогоплательщика (ИНН), присвоенный клиенту.
billing_address	object	Секция данных имени и адреса клиента. Уточните у службы поддержки, требуется ли вам передавать параметры этой секции.
first_name	string	Имя клиента. Максимальная длина - 30 символов.
last_name	string	Фамилия клиента. Максимальная длина - 30 символов.
country	string	Страна клиента в ISO 3166-1 alpha-2 формате.
city	string	Город клиента. Максимальная длина - 60 символов.
state	string	Двухбуквенная аббревиатура штата, если страна клиента - `US` или `CA`.
zip	string	Почтовый индекс клиента. Если страна клиента - `US`, формат `почтового индекса` должен иметь вид NNNNN или NNNNN-NNNN.
address	string	Адрес клиента. Максимальная длина - 255 символов.
phone	string	Номер телефона клиента. Максимальная длина - 100 символов.
travel	object	Секция расширенной информации о продаже авиабилетов, туристических путевок и т.д.
airline	object	Секция расширенной информации о проданном авиабилете.
agency_code	string	IATA код агентства (например, `03`).
agency_name	string	Название агентства, продавшего билет (например, `Coral travel`).
ticket_number	string	14-значный номер билета. Должен содержать 3-значный код билета, 4-значный номер формы, 6-значный серийный номер и контрольное число (например, `390 5241 025377 1`).
booking_number	string	Код брони (например, `DKZVUA`).
restricted_ticked_indicator	string	Информация о возврате билета. `0` - если билет можно вернуть. `1` - если билет вернуть нельзя.
legs	array	Список перелетов, каждый элемент которого состоит из:
airline_code	string	2-символьный IATA код авиакомпании (например, `B2`).
stop_over_code	string	IATA код длительности пересадки. Если пересадка больше 24 часов, то значение параметра `O` или пусто. Если аэропорт является транзитным, то значение параметра `X`.
flight_number	string	Номер рейса (например, `A3 971`).
departure_date_time	string	Время и дата вылета (например, `2014-05-26T05:15:00`).
arrival_date_time	string	Время и дата прибытия, например `2014-05-26T07:30:00`.
originating_country	string	Страна вылета (например, `RU`).
originating_city	string	Город вылета (например, `Moscow`).
originating_airport_code	string	3-значный код аэропорта вылета (например, `DME`).
destination_country	string	Страна прилета (например, `Greece`).
destination_city	string	Город прилета (например, `Athens`).
destination_airport_code	string	3-значный код аэропорта прилета (например, `ATH`).
coupon	string	Номер скидочного купона, если он был применен.
class	string	Класс полета, 1-значный IATA код (например, `C`).
passengers	array	Список пассажиров, каждый элемент которого состоит из:
first_name	string	Имя пассажира (например, `KONSTANTIN`).
last_name	string	Фамилия пассажира (например, `IVANOV`).

Пример запроса

{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction",
    "tracking_id": "tracking_id_000",
    "credit_card": {
      "number": "5204240000015003",
      "verification_value": "123",
      "holder": "John Doe",
      "exp_month": 10,
      "exp_year": 2027
    },
    "additional_data": {
      "browser": {
        "screen_width": 1920,
        "screen_height": 1080,
        "screen_color_depth": 24,
        "language": "en",
        "java_enabled": false,
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
        "time_zone": -180,
        "time_zone_name": "Europe/Vilnius",
        "accept_header": "*/*",
        "window_height": 667,
        "window_width": 600
      },
      "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    },
    "three_d_secure": {
      "advanced": false
    },
    "test": true
  }
}

Ответ

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

Параметр	Тип	Описание
type * обязательный	string	Тип транзакции, имеет значение `charge`
parent_uid * обязательный	string	ID транзакции списания средств, если общий запрос был преобразован в операции авторизации и списания. Совпадает со значением `uid`, если общий запрос был преобразован в операцию платежа.
redirect_url * обязательный	string	URL страницы для завершения транзакции. Если параметр `status` имеет значение `incomplete`, перенаправьте покупателя на этот URL для прохождения проверки 3-D Secure.
additional_data	object	Секция, содержащая дополнительную информацию о транзакции.
referer	string	URL ресурса, с которого осуществляется запрос на проведение транзакции.

Info

В настоящий момент, если вы указываете charge как значение параметра transaction_type при использовании платежного виджета Overpay, значения параметров rrn и bank_code в ответе на запрос могут отсутствовать.

Пример ответа на запрос на взимание платы

{
    "uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "parent_uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "status": "successful",
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "type": "charge",
    "payment_method_type": "credit_card",
    "tracking_id": "tracking_id_000",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2024-06-19T08:53:41.211Z",
    "updated_at": "2024-06-19T08:53:46.217Z",
    "paid_at": "2024-06-19T08:53:46.149Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://gateway.overpay.io/process/c74e1b00-9b94-4682-82c3-60167ce64841",
    "credit_card": {
        "holder": "John Doe",
        "stamp": "a282993adc1299dacc79248e77e04c2995f79fcc9f82f408bec59ba20ff55739",
        "brand": "master",
        "last_4": "5003",
        "first_1": "5",
        "bin": "520424",
        "bin_8": "52042400",
        "issuer_country": null,
        "issuer_name": null,
        "product": null,
        "exp_month": 10,
        "exp_year": 2027,
        "token_provider": null,
        "token": null
    },
    "status_code": null,
    "gateway": {
        "iframe": true
    },
    "mute_notifications": null,
    "id": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "additional_data": {
      "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    },
    "links": {
        "receipt_url": "https://backoffice.overpay.io/customer/transactions/c74e1b00-9b94-4682-82c3-60167ce64841/33724a6fe94fe937575c6ed18d2ab8abdc34732df17e51be6da88e9b37356101?language=en"
    },
    "code": "S.0000",
    "friendly_message": "The operation is successful.",
    "smart_routing_verification": {
        "status": "successful"
    },
    "charge": {
        "auth_code": "654321",
        "bank_code": "05",
        "rrn": "999",
        "ref_id": "777888",
        "message": "Payment was approved",
        "amount": 100,
        "currency": "USD",
        "billing_descriptor": "test descriptor",
        "gateway_id": 3483,
        "status": "successful"
    },
    "avs_cvc_verification": {
        "avs_verification": {
            "result_code": "1"
        },
        "cvc_verification": {
            "result_code": "1"
        }
    },
    "customer": {
        "ip": null,
        "email": null,
        "device_id": null,
        "birth_date": null,
        "taxpayer_id": null,
        "external_id": null,
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    },
    "billing_address": {
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    }
}