API версия 3

Общее описание

Чтобы предоставлять своим клиентам больше доступной информации о статусе обработки транзакции, сервис UnonaPay начал внедрение API версии 3 (API v.3). Основным отличием этой версии API системы от предыдущей является формат и параметры ответов на запросы и новые коды ошибок обработки транзакций. Коды ошибок обработки транзакции теперь также будут сопровождаться понятным текстовым описанием, что поможет понимать статус или причину ошибки обработки транзакции.

C 15 сентября 2022 API v.3 применяется для всех https://gateway.unonapay.com/- методов. В запросах к этой версии API следует только добавить заголовок X-API-Version: 3. Описание параметров и их значений приведено ниже на странице.

По всем вопросам, связанным со взаимодействием с UnonaPay API v.3, вы можете обращаться в Службу технической поддержки на support@unonapay.com.

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

Для отправки POST или GET запроса к API v.3 https://gateway.unonapay.com/-методов, добавьте к запросу заголовок X-API-Version: 3 или посылайте его вместо заголовка X-API-Version: 2, если такой требуется.

В теле запроса используйте параметры, описанные для требуемого метода. Дополнительных параметров для API v.3 передавать не требуется.

Формат ответов

Ответы от API v.3 системы содержат следующие параметры:

Параметр	Тип	Описание
uid	string	UID обработанной транзакции.
status	string	Статус обработанной транзакции.
code	string	Код обработанной транзакции.
friendly_message	string	Сообщение системы для покупателя.
message	string	Сообщение системы банка.
amount	integer	Сумма обработанной транзакции в минимальных денежных единицах. Например, USD 12.00 передается как `1200`.
currency	string	Валюта обработанной транзакции в формате ISO-4217, например `USD`.
description	string	Описание обработанной транзакции.
type	string	Тип обработанной транзакции.
tracking_id	string	Устанавливается в значении параметра `tracking_id` из запроса.
test	boolean	Устанавливается в значении `true`, если транзакция была обработана как тестовая.
created_at	string	Дата и время создания транзакции в формате ISO 8601 `YYYY-MM-DDThh:mm:ssTZD`.
updated_at	string	Дата и время последнего обновления транзакции в формате ISO 8601 `YYYY-MM-DDThh:mm:ssTZD`.
paid_at	string	Дата и время завершения транзакции в формате ISO 8601 `YYYY-MM-DDThh:mm:ssTZD`. Устанавливается в значении `null`, если транзакция имеет статус `incomplete`.
expired_at	string	Дата и время окончания периода для возможного проведения транзакции в формате ISO 8601 `YYYY-MM-DDThh:mm:ssTZD`, т.е. срока, до которого клиент может совершить платеж. Устанавливается в значении `null`, если параметр не применим к транзакции.
closed_at	string	Дата и время окончания банковского дня в формате ISO 8601 `YYYY-MM-DDThh:mm:ssTZD`. Устанавливается в значении `null`, если параметр не применим к транзакции.
settled_at	string	Дата и время перечисления суммы транзакции на счет торговца в формате ISO 8601 `YYYY-MM-DDThh:mm:ssTZD`. Устанавливается в значении `null`, если параметр не применим к транзакции.
manually_corrected_at	string	Дата и время ручной корректировки транзакции в формате ISO 8601 `YYYY-MM-DDThh:mm:ssTZD`. Устанавливается в значении `null`, если параметр не применим к транзакции.
redirect_url	string	URL страницы для завершения транзакции. Если параметр `status` имеет значение `incomplete`, необходимо перенаправить покупателя на этот URL для прохождения проверки 3-D Secure.
parent_uid	string	UID родительской транзакции, если требуется.
reason	string	Описание причины оспоренного платежа.
recurring_type	string	Тип транзакции по сохраненным данным карты. Устанавливается в значении `null`, если параметр не применим к транзакции.
language	string	Значение параметра `language` из запроса, или `en` по умолчанию.
status_code	integer	Код статуса проверки 3-D Secure. Устанавливается в значении `null`, если параметр не применим к транзакции.
errors	object	Секция данных и парамтеров ошибки обработки транзакции.
customer	object	Секция информации о покупателе.
ip	string	IP-адрес клиента.
email	string	Адрес электронной почты клиента.
device_id	string	ID устройства клиента.
birth_date	string	Дата рождения клиента.
first_name	string	Имя клиента.
last_name	string	Фамилия клиента.
address	string	Адрес клиента.
country	string	Страна клиента в формате ISO 3166-1 alpha-2.
city	string	Город клиента.
state	string	Двухбуквенный ккод штата клиента, если страна - `US` или `CA`.
zip	string	Индекс клиента. Если страна - `US`, то индекс должен быть представлен в формате NNNNN или NNNNN-NNNN.
phone	string	Номер телефона клиента.
payment_method	object	Секция параметров способа оплаты, использованного клиентом при проведении транзакции.
payment_method_type	string	Тип платежного метода.
holder	string	Имя владельца карты.
stamp	string	Хэш карты.
brand	string	Бренд карты.
last_4	string	Последние 4 цифры карты.
first_1	string	Первая цифра карты.
bin	string	BIN карты.
issuer_country	string	Страна банка-эмитента карты.
issuer_name	string	Название банка-эмитента карты.
product	string	Тип карточного продукта.
exp_month	integer	Месяц окончания срока действия карты, представленный двумя цифрами, например `01`.
exp_year	integer	Год окончания срока действия карты, представленный четырьмя цифрами, например, `2026`.
token_provider	string	Провайдер токена карты, если применяется.
token	string	Токен карты.
recipient	object	Секция данных получателя средств. Применяется к выплатам и P2P переводам средств от клиента к получателю.
customer	object	Секция персональных данных и данных адреса получателя средств.
first_name	string	Имя получателя.
last_name	string	Фамилия получателя.
address	string	Адрес получателя.
country	string	Страна получателя в формате ISO 3166-1 alpha-2.
city	string	Город получателя.
state	string	Двухбуквенный код штата получателя, если страна - `US` или `CA`.
zip	string	Индекс получателя. Если страна - `US`, то индекс должен быть представлен в формате NNNNN или NNNNN-NNNN.
phone	string	Номер телефона получателя.
payment_method	object	Секция параметров способа оплаты, использованного для получения выплаты или P2P перевода.
holder	string	Имя владельца карты-приемника средств.
stamp	string	Хэш карты-приемника средств.
brand	string	Бренд карты-приемника средств.
last_4	string	Последние 4 цифры карты-приемника средств.
first_1	string	Первая цифра карты-приемника средств.
bin	string	BIN карты-приемника средств.
issuer_country	string	Страна карты-приемника средств.
issuer_name	string	Название банка-эмитента карты-приемника средств.
product	string	Тип карты-приемника средств.
exp_month	integer	Месяц окончания срока действия карты-приемника средств, представленный двумя цифрами, например `01`.
exp_year	integer	Год окончания срока действия карты-приемника средств, представленный четырьмя цифрами, например, `2026`.
token	string	Токен карты-приемника средств.
token_provider	string	Провайдер токена карты-приемника средств, если применяется.
payment_method_type	string	Тип платежного метода, использованного для получения выплаты или P2P перевода.
smart_routing_verification	object	Секция параметров сервиса Smart Routing. Применяется, если сервис активирован.
status	string	Статус обработки транзакции сервисом.
three_d_secure_verification	object	Секция параметров проверки 3-D Secure.
additional_data	object	Секция дополнительных данных о транзакии.
browser	object	Секция данных браузера клиента.
contract	object	Секция параметров выдачи карточных токенов для платежей по сохраненным картам.
avs_cvc_verification	object	Секция проверки AVS/ CVC параметров.
avs_verification	object	Секция с результатом проверки AVS параметров.
result_code	string	Код результата проверки AVS параметров.
cvc_verification	object	Секция с результатом проверки CVC параметров.
result_code	string	Код результата проверки CVC параметров.
transaction	object	Секция данных о транзакции.
ref_id	string	Идентификационный номер транзакции в системе банка (reference ID).
message	string	Сообщение об обработке транзакции.
amount	integer	Сумма обработанной транзакции в минимальных денежных единицах.
currency	string	Валюта обработанной транзакции в формате ISO-4217, например `USD`.
billing_descriptor	string	Описание обработанной транзакции.
gateway_id	integer	ID платежного шлюза, через который транзакция была обработана в системе UnonaPay.
status	string	Статус обработанной транзакции.
auth_code	string	Код авторизации обработанной транзакции.
rrn	string	Номер транзакции в системе банка (Retrieval Reference Number).
bank_code	string	Код обработки транзакции в системе банка.
links	object	Секция ссылок.
receipt_url	string	URL на получение чека об обработанной транзакции.
bank_info	object	Секция параметров запроса баланса.

Если параметр не применим к транзакции, он будет установлен в значении null.

Коды обработки транзакций

Ответ по формату API v.3 обязательно содержит параметр code со значением в формате {Буквенный код}.{4 цифры кода ошибки}, где:

{Буквенный код} относится к статусу обработки транзакции;
{4 цифры кода ошибки} относится к коду ошибки того сервиса системы, который не смог успешно обработать транзакцию.

Буквенный код

Буквенный код API v.3	Статус API v2	Описание статуса
S	`sucсessful`	Транзакция была успешно обработана.
F	`failed`	Транзакция была отклонена по причине на стороне банка / провайдера интеграции.
P	`pending` `incomplete`	Транзакция все еще находится в обработке, или система ожидает действия клиента для завершения транзакции.
E	`error`	Ошибка обработки транзакции внутренними сервисами UnonaPay.

4 цифры кода ошибки

Диапазон кодов API v.3	Описание
0000	Операция успешна.
0001 - 0499	Коды ошибок валидации и обработки параметров карточных платежей.
0501 - 0999	Коды ошибок валидации и обработки параметров платежей альтернативными платежными методами.
1000 - 1999	Коды ошибок сервиса платежного шлюза.
2000 - 3999	Коды ошибок сервиса Smart Routing.
4000 - 4999	Коды ошибок сервиса проверки 3-D Secure.
6000 - 6999	Коды ошибок сервиса проверки AVS/ CVC.
7000 - 7999	Коды ошибок сервиса Verify.
8001	Код ошибки сервиса проверки P2P транзакций.
8010	Код ошибки сервиса платежного шлюза при работе в асинхронном режиме.
8011 - 9999	Коды ошибок банка.

Детальное описание всех кодов представлено в приложении Коды ошибок обработки транзакции API v.3.

Пример ответа по формату API v.3 на запрос проведения платежа

В примере транзакция имеет статус incomplete и код P.9998. С учетом того, что только секция three_d_secure_verification имеет статус incomplete, транзакция получила такой статус, т.к. система UnonaPay ожидает прохождения клиентом проверки 3-D Secure.

{
    "uid": "46154-aba1cf5e57",
    "code": "P.9998",
    "friendly_message": "Incomplete transaction",
    "status": "incomplete",
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "type": "payment",
    "payment_method": {
        "payment_method_type": "credit_card",
        "holder": "John Doe",
        "stamp": "5f854c844e3007f2ecff2aa614f6a4cc6b8a2c241aab3e5776fe7912dc7b9d92",
        "brand": "visa",
        "last_4": "0000",
        "first_1": "4",
        "bin": "420000",
        "issuer_country": "LT",
        "issuer_name": "VISA",
        "product": "VISA",
        "exp_month": 10,
        "exp_year": 2026,
        "token_provider": null,
        "token": "2efef4c9-d4de-4603-bc84-7a9bc5456939"
    },
    "tracking_id": "tracking_id_000",
    "message": null,
    "test": true,
    "created_at": "2022-09-15T08:43:56.521Z",
    "updated_at": "2022-09-15T08:43:57.943Z",
    "paid_at": null,
    "expired_at": null,
    "recurring_type": "initial",
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://gateway.unonapay.com/process/46154-aba1cf5e57",
    "status_code": 21,
    "links": {
        "receipt_url": "https://online.unonapay.com/customer/transactions/46154-aba1cf5e57/bbe9f4090e43351ca1ee724a202376cb24da3ffbfa86df30c80e95fb4fdee386?language=en"
    },
    "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
        },
        "contract": [
            "recurring"
        ]
    },
    "customer": {
        "ip": "127.0.0.1",
        "email": "john@example.com",
        "device_id": "12312312321fff67",
        "birth_date": "1980-01-31",
        "first_name": "John",
        "last_name": "Doe",
        "address": "1st Street",
        "country": "US",
        "city": "Denver",
        "zip": "96002",
        "state": "CO",
        "phone": null
    },
    "smart_routing_verification": {
        "status": "successful"            
    }, 
    "max_mind_verification": {
        "score": 45,
        "status": "successful",
        "distance": null,
        "countryMatch": "No",
        "countryCode": null,
        "freeMail": "No",
        "anonymousProxy": "No",
        "binMatch": "No",
        "binCountry": "RU",
        "err": "IP_NOT_FOUND",
        "proxyScore": "0.00",
        "ip_region": null,
        "ip_city": null,
        "ip_latitude": null,
        "ip_longitude": null,
        "binName": null,
        "ip_isp": null,
        "ip_org": null,
        "binNameMatch": "NA",
        "binPhoneMatch": "NA",
        "binPhone": null,
        "custPhoneInBillingLoc": "NotFound",
        "highRiskCountry": "No",
        "queriesRemaining": "14286",
        "cityPostalMatch": "No",
        "shipCityPostalMatch": null,            
        "carderEmail": "No"
    },
    "three_d_secure_verification": {
        "status": "incomplete",
        "message": "Authentication Available",
        "ve_status": "Y",
        "acs_url": null,
        "pa_req": null,
        "md": null,
        "pa_res_url": "https://gateway.unonapay.com/process/46154-aba1cf5e57",
        "eci": null,
        "pa_status": null,
        "xid": null,
        "cavv": null,
        "cavv_algorithm": null,
        "fail_reason": null,
        "method_process_url": "https://gateway.unonapay.com/api/v1/transactions/bd79f747-a42f-4ee3-b993-069310ca8238/method-process",
        "creq": null
    },
    "transaction": {
        "auth_code": null,
        "bank_code": null,
        "rrn": null,
        "ref_id": null,
        "message": null,
        "amount": 100,
        "currency": "USD",
        "billing_descriptor": null,
        "gateway_id": 645,
        "status": "incomplete"
    },
    "avs_cvc_verification": {
        "avs_verification": {
            "result_code": null
        },
        "cvc_verification": {
            "result_code": null
        }
    }
}