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

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

Ваши запросы к 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" }
  ],
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}

Поле	Тип	Обязательное	Описание
`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	нет	Список резервных контактов, задействуемых, если попытки уведомления через основные контакты не удались.
`additionalInfo`	object	нет	Отправьте этот объект с `externalUserID`, чтобы включить Тихую верификацию для этой транзакции.
`additionalInfo.externalUserID`	string	да (если отправлен `additionalInfo`)	Тот же идентификатор, который настроен через `externalUserId` SDK при сборе метаданных устройства. Требуется для запуска тихой валидации — без него транзакция создаётся в обычном режиме, но всегда следует стандартному визуальному потоку.

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.

примечание

Если был отправлен additionalInfo.externalUserID и транзакция одобрена в тихом режиме, ответ также не содержит ссылки на захват:

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

Полный процесс, включая настройку SDK и требования по времени, см. в разделе Тихая верификация.

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

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

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`	Сгенерированная ссылка для уведомления.

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

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

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

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

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

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

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

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

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

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

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