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-адрес клиента. |
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
}
}
}