Удержание платежа

API Документация: удерживать создание, удерживать заряд и удерживать отклонение

Этот API позволяет вам временно заблокировать средства пользователя, а затем списать удержанную сумму.

• Hold Create резервирует указанную сумму на карте пользователя на ограниченный период времени.
• Hold Charge обрабатывает платеж, взимая полную или меньшую часть удержанной суммы.
• Удержание средств API позволяет отменить ранее созданное удержание средств пользователя. После отмены удержания зарезервированная сумма разблокируется, и в отношении этого удержания невозможно взимать дополнительные средства.

1. Удерживайте Создать

Метод: POST
URL: BASE_URL/merchant/payment/hold/create/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Тело запроса

Поле	Пример данных	Тип	Требуется	Описание
amount	1000	int	Да	Сумма в SUM (1000 = 1000 SUM)
userId	123	string	Нет	Пользователь ID заявлен мерчантом
account	{"field_name": "sample data"}	dict	Нет	Отправьте пустой dict {}, если нет дополнительных данных
cardId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Да	Карта ID создана в системе Paylov
time	10	int	Да	Время выдержки в минутах. Макс.: 40320 (28 дней)
externalId	externalId1	string	Нет	Внешний ID. Максимальная длина: 64 символа
serviceId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Нет	Предоставлено Платежной системой

{
  "userId": "string",
  "cardId": "string",
  "amount": 10,  # 10 = 10 Sum
  "account": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "time": 10,
  "externalId": "string", # max_chars: 64
  "serviceId": "uuid" 
}

Поле	Тип	Требуется	Описание
userId	string	Да	Уникальный идентификатор пользователя.
cardId	string	Да	Уникальный идентификатор карты, используемой в удержании.
amount	integer	Да	Сумма, которую необходимо удерживать. (сумма в сумме)
account	object	Нет	Содержит дополнительные свойства учетной записи.
account.additionalProp1	string	Необязательно	Данные пользовательского аккаунта.
account.additionalProp2	string	Необязательно	Данные пользовательского аккаунта.
account.additionalProp2	string	Необязательно	Данные пользовательского аккаунта.
time	integer	Да	Продолжительность удержания в минутах. Максимально допустимое значение — 28 дней (40320 минут).

Успешный ответ

{
  "result": {
    "transactionId": "uuid4"
  }
}

Поле	sample_data	Тип	Описание
transactionId	uuid4	string	Уникальный идентификатор пользователя.

2. Удержание заряда

Метод: POST
URL: /merchant/payment/hold/charge/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Тело запроса

{
  "transactionId": "string",
  "amount": 10
}

Поле	Тип	Требуется	Описание
transactionId	string	Да	Уникальный идентификатор пользователя.
amount	integer	Да	Сумма, которую необходимо снять с удержания.

Успешный ответ

{
  "result": {
    "transactionId": "string",
    "cardId": "string",
    "payedAt": "YYYY-MM-DD HH:mm:ss"
  }
}

Поле	Тип	Описание
transactionId	string	Уникальный идентификатор пользователя.
cardId	string	Карта, использованная для списания средств.
payedAt	string	Временная метка обработки платежа в формате YYYY-MM-DD HH:mm:ss.

3. Удержать Отпустить

Этот API полезен, когда зарезервированные средства должны быть снова доступны пользователю. Удерживаемые деньги будут доступны пользователю банковской карты.

Метод: POST
URL /merchant/payment/hold/dismiss/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Тело запроса

{
  "transactionId": "string"
}

Поле	Тип	Требуется	Описание
transactionId	string	Да	Уникальный идентификатор транзакции удержания, которую вы хотите отменить.

Успешный ответ

{
  "result": {
    "transactionId": "uuid",
    "status": "cancelled"
  }
}

Поле	Тип	Описание
transactionId	string (UUID)	Уникальный ID отмененной транзакции удержания.
status	string	Статус транзакции.

HOLD Статус

Метод: GET
Конечная точка: BASE_URL/merchant/payment/hold/status/
queryParams: externalId или transactionId

Пример запроса GET с внешним идентификатором

Метод: GET
URL: BASE_URL/merchant/payment/hold/status/?externalId=123
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Ответ

{
  "result": {
    "transactionId": "d1be13da-4355-4b27-956d-d83b87e013f1",
    "status": "cancelled",
    "cancelTime": "2025-02-03 11:13:42",
    "payedAt": null,
    "amount": 10,
    "serviceId": "d1be13da-4355-4b27-956d-d83b87e013f1"
  }
}

Статусы результатов

paid — успешная транзакция
cancelled - отмененная транзакция
hold — транзакция удержания, может взиматься плата, если время удержания не истекло
created

Структура ответа на ошибку

{
  "error": {
    "code": "hold_not_found",
    "message": "hold_not_found"
  }
}

Коды ошибок

hold_not_found
hold_time_expired
invalid_amount
field_not_valid
gateway_not_working
field_required
transaction_not_found