Базовые запросы | API платёжного шлюза интернет-эквайринга

Аутентификация

Для осуществления HTTP-запросов к сервису требуется наличие TLS-сертификата, а также заголовка Authorization: Basic в качестве обязательных параметров.

Примеры

Полные примеры

curl --key crt/bspb_test.key --cert crt/bspb_test.pem \
-H "Content-Type: application/json" \
-H "Authorization:Basic %base64Credentials%"

%base64Credentials% - username:password в Base64-URL

// Инициализация cURL-сессии
$ch = curl_init($pay_url);

// Заголовки для отправки JSON и базовой авторизации
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Basic ' . $base64Credentials
]);

// Настройка для использования сертификата и ключа при выполнении запроса
curl_setopt($ch, CURLOPT_SSLCERT, $certificate_path);
curl_setopt($ch, CURLOPT_SSLKEY, $private_key_path);

// Выполнение запроса и получение результата
$response = curl_exec($ch);

    # Заголовки запроса
    headers = {'Content-Type': 'application/json'}

    # Данные для авторизации: username, password
    auth = HTTPBasicAuth('', '')
    
    # Путь к ключу и сертификату
    certificate_path = 'crt/bspb_test.pem'
    private_key_path = 'crt/bspb_test.key'
    
    # Пример выполнения запроса
    post(url, headers=headers, auth=auth, cert=(certificate_path, private_key_path), json=create_order) 

    const options = {
    method: 'POST',
    // Настройка для использования сертификата и ключа при выполнении запроса
    key: fs.readFileSync('./crt/bspb_test.key')
    cert: fs.readFileSync('./crt/bspb_test.pem')
    // Установка заголовков для отправки JSON и базовой авторизации
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic ' + Buffer.from('' + ':' + '').toString('base64')
    }
};

// Пример выполнения запроса
const req = https.request(url, options, (res)

    // Данные для авторизации: username:password
    auth := "" + ":" + ""
    basicAuth := "Basic " + base64.StdEncoding.EncodeToString([]byte(auth))
    
    // Заголовки запроса
    req.Header.Set("Authorization", basicAuth)
    req.Header.Set("Content-Type", "application/json")

    // Путь к ключу и сертификату
    cert, err := tls.LoadX509KeyPair("./crt/bspb_test.pem", "./crt/bspb_test.key")
    
    tlsConfig := &tls.Config{
        Certificates: []tls.Certificate{cert},
    }
    
    transport := &http.Transport{
        TLSClientConfig: tlsConfig,
    }
    
    client := &http.Client{
        Transport: transport,
    }
    
    // Пример выполнения запроса
    resp, err := client.Do(req)

Создание заказа

Первоначальный и обязательный запрос.

Запрос

{
    "order": {
        "typeRid": "Purchase",
        "amount": 200.00,
        "currency": "RUB",
        "title": "Название заказа",
        "description": "Описание заказа",
        "hppRedirectUrl":"https://pgtest.bspb.ru/result"
    }
}

Ответ

    {
        "order": {
            "id": 2000000004730,
            "hppUrl": "https://pgtest.bspb.ru/flex",
            "password": "11r23x81ncu2k",
            "accessToken": "0-cNtluTUmf9FGyx6IlTBaL8IXKmIyx26lTj8dixAJPV8",
            "status": "Preparing",
            "cvv2AuthStatus": "Required"
        }
    }

Создание заказа с ОФД

Запрос

{
    "order": {
        "typeRid": "Purchase",
        "amount": 300.00,
        "currency": "RUB",
        "title": "Название заказа",
        "description": "Описание заказа",
        "srcEmail": "pg@bspb.ru",
        "hppRedirectUrl":"https://pgtest.bspb.ru/result",
        "receipt": {
            "consumer": {
                "email": "pg@bspb.ru",
                "phone": "+79211234567"
            },
            "items": [
                {
                    "desc": "Товар 1",
                    "quantity": 1,
                    "price": 100.00,
                    "taxRate": 1,
                    "type": 1,
                    "mode": 1
                },
                {
                    "desc": "Товар 2",
                    "quantity": 1,
                    "price": 200.00,
                    "taxRate": 1,
                    "type": 2,
                    "mode": 4
                }
            ],
            "payments": [
                {
                    "type": 1,
                    "amt": 300.00
                }
            ]
        }
    }
}

Параметры запроса

typeRid - тип операции. Purchase для оплаты заказа.
amount - сумма заказа.
currency - валюта заказа.
title - название заказа.
description - описание заказа. Отображается на платёжной странице.
srcEmail - email, на который будет отправлен чек от ОФД.
hppRedirectUrl - адрес для перенаправления клиента после оплаты заказа.
receipt | consumer | email - email клиента.
receipt | consumer | phone - номер телефона клиента.
receipt | items | desc - описание позиции, отображается в чеке.
receipt | items | quantity - количество позиции, отображается в чеке.
receipt | items | price - сумма позиции, отображается в чеке.
receipt | items | taxRate - ставка НДС позиции, отображается в чеке.
receipt | items | type - предмет расчёта позиции, отображается в чеке.
receipt | items | mode - способ расчёта позиции, отображается в чеке.
receipt | payments | type - тип оплаты, отображается в чеке.
receipt | payments | amt - сумма всех позиции, отображается в чеке.

Параметры taxRate (items)

1 - НДС 20%
2 - НДС 10%
3 - НДС 20/120
4 - НДС 10/110
5 - НДС 0%
6 - НДС не облагается

Параметры mode (items)

1 - Предоплата 100%
2 – Частичная предоплата
3 - Аванс
4 - Полный расчёт
5 - Частичный расчёт и кредит
6 - Передача в кредит
7 - Оплата кредита

Параметры type (items)

1 – Товар
2 – Подакцизный товар
3 – Работа
4 – Услуга
5 – Ставка азартной игры
6 – Выигрыш азартной игры
7 – Лотерейный билет
8 – Выигрыш лотереи
9 – Предоставление РИД
10 – Платеж
11 – Агентское вознаграждение
12 – Выплата
13 – Иной предмет расчета
14 – Имущественное право
15 – Внереализационный доход
16 – Иные платежи и взносы
17 – Торговый сбор
18 – Курортный сбор
19 – Залог
20 – Расход
21 – Взносы на обязательное пенсионное страхование ИП
22 – Взносы на обязательное пенсионное страхование
23 – Взносы на обязательное медицинское страхование ИП
24 – Взносы на обязательное медицинское страхование
25 – Взносы на обязательное социальное страхование
26 – Платеж казино
27 – Выдача денежных средств
30 – АТНМ (не имеющем кода маркировки)
31 – АТМ (имеющем код маркировки)
32 – ТНМ
33 – ТМ

Параметры type (payments)

1 - Наличные
2 - Безналичные

Ответ

Ответ аналогичен базовому запросу

Получение чеков ОФД

Ответ

{
    "receipts": [
        {
            "tranId": "231216-19541818-003y7x=",
            "content": {
                "consumer": {
                    "email": "pg@bspb.ru",
                    "phone": "+79211234567"
                },
                "items": [
                    {
                        "desc": "Товар 1",
                        "quantity": 1,
                        "price": 100.00,
                        "taxRate": "1",
                        "type": "1",
                        "mode": "1"
                    },
                    {
                        "desc": "Товар 2",
                        "quantity": 1,
                        "price": 200.00,
                        "taxRate": "1",
                        "type": "2",
                        "mode": "4"
                    }
                ],
                "payments": [
                    {
                        "type": 1,
                        "amt": 300.00
                    }
                ],
                "taxRid": "7831000027",
                "taxSystemCode": "1"
            },
            "regData": {
                "docId": "201743",
                "regTime": "2023-12-16 22:52:57",
                "url": "https://cheques-lk.orangedata.ru/7831000027/231216-19541818-003y7x=",
                "deviceSer": "0001660038015559",
                "deviceReg": "0000000000034229",
                "storage": "9999078900011495",
                "ofdName": "Такcком ТЕСТ",
                "ofdWebSite": "www.taxcom.ru",
                "taxAuthorityWebSite": "www.nalog.gov.ru",
                "companyTaxRid": "7831000027",
                "companyName": "ПАО \"Банк \"Санкт-Петербург\"",
                "shift": "198",
                "docInShift": "23"
            }
        }
    ]
}

Статический QR

Запрос

{
    "kind": "IpsRuStatic",
    "amt": 100.00,
    "currency": "RUB",
    "description": "Описание статического QR",
    "orderTypeRid": "QR Static"
}

Ответ

{
    "qrc": {
        "payload": "https://qr.nspk.ru/AS10004JJVD5LF1697G8CF41T8RJUD1B?type=01&bank=100000000029&sum=10000&cur=RUB&crc=FDBE",
        "image": {
            "format": "image/png",
            "content": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAYAAACI..."
        }
    }
}

Частичная отмена (Partial reverse)

Запрос

{
    "tran": {
        "phase": "Single",        
        "voidKind": "Partial",
        "amount": 50.00
    }
}

Запрос на частичную отмену заказа с ОФД

{
    "tran": {
        "phase": "Single",
        "voidKind": "Partial",
        "amount": 40.00,
        "receipt": {
            "items": [
                {
                    "desc": "Товар 2",
                    "quantity": 1,
                    "price": 200.00,
                    "taxRate": 1,
                    "type": 2,                    
                    "mode": 4
                }
            ]
        }
    }
}

Параметры запроса

phase - фаза транзакции, по умолчанию "Single".
voidKind - тип отмены (возврат средств), Partial - частичная.
amount - сумма отмены.
receipt | items | desc - описание позиции, отображается в чеке.
receipt | items | quantity - количество позиции, отображается в чеке.
receipt | items | price - сумма позиции, отображается в чеке.
receipt | items | taxRate - ставка НДС позиции, отображается в чеке.
receipt | items | type - предмет расчёта позиции, отображается в чеке.
receipt | items | mode - способ расчёта позиции, отображается в чеке.

Ответ

{
    "tran": {
        "approvalCode": "004545",
        "approvedPartial": false,
        "match": {
            "tranActionId": "230822-07063337-00300r=",
            "ridByPmo": "230822255935240835"
        }
    }
}

Отмена (Reverse)

Запрос

{
    "tran": {
        "voidKind": "Full",
        "amount": 200.00,
        "phase": "Single"
    }
}

Ответ

{
    "tran": {
        "approvedPartial": false,
        "match": {
            "tranActionId": "231216-21225443-003y6q=",
            "ridByPmo": "231216769747838494"
        }
    }
}

Возврат (Refund)

Запрос

{
    "tran": {
        "type": "Refund"        
        "phase": "Single",
        "amount": 50.00
    }
}

Запрос на частичный возврат заказа с ОФД

{
    "tran": {
        "type": "Refund",
        "phase": "Single",
        "amount": 100.00,
        "receipt": {
            "items": [
                {
                    "desc": "Товар 1",
                    "quantity": 1,
                    "price": 100,
                    "taxRate": 1,
                    "type": 1,
                    "mode": 1
                }
            ]
        }
    }
}

Параметры запроса

type - тип операции, Refund - возврат средств.
phase - фаза транзакции, по умолчанию "Single".
amount - сумма возврата, равна сумме всех возвращаемых позиций.
receipt | items | desc - описание позиции, отображается в чеке.
receipt | items | quantity - количество позиции, отображается в чеке.
receipt | items | price - сумма позиции, отображается в чеке.
receipt | items | taxRate - ставка НДС позиции, отображается в чеке.
receipt | items | type - предмет расчёта позиции, отображается в чеке.
receipt | items | mode - способ расчёта позиции, отображается в чеке.

Ответ

{
    "tran": {
        "approvalCode": "716684",
        "approvedPartial": false,
        "match": {
            "tranActionId": "231216-21365573-003y6v=",
            "ridByPmo": "231216778160538495"
        }
    }
}

Информация по заказу

Ответ

{
    "order": {
        "id": 2000000004730,
        "typeRid": "Purchase",
        "status": "FullyPaid",
        "prevStatus": "Preparing",
        "lastStatusLogin": "TT00001",
        "amount": 300,
        "currency": "RUB",
        "createTime": "2023-12-16 22:52:57",
        "title": "Название заказа",
        "expTime": "2023-12-17 00:52:57",
        "type": {
            "allowVoid": false,
            "title": "TWPGPurchase",
            "allowCVV2": false
        }
    }
}

Детальная информация по заказу

Ответ

{
    "order": {
        "id": 2000000004730,
        "hppUrl": "https://pgtest.bspb.ru/flex",
        "hppRedirectUrl": "https://pgtest.bspb.ru/payment_result",
        "password": "11r23x81ncu2k",
        "accessToken": "0-cNtluTUmf9FGyx6IlTBaL8IXKmIyx26lTj8dixAJPV8",
        "status": "FullyPaid",
        "prevStatus": "Preparing",
        "lastStatusLogin": "TT00001",
        "amount": 300,
        "currency": "RUB",
        "terminal": {
            "id": 38,
            "rid": "TT00001",
            "title": "TT00001",
            "mcc": 8062,
            "status": "Active"
        },
        "srcAmount": 300,
        "srcAmountFull": 300,
        "srcCurrency": "RUB",
        "dstAmount": 300,
        "dstCurrency": "RUB",
        "createTime": "2023-12-16 22:52:57",
        "lastTran": {
            "approvalCode": "643027",
            "actionId": "231216-19541818-003y6b=",
            "orderId": 2000000004730,
            "terminalId": 38,
            "merchantId": 42,
            "billingStatus": "Normal",
            "isReversal": false,
            "ridByAcquirer": "231216716583438418",
            "ridByPmo": "231216716583438418",
            "regTime": "2023-12-16 22:54:18",
            "clearAmount": 300,
            "clearCcy": "RUB",
            "amount": 300,
            "currency": "RUB",
            "description": "Покупка",
            "phase": "Single",
            "type": "Purchase",
            "pmoResultCode": "Approved",
            "receiptContent": {
                "consumer": {
                    "email": "pg@bspb.ru",
                    "phone": "+79211234567"
                },
                "items": [
                    {
                        "desc": "Товар 1",
                        "quantity": 1,
                        "price": 100.00,
                        "taxRate": "1",
                        "type": "1",
                        "mode": "1"
                    },
                    {
                        "desc": "Товар 2",
                        "quantity": 1,
                        "price": 200.00,
                        "taxRate": "1",
                        "type": "2",
                        "mode": "4"
                    }
                ],
                "payments": [
                    {
                        "type": 1,
                        "amt": 300.00
                    }
                ],
                "taxRid": "7831000027",
                "taxSystemCode": "1"
            }
        },
        "cvv2AuthStatus": "Provided",
        "tdsV1AuthStatus": "NotSupportedIss",
        "tdsV2AuthStatus": "Verified",
        "authorizedChargeAmount": 200,
        "clearedChargeAmount": 200,
        "clearedRefundAmount": 0,
        "title": "Название заказа",
        "description": "Описание заказа",
        "srcEmail": "pg@bspb.ru",
        "consumerDevice": {
            "browser": {
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15",
                "colorDepth": 24,
                "pixelRatio": 1,
                "language": "ru",
                "tzOffset": -180,
                "localStorage": false,
                "languageReplaced": false,
                "resolutionReplaced": false,
                "osReplaced": false,
                "browserReplaced": false,
                "screenW": 1920,
                "screenH": 1080,
                "screenAvailW": 1920,
                "screenAvailH": 1055,
                "platform": "MacIntel",
                "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
                "ip": "127.0.0.1",
                "refUrl": "pgtest.bspb.ru",
                "javaEnabled": false,
                "jsEnabled": true
            }
        },
        "merchant": {
            "id": 42,
            "rid": "TT00001",
            "title": "TT00001",
            "businessAddress": {
                "country": "RUS",
                "countryA2": "RU",
                "countryN3": 643
            }
        },
        "initiationEnvKind": "Browser",
        "expTime": "2023-12-17 00:52:57",
        "type": {
            "allowVoid": true,
            "hppTranPhase": "Single",
            "secretLength": 0,
            "title": "TWPGPurchase",
            "rid": "Purchase",
            "paymentMethods": [
                "Card",
                "IpsRu",
                "MirPay"
            ],
            "cardBrands": [
                "Mir",
                "Visa",
                "Mastercard",
                "UP"
            ],
            "allowTdsAttempt": false,
            "allowTdsCant": false,
            "allowTdsChallenged": false,
            "allowTranTypes": [
                "Purchase",
                "Refund",
                "CheckToken"
            ],
            "allowAuthKinds": [
                "Final",
                "Undefined"
            ],
            "allowCofStoreUsages": [
                "Cit",
                "PartialShipment",
                "Instalment",
                "Recurring",
                "UnspecifiedMit",
                "DelayedCharge"
            ],
            "orderClass": "Sale",
            "allowCVV2": true
        },
        "receipt": {
            "consumer": {
                "email": "pg@bspb.ru",
                "phone": "+79211234567"
            },
            "items": [
                {
                    "desc": "Товар 1",
                    "quantity": 1,
                    "price": 100.00,
                    "taxRate": "1",
                    "type": "1",
                    "mode": "1"
                },
                {
                    "desc": "Товар 2",
                    "quantity": 1,
                    "price": 200.00,
                    "taxRate": "1",
                    "type": "2",
                    "mode": "4"
                }
            ],
            "payments": [
                {
                    "type": 1,
                    "amt": 200.00
                }
            ]
        },
        "fdoKind": "PayKiosk",
        "custAttrs": [],
        "reportPubs": {}
    }
}