Skip to content

General

Payouts via Sber are made from a corporate card (Sber Business Card) within an authorized Sber user session obtained through the merchant's personal account in the "Integrations" section. Each payout is confirmed by the user on Sber's side, after which the merchant calls the payout confirmation method.

Base url

Payout API methods (payouts to a card or via SBP):

  • Production url: https://api.pay.kvell.group/v1
  • Stage url: https://api.pay.stage.kvell.group/v1

Reference API methods (user information, list of corporate cards, list of SBP banks):

  • Production url: https://api.baas.kvell.group/v1
  • Stage url: https://api.baas.stage.kvell.group/v1

Request headers

Name Type Required Description
X-Api-Key string Yes Unique shop identifier
X-Signature string Yes Signature

Building the signature

For the payout creation methods, an electronic signature is used with the RSA/SHA256 algorithm:

The merchant generates a key pair on their own side and passes the public part to technical support. The signature building algorithm is the same as for making a payout to a card.

For the remaining methods, the signature is formed by concatenating the request parameters, and sha256 is taken from the resulting string:

Method Signature
User information sha256({X-Api-Key}{session_id}{secret_key})
List of corporate cards sha256({X-Api-Key}{session_id}{secret_key})
List of SBP banks sha256({X-Api-Key}{session_id}{secret_key})
SBP payout feasibility check sha256({X-Api-Key}{phone}{bank_id}{secret_key})
Getting the payout feasibility check status sha256({X-Api-Key}{request_id}{secret_key})
Payout confirmation sha256({X-Api-Key}{transaction}{session_id}{secret_key})

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

Sber session parameters

Name
 Type Description
session_id string Identifier of the authorized Sber session. Created after the user completes authorization with Sber.
business_card_id string Identifier of the corporate card the payout is made from. Returned in the business_card_id field of the card list method.
user_crypto_type string Sber user crypto profile: SMS — SMS confirmation, Token — electronic key (token). Returned in the user_crypto_type field of the user information method. Defaults to SMS.

Method call order

Payout to a card:

  1. User information — get user_crypto_type by session_id.
  2. List of corporate cards — choose a card and get business_card_id.
  3. Payout to a card — create the payout; the response includes redirect_url.
  4. Open redirect_url and confirm the operation in Sber.
  5. Payout confirmation — update the payout status in KVELL.

SBP payout:

  1. User information — get user_crypto_type by session_id.
  2. List of corporate cards — choose a card and get business_card_id.
  3. List of SBP banks — check that the recipient's bank is available for payouts via Sber.
  4. SBP payout feasibility check — get request_id. This step is optional.
  5. Getting the payout feasibility check status. This step is optional.
  6. SBP payout — create the payout, passing the obtained request_id; the response includes redirect_url.
  7. Open redirect_url and confirm the operation in Sber.
  8. Payout confirmation — update the payout status in KVELL.

Payout feasibility check

Calling the SBP payout feasibility check and status methods is optional — a payout to a card or via SBP can be created right away. The check is needed if you need to confirm in advance that a payout to the recipient's bank details is possible, verify the recipient's full name against NSPK data, or obtain a request_id to pass in the payout request.

Payout status

If the payout remains in processing status after confirmation, the final status must be obtained using the transaction status method.

Return redirect

The redirect_url link from the payout creation methods' response is opened to confirm the operation in the SberBusiness interface. redirect_url arrives without a return address, so the backUrl parameter with the merchant's return page address is appended to the end of the received link:

{redirect_url}?backUrl=https%3A%2F%2Fmerchant.example.com%2Fpayout-result

Sber's requirements for the parameter:

  • backUrl must be URLEncode-encoded;
  • if backUrl is not specified, the user won't be able to return to the merchant's platform after signing;

Error codes

Errors are returned in the errors list of the JSON response body. 5xx responses, timeouts, and connection drops are handled separately — see Error and timeout handling.

{
  "errors": [
    {
      "code": 20002,
      "message": "Invalid signature"
    }
  ]
}
Code Description
20001 Invalid api-key
20002 Invalid signature
20003 Payout profile is not linked to the shop
20005 Error from the PSP service
20007 Transaction has already been performed
20009 Order not found
20015 Insufficient funds
20019 Shop payout limit exceeded
20020 Recipient not specified
20038 Invalid draft number
20040 Payout draft not found
20041 The resulting description field exceeds the allowed length
20042 Payout data and payout draft data do not match
20098 Request field validation error