Платёжные транзакции

Прежде чем начать

Ваши запросы к API аутентифицируются с помощью токена доступа. Любой запрос без действительного токена доступа вернёт ошибку. Подробнее в разделе Аутентификация.

Базовый URL

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• Продакшн: https://transactions.transactional.unico.app/api/public/v1

Создание транзакции

POST /credit/transaction — создаёт новую транзакцию.

опасность

Чтобы обеспечить лучшую конверсию, создавайте транзакцию только после завершения любой предварительной аутентификации или валидации, которая могла бы завершить операцию до начала работы с Верификацией без предъявления карты.

опасность

Поле orderNumber должно быть заполнено уникальным номером заказа этой покупки в системе электронной коммерции — использование отдельного транзакционного идентификатора неверно. Повторное использование может привести к низкой конверсии (номер заказа помогает конечному пользователю завершить поток) и к ошибкам API, таким как replicated transaction, если используются одинаковые номер заказа, CPF, BIN и последние 4 цифры.

Заголовки

Заголовок	Значение
Authorization	Bearer {token} — действительный токен доступа.

Тело запроса

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "order-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/checkout/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 199.90,
  "mainContacts": [
    { "key": "phone", "value": "5543999999999" }
  ]
}

Поле	Тип	Обязательное	Описание
identity	object	да	Данные идентификации пользователя.
identity.key	string	да	Тип ключа идентификации пользователя. Рекомендуется cpf — более высокий процент конверсии.
identity.value	string	да	Значение ключа идентификации пользователя, без точек и дефисов.
orderNumber	string	да	Номер заказа, связанный с транзакцией. Используется как индекс в портале и как внешний ключ между вашей системой и Верификацией без предъявления карты.
company	string	да	Идентификатор компании, ответственной за транзакцию, предоставленный Unico.
redirectUrl	string	нет	URL для перенаправления пользователя после завершения транзакции (HTTPS-URL для веб или URL-схема для нативных мобильных приложений).
card	object	да	Информация о карте, использованной в транзакции.
card.binDigits	string	да	Первые 8 цифр карты.
card.lastDigits	string	да	Последние 4 цифры карты.
card.expirationDate	string	нет	Срок действия карты.
card.name	string	да	Имя держателя карты. Отправляйте его корректно, избегая проблем с кодировкой — эти данные используются в пользовательском опыте и коммуникации.
value	number	да	Общая сумма покупки.
mainContacts	array	нет	Список основных контактов (email и/или телефоны), используемых для уведомления пользователя, когда за уведомление отвечает Верификация без предъявления карты.
fallbackContacts	array	нет	Список резервных контактов, задействуемых, если попытки уведомления через основные контакты не удались.

200 OK

{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "processing",
  "link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-07-22T15:30:00Z"
}

Поле	Описание
id	Идентификатор созданной транзакции.
status	Текущий статус транзакции.
link	Ссылка, связанная с транзакцией.
token	Подписанный токен, содержащий параметры, необходимые для инициализации веб-SDK Верификации без предъявления карты.
expiresAt	Дата и время истечения срока действия транзакции, ISO 8601 (UTC).

предупреждение

Если проверки определяют, что биометрический захват не требуется, ответ будет иметь другой статус, и ссылка на захват не генерируется:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

Это происходит при использовании модулей Pre или Super Pre для Checkout, согласно Feature.

Об ответах с ошибками см. в разделе Ошибки — Создание транзакции.

Получение статуса транзакции

GET /credit/transactions/{transaction_id} — проверяет текущий статус конкретной транзакции.

Заголовки

Заголовок	Значение
Authorization	Bearer {token} — действительный токен доступа.

200 OK

{
  "status": "processing"
}

Поле	Описание
status	Текущий статус транзакции.

См. Перечисления для всех возможных статусов. Для оптимизации производительности реализуйте Webhook вместо опроса (polling) этого эндпоинта.

Об ответах с ошибками см. в разделе Ошибки — Получение статуса транзакции.

Получение доказательного набора транзакции

GET /credit/transactions/{transaction_id}/probative — получает доказательный набор конкретной транзакции.

предупреждение

Доказательный набор может быть сформирован только для одобренных транзакций.

опасность

Ссылка, возвращаемая для доказательного набора, действительна в течение пяти минут с момента её получения — не сохраняйте её, а используйте немедленно для скачивания доказательного набора.

Заголовки

Заголовок	Значение
Authorization	Bearer {token} — действительный токен доступа.

200 OK

{
  "link": "https://unico.io/probative.pdf"
}

Поле	Описание
link	URL доказательного файла.

Об ответах с ошибками см. в разделе Ошибки — Получение доказательного набора транзакции.

Повторная отправка уведомления о транзакции

POST /credit/transactions/{transaction_id}/notify — повторно отправляет уведомления по email и/или телефону для конкретной транзакции.

примечание

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

Заголовки

Заголовок	Значение
Authorization	Bearer {token} — действительный токен доступа.

Тело запроса

{
  "phone": "NOTIFICATION_PHONE",
  "email": "NOTIFICATION_EMAIL"
}

Поле	Тип	Обязательное	Описание
phone	string	да	Номер телефона для отправки уведомления.
email	string	да	Адрес электронной почты для отправки уведомления.

200 OK

{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}

Поле	Описание
id	Уникальный идентификатор сгенерированного уведомления.
link	Сгенерированная ссылка для уведомления.

Об ответах с ошибками см. в разделе Ошибки — Повторная отправка уведомления о транзакции.