SBP payout feasibility check with currency conversion

A method for checking the recipient's details before an SBP payout, with the option to specify the amount in a currency other than the shop's currency. If currency is passed, the amount is converted before the check, and the conversion result is returned in the response. All other parameters are identical to «SBP payout feasibility check».

When to use this method instead of the base one

Use this method if the intended payout amount is in a currency other than the shop's currency and you need to see the conversion result in advance (the rate and the amount in the profile currency) before creating the payout itself. If currency is not passed, the method behaves identically to the base check method — fx_conversion in the response will be null.

Integration flow

Get bank_id from the list of SBP banks.
Build a request with the phone number, the recipient's bank, and the payout amount. If the amount is in a currency other than the shop's currency, pass its numeric ISO 4217 code in the currency field. See «Currency codes».
Save the request_id from the 200 response. This response only means that the check request has been registered.
Poll for the check status with the same request_id until you receive success or error. On processing, keep polling instead of creating a new check.
When creating the payout itself via the conversion payout method, pass the source amount and currency again — the conversion at this step is performed again.

When a preliminary check is needed

A check is useful when, before creating the payout, you need to make sure the chosen bank can accept a transfer to the given phone number, retrieve the full name from NSPK, verify that it matches, or see the amount and conversion rate in advance.

URL

ProductionStage

POST https://api.pay.kvell.group/v2/orders/payout/sbp/check

POST https://api.pay.stage.kvell.group/v2/orders/payout/sbp/check

Request

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Shop identifier.
`X-Signature`	string	Yes	Request signature.

Building the signature

Concatenate X-Api-Key, phone, bank_id, and secret_key with no separators, compute the SHA-256 hash of the resulting UTF-8 encoded string, and pass the lowercase hash in the X-Signature header.

SHA256(X-Api-Key + phone + bank_id + secret_key)

secret_key is found in the shop settings. The order of the values must not be changed. The currency field is not included in the signature.

Request body

Parameter	Type	Required	Description
`amount`	integer	Yes	The intended payout amount in the minor units of the currency specified in `currency`. If `currency` is not passed, the amount is in the minor units of the shop's payout profile currency. For example, `10000` is 100.00 in the corresponding currency.
`bank_id`	string	Yes	Recipient bank identifier from the list of SBP banks.
`bank_bic`	string	Conditional	BIC from the list of banks. Required if the acquiring bank requires it. Check with your account manager.
`phone`	string	Yes	Recipient's phone number: 11 digits, without `+`, spaces, parentheses, or separators. Example: `79999999999`.
`currency`	string	No	Numeric ISO 4217 code of the source currency as a string, e.g. `"840"` for USD. If not passed, `amount` is assumed to already be in the shop's currency — no conversion is performed. See «Currency codes».
`fio`	string	No	Recipient's full name. Used together with `fio_check` to verify a match against NSPK data.
`fio_check`	boolean	No	`true` — check that `fio` matches the full name received from NSPK.
`description`	string	No	Purpose of the intended payout. Defaults to `выплата` (payout). The final string, together with the shop prefix, must not exceed 110 characters.

Full name check

fio and fio_check can be omitted; in that case, the full name of the customer received from the bank will be returned when checking the payout feasibility status.

If you pass fio_check: true, use the full name exactly as it is registered with the recipient's bank. Some banking channels reject the characters Ё/ё before the match check even runs. If you get a format error, pass the variant with Е/е instead.

Example

JSON (with conversion)cURL

{
  "amount": 10000,
  "currency": "840",
  "bank_id": "100100000014",
  "fio": "Иванов Иван Иванович",
  "fio_check": true,
  "phone": "79999999999",
  "description": "Выплата по договору 42"
}

curl --request POST \
  --url 'https://api.pay.stage.kvell.group/v2/orders/payout/sbp/check' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000' \
  --header 'X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' \
  --data '{"amount":10000,"currency":"840","bank_id":"100100000014","fio":"Иванов Иван Иванович","fio_check":true,"phone":"79999999999","description":"Выплата по договору 42"}'

Response

Select the HTTP code to see an example, the response parameters, and recommended actions.

2004004034044225XX

Example 200 (OK) response: with conversion

{
  "request_id": "check-req-20260811-0001",
  "fx_conversion": {
    "source_currency": "840",
    "source_amount": 10000,
    "target_currency": "643",
    "target_amount": 853846,
    "rate_source": "montra",
    "source_to_base": 12210,
    "base_to_target": 143,
    "base_currency": "UZS",
    "converted_at": "2026-08-11T09:15:20.000000+00:00"
  }
}

Example 200 (OK) response: without conversion

{
  "request_id": "check-req-20260811-0002",
  "fx_conversion": null
}

Response parameters

Parameter	Type	Description
`request_id`	string	Identifier of the registered check. Used to retrieve its status.
`fx_conversion`	object \| null	The amount conversion result. `null` if `currency` was not passed in the request.
`fx_conversion.source_currency`	string	Numeric code of the source currency — the `currency` value from the request.
`fx_conversion.source_amount`	integer	The amount from the request, in the minor units of the source currency.
`fx_conversion.target_currency`	string	Numeric code of the shop's payout profile currency.
`fx_conversion.target_amount`	integer	The converted amount in the minor units of the shop's currency — this exact amount will be used when creating the payout.
`fx_conversion.rate_source`	string	Rate source: `montra` — the partner bank's rate; `same_currency` — no conversion was needed, `currency` matched the profile currency.
`fx_conversion.source_to_base`	number \| null	Rate of the source currency to the base currency (`UZS`). Present only when `rate_source: "montra"`.
`fx_conversion.base_to_target`	number \| null	Rate of the base currency (`UZS`) to the shop's currency. Present only when `rate_source: "montra"`.
`fx_conversion.base_currency`	string \| null	Base currency used for the rate calculation. Present only when `rate_source: "montra"`, value is always `"UZS"`.
`fx_conversion.converted_at`	string	Date and time the conversion was calculated, in ISO 8601 format.

The rate is only current at the time of the response

fx_conversion is calculated at the moment this method is called and is not stored on KVELL's side. The rate at the time the payout is actually created may differ — store fx_conversion only for display to the user, not as a guarantee of the final amount.

What to do next

Save request_id.
If needed, show the user the amount and rate from fx_conversion.
Call the check status method.

Example 400 (Bad Request) response

{
  "errors": [
    {
      "code": 20002,
      "message": "Invalid signature"
    }
  ]
}

Example bank error

{
  "errors": [
    {
      "code": 20099,
      "message": "1706: Bank with RbankID = 100000000118 not found!"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. In the examples — `20002` and `20099`.
`errors[].message`	string	Description of why the request was rejected.

What to do next

For 20002, check the order of values in the signature and the shop's secret key.
For 20099, fix the cause described in message.
If phone or bank_id changed, recompute X-Signature, then retry the request.

Example 403 (Forbidden) response

{
  "errors": [
    {
      "code": 20037,
      "message": "Access denied"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. In the example — `20037`.
`errors[].message`	string	Description of why access was denied.

Example 404 (Not Found) response: shop not found

{
  "errors": [
    {
      "code": 20006,
      "message": "Shop not found"
    }
  ]
}

Example 404 (Not Found) response: payout profile has no currency set

{
  "errors": [
    {
      "code": 20045,
      "message": "The shop's payout profile has no currency set"
    }
  ]
}

Example 404 (Not Found) response: Montra integration not configured

{
  "errors": [
    {
      "code": 20044,
      "message": "The integration with Montra is not configured for the shop"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	`20006` — shop not found; `20045` — the shop's payout profile has no currency set; `20044` — the integration with the rates provider is not configured.
`errors[].message`	string	Description of the resource that was not found.

What this response means

20045 and 20044 occur only if currency was passed: the amount cannot be converted, the check is not registered, and no request_id is created.

What to do next

For 20006, check X-Api-Key and the request environment.
For 20045/20044, contact KVELL support to configure the payout profile currency or the rates provider integration, or send the request without currency.
Retry the request only after fixing the cause of the error.

Example 422 (Unprocessable Entity) response

{
  "errors": [
    {
      "code": 20098,
      "message": "amount: Field required"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. Possible values: field error `20098` or dependent service code `20099`.
`errors[].message`	string	Reason for the validation error.

Currency field format

currency must consist of 1-3 digits (^\d{1,3}$). Letter currency codes ("USD") are rejected with error 20098.

What to do next

For 20098, fix the fields listed in errors[].message.
For 20099, check the request parameters; if the cause is unclear, contact KVELL support.
If phone or bank_id changed, recompute X-Signature.
Send the corrected request and save request_id from the 200 response.

Example 5XX (Internal Server Error) response

{
  "errors": [
    {
      "code": 20000,
      "message": "Unknown error"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Technical error code. Possible values: `20000` or dependent service code `20099`.
`errors[].message`	string	Description of the technical error.

5XX, timeout, and connection loss

A technical error does not mean the details check or conversion finished with a business status of error. The request may have been registered even if the client did not receive request_id. This method does not create a payout or financial transaction.

What to do next

If request_id was received earlier, request the status with the same identifier.
If request_id was not received, try retrying the request.
For a recurring error, contact KVELL support and provide the request time, the shop, and a sample request body.