API SmartPay

Независимо от способа создания смартапа (через Code, Graph, webhook и т. д.), вы можете использовать следующие методы для подключения приема платежей:

Создание счета.
Проведение платежа.
Получение статуса.
Подтверждение оплаты.
Отмена счеты.
Возврат платежа: полный и частичный.

Авторизация

В заголовке каждого запроса необходимо передавать токен в следующем формате:

Имя заголовка: Authorization
Тип токена: Bearer
Токен: <платежный токен>

Подробнее о получении параметров авторизации — в разделе Получение токена.

Создание счета

Для создания счета на проведение платежа используйте запрос POST /invoices.

Пример тела запроса:

{
  "user_id": {
    "partner_client_id": "43u111539f0q"
  },
  "ptype": 0,
  "invoice": {
    "purchaser": {
      "email": "qq@dd.eof",
      "phone": "9123456789",
      "contact": "email"
    },
    "delivery_info": {
      "address": {
        "country": "RU",
        "city": "Москва",
        "address": "ул. Вавилова, 19, офис 1"
      },
      "delivery_type": "courier",
      "description": "Перезвонить за 1,5 часа"
    },
    "invoice_params": [
      {
        "key": "packageName",
        "value": "com.MashaAndTheBear.HairSalon"
      }
    ],
    "order": {
      "order_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "order_number": "145",
      "order_date": "2020-04-29T08:17:03+03",
      "service_id": "223",
      "amount": 11836,
      "currency": "RUB",
      "purpose": "Покупка в игре «Маша и Медведь, салон красоты Чародейка».",
      "description": "Покупка внутриигрового контента в игре «Маша и Медведь, салон красоты Чародейка».",
      "language": "ru-RU",
      "expiration_date": "2022-05-20T10:07:44.337Z",
      "tax_system": 0,
      "order_bundle": [
        {
          "position_id": 1,
          "name": "Кучка из 100 кристаллов для использования при нырянии",
          "item_params": [
            {
              "key": "packageName",
              "value": "com.MashaAndTheBear.HairSalon"
            }
          ],
          "quantity": {
            "value": 1.05,
            "measure": "кг."
          },
          "item_amount": 11836,
          "currency": "RUB",
          "item_code": "com.MashaAndTheBear.HairSalon.crystal100",
          "item_price": 11836,
          "discount_type": "percent",
          "discount_value": 5.25,
          "interest_type": "agentPercent",
          "interest_value": 15.105,
          "tax_type": 6,
          "tax_sum": 2367,
          "image": "https://i-love-png.com/images/grim-reaper-icon.png"
        }
      ]
    }
  }
}

Пример ответа:

{
  "error": {
    "user_message": "",
    "error_description": "",
    "error_code": "0"
  },
  "invoice_id": "1234567890"
}

Проведение платежа

Для оплаты счета используйте запрос POST /invoices/{invoice_id}.

Пример тела запроса

{
  "user_id": {
    "partner_client_id": "43u111539f0q"
  },
  "operations": [
    {
      "operation": "payment",
      "code": "sbrf_spasibo",
      "value": "19800"
    }
  ],
  "device_info": {
    "device_platform_type": "iOS",
    "device_platform_version": "13.6.1",
    "device_model": "iPhone 7",
    "device_manufacturer": "Apple",
    "device_id": "83c3f257-46d8-41fe-951b-f79d04e288c2",
    "surface": "SBOL",
    "surface_version": "11.5.0"
  },
  "return_url": "string",
  "fail_url": "string",
  "return_deeplink": "string"
}

Пример ответа

{
  "error": {
    "user_message": "",
    "error_description": "",
    "error_code": "0"
  },
  "form_url": "https://3dsec.sberbank.ru/payment/merchants/test/payment_ru.html?mdOrder=70906e55-7114-41d6-8332-4609dc6590f4",
  "deeplink": "sberbankonline://connect?addcard",
  "product": {
    "provider": "applestore",
    "product_code": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "quantity": 1.5,
    "user_uid": {
      "user_uid": "d43f2eb6-f299-439b-8a3b-43b114531f0d"
    },
    "params": [
      {
        "key": "packageName",
        "value": "com.MashaAndTheBear.HairSalon"
      }
    ],
    "inapp_type": "consumable"
  }
}

При завершении оплаты приходит сообщение PAY_DIALOG_FINISHED, которое позволяет определить статус счета. Сообщение можно получить независимо от типа платежа — одностадийный или двухстадийный.

Получение статуса

После создания счета вы можете проверить, успешно ли прошел платеж. Для этого используйте следующий запрос: GET /invoices/{invoice_id}.

Пример запроса:

curl -X GET "https://smartmarket.online.sberbank.ru/smartpay/v1/invoices/ad454ffg-6c54-4b01-90e6-d701748f0851?inv_status=executed&wait=50" -H "accept: application/json"

Пример ответа:

{
  "error": {
    "user_message": "",
    "error_description": "",
    "error_code": "0"
  },
  "invoice_id": "1234567890",
  "invoice_date": "2020-04-29T08:18:03+03",
  "invoice_status": "created",
  "invoice": {
    "purchaser": {
      "email": "qq@dd.eof",
      "phone": "9123456789",
      "contact": "email"
    },
    "delivery_info": {
      "address": {
        "country": "RU",
        "city": "Москва",
        "address": "ул. Вавилова, 19, офис 1"
      },
      "delivery_type": "courier",
      "description": "Перезвонить за 1,5 часа"
    },
    "invoice_params": [
      {
        "key": "packageName",
        "value": "com.MashaAndTheBear.HairSalon"
      }
    ],
    "order": {
      "order_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "order_number": "145",
      "order_date": "2020-04-29T08:17:03+03",
      "service_id": "223",
      "amount": 11836,
      "currency": "RUB",
      "purpose": "Покупка в игре «Маша и Медведь, салон красоты Чародейка».",
      "description": "Покупка внутриигрового контента в игре «Маша и Медведь, салон красоты Чародейка».",
      "language": "ru-RU",
      "expiration_date": "2022-05-20T12:55:16.118Z",
      "tax_system": 0,
      "trade_name": "Romashka",
      "visual_name": "Покупка/продление подписки",
      "org_name": "ООО Ромашка",
      "org_inn": "1234567890",
      "visual_amount": "1 500,45 ₽",
      "order_bundle": [
        {
          "position_id": 1,
          "name": "Кучка из 100 кристаллов для использования при нырянии",
          "item_params": [
            {
              "key": "packageName",
              "value": "com.MashaAndTheBear.HairSalon"
            }
          ],
          "quantity": {
            "value": 1.05,
            "measure": "кг."
          },
          "item_amount": 11836,
          "currency": "RUB",
          "item_code": "com.MashaAndTheBear.HairSalon.crystal100",
          "item_price": 11836,
          "discount_type": "percent",
          "discount_value": 5.25,
          "interest_type": "agentPercent",
          "interest_value": 15.105,
          "tax_type": 6,
          "tax_sum": 2367,
          "image": "https://i-love-png.com/images/grim-reaper-icon.png"
        }
      ]
    }
  },
  "image": "https://i-love-png.com/images/grim-reaper-icon.png",
  "payment_info": {
    "payment_date": "2022-05-20T12:55:16.118Z",
    "payment_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "payment_params": {
      "key": "googlePurchaseToken",
      "value": "ameinkbophchljaejnocadib.AO-J1Oyrh3GSPGrLocZlW4UXiilTv_fMDz8Wpjadky8-26BhzBPMiwtoKql706e3ntW2BQNdl9WSiBjsjLebCcz3BhFyM7FVxDnOB1TFeeA0SHnco9j8G_OZVxghv7bwXWLgWsaUUGfw"
    },
    "device_info": {
      "device_platform_type": "iOS",
      "device_platform_version": "13.6.1",
      "device_model": "iPhone 7",
      "device_manufacturer": "Apple",
      "device_id": "83c3f257-46d8-41fe-951b-f79d04e288c2",
      "surface": "SBOL",
      "surface_version": "11.5.0"
    },
    "loyalty_info": {
      "service_code": "sbrf_spasibo",
      "service_name": "Сбербанк Спасибо",
      "change_rate": 1,
      "payment_bonus": 19800,
      "award_bonus": 21850,
      "image": "https://i-love-png.com/images/grim-reaper-icon.png"
    },
    "card_id": "ad454ffg-6c54-4b01-90e6-d701748f0851",
    "name": "Главная",
    "paysys_code": "RBS-shortname",
    "masked_pan": "**1111",
    "expiry_date": "201912",
    "cardholder": "Ivan Petrov",
    "payment_system": "Visa",
    "payment_system_image": "https://smartmarkettestift.online.sberbank.ru/icons/logo_visa.png",
    "image": "https://smartmarkettestift.online.sberbank.ru/icons/sberbank_mastercard_league_legends.jpeg",
    "paysys": "Эквайринг Сбербанка",
    "paysys_image": "https://www.sberbank.ru/common/img/uploaded/redirected/s_m_business/acquiring/assets/images/intro@2x.png",
    "payment_way": "Sber Pay",
    "payment_way_code": "SberPay",
    "payment_way_logo": "https://cdn1.telegram.one/i/f7640dada78306b1c993e04001b8738d/828b1eb30921659e22e53a9edc92c4c4/24e01830d213d75deb99c22b9cd91ddd",
    "bank_info": {
      "bank_name": "ПАО Сбербанк",
      "bank_country_code": "RU",
      "bank_country_name": "Россия",
      "bank_image": "https://emoji.slack-edge.com/TKK9DHNCV/sber/ad2df81a6cd9812d.png"
    }
  },
  "payment_methods": {
    "user_message": "Для подключения подписки сохраните банковскую карту в мобильном приложении СалютАпп",
    "methods": [
      {
        "method": "QR",
        "action": "Оплатить по QR-коду"
      }
    ]
  }
}

Подтверждение оплаты

Для успешного завершения двухстадийного платежа по счету используйте запрос PUT /invoices/{invoice_id}.

Параметры запроса будут зависеть от того, на полную или не полную сумму делается подтверждение.

Параметры для полной суммы:

Если необходимо завершить покупку на полную сумму, достаточно передать в качестве path-параметра значение для invoice_id.

Параметры для неполной суммы:

Если завершение делается на неполную сумму и при создании счета товара была передана корзина, при завершении необходимо также передать новую товарную корзину, сумма позиций которой должна совпадать с суммой завершения.

Пример запроса для неполной суммы:

{
  "invoice": {
    "order": {
      "amount": 11836,
      "currency": "RUB",
      "order_bundle": [
        {
          "position_id": 1,
          "name": "Кучка из 100 кристаллов для использования при нырянии",
          "item_params": [
            {
              "key": "packageName",
              "value": "com.MashaAndTheBear.HairSalon"
            }
          ],
          "quantity": {
            "value": 1.05,
            "measure": "кг."
          },
          "item_amount": 11836,
          "currency": "RUB",
          "item_code": "com.MashaAndTheBear.HairSalon.crystal100",
          "item_price": 11836,
          "discount_type": "percent",
          "discount_value": 5.25,
          "interest_type": "agentPercent",
          "interest_value": 15.105,
          "tax_type": 6,
          "tax_sum": 2367,
          "image": "https://i-love-png.com/images/grim-reaper-icon.png"
        }
      ]
    }
  }
}

Пример ответа

{
    "error": {
        "error_code": "0",
        "user_message": "Оплата проведена",
        "error_description": ""
    }
}

Отмена счета

Для отмены счета используйте запрос DELETE /invoices/{invoice_id}.

Пример запроса

{
    "invoice_id": "1234567890",
    "author": "" 
}

Пример ответа

{
    "error": {
        "error_code": "0",
        "user_message": "Отмена выполнена",
        "error_description": ""
    }
}

Полный возврат платежа

Для возврата средств на полную сумму используйте запрос PATCH /invoices/{invoice_id}.

Для возврата на полную сумму необходимо передать параметр invoice_id в качестве path-параметра.

Пример запроса

{
    "invoice_id": "1234567890",
    "author": "" 
}

Пример ответа

{
    "error": {
        "error_code": "0",
        "user_message": "Возврат выполнен",
        "error_description": ""
    }
}

Частичный возврат платежа

Для оформления частичного возврата суммы используйте запрос PATCH /invoices/{invoice_id}. Возврат можно сделать только из статуса confirmed. В рамках одной операции частичные возвраты можно делать неограниченное количество раз. Главное условие — возвращаемый товар должен совпадать по составу и количеству с товаром из корзины.

Для частичного возврата необходимо передать invoice_id в качестве path-параметра и корзину возвращаемых товаров в теле запроса.

Пример тела запроса:

{
  "invoice": {
    "order": {
      "current_amount": 20038,
      "refund_amount": 11836,
      "currency": "RUB",
      "order_bundle": [
        {
          "position_id": 1,
          "name": "Кучка из 100 кристаллов для использования при нырянии",
          "quantity": {
            "value": 1.05,
            "measure": "кг."
          },
          "item_amount": 11836,
          "item_code": "com.MashaAndTheBear.HairSalon.crystal100"
        }
      ]
    }
  }
}

Пример ответа

{
    "error": {
        "error_code": "0",
        "user_message": "Возврат выполнен",
        "error_description": ""
    }
}

Коды ответа

В ответ на каждый запрос могут возвращаться следующие коды:

Код ответа	Описание
200	Запрос обработан успешно
400	Один из параметров в запросе передан в некорректном формате, либо формат запроса некорректный
403	Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки

Обновлено 15 июля 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней