Приём карт по H2H

Приём карточных платежей без платёжной формы: реквизиты карты шифруются на стороне плательщика и передаются в Platega одним зашифрованным конвертом.

Последовательность вызовов

POST /transaction/process — создать карточную транзакцию.

GET /h2h/card/encryption-key — получить публичный ключ шифрования.

Сформировать одноразовый compact JWE с реквизитами карты.

POST /h2h/{transactionId}/card — запустить оплату.

Обработать ответ по значению threeDsStep или redirectUrl.

Дождаться финального статуса через колбэк или GET /transaction/{transactionId}.

Авторизация

Заголовок	Значение	Где использовать
`X-MerchantId`	Идентификатор мерчанта, UUID	Во всех запросах
`X-Secret`	Секретный ключ мерчанта	Только на вашем сервере
`Content-Type`	`application/json`	Во всех POST-запросах

X-Secret передавать в браузер нельзя. Браузеру можно отдавать публичный ключ, transactionId и данные, необходимые для прохождения 3DS.

Шаг 1. Создать транзакцию

POST /transaction/process

Поле	Тип	Обяз.	Описание
`paymentMethod`	number	да	`11` — карта
`paymentDetails.amount`	number	да	Сумма платежа
`paymentDetails.currency`	string	да	Код валюты, например `RUB`
`description`	string	нет	Описание платежа
`return`	string	нет	Адрес возврата плательщика при успехе
`failedUrl`	string	нет	Адрес возврата плательщика при ошибке
`payload`	string	нет	Ваш идентификатор заказа или служебные данные
`metadata`	object	нет	Дополнительные данные заказа

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

{
  "paymentMethod": 11,
  "paymentDetails": {
    "amount": 1100,
    "currency": "RUB"
  },
  "description": "Заказ 123",
  "return": "https://merchant.example/success",
  "failedUrl": "https://merchant.example/fail",
  "payload": "order-123",
  "metadata": {
    "userId": "123456789",
    "userName": "@username"
  }
}

Пример ответа, 200

{
  "paymentMethod": "Card",
  "transactionId": "b168b4f5-e6fe-4a96-ae8d-82405617a277",
  "status": "PENDING",
  "expiresIn": "00:15:00"
}

Сохраните transactionId. Поле redirect из ответа в этом сценарии не открывайте: дальше вызываются эндпоинты H2H.

Шаг 2. Получить ключ шифрования

GET /h2h/card/encryption-key

Ключ выдаётся отдельно для каждого мерчанта и периодически обновляется. Запрашивайте его перед формированием конверта и не кэшируйте дольше, чем указано в заголовке Cache-Control.

Пример ответа, 200

{
  "kid": "a3f1c2d4e5b6",
  "kty": "RSA",
  "use": "enc",
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM",
  "typ": "platega-h2h-card+jwe",
  "n": "<модуль RSA в Base64URL>",
  "e": "AQAB",
  "activatedAt": "2026-10-01T10:00:00Z",
  "expiresAt": "2026-12-30T10:00:00Z",
  "envelopeTtlSeconds": 120
}

Шаг 3. Зашифровать карту

Сформируйте compact JWE из пяти сегментов Base64URL, разделённых точкой.

Часть JWE	Содержимое
Защищённый заголовок	Ровно четыре поля: `alg`, `enc`, `kid`, `typ` — со значениями из ответа предыдущего шага
Полезная нагрузка	`v`, `merchantId`, `transactionId`, `iat`, `exp`, `jti`, `card`
`card`	`pan`, `expMonth`, `expYear`, `cvv`

Полезная нагрузка до шифрования

{
  "v": 1,
  "merchantId": "8b2f1c3a-0d4e-4f51-9a62-7c8d9e0f1a2b",
  "transactionId": "b168b4f5-e6fe-4a96-ae8d-82405617a277",
  "iat": 1785141000,
  "exp": 1785141090,
  "jti": "b8d872f8-e0db-4c0d-90cf-d89e601b7f92",
  "card": {
    "pan": "4111111111111111",
    "expMonth": "12",
    "expYear": "29",
    "cvv": "123"
  }
}

Ограничения:

v всегда равно 1;

merchantId и transactionId в нагрузке должны совпадать с теми, по которым выполняется запрос;

конверт одноразовый, jti — от 16 до 128 символов Base64URL, новый для каждого запроса;

разница exp и iat не должна превышать envelopeTtlSeconds;

pan — от 13 до 19 цифр, проходит проверку по алгоритму Луна;

expMonth — от 01 до 12, expYear — в формате YY или YYYY, срок действия не истёк;

cvv — 3 или 4 цифры;

имя держателя, IP и данные браузера не передаются.

Шаг 4. Отправить карту

POST /h2h/{transactionId}/card

{
  "card": {
    "encryptedData": "<compact JWE>"
  }
}

Разберите ответ и выполните ровно одну подходящую ветку.

Что вернул эндпоинт	Что видит плательщик	Что делает мерчант
`threeDsStep` = `method`	Ничего, шаг проходит в скрытом фрейме	Создать скрытую форму и методом POST отправить `formParameters` на `threeDsData.url`. После загрузки фрейма или через 10 секунд вызвать `/h2h/{transactionId}/card/3ds/complete`, передав `continuationParameters`
`threeDsStep` = `challenge`	Страницу подтверждения банка	Открыть видимый фрейм или окно и методом POST отправить `formParameters` на `threeDsData.url`. `/3ds/complete` не вызывать, ждать колбэк или проверять статус
`threeDsStep` = `complete`	Ничего	Ничего не открывать и `/3ds/complete` не вызывать. Ждать колбэк или проверять статус
`redirectUrl`	Внешнюю страницу оплаты	Перенаправить плательщика на `redirectUrl`. `/3ds/complete` не вызывать, ждать колбэк или проверять статус

Отправка формы: создайте форму с методом POST и адресом threeDsData.url, добавьте по скрытому полю на каждую пару из formParameters с тем же именем и значением, затем отправьте её. Имена параметров не фиксируйте в коде — передавайте весь словарь целиком.

На threeDsData.url отправляются только formParameters. continuationParameters остаются на вашем сервере и на этот адрес не отправляются.

Пример ответа с шагом method, 200

{
  "id": "b168b4f5-e6fe-4a96-ae8d-82405617a277",
  "status": "PENDING",
  "threeDsStep": "method",
  "threeDsData": {
    "url": "https://example.com/3ds/method",
    "method": "POST",
    "formParameters": {
      "threeDSMethodData": "..."
    },
    "continuationParameters": {
      "gatewaySessionId": "...",
      "threeDSMethodData": "...",
      "bankOperationId": "..."
    }
  }
}

Шаг 5. Завершить шаг method

Вызывается только если на предыдущем шаге пришло threeDsStep = method.

POST /h2h/{transactionId}/card/3ds/complete

Тело запроса — continuationParameters из предыдущего ответа без изменений.

{
  "gatewaySessionId": "...",
  "threeDSMethodData": "...",
  "bankOperationId": "..."
}

Ответ с шагом challenge, 200

{
  "threeDsStep": "challenge",
  "threeDsData": {
    "url": "https://example.com/3ds/challenge",
    "method": "POST",
    "formParameters": {
      "creq": "...",
      "threeDSSessionData": "..."
    }
  }
}

Покажите плательщику страницу подтверждения и передайте весь словарь formParameters методом POST на threeDsData.url. После этого /3ds/complete повторно не вызывается — ждите колбэк или проверяйте статус транзакции.

Ответ с шагом complete, 200

{
  "threeDsStep": "complete"
}

Ничего не открывайте и повторно /3ds/complete не вызывайте. Переходите к проверке финального статуса.

Проверка перед запуском

Все обращения к Platega с X-Secret выполняются только с вашего сервера.

Браузер получает только публичный ключ и шифрует карту до отправки.

Каждый конверт имеет новый jti и создаётся непосредственно перед вызовом /h2h/{transactionId}/card.

Для шага method отправляются только formParameters, затем вызывается /3ds/complete.

Для шага challenge /3ds/complete повторно не вызывается.

Заказ подтверждается только по финальному статусу транзакции.

Приём карт по H2H

Последовательность вызовов#

Авторизация#

Шаг 1. Создать транзакцию#

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

Пример ответа, 200#

Шаг 2. Получить ключ шифрования#

Пример ответа, 200#

Шаг 3. Зашифровать карту#

Полезная нагрузка до шифрования#

Шаг 4. Отправить карту#

Пример ответа с шагом method, 200#

Шаг 5. Завершить шаг method#

Ответ с шагом challenge, 200#

Ответ с шагом complete, 200#

Проверка перед запуском#

Последовательность вызовов

Авторизация

Шаг 1. Создать транзакцию

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

Пример ответа, 200

Шаг 2. Получить ключ шифрования

Пример ответа, 200

Шаг 3. Зашифровать карту

Полезная нагрузка до шифрования

Шаг 4. Отправить карту

Пример ответа с шагом method, 200

Шаг 5. Завершить шаг method

Ответ с шагом challenge, 200

Ответ с шагом complete, 200

Проверка перед запуском