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.

PX Integration option

SBP Data (Faster Payments System Data)

Payment Flow

  1. The customer clicks Pay on the merchant's website.
  2. The merchant displays a page with the bank details, transaction amount and the phone number to which the payment must be made.
  3. The customer copies the information from the page and makes a payment using an application or an internet banking option of their choice within a 15-minute timeframe.
  4. To speed up the transaction processing, the merchant may add a button for payment confirmation. Clicking this button after the payment will send a transaction confirmation request. This step is optional.
  5. The merchant receives a webhook notification with the transaction status.
  6. If the transaction status is successful, the amount is credited to the customer's account balance on the merchant's website.
  7. If the customer makes a payment later than the designated 15-minute timeframe, the returned transaction status is failed.
  8. If the customer's balance hasn't been updated on the merchant's website but they made the payment, they should request the payment proof from the merchant providing the evidence documents of the money withdrawal from their account.
  9. The merchant sends the payment proof request to Constantpos attaching the file with all the evidence documents provided by the customer. Each evidence document must be placed on a separate page within the attached file. Payment proof can only be requested for failed payments. Proof requests with "payment_status": "pending" or "payment_status": "successful" will be declined.
  10. Below are the possible scenarios for after the proof request has been sent:
Statuses in the status query response Description
"payment_status": "successful"

"proof_status": "successful"		 Proof request is approved. The webhook notification with the updated payment status and payment amount will be sent to the merchant.
"payment_status": "failed"

"proof_status": "failed"		 Proof request is declined. The webhook notification with failed statuses for both objects will be sent to the merchant.
"payment_status": "pending" or "payment_status": "failed"

"proof_status": "successful"		 Proof request is being processed. The merchant needs to wait until the payment transaction is successful (either in the response to the status query or in the webhook notification) before finalizing the transaction in their system.

Note

The merchant must not send another payment proof request unless they receive the payment webhook notification after the previous payment proof request. The payment proof request processing takes from 1 hour to 2 business days. The maximum number of proof requests per payment is 3.

Payment

Request

Send a payment request with the following additional parameters:

Parameter Type Description
request object
return_url * required
 string A URL, to which the customer is returned once the transaction is completed.
method object A section of the payment method.
type
* required
 string sbp_data
channel
* required
 string Send SBP. Note that this parameter value must be specified in capital letters.

Note

The value in the amount field must be an integer amount specified in minimal currency units. For example, 50000 (500 rubles).

Note

The amount value must be in the range from 50000 to 15000000 (500—150000 RUB).

Example of the request 
{
  "request":{
      "amount":100000,
      "currency":"RUB",
      "description":"description",
      "test": true,    
      "tracking_id":"11111111",      
      "language":"en",
      "notification_url":"https://merchant.ltd/notification",
      "return_url":"https://merchant.ltd/return",      
      "method":{
        "type": "sbp_data",
        "channel": "SBP"

      }
  }
}
Response

The response will contain the following additional parameters:

Parameter Type Description
sbp_data object
mark
* required
 string The code the customer needs to specify in the comment field if there is such a field in their banking option.
target_card
* required
 string Phone number, to which the payment must be made.
bank_type * required
 string The issuing bank of the customer.
expired_at
* required
 string Time that the order expires at. Set in the ISO-8601 format: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example, 2019), MM – month (for example, 02), DD – day (for example, 09), hh – hours (for example, 18), mm – minutes (for example, 20), ss – seconds (for example, 45), TZD – time zone (+hh:mm or –hh:mm indicating an offset from UTC).
Example of the response 
{
  "transaction": {
    "uid": "0f654679-0485-4061-8638-d8690e6505e5",
    "type": "payment",
    "status": "pending",
    "amount": 100000,
    "currency": "RUB",
    "description": "description",
    "created_at": "2024-05-22T13:40:45Z",
    "updated_at": "2024-05-22T13:40:45Z",
    "method_type": "sbp_data",
    "receipt_url": "https://my.constantpos.com/customer/transactions/0f654679-0485-4061-8638-d8690e6505e5/2c4d0ab640d08934dc1d9aca64aa652fc41c4bfb51830c2319bacc5e5b8260a9?language=en",
    "payment": {
      "status": "pending",
      "gateway_id": 3898,
      "ref_id": "40abf7cd-aa9f-43c5-a523-f4c10aed7e83",
      "message": "Transaction was initialized."
    },
    "sbp_data": {
      "type": "sbp_data",
      "mark": "",
      "target_card": "+1111",
      "expired_at": "2024-05-22 13:55:46+0000",
      "bank_type": "TINKOFF"
    },
    "customer": {
      "email": null,
      "ip": null
    },
    "manually_corrected_at": null,
    "message": "Transaction was initialized.",
    "tracking_id": "11111111",
    "test": true,
    "language": "en",
    "additional_data": {
      "payment_method": {
        "type": "alternative"
      }
    },
    "gateway": {
      "iframe": false
    }
  }
}

Payment proof

Request

POST https://api.constantpos.com/beyag/transactions/{uid}/proof

Parameter Type Description
request object
skip_duplicate_check boolean If false, declines a request if the request with the same uid was sent within 30 seconds prior to it. By default, set to false.
amount * required
 bigInteger Payment proof amount in minimal currency units without coins.
currency * required
 string (3) Transaction currency in the ISO-4217 alpha-3 code format.
document object
content_type * required
 string application/pdf
file_name * required
 string File name including the file extension.
file_size * required
 integer File size in bytes.
content * required
 string Payment proof documents, base64 encoded. Each evidence document must be placed on a separate page within the file.
checksum * required
 string Payment proof amount, SHA256 encrypted.
Request example 
{
  "request": {
    "skip_duplicate_check": false,
    "amount": 322400,
    "currency": "RUB",
    "document": {
      "content_type": "application/pdf",
      "file_name": "3224.pdf",
      "file_size": 198149,
      "content": "cmVmCjE5Yzd2NwolJUVPRgo=",
      "checksum": "45EA3C910A727823079CF1E7DAB4B8BA"
    }
  }
}
Status query responses

After the proof request has been sent, the response to the status query will contain an object proof with 3 possible statuses: pending, failed and successful.

Once the proof request is processed, the merchant will get a webhook notification either with a failed status for both the payment and the proof request or with a successful status for both requests.

Example of status query response with the pending status for proof 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "failed",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://my.constantpos.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was declined."
        },
        "sbp_data": {
            "mark": "160385A",
            "type": "sbp_data",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "SBP",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "test@example.com",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was declined.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
            "ref_id": "97be822d-6c34-4ead-9579-21a8f42a92e1",
            "gateway_id": 2976,
            "status": "pending",
            "message": "Proof was initialized."
        }
    }
}
Example of status query response with the successful status for proof 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "successful",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://my.constantpos.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was successfully processed."
        },
        "sbp_data": {
            "mark": "160385A",
            "type": "sbp_data",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "SBP",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "test@example.com",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was successfully processed.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
          "ref_id": "f8casdf56-1e85-r456-9842-fasdfasdf",
          "gateways_id": 2985,
          "status": "successful",
          "message": "Proof was successfully processed."
        }
    }
}
Example of status query response with the failed status for proof 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "failed",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://my.constantpos.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was declined."
        },
        "sbp_data": {
            "mark": "160385A",
            "type": "sbp_data",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "SBP",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "test@example.com",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was declined.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
            "ref_id": "f8casdf56-1e85-r456-9842-fasdfasdf",
            "gateways_id": 2985,
            "status": "failed",
            "message": "Proof was declined."
        }
    }
}

Transaction confirmation

Request

POST https://api.constantpos.com/beyag/transactions/{uid}/confirm

Parameter Type Description
skip_duplicate_check boolean If false, declines a request if the request with the same uid was sent within 30 seconds prior to it. By default, set to false.
Response
Successful response example 
{
    "response": {
        "parent_uid": "2-310b0da80b", 
        "type": "confirm",
        "status": "successful", 
        "message": "Confirm was successfully processed",
        "created_at": "2023-05-11T12:04:59+03:00",
        "amount": 332400,
        "currency":"RUB"
    }
}
Response example with failed status 
{
    "response": {
        "parent_uid": "2-310b0da80b",
        "type": "confirm",
        "status": "failed",
        "message": "Confirm was failed",
        "created_at": "2023-05-11T12:04:59+03:00",
        "amount": 50,
        "currency": "RUB"
    }
}
Response example when the transaction is not found 
{
        "response": {
            "message": "Record not found",                
        }
}

GOP Integration option

Payout

Warning

The amount parameter value in the webhook notification and in the response to the transaction status query can be different from the value sent in the initial payout request and will equal the actual payout amount according to the information in the provider's system.

Note

The value in the amount field must be a rounded integer amount specified in minimal currency units. For example, 500000 (5000 rubles).

Note

Minimal payout amount is 5000 rubles.

Send a payout request with the following additional data:

Parameter Type Description
method object A section of the payment method information.
type * required
 string sbp
account_number * required
 string The identifier of the payout recipient's account, in this case, the phone number in the international format, + prefix is optional. Can include (), - and spaces. In any case the submitted phone number will be converted to +79151002030 or 79151002030 by Constantpos system.
bank_code * required
 string The bank ID of the payout recipient.
Request example 
{
  "request": {
    "amount": 1500000,
    "currency": "RUB",
    "description": "description",
    "test": false,
    "tracking_id": "your_uniq_number",
    "language": "en",
    "return_url": "https://your-success.url",
    "method": {
      "type": "sbp",
      "account_number": "+74951234567",
      "bank_code": "123456789012"
    }
  }
}
Response example 
{
  "transaction": {
    "uid": "17022b24-f04f-4159-88be-9c08a7ac8366",
    "type": "payout",
    "status": "pending",
    "amount": 100000,
    "currency": "RUB",
    "description": "description",
    "created_at": "2024-05-03T06:31:32Z",
    "updated_at": "2024-05-03T06:31:33Z",
    "manually_corrected_at": null,
    "method_type": "sbp",
    "receipt_url": "https://my.constantpos.com/customer/transactions/17022b24-f04f-4159-88be-9c08a7ac8366/5814549a7a3d80f63f7e46ac6b6217b8cc6012bfa8382e89d6c8d05631351d91?language=en",
    "payout": {
      "status": "pending",
      "gateway_id": 3978,
      "ref_id": "70352270-b978-4a9f-aa82-5053d6e5070e",
      "message": "заявка создана успешно.",
      "bank_code": 0
    },
    "sbp": {
      "type": "sbp"
    },
    "customer": {
      "email": "null",
      "ip": "null"
    },
    "message": "заявка создана успешно.",
    "tracking_id": "your_uniq_number",
    "test": false,
    "language": "en",
    "billing_address": {},
    "additional_data": {
      "payment_method": {
        "type": "alternative"
      }
    }
  }
}