Skip to content

Faster Payments System (SBP)

Payment flow

The Faster Payments System payment flow contains the following steps:

  1. You initiate a payment request.
  2. The system submits a request to the payment method provider. The Faster Payments System generates a QR-code used to complete a payment.
  3. You get a response and redirect your customer to the received URL.
  4. Your customer gets the payment QR-code and completes the payment.
  5. You get a webhook notification about a payment status, if you send notification_url in the payment request.

This alternative payment method supports the following operations:

Payment

Request

Send a payment request with the following additional data:

Parameter Type Description
method object A section of the payment method information.
type
required
 string sbp
Response

The payment response additionally contains the form section with the URL of a page with the QR-code. Redirect your customer to the URL received as a value of the form.action parameter.

Payment status query

Request

To check a status of the payment, send a transaction status query.

Response

The response contains the transaction status, a section of the payment method as well as other details related to the transaction according to the description of a transaction status query.

Refund

Request

To pay money back to the customer, send a refund request with the UID of the payment transaction.

Response

The response contains the status of the refund transaction as well as other relevant transaction details according to the description of a refund transaction.

SY Integration option

Payment flow

  1. The customer initiates the payment.
  2. The merchant sends the payment request to Freepayment.
  3. Freepayment returns a URL to the payment page with SBP QR-code.
  4. The merchant redirects the customer to the received payment page URL. The transaction has the pending status.
  5. The customer scans/clicks QR-code on the SBP page, selects a bank and confirms the payment in their bank application.
  6. Freepayment sends a webhook notification to the merchant.
  7. The merchant displays the payment status to the customer.

This alternative payment method supports the payment transaction:

Payment

Request

Send a payment request with the following additional data:

Parameter Type Description
request object
ip * required
 string The customer's IP address.
return_url * required
 string A URL to return the customer to when the transaction is completed.
notification_url string A URL to get webhook notifications.
customer object A section of information about the customer. It should contain at least one parameter of the customer's data.
email *conditionally required
 string The customer's email address.
phone *conditionally required
 string (15) The customer's phone number with country code.
country
*conditionally required
 string (3) The customer's country in ISO_3166-1_alpha-3 format.
method object A section of the payment method information.
type
* required
 string sbp
Request example 
{
  "request": {
      "amount": 100000,
      "currency": "RUB",
      "description": "description",
      "test": false,
      "ip": "127.0.0.1",
      "language": "en",
      "notification_url": "https://merchant.ltd/notification",
      "return_url": "https://merchant.ltd/return",
      "customer": {
          "phone": "17777777777",
          "email": "example@example.com"
      },
      "method": {
          "type": "sbp"
      }
  }
}
Response

The payment response additionally contains the form section with the URL of a page with the QR-code. Redirect your customer to the URL received as a value of the form.action parameter.

Sucсessful response example 
{
  "transaction": {
    "uid": "12c34ec5-a678-9d1a-2345-f678d912c345",
    "type": "payment",
    "status": "pending",
    "amount": 100000,
    "currency": "RUB",
    "description": "description",
    "created_at": "2023-10-15T13:33:53Z",
    "updated_at": "2023-10-15T13:33:54Z",
    "method_type": "sbp",
    "receipt_url": "https://account.freepayment.online/customer/transactions/12c34ec5-a678-9d1a-2345-f678d912c345/7fc22e3697ad822bc004bb3812282a547780c204fd0451c974e3a599fe949326?language=en",
    "payment": {
      "status": "pending",
      "gateway_id": 1234,
      "ref_id": "12c34ec5-a678-9d1a-2345-f678d912c345",
      "message": "Transaction was initialized.",
      "bank_code": "0",
      "rrn": "1234567891000000123"
    },
    "sbp": {
      "type": "sbp"
    },
    "customer": {
      "email": "example@example.com",
      "phone": "17777777777",
      "ip": "127.0.0.1"
    },
    "manually_corrected_at": null,
    "message": "Transaction was initialized.",
    "test": false,
    "language": "en",
    "billing_address": {
      "email": "example@example.com",
      "phone": "17777777777"
    },
    "additional_data": {
      "payment_method": {
        "type": "alternative"
      }
    },
    "form": {
      "action": "https://qr.nspk.ru/AD10006L6KIM6I7784A993TVF4QJ9JCE?type=02&bank=100000000017&sum=100000&cur=RUB&crc=0953",
      "method": "GET",
      "fields": []
    }
  }
}

BC Integration option

Payment flow

  1. The customer initiates the payment on the merchant's website.
  2. The merchant sends the payment request to Freepayment.
  3. Freepayment returns a URL to the payment page with SBP QR-code. The QR-code is valid for 1 hour.
  4. The merchant redirects the customer to the received payment page URL.
  5. The customer scans the QR-code on the SBP page, selects the bank from the displayed list of the available banks, gets redirected to the corresponding bank application and completes the payment. Alternatively the customer scans the QR-code in their bank application and completes the payment.
  6. Freepayment sends a webhook notification to the merchant.
  7. The merchant displays the payment status to the customer.

Info

This integration option only supports RUB currency.

Payment

Request

Send a payment request with the following additional data:

Parameter Type Description
request object
return_url * required
 string A URL to return the customer to when the transaction is completed.
method object A section of the payment method information.
type
* required
 string sbp
Request example 
{
  "request": {
    "amount": 100000,
    "currency": "RUB",
    "description": "description",
    "return_url": "https://merchant.ltd/return",
    "method": {
      "type": "sbp"
    }
  }
}
Response

The response will contain form.action parameter with the link to the provider's website with the QR-code for making the payment.

Response example 
{
    "transaction": {
        "uid": "80395db5-0127-4220-ba5b-fb354d191ba8",
        "type": "payment",
        "status": "pending",
        "amount": 100000,
        "currency": "RUB",
        "description": "description",
        "created_at": "2024-01-08T12:11:55Z",
        "updated_at": "2024-01-08T12:11:55Z",
        "method_type": "sbp",
        "receipt_url": "https://account.freepayment.online/customer/transactions/80395db5-0127-4220-ba5b-fb354d191ba8/2c8ec02c64a928b4d48113d6adc50d179d3a913b4c7831ca0329f1af0353e9ec",
        "payment": {
            "status": "pending",
            "gateway_id": 3584,
            "ref_id": "34142099219264211662",
            "message": "Transaction was initialized",
            "bank_code": 0
        },
        "sbp": {
            "type": "sbp"
        },
        "customer": {
            "email": null,
            "ip": null
        },
        "manually_corrected_at": null,
        "message": "Transaction was initialized",
        "test": false,
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },     
              "gateway": {
            "iframe": true
        },
        "form": {
            "action": "https://qr.nspk.ru/BS10000LE9UMVMG79SARVEE105HKATPO",
            "method": "GET",
            "fields": []
        }
    }
}

Refund

Request

For the refund, send a refund request with the UID of the payment transaction. The amount value must not exceed the amount of the parent transaction.

Request example 
{
    "request": {
        "parent_uid": "bdf1314f-ba06-4265-acaf-7bc533aacf11",
        "reason": "reason",
        "amount": 1000
    }
}
Response

The final refund status will be displayed in the back office or sent in the webhook notification or in the response to the status query.

Response example 
{
  "transaction": {
    "uid": "52b4d133-474c-469b-b240-72385b1dfd10",
    "parent_uid": "bdf1314f-ba06-4265-acaf-7bc533aacf11",
    "type": "refund",
    "status": "pending",
    "reason": "reason",
    "created_at": "2024-01-08T13:41:30Z",
    "updated_at": "2024-01-08T13:41:31Z",
    "method_type": "sbp",
    "receipt_url": "https://account.freepayment.online/customer/transactions/52b4d133-474c-469b-b240-72385b1dfd10/fe69a35c3d7f0896edfc2c73ec08652f7b0a47eeb96d1c6050f55ca03bd75924",
    "refund": {
      "status": "pending",
      "ref_id": "16192",
      "message": "Transaction was initialized",
      "bank_code": 0
    },
    "manually_corrected_at": null,
    "message": "Transaction was initialized",
    "amount": 1000,
    "test": false,
    "additional_data": {
      "payment_method": {
        "type": "alternative"
      }
    }
  }
}

IZ Integration option

Info

This integration option supports only RUB currency.

Payment

Payment flow

  1. The customer initiates the payment on the merchant's website.
  2. The merchant sends the payment request to Freepayment.
  3. Freepayment sends parameters for building an HTML-form for the payment.
  4. The merchant builds an HTML-form based on the parameters from the response. The lifespan of the link in the form.action parameter is 15 minutes.
  5. The merchant redirects the customer to the form for completing the payment.
  6. The customer confirms the payment.
Request

Send a payment request with the following additional data:

Parameter Type Description
request object
return_url * required
 string A URL to return the customer to when the transaction is completed.
method object A section of the payment method information.
type
* required
 string sbp
customer object A section of information about the customer.
email
* required
 string The customer's email address.
phone
* required
 string The customer's phone number without +.
Request example 
{
  "request": {
    "amount": 10000,
    "currency": "RUB",
    "description": "description",
    "test": false,
    "tracking_id": "your_uniq_number",
    "return_url": "https://return-url",
    "customer": {
      "phone": "1234567890",
      "email": "example@example.com"
    },
    "method": {
      "type": "sbp"
    }
  }
}
Response

Build an HTML form based on the parameters in the form object. Redirect the customer to the form to finalize the payment.

Response example 
{
    "transaction": {
        "uid": "19088621-95e0-4100-b0a8-1717c69a9600",
        "type": "payment",
        "status": "pending",
        "amount": 10000,
        "currency": "RUB",
        "description": "description",
        "created_at": "2024-07-03T12:21:16Z",
        "updated_at": "2024-07-03T12:21:16Z",
        "method_type": "sbp",
        "receipt_url": "https://account.freepayment.online/customer/transactions/19088621-95e0-4100-b0a8-1717c69a9600/863e4e14692a6698664f758c39177d6b2c03f8f3de6e233e1020d098a7b0428f",
        "payment": {
            "status": "pending",
            "gateway_id": 4163,
            "message": "Transaction was initialized."
        },
        "sbp": {
            "type": "sbp"
        },
        "customer": {
            "email": "example@example.com",
            "phone": "1234567890",
            "ip": null
        },
        "manually_corrected_at": null,
        "version": 0,
        "message": "Transaction was initialized.",
        "tracking_id": "your_uniq_number",
        "test": false,
        "billing_address": {
            "email": "example@example.com",
            "phone": "1234567890"
        },
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },        
        "gateway": {
            "iframe": true
        },
        "form": {
            "action": "https://payment-page",
            "method": "POST",
            "fields": [
                {
                    "name": "amount",
                    "value": "100.00",
                    "type": "hidden"
                },
                {
                    "name": "amountcurr",
                    "value": "RUB",
                    "type": "hidden"
                },
                {
                    "name": "currency",
                    "value": "EXT",
                    "type": "hidden"
                },
                {
                    "name": "number",
                    "value": "a241a368c8hu9639786382d7592e34",
                    "type": "hidden"
                },
                {
                    "name": "description",
                    "value": "www.site.com",
                    "type": "hidden"
                },
                {
                    "name": "trtype",
                    "value": "1",
                    "type": "hidden"
                },
                {
                    "name": "phone",
                    "value": "0987654321",
                    "type": "hidden"
                },
                {
                    "name": "email",
                    "value": "1@example.com",
                    "type": "hidden"
                },
                {
                    "name": "account",
                    "value": "ACC041111",
                    "type": "hidden"
                },
                {
                    "name": "signature",
                    "value": "6A886FJ609RITN5960HIYK403D5170CA3EBB555",
                    "type": "hidden"
                }
            ]
        }
    }
}

MT Integration option

Info

This integration option only supports RUB currency.

Payment

Payment flow

  1. The customer initiates the payment on the merchant's website.
  2. The merchant sends the payment request to Freepayment.
  3. Freepayment returns a URL to the payment page with SBP QR-code.
  4. The merchant redirects the customer to the received payment page URL. The default lifespan of the payment link is 15 minutes.
  5. On desktop: the customer scans the QR-code on the SBP page with the mobile device, selects the bank from the displayed list of the available banks, gets redirected to the corresponding bank application and completes the payment. Alternatively the customer scans the QR-code in their bank application and completes the payment. On mobile: the customer is redirected to the bank selection page to complete the payment.
  6. Freepayment sends a webhook notification to the merchant.
  7. The merchant displays the payment status to the customer.
Request

Send a payment request with the following additional data:

Parameter Type Description
request object
return_url * required
 string A URL to return the customer to when the transaction is completed.
method object A section of the payment method information.
type
* required
 string sbp
Request example 
{
    "request": {
        "amount": 100000,
        "currency": "RUB",
        "description": "description",
        "return_url": "https://merchant.ltd/return",
        "method": {
            "type": "sbp"
        }
    }
}
Response

Redirect your customer to the URL received as the value of the form.action parameter.

Response example 
{
    "transaction": {
        "uid": "ff907a25-c194-44bb-b3ec-9a943f89f863",
        "type": "payment",
        "status": "pending",
        "amount": 100000,
        "currency": "RUB",
        "description": "description",
        "created_at": "2024-09-23T13:21:05Z",
        "updated_at": "2024-09-23T13:21:06Z",
        "method_type": "sbp",
        "receipt_url": "https://account.freepayment.online/customer/transactions/ff907a25-c194-44bb-b3ec-9a943f89f863/fc6fcec74ae131c4afad01db10a2abd209b91b0b4e54c8af65a38485bbcdd245",
        "payment": {
            "status": "pending",
            "gateway_id": 4497,
            "ref_id": "3960848",
            "message": "Transaction was initialized."
        },
        "sbp": {
            "type": "sbp"
        },
        "customer": {
            "email": null,
            "ip": null
        },
        "manually_corrected_at": null,
        "version": 0,
        "message": "Transaction was initialized.",
        "test": false,
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },      
        "gateway": {
            "iframe": false
        },
        "form": {
            "action": "https://qr.nspk.ru/AD100066PTMO2TOG8S1B64I8GGMR32GR",
            "method": "GET",
            "fields": []
        }
    }
}

Refund

Request

For the refund, send a refund request with the UID of the payment transaction. The refund can be executed once for an amount less than or equal to the parent transaction amount.