API-ключи, окружения test и live, scopes и заголовки, которые принимает recv.

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

Developer API recv (https://recv.money/v1) авторизует каждый запрос API-ключом. Ключи создаются в Developer Portal и принадлежат одному workspace.

Доступ к API требует тарифа, который включает API. Тарифы Developer и Business включают его; Trial и Merchant — нет. Ключ на тарифе без API-доступа получает 403 Forbidden.

Передача ключа

Передавайте ключ в любом из заголовков — оба принимаются:

# Предпочтительно
curl https://recv.money/v1/me -H "X-API-Key: $RECV_API_KEY"

# Также поддерживается
curl https://recv.money/v1/me -H "Authorization: Bearer $RECV_API_KEY"

Если присутствуют оба, используется X-API-Key.

Окружения: test и live

Каждый ключ привязан к одному окружению, закодированному в префиксе:

Префикс	Окружение	Поведение
`test_`	test	Создает тестовые счета. Live-воркеры блокчейна их игнорируют. Их можно пометить оплаченными через симулятор платежей.
`live_`	live	Создает реальные счета, оплачиваемые on-chain на ваш кошелек.

Окружение созданного счета следует за ключом, который его создал — в теле запроса нет поля mode. Держите отдельные ключи test_ и live_ и никогда не используйте live-ключ для тестов.

Scopes

Ключи несут один или оба scope:

Scope	Дает доступ
`invoices:read`	`GET /v1/invoices`, `GET /v1/invoices/:id`
`invoices:write`	`POST /v1/invoices`, `POST /v1/invoices/:id/cancel`, `POST /v1/test/invoices/:id/simulate-payment`

Если создать ключ без указания scopes, он получает оба по умолчанию. Вызов, требующий отсутствующий scope, возвращает 403 с ошибкой вроде API key scope invoices:write is required. (Для GET /v1/me scope не требуется.)

Информация о текущем ключе

GET /v1/me возвращает workspace, тариф, текущее использование и метаданные самого ключа:

curl https://recv.money/v1/me -H "X-API-Key: $RECV_API_KEY"

{
  "key": {
    "id": 7,
    "label": "Server key",
    "prefix": "live_b3c4",
    "environment": "live",
    "scopes": ["invoices:read", "invoices:write"]
  },
  "usage": { "monthly_requests": 128, "monthly_limit": 50000 }
}

Лучшие практики безопасности

Только на сервере. Никогда не передавайте ключ в браузер, мобильное приложение или клиентский код и не коммитьте его в репозиторий.
Используйте переменные окружения. Храните секрет в RECV_API_KEY или менеджере секретов вашей платформы.
Ротируйте при подозрении. Отзовите скомпрометированный ключ в Developer Portal и создайте новый. Полный секрет показывается только один раз при создании.
Разделяйте окружения. Используйте разные ключи test_ и live_.

Пример (Node.js)

const response = await fetch("https://recv.money/v1/me", {
  headers: { "X-API-Key": process.env.RECV_API_KEY }
});
const data = await response.json();

← НазадQuickstart Далее →Invoices

Готовы принимать криптоплатежи?

Запустить Консоль Сети