Hold Form

A card-binding form using a hold (authorization hold) or card preauthorization followed by cancellation.

A card can be bound with a zero balance: to do this, pass amount equal to 0.

URL

Method: GET or POST

Production: https://customer.pay.kvell.group/bind/card/preauthorize
Stage: https://customer.stage.kvell.group/bind/card/preauthorize

Request parameters

Name	Data type	Required	Description
`api_key`	string	Yes	Unique shop identifier
`customer_key`	string	Yes	Customer identifier in the merchant's system
`transaction`	string	Yes	Unique transaction number on the merchant's side
`amount`	string	Yes	Amount in kopecks
`description`	string	Yes	Transaction description
`success_url`	string	Yes	Redirect link after a successful binding
`fail_url`	string	Yes	Redirect link after a binding error
`auto_return`	string	No	Automatic redirect to `success_url` or `fail_url` after payment. Specified in seconds. If a value greater than 0 is passed, the redirect happens after N seconds. If the value is 0, the redirect happens immediately.
`signature`	string	Yes	Signature

Generating the signature

The signature is generated by concatenating api_key, customer_key, transaction, amount, success_url, fail_url, and secret_key. sha256 is computed from the resulting string:

sha256({api_key}{customer_key}{transaction}{amount}{success_url}{fail_url}{secret_key})

where secret_key is the secret key found in the merchant's shop settings.

Request examples

`GET` request

https://customer.stage.kvell.group/bind/card/preauthorize?api_key={api_key}&customer_key={customer_key}&transaction={transaction}&description={description}&amount={amount}&signature={signature}&success_url={success_url}&fail_url={fail_url}

https://customer.stage.kvell.group/bind/card/preauthorize?api_key=a1aea13e-f94a-47ac-9687-633f3f8167fc&customer_key=bind_card_test&transaction=4416ea3d-ea94-4319-87d0-8fdf44b1bc87&description=Goody+goods&amount=627&signature=1cd3f0c885b15a63974406c453b6b7a0a1b2319c0ca017c7eb4bad15d73f5e86&success_url=http%3A%2F%2F127.0.0.1%3A5500&fail_url=http%3A%2F%2F127.0.0.1%3A5500

`POST` request

<form action="https://customer.stage.kvell.group/bind/card/preauthorize" method="POST">
    <input type="hidden" name="api_key" value="3a8c82d6-d2c6-4165-9a6b-ab3f14d965ae">
    <input type="hidden" name="transaction" value="fbfe9f88-d5c7-4994-aed6-ee8003f4f342">
    <input type="hidden" name="customer_key" value="bind_card_test">
    <input type="hidden" name="amount" value="10000">
    <input type="hidden" name="description" value="Product No. 1">
    <input type="hidden" name="signature" value="afc09ed74d83849d44c1f1906b10d20c147bf0eb25da940c020c980b3b44ca38">
    <input type="hidden" name="success_url" value="http://yoursite.com/success">
    <input type="hidden" name="fail_url" value="http://yoursite.com/fail">
    <input type="submit" value="Bind card">
</form>

Sending the callback

Sends a callback with information about the linked card. The callback is configured in the merchant's personal account, in the shop's technical settings. You need to select the callback type Сохранение привязанной карты (Saved card callback).

Method: POST

Parameters

Name	Data type	Description
`customer_key`	string	Customer identifier in the merchant's system
`customer_card_token`	string	Linked card token
`pan_mask`	string	Masked card number
`holder`	string	Cardholder name
`expire`	string	Card expiration date in `YYYY-MM` format
`transaction`	string	Unique transaction number on the merchant's side
`bank_name`	string	Name of the card-issuing bank
`bank_id`	string	Card-issuing bank identifier in the NSPK (SBP) system

{
  "customer_key": "bind_card_test",
  "customer_card_token": "4VNSbS7nF410G8WLEhUUUnflH2UKvWlHxIzN3Jr9JJs",
  "pan_mask": "411111******1111",
  "holder": "IVAN IVANOV",
  "expire": "2028-12",
  "transaction": "563bb54d-ed4c-4ca1-84a3-6a35c0178cf5",
  "bank_name": "Sberbank",
  "bank_id": "100000000111"
}

Callback delivery

A callback delivery is considered successful if the merchant's server returns HTTP code 200. Any other HTTP code in the response means the request was not delivered.

If the first attempt was unsuccessful, 5 more attempts will be made every 10 minutes.