Hold Payment

API Documentation: Hold Create & Hold Charge & Hold Dismiss

This API allows you to place a temporary hold on a user's funds and later charge the held amount.

• Hold Create reserves a specified amount on a user's card for a limited time.
• Hold Charge processes the payment by charging either the full or a smaller portion of the held amount.
• Hold Dismiss API allows you to cancel a previously created hold on a user's funds. Once a hold is dismissed, the reserved amount is released, and no further charges can be made against that hold.

1. Hold Create

Method: POST
URL: BASE_URL/payment/hold/create/

Request body

Field	Sample Data	Type	Required	Description
amount	1000	int	Yes	Amount in SUM (1000 = 1,000 SUM)
userId	123	string	No	User ID declared by the merchant
account	{"field_name": "sample data"}	dict	No	Send empty dict {} if no additional data
cardId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Yes	Card ID created in Paylov system
time	10	int	Yes	Hold time in minutes. Max: 40320 (28 days)
externalId	externalId1	string	No	External ID. Max length: 64 characters
serviceId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	No	Provided by the Payment System

{
  "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" 
}

Field	Type	Required	Description
userId	string	Yes	The unique identifier for the user.
cardId	string	Yes	The unique identifier for the card used in the hold.
amount	integer	Yes	The amount to be held. (amount in sum)
account	object	No	Contains additional properties for the account.
account.additionalProp1	string	Optional	Custom account data.
account.additionalProp2	string	Optional	Custom account data.
account.additionalProp2	string	Optional	Custom account data.
time	integer	Yes	The duration of the hold in minutes. The maximum allowed value is 28 days (40320 minutes).

Success response

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

Field	sample_data	Type	Description
transactionId	uuid4	string	The unique identifier for the user.

2. Hold Charge

Method: POST
URL: /payment/hold/charge/

Request body

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

Field	Type	Required	Description
transactionId	string	Yes	The unique identifier for the user.
amount	integer	Yes	The amount to charge from the hold.

Success Response

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

Field	Type	Description
transactionId	string	The unique identifier for the user.
cardId	string	The card used for the charge.
payedAt	string	The timestamp when the payment was processed, formatted as YYYY-MM-DD HH:mm:ss.

3. Hold Dismiss

This API is useful when the reserved funds should be made available to the user again. Held Money will be available user bank card.

Method: POST
URL /payment/hold/dismiss/

Request Body

{
  "transactionId": "string"
}

Field	Type	Required	Description
transactionId	string	Yes	The unique identifier for the hold transaction you wish to cancel.

Success response

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

Field	Type	Description
transactionId	string (UUID)	The unique ID of the dismissed hold transaction.
status	string	The status of the transaction.

HOLD Status

Method: GET
Endpoint: BASE_URL/merchant/payment/hold/status/
queryParams: externalId or transactionId

Example GET request with external id

Method: GET
URL: BASE_URL/merchant/payment/hold/status/?externalId=123

Response

{
  "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"
  }
}

Result statuses

paid - success transaction
cancelled - cancelled transaction
hold - hold transaction, can be charged if hold time have not been expired
created

Error response structure

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

Error codes

hold_not_found
 
hold_time_expired

invalid_amount

field_not_valid

gateway_not_working

field_required

transaction_not_found