API Capusta.Space: принимай переводы
и собирай донаты через свой сайт

Capusta.Space — универсальное решение для работы с онлайн-переводами и платежами. API построено на REST-принципах, работает с реальными объектами и обладает предсказуемым поведением. С помощью этого API можно отправлять запросы на оплату, получать информацию о созданных счетах, а также многое другое.
API в качестве основного протокола использует HTTP, потому подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (например cURL).
1
API поддерживает POST и GET-запросы
2
POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов.
3
API всегда возвращает ответ в формате JSON, независимо от типа запроса
Базовый URL для API:
https://api.capusta.space/v1/partner

Авторизация

Каждому проекту, созданному пользователем сервиса Capusta.Space, выдается уникальный секретный токен для авторизации. Его можно получить в настройках проекта Личного кабинета.
У тебя ещё нет токена?! Получи его сразу после регистрации в сервисе Capusta.Space!
Каждый запрос к Capusta.API должен быть авторизован данным токеном. Авторизация производится при помощи HTTP-заголовка Authorization. Например:
 Authorization: Bearer partner@mail.com:TOKEN
Секретный токен отвечает за безопасность данных. Храни его в защищенном месте и не публикуй на сторонних ресурсах.

Создание платежа

Для создания платежа необходимо отправить POST-запрос вида
POST /payment
        {
            "id": "uniq_string",
            "amount": {
                "amount": 1000,
                "currency": "RUB"
            },
            "expire": "2020-06-17T15:45:41.000+03:00",
            "description": "...",
            "projectCode": "myproject",
            "sender": {
                "name": "...",
                "phone": "...",
                "email": "...",
                "comment": "..."
            },
            "contentUrl": "...",
            "custom": {
                "id": 1,
                "shopName": "myshop",
                "shopDescription": "Clothes",
	         // Любой набор параметров
            }
        }
Важно: суммы, передаваемые в запросах и ответах API, выражаются в копейках, потому, например, для выставления счета на 10 руб. в amount указывается значение 1000
где:

currency* - валюта (на данный момент всегда RUB),

projectCode* - символьный идентификатор проекта (выдается вместе с токеном, доступен в настройках личного кабинета и является частью постоянной ссылки на перевод произвольных сумм в адрес проекта).

Необязательные параметры:

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

amount - сумма платежа в минорных единицах (копейки). Если amount не будет передан, то будет создан счет на перевод произвольной суммы.

NEW!⭐
expire
- дата, после которой невозможна оплата счета. Указывается в формате YYYY-MM-DDTHH:MI:SS.sss±ZZ:ZZ, где ZZ:ZZ - параметр, отвечающий за смещение по стандарту UTC (формат ISO 8601). ❗❗❗ Необходимо указывать дату, находящуюся в будущем от текущего времени, иначе API отвечает кодом 400.

description - описание платежа (максимум 255 симоволов),

sender - используется для сбора ИЛИ передачи информации об отправителях средств. Подробнее тут

С помощью contentUrl можно указать ссылку или код iframe с платным цифровым контентом (например, c электронной книгой, видео, закрытым telegram-каналамом и т.п.), который должен быть показан результате оплаты счета.

custom — позволяет указывать дополнительную информацию по платежу. Поле custom и его содержимое также отправляется на callback url, указанный вами, после изменения статуса платежа.

❗❗Содержимое поля custom необходимо указывать в виде JSON-объекта. Длина JSON-объекта custom не должна превышать 255 символов без пробелов и переводов строк. JSON-объект custom должен быть первого уровня вложенности (не содержать вложенных JSON-объектов)

В ответ метод отдает объект платежа вида:
 {
    "amount": {
        "amount": 1000,
        "commission": 0,
        "currency": "RUB"
    },
    "created_at": "2019-09-22T13:50:16.119Z",
    "description": "...",
    "id": "some_string",
    "projectId": 6,
    "status": "CREATED",
    "payUrl": "https://get.capusta.space/bill/uuid"
}
Если статус платежа "CREATED", то необходимо перенаправить пользователя на payUrl

Создание мультисчёта

API Causta.Space предоставляет возможность создавать "мультисчета" - это счета, которые можно оплачивать неограниченное количество раз по одной и той же ссылке. Тело запроса на создание мультисчёта полностью аналогичное телу запроса создания платежа:
POST /bill
  {
            "id": "uniq_string",
            "amount": {
                "amount": 1000,
                "currency": "RUB"
            },
             "expire": "2020-06-17T15:45:41.000+03:00",
             "description": "...",
             "projectCode": "myproject",
             "sender": {
                "name": "...",
                "phone": "...",
                "email": "...",
                "comment": "..."
            },
             "contentUrl": "...",
             "custom": {
                "id": 1,
                "shopName": "myshop",
                "shopDescription": "Clothes",
	         // Любой набор параметров
            }
В данном случае id - это идентификатор счета, а не платежа. Так же, как и в методе создания платежа он может передаваться, а может генерироваться автоматически. Платежам же в таком случае системой будет генерироваться уникальный строковый идентификатор. В уведомлениях на callback_url в тело так же будет добавлен billId - идентификатор мультисчёта.

Остальные параметры — идентичны запросу создания платежа.

Форма оформления заказа и для сбора доната: запрос дополнительных сведений о плательщиках

Чтобы запросить имя отправителя перевода, email, телефон и позволить ему оставить комментарий, сообщение или свой адрес, добавь в тело запроса /payment или /bill объект sender. Например:
POST /payment
 {
            "id": "uniq_string",
            "amount": {
                "amount": 1000,
                "currency": "RUB"
            },
            "description": "...",
            "projectCode": "myproject",
            "sender": {
                "name": "...",
                "phone": "...",
                "email": "...",
                "comment": "...",
            }  
        }
Внимание! В примере указаны все допустимые поля. В реальном запросе можно использовать только нужные.

Используй вместо comment поле "message": "...", чтобы предлагать пользователю оставить сообщение.

Используй вместо comment поле "address": "...", чтобы предлагать пользователю указать адрес доставки.
Поля могут передаваться как пустыми (плательщику нужно будет заполнить их), так и предзаполненными (плательщик сможет скорректировать значения в них, при необходимости).
Если у пользователя запрашивается email, после успешной оплаты на него него будет автоматически выслана квитанция.

Параметры необязательно включать в запрос, если они настроены тобой по умолчанию в личном кабинете

Создание выплаты

Внимание! Метод выплат недоступен по умолчанию и предоставляется по запросу в support@capusta.space
Для создания выплаты необходимо отправить POST-запрос вида:
POST /payout
{
    "id": "your-transaction-id",
    "amount": {
        "amount": 10000,
        "currency": "RUB"
    },
    "projectCode": "lalala",
    "pan": "1111111111111111",
    "description": "any description"
}
где amount - сумма выплаты в минорных единицах,
currency - код валюты (в настоящее время только RUB),
projectCode - идентификатор проекта (вместо него может быть использован projectId, если известен числовой идентификатор проекта),
pan - номер карты,
id - уникальный идентификатор выплаты
а description - любое текстовое описание для выплаты.
Параметр id не является обязательным, однако в случае создания выплаты мы настоятельно рекомендуем указывать его для того, чтобы иметь возможность получить статус выплаты в случае если по каким-то причинам ответ от метода не был получен

В качестве результата метод возвращает объект выплаты обогащенный идентификатором операции:
{
    "id": "some_string",
    "amount": {
        "amount": 10000,
        "currency": "RUB"
    },
    "projectCode": "lalala"
}

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

Обновленная версия метода. Предыдущая — поддерживается.
Для использования обновлённого метода используйте базовый URL

https://api.capusta.space/v2/partner
В любой момент есть возможность получить статус по любой из транзакций или счету с помощью GET-запроса:
GET /status?transaction-id=...
Пример запроса:
https://api.capusta.space/v2/partner/status?transaction-id=22738e1c-5945
Ответ для счёта содержит в себе информацию о счете (контент, признак мультисчета, expire и другое) + все успешные транзакции, совершенные по данному счету.

Ответ для транзакции — информацию о счете + информацию о конкретной транзакции.

Пример ответа для счёта или транзакции по счёту:
{
    "publicId": "76c39ccd-8ab8",
    "partnerPaymentId": null,
    "amount": {
        "amount": 100,
        "commission": 0,
        "currency": "RUB"
    },
    "status": "CLOSED",
    "description": "",
    "contentUrl": null,
    "projectId": 91,
    "projectCode": "new_testinggg",
    "payUrl": "https://capu.st/stg-bill76c39ccd-8ab8",
    "sender": null,
    "expire": null,
    "custom": null,
    "multiBill": false,
    "billPaymentEnabled": true,
    "createdAt": "2020-07-24T10:42:05.000+0000",
    "transactions": [
        {
            "id": "40f73049-ce05",
            "amount": {
                "amount": 100,
                "commission": 0,
                "currency": "RUB"
            },
            "status": "SUCCESS",
            "createdAt": "2020-08-11T13:20:39.000+0000",
            "updatedAt": "2020-08-11T13:21:09.000+0000"
        }
    ]
}
Пример ответа для выплаты:
{
    "id": "22738e1c-5945",
    "amount": {
        "amount": 5000,
        "commission": 5000,
        "currency": "RUB"
    },
    "description": "",
    "projectId": 91,
    "projectCode": null,
    "contentUrl": null,
    "sender": null,
    "custom": null,
    "expire": null,
    "testPayment": false,
    "status": "SUCCESS",
    "payUrl": null,
    "created_at": "2020-04-16T12:40:43.000+0000",
    "updated_at": "2020-04-16T12:40:43.000+0000"
}
Предыдущая версия метода
Работает с v1/partner

В любой момент есть возможность получить статус по любой из транзакций с помощью GET-запроса:

GET /status?transaction-id=...

В ответе будет получен объект транзакции с актуальным статусом по данному идентификатору:

{
"amount": {
"amount": 1000,
"commission": 0,
"currency": "RUB"
},
"created_at": "2019-09-22T13:50:16.119Z",
"description": "...",
"id": "...", "projectId": 6,
"status": "SUCCESS",
"pay_url": "https://get.capusta.space/{partner}/{project_code}/{payment_id}"
}

Уведомления и переадресация

При любом изменении статуса транзакции на Сallback Url проекта отправляется оповещение следующего вида:
{
            "amount": {
                "amount": 1000,
                "commission": 0,
                "currency": "RUB"
            },
            "transactionId": "some_string",
            "status": "SUCCESS",
            "custom": {
                "id": 1,
                "shopName": "myshop",
                "shopDescription": "Clothes",
           // Любой набор параметров
            }
        }
где transactionId — это идентификатор платежа,
status — может принимать значения SUCCESS и FAIL
custom
— набор произвольных параметров, переданных при создании счета (передается, если был использован в методе /payment)
Пример ответа для мультисчета:
{
            "amount": {
                "amount": 1000,
                "commission": 0,
                "currency": "RUB"
            },
            "transactionId": "some_string",
            "billId": "some_string",
            "status": "SUCCESS",
            "custom": {
                "id": 1,
                "shopName": "myshop",
                "shopDescription": "Clothes",
           // Любой набор параметров
            }
        }
где transactionId — это идентификатор платежа,
billId — идентификатор оплачиваемого мультисчета.
status — может принимать значения SUCCESS и FAIL
custom — набор произвольных параметров, переданных при создании счета (передается, если был использован в методе /bill)

В качестве подтверждения подлинности запроса нужно проверить заголовок Authorization, который строится по тому же принципу, что и для вызовов API Capusta.Space.

Для проекта могут быть назначены Success Url и Fail Url — это адрес страницы сайта или проекта, который можно использовать для переадресации плательщика после проведения оплаты (по умолчанию, совпадает с ссылкой на проект). Плательщик попадет туда, нажав на кнопку "Вернуться на сайт".

Если оплата прошла успешно, плательщик сможет перейти на Success Url, а в случае ошибки платежа — на Fail Url.

Эти ссылки можно обогатить параметром ?payment_id=, куда будет подставляться id операции. Это поможет персонализировать страницу, на которую возвращается плательщик или настроить необходимую бизнес-логику.

Чтобы прописать Callback, Success и Fail URL, нажми кнопку или напиши нам в Telegram
Настрой уведомления

Получение реестра операций

Получить список операций за выбранный период возможно с помощью GET-запроса:
GET /registry?projectId=1
&from=2020-02-17T12:19:47.000%2B04:00
&to=2020-02-17T14:19:47.000%2B04:00
или
GET /registry?projectCode=kotiki
&from=2020-02-17T12:19:47.000%2B04:00
&to=2020-02-17T14:19:47.000%2B04:00
где projectId - идентификатор проекта (числовой),
projectCode - код проекта (строковый),
from - левая граница запрашиваемого временного интервала,
to - правая граница запрашиваемого временного интервала

❗❗❗ Для указания проекта необходимо использовать один из известных вам параметров - projectId или projectCode (в ЛК он называется ID проекта).

Даты указываются в формате YYYY-MM-DDTHH:MI:SS.sss±ZZZZ, где ZZZZ - параметр, отвечающий за смещение по стандарту UTC. (формат ISO 8601)

❗❗❗ При указании смещения по UTC необходимо экранировать знак "+", заменяя "+" на "%2B". Пример запроса со смещением вправо (знак "+"). Пример запроса со смещением вправо (знак "+"):
GET /registry?projectId=1
&from=2020-02-17T12:19:47.000%2B04:00
&to=2020-02-17T14:19:47.000%2B04:00
Пример запроса со смещением влево (знак "-"):
GET /registry?projectId=1
&from=2020-02-17T12:19:47.000-04:00
&to=2020-02-17T14:19:47.000-04:00
Максимальный возможный временной интервал для запроса реестра — 1 / сутки.
В ответе будет получен список транзакций, совершенных пользователем за выбранный период времени:
[
    {
        "id": "beb54af1-2b08",
        "status": "CREATED",
        "amount": {
            "amount": 10000,
            "commission": 0,
            "currency": "RUB"
        },
        "description": "Оплата счёта",
        "projectId": 1,
        "projectCode": "test_project",
        "created_at": "2020-02-17T10:19:47.000+0000",
        "updated_at": "2020-02-17T10:19:47.000+0000",
        "payUrl": "https://capu.st/bill/beb54af12b08",
        "contentUrl": "https://www.youtube.com/watch?v=Om6aN8wKKIg",
        "sender": {
            "name": "Ivan",
            "email": "ura@capusta.space",
            "phone": +79991112233,
            "comment": "Оплата счёта",
            "message": null,
            "address": null
        }
    },
    {
        "id": "asd12ff3-87a1",
        "status": "SUCCESS",
        "amount": {
            "amount": 5000,
            "commission": 5000,
            "currency": "RUB"
        },
        "description": "Вывод средств",
        "projectId": 1,
        "projectCode": "test_project",
        "created_at": "2020-02-17T10:19:47.000+0000",
        "updated_at": "2020-02-17T10:19:47.000+0000",
        "payUrl": "https://capu.st/bill/asd12ff387a1",
        "contentUrl": "https://www.youtube.com/watch?v=Om6aN8wKKIg",
        "sender": {
            "name": "Konstantin",
            "email": "tysuper@capusta.space",
            "phone": +79991112233,
            "comment": null,
            "message": "Вывод средств",
            "address": null
        }
    }
]

API для партнёров: создание новых пользователей и проектов

Внимание! Метод создания новых проектов недоступен по умолчанию и предоставляется по запросу в support@capusta.space
API Capusta.Space предоставляет возможность создания новых пользователей в системе. Для этого необходимо отправить запрос вида:
POST /project
{
    "email": "user@capusta.space",
    "projectLink": "https://project.link",
    "callbackUrl": "https://project.link/callback",
    "failUrl": "https://project.link/fail",
    "successUrl": "https://project.link/success"
}
где email — это email адрес нового пользователя,
projectLink — URL проекта нового пользователя, а callbackUrl, failUrl и successUrl — ссылки для получения уведомлений для данного проекта.
В ответ возвращается структура вида:
{
    "merchantId": 1,
    "projectId": 1,
    "projectCode": "code",
    "token": "very_secret_token"
}
Если пользователя с email указанном в запросе не существует, то он будет создан и в ответ будет возвращены его данные: merchantId - идентификатор продавца, projectId - идентификатор проекта, projectCode - символьный код проекта, а token, соответственно, его секретный токен.

Если же пользователь с таким email уже существует, то token в ответе возвращен не будет. Пользователю с существующим email-адресом придет уведомление о том, что твой проект хочет получить возможность создавать платежи от его имени, и только в случае согласия пользователя на твой callback_url придет уведомление с токеном пользователя:
{
    "merchantId": 1,
    "projectId": 1,
    "token": "token"
}
Чтобы легко определить, что это нотификация именно о подтверждении пользователя а не, к примеру, о совершенном платеже, в URL параметры запроса добавляется переменная action=partner

Лайфхаки

Создание перевода с предзаполненной суммой и другими данными

Обращаться к API необязательно, если нужно указывать желаемую сумму перевода. С этой целью используй параметр ?amount= в постоянной ссылке для приема переводов, которая выдается всем проектам сразу после регистрации.

Разберем на примере. Проекту была выдана ссылка для приема переводов: https://get.capusta.space/demo. По ней, по умолчанию, для всех открывается форма с пустым полем для ввода суммы.

Если хочется, чтобы по умолчанию в нём было указано 150 рублей, "обогати" ссылку этой суммой (в копейках) с помощью параметра
?amount=15000. Получится вот так: https://get.capusta.space/demo?amount=15000.

Разницу можешь ощутить, перейдя по ссылкам ;)

NEW!⭐
По аналогии можно использовать и другие параметры.
name= — для предзаполнения имени
phone= — для предзаполнения номера телефона
email= — для предзаполнения адреса электронной почты
comment= ИЛИ message= ИЛИ address= — для предзаполнения комментария ИЛИ сообщения ИЛИ адреса.

Чтобы использовать несколько параметров, перечисляй их с помощью символа & (например, ?name=Nikolay&phone=899199191111)

Отправителю средств можно запретить редактировать любое значение, добавив параметр readonly=. В нем нужно перечислить названия параметров, редактирование которых требуется запретить. Если таких несколько, используй между ними %2C (вместо запятой).

Таким образом, если мы хотим попросить Николая перевести нам 1000 рублей и оставить нам свой номер телефона, ссылка может выглядеть вот так: https://get.capusta.space/demo?name=Nikolay&phone=&amount=100000&readonly=name%2Camount.

В ней с помощью параметра name=Nikolay мы обозначили имя отправителя (можно использовать кириллицу, но при условии декодирования url — подробности и инструментарий тут). С помощью параметра phone=, мы обозначили, что мы хотим узнать номер телефона Николая. С помощью параметра amount=100000, мы указали сумму 1000 рублей в копейках. А с помощью параметра readonly=name%2Camount, запретили Николаю изменять имя и сумму перевода.
Получилось? Ну ваще ты программист(ка)!!!

Интеграция с Tilda

Если ты продаешь 2-3 товара и всегда оплачивается один из них — можно просто создать ссылки на их оплату и вставить их в кнопку на твоем сайте. А данные о покупателях собирать через форму прямо на платежной странице без изменения настроек твоего сайта. Если нужная форма в Tilda у тебя уже есть — вот, как подключить к ней оплату.

Если нужно отправлять клиентов на оплату заказов, сумма которых зависит от количества товаров и/или способа их доставки, используй блок «Корзина: ST100» и следующую инструкцию.

Настройка оплаты заказов через блок «Корзина: ST100» в Tilda

Чтобы из корзины сайта, сделанном в Тильде (блок ST100), отправлять покупателей на оплату через Capusta.Space, нужно:

  1. В подразделе "Формы" настроек твоего Тильдо-сайта добавить сервис "Webhook"
  2. Прописать URL https://api.capusta.space/v1/callback/tilda и нажать "Сохранить". Согласиться на подключение сервиса "Webhook" ко всем формам.
  3. В списке подключенных сервисов перейти в настройки "Webhook: api.capusta.space/v1/callback/tilda", установить чекбоксы "Посылать UTM" и "Передавать данные по товарам в заказе - массивом" и нажать на кнопку "Изменить".
  4. В разделе "Платежные системы" настроек Тильдо-сайта выбрать "Безналичный расчет".
  5. В "URL успеха" вставить ссылку для принятия переводов из твоего проекта в Capusta.Space и сохранить изменения. Поля "Наименование оплаты" и "Сообщение об успехе" можно заполнить произвольно.
  6. На странице, где размещен блок с корзиной (ST100) необходимо разместить блок "HTML-код" (T123). Его можно вставить в футер сайта, если блок с корзиной используется на нескольких страницах.
  7. В HTML-блоке нажать кнопку для редактирования контента. Ввести код:
    <script type="text/javascript" src="https://my.capusta.space/tilda.js"></script>
  8. Сохранить изменения и опубликовать страницы.
Готово! Заказы будут оплачиваться через сервис Capusta.Space

Настройка оплаты через блок «Форма» в Tilda

С этой инструкцией можно настроить любую форму в Tilda на прием платежей:

  1. В подразделе "Формы" настроек твоего Тильдо-сайта добавить сервис "Webhook"
  2. Прописать URL https://api.capusta.space/v1/callback/tilda и нажать "Сохранить". Согласиться на подключение сервиса "Webhook" ко всем формам.
  3. В списке подключенных сервисов перейти в настройки "Webhook: api.capusta.space/v1/callback/tilda", установить чекбоксы "Посылать UTM" и "Передавать данные по товарам в заказе - массивом" и нажать на кнопку "Изменить".
  4. На странице, где размещен блок с формой (например, BF204N) необходимо разместить блок "HTML-код" (T123). Его можно вставить в футер сайта, если блок с формой используется на нескольких страницах.
  5. В HTML-блоке нажать кнопку для редактирования контента. Ввести код:
    <script type="text/javascript" src="https://my.capusta.space/tilda.js"></script>
  6. В настройках полей для ввода формы BF204N добавить скрытое поле с именем переменной capusta-payment-page и ввести в качестве значения адрес своей страницы для приема переводов через Capusta.Space (выдается сразу после регистрации).
  7. Форма BF204N должна содержать поле, в котором должна передаваться общая сумма выставляемого счета (она может как вводиться вручную, так быть скрытым или высчитываемым полем). Этому полю необходимо задать имя переменной — amount
  8. Сохранить изменения и опубликовать страницы.
Готово! Теперь при отправке формы в Capusta.Space будут выставляться счета на оплату, а пользователи сразу переадресовываться на страницу оплаты.

Есть пожелания по улучшению API?
Мы с радостью с ними ознакомимся! Оставь предложение через форму или напиши нам в Telegram
Имя
E-mail
Ваше предложение
Как видишь, всё очень просто! Если у тебя ещё нет токена, получи его сразу после регистрации в сервисе Capusta.Space и приступай к интеграции :)