Skip to content

Commit

Permalink
Initial commit
Browse files Browse the repository at this point in the history
  • Loading branch information
Andrey Mayorov committed Feb 9, 2017
0 parents commit 5e7fae7
Show file tree
Hide file tree
Showing 20 changed files with 626 additions and 0 deletions.
2 changes: 2 additions & 0 deletions .gitignore
@@ -0,0 +1,2 @@
mkdocs/site
plantuml-toolset
13 changes: 13 additions & 0 deletions Makefile
@@ -0,0 +1,13 @@
FORMAT := png svg
SOURCEDIR := $(CURDIR)/content
STYLE := plantuml-toolset/super-serious-style.isvg

all: plantuml-toolset

plantuml-toolset:
git clone https://github.com/rbkmoney/plantuml-toolset.git

update-toolset: plantuml-toolset
cd $< && git pull

-include plantuml-toolset/wsd.mk
35 changes: 35 additions & 0 deletions README.md
@@ -0,0 +1,35 @@
# RBKmoney public docs

После деплоя документация будет доступна по адресу [https://rbkmoney.github.io/docs/](https://rbkmoney.github.io/docs/)

## Сборка

Для генерации статического сайта с документацией мы используем [MkDocs](http://www.mkdocs.org/). Убедитесь, что в используемой вами системе наличествует [make](https://www.gnu.org/software/make/), актуальная версия [Python](https://python.org) и его верный менеджер [pip](https://pypi.python.org/pypi/pip/).

Для начала установите необходимый инструментарий:

```shell
pip install -r requirements.txt
```

После чего вы уже можете запускать локальный сервер для разработки с готовой документацией:

```shell
mkdocs serve --livereload
```

### Диаграммы

Для генерации картинок из диаграмм на языке [PlantUML](http://plantuml.com) мы используем простой в использовании [platinum-toolset](https://github.com/rbkmoney/platinum-toolset). Будьте внимательны, для работы этому инструменту необходима Java Runtime.

Установить его можно при помощи:

```shell
make install-toolset
```

Теперь, чтобы сгенерировать изображения png и svg из файлов с диаграммами wsd, достаточно всего лишь:

```shell
make
```
8 changes: 8 additions & 0 deletions content/api.md
@@ -0,0 +1,8 @@
<!DOCTYPE html>
<meta charset="utf-8">
<title>Redirecting...</title>
<link rel="canonical" href="https://rbkmoney.github.io/api/">
<meta http-equiv="refresh" content="0; url=https://rbkmoney.github.io/api/">
<h1>Redirecting...</h1>
<a href="https://rbkmoney.github.io/api/">Click here if you are not redirected.</a>
<script>location="https://rbkmoney.github.io/api/"</script>
18 changes: 18 additions & 0 deletions content/index.md
@@ -0,0 +1,18 @@
# Добро пожаловать в RBKmoney!

Наша платежная платформа позволяет подключить на ваш веб-сайт прием платежей с пластиковых карт в интернете в виде готового плагина для Drupal, 1C-Bitrix и других, в виде готовой платежной формы в iframe, а также и с помощью кастомной платёжной формы, использующей наши JS-библиотеки и публичные API.
С нами вы можете организовать прием платежей в интернете быстро и гибко так, как это нужно именно вам. Мы создаем продукт, который удобен не только для бизнеса, но и для разработчиков.

## Быстрый старт

- [Зарегистрируйтесь](https://dashboard.rbk.money/) на нашем сайте для того, чтобы получить возможность сразу же начать техническую интеграцию и провести платежи в уже созданном для вас тестовом магазине.
- Прочитайте [обзор](/integrations/overview) технической интеграции с платформой.
- Выберите решение, которое наиболее подходит для вас:
+ Вы не разработчик, используете готовые решения для продажи товаров и услуг в интернете и хотите быстро организовать прием платежей на вашем сайте? [Прочтите инструкцию по быстрой настройке платежных модулей](#).
+ Вы хотите минимизировать время подключения и затраты на разработку? Попробуйте наше [готовое решение по приему платежей](/integrations/checkout).
+ Вы хотите полностью управлять внешним видом и действиями плательщика прямо на вашем сайте? Реализуйте собственную кастомную форму и [интегрируйтесь](/integrations/tokenizer) с платформой, использующей наше API для приема платежей.

## Нужна помощь?

- Прочитайте [полную документацию](https://rbkmoney.github.io/api/) по нашим публичным API.
- Мы отвечаем на [вопросы](https://github.com/rbkmoney/docs/issues) и принимаем [предложения по изменениям](https://github.com/rbkmoney/docs/pulls) в нашем публичном репозитории этой документации на [Github](https://github.com/rbkmoney/docs).
87 changes: 87 additions & 0 deletions content/integrations/checkout.md
@@ -0,0 +1,87 @@
Платежная форма Checkout предоставляет собой готовое техническое решение, использующее HTML, CSS и наши JS-библиотеки, которое позволяет сделать рендер платежной формы для ввода данных карт в веб-браузере плательщика. Форма отдается с веб-серверов RBKmoney и открывается в iFrame таким образом, чтобы создать для плательщика внешнюю видимость нахождения на сайте мерчанта.
Checkout валидирует и отправляет на нашу серверную часть карточные данные плательщика, а наша библиотека tokenizer.js в ответ возвращает токен платежного средства, который используется для создания транзакций на стороне вашего серверного кода.

## Пример кода инициализации платежной формы

```html
<script src="http://checkout.rbk.money/payframe/payframe.js" class="rbkmoney-checkout"
data-key="your_tokenizer_key"
data-invoice-id="e213ed1"
data-order-id="1"
data-endpoint-init="http://<your-server-side>/init_endpoint"
data-endpoint-events="http://<your-server-side>/events_endpoint"
data-endpoint-success="http://<your-server-side>/success_endpoint"
data-endpoint-failed="http://<your-server-side>/failed_endpoint"
data-amount="7,700"
data-currency="Р"
data-logo="http://<your-server-side>/logo.png"
data-button-color="rgb(39, 136, 181)"
data-name="Company name">
</script>
```

```
data-key - ключ для токенизации карточных данных
data-invoice-id - номер инвойса
data-order-id - номер вашего заказа
data-endpoint-init - инициализация платежа
data-endpoint-events - страница получения статуса инвойса, платежа
data-endpoint-success и data-endpoint-failed - страницы для отправки запроса в случае успеха или неуспеха
data-amount - поле для вывода в платежной форме стоимости заказа
data-currency - для вывода в платежной форме типа валюты
data-logo - путь к логотипу, который будет отображаться в платежной форме
data-button-color - цвет кнопки для вызова платежной формы
data-name - название компании, которое будет отображаться в платежной форме
```
```
data-endpoint-init - url на который форма отправит POST запрос
с данными для инициализации платежа. В ответ ожидается ответ
со статусом 200, который форма воспринимает как успешный запуск платежа.
Пример запроса:
```
```json
{
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: {
invoiceId: <invoiceId>,
token: <token>,
session: <token session>,
contractInfo: {
email: <payer email>
}
}
}
```
```
data-endpoint-events - url на который форма будет
отправлять GET запросы для получения событий платежа.
Пример запроса:
```
```js

`<your url>?invoiceId=<your invoiceId>&orderId=<your orderId>`, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
}
}
```
```
data-endpoint-success и data-endpoint-failed - страницы для отправки запроса в случае успеха или неуспеха
url's на который придет POST запрос в случае успешного или неуспешного платежа.
Пример запроса:
```
```js
{
method: 'POST',
headers: {
'Content-Type': 'x-form-urlencoded'
}
}
```

После чего необходимо реализовать серверную часть для инициализации платежа, получения статусов заказа и обработку запросов в случае успеха и неуспеха.
74 changes: 74 additions & 0 deletions content/integrations/overview.md
@@ -0,0 +1,74 @@
## Регистрация в личном кабинете

Перед началом работы с платформой вам будет необходимо пройти регистрацию в [личном кабинете мерчанта](https://dashboard.rbk.money/).

!!! note "Мерчант (Merchant)"
Участник технического и финансового взаимодействия, предоставляющий товары и услуги, выставляющий инвойсы и имеющий возможность вывести средства из системы.

!!! note "Платформа (Platform)"
Программно-аппаратный комплекс RBKmoney, обеспечивающий техническую реализацию бизнес-процессов по приему платежей

## Магазины

Магазин – это способ обобщения товаров и услуг, объединённых одной категорией, которые вы продаете вашим клиентам. К конкретным магазинам привязаны ваши счета, на которых аккумулируются средства плательщиков, впоследствии перечисляемые вам с помощью банковских переводов или других средств вывода.

!!! note "Плательщик (Payer)"
Физическое лицо, покупатель ваших товаров и услуг, который владеет платёжными средствами и участвует в процессах оплаты созданных вами инвойсов. Уникальным обязательным идентификатором плательщика в системе является его email.

Магазины могут быть тестовыми и активными. Тестовый магазин – магазин с тестовой категорией товаров или услуг, по которому разрешен запуск платежей только с использованием [тестовых банковских карт](/refs/testcards/), а также запрещены процессы вывода средств с помощью банковских переводов.

!!! note "Информация"
Тестовые магазины используют ту же производственную среду, что и активные, поэтому их можно использовать для мониторинга доступности платформы.

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

## Инвойсы

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

!!! note "Платёж (Payment)"
Процесс в рамках инвойса, в ходе которого средства плательщика поступают в вашу пользу в виде финансовых обязательств платформы. После того, как инвойс полностью оплачен, вы должны приступить к исполнению своих обязательств перед плательщиком, например направить товар в службу доставки или оказать обещанную услугу.

В магазине, в рамках которого вы создаёте инвойсы, на ваше усмотрение вы можете включить доставку callback-уведомлений на указанный вами URL вашей серверной части. Платформа отправляет подобные уведомления, чтобы как можно скорее уведомить о важных изменениях инвойса, например, по факту полной его оплаты.

## Прием платежей

В общем случае последовательность действий с платформой выглядит так:

- С помощью вызова нашего API вы создаете в платформе инвойс, который используется для дальнейшего списания средств.
- Вы встраиваете платежную форму в браузер плательщика, а именно:
- открываете iframe с нашей платежной формой и передаете в него параметры, или
- верстаете платежную форму самостоятельно и вызываете ее с ваших серверов.
- После ввода плательщиком данных банковской карты на платежной форме наша библиотека tokenizer.js отправляет полученные данные на нашу серверную часть, и получает в ответ токен платежного средства.
- Платёжная форма передает полученный токен на вашу серверную часть.
- С вашей серверной стороны вы инициируете запуск платежа, после чего начинаете опрашивать изменения состояния инвойса или ожидает callback-уведомлений.

### Диаграмма последовательности взаимодействия

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

!!! note "Информация"
Callback-уведомления являются синхронными, то есть платформа посчитает инвойс оплаченным только после того, как успешно доставит соответствующее уведомление до вашей серверной части.

![/wsd/custom_form_w_cb.png](/wsd/custom_form_w_cb.png)

## Авторизация запросов

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

### Ключ токенизации

Публикуемый в открытом доступе ключ (_Tokenizer Key_), который позволяет платежным формам авторизоваться на нашем API и получить платежный токен, в дальнейшем используемый для списания средств с платежного инструмента плательщика. Вы можете публиковать этот ключ без ограничений.

### API-ключ

Ваш приватный ключ (_API Key_), используемый для авторизации вашей серверной части. Этот ключ используется для наиболее критичных действий, таких, как инициация списания средств с платежного инструмента плательщика. Этот ключ должен быть доступен и известен только вам.

## Авторизация callback-уведомлений

В обратной ситуации, в тех случаях, когда ваша серверная часть получает callback-уведомления на указанный вами URL, вам необходимо убедиться, что уведомление действительно было отправлено платформой. Для решения этой задачи в каждом магазине указан публичный ключ (_Callback Key_), служащий для проверки подписи, передаваемой с каждым callback-уведомлением.

## Сценарии интеграции

- Вы хотите интегрировать готовую платежную форму Checkout, которая обеспечивает оркестрацию всего процесса платежа? Вам [сюда](/integrations/checkout).
- Вы хотите интегрировать вашу кастомную платежную форму с платформой? Тогда вам [сюда](/integrations/tokenizer).

0 comments on commit 5e7fae7

Please sign in to comment.