Справочник API

Справочник

Маршруты, объектные модели, перечисления, конфигурация и форматирование ошибок.

Ссылка на маршрут

Метод	Маршрут
GET	`/api/partner/v1/companies`
Auth Сессия Назначение Список компаний пользователя Возвращает команды, доступные для инструментов портала аутентифицированного пользователя MakeCrypto.
POST	`/api/partner/v1/onboarding/company`
Auth Секрет onboarding партнера Назначение Создать ссылку onboarding компании Создает черновик onboarding, предварительно заполненный партнером, и возвращает URL для получения merchant.
GET	`/api/partner/v1/makepay/payment-links`
Auth Ключ MakePay API Назначение Список или создание платежных ссылок Читает платежные ссылки компании, связанной с ключом API, или создает хостинговые ссылки checkout MakePay.
POST	`/api/partner/v1/makepay/payment-links`
Auth Ключ MakePay API или публично Назначение Список или создание платежных ссылок Читает платежные ссылки компании, связанной с ключом API, или создает хостинговые ссылки checkout MakePay.
POST	`/gateway/pay/{makepayKeyId}`
Auth Публичный ключ формы Назначение Отправить HTML-форму оплаты Принимает поля формы из браузера, создает хостинговую платежную ссылку и перенаправляет покупателя в checkout.
GET	`/api/partner/v1/makepay/payment-links/{uid}`
Auth Ключ MakePay API Назначение Прочитать или обновить платежную ссылку Читает детали платежной ссылки или меняет ее статус на active, paused или archived.
PATCH	`/api/partner/v1/makepay/payment-links/{uid}`
Auth Ключ MakePay API Назначение Прочитать или обновить платежную ссылку Читает детали платежной ссылки или меняет ее статус на active, paused или archived.
POST	`/api/partner/v1/makepay/payment-links/{uid}/send-request-email`
Auth Ключ MakePay API Назначение Отправить запрос на оплату Отправляет или повторно отправляет хостинговую ссылку на e-mail клиента.
GET	`/api/partner/v1/makepay/subscriptions`
Auth Ключ MakePay API Назначение Список или создание подписок Возвращает планы регулярных подписок MakePay или создает подписку и первый счет.
POST	`/api/partner/v1/makepay/subscriptions`
Auth Ключ MakePay API Назначение Список или создание подписок Возвращает планы регулярных подписок MakePay или создает подписку и первый счет.
GET	`/api/partner/v1/makepay/customers`
Auth Ключ MakePay API Назначение Список или обновление клиентов Возвращает профили клиентов MakePay или создает/обновляет клиентов по e-mail.
POST	`/api/partner/v1/makepay/customers`
Auth Ключ MakePay API Назначение Список или обновление клиентов Возвращает профили клиентов MakePay или создает/обновляет клиентов по e-mail.
POST	`/api/partner/v1/makepay/customers/{customerId}/portal`
Auth Ключ MakePay API Назначение Создать ссылку клиентского портала По запросу генерирует подписанный URL клиентского портала MakePay, действительный 24 часа.
GET	`/api/partner/v1/timezones`
Auth Публичный Назначение Список часовых поясов Возвращает поддерживаемые идентификаторы часовых поясов IANA.
GET	`/api/partner/v1/makepay/settings`
Auth Ключ MakePay API Назначение Прочитать или обновить настройки MakePay Читает или обновляет настройки расчетов, редиректов, комиссий и обработки недоплаты.
PUT	`/api/partner/v1/makepay/settings`
Auth Ключ MakePay API Назначение Прочитать или обновить настройки MakePay Читает или обновляет настройки расчетов, редиректов, комиссий и обработки недоплаты.
GET	`/api/partner/v1/makepay/destination-assets`
Auth Ключ MakePay API Назначение Список целевых активов Возвращает поддерживаемые расчетные активы и текущий актив по умолчанию.
GET	`/api/partner/v1/makepay/webhook-requests`
Auth Ключ MakePay API Назначение Список доставок webhook Показывает попытки доставки payment и subscription webhooks, а также статус повторных попыток.

Регистрация партнера OAuth

POST /api/partner/v1/onboarding/company может включать дополнительный объект oauth. MakeCrypto проверяет приложение OAuth, URI перенаправления, области и запрос PKCE перед созданием внутренней ссылки. Когда merchant завершает регистрацию, MakeCrypto создает компанию, предоставляет приложению OAuth доступ к этой компании и перенаправляет на зарегистрированный redirectUri с авторизацией code.

{
  "idempotencyKey": "merchant_123",
  "company": {
    "name": "Acme Markets",
    "website": "https://acme.example"
  },
  "oauth": {
    "clientId": "mco_app_example",
    "redirectUri": "https://apps.makecrypto.io/oauth/callback",
    "scope": "company:read makepay:payment-links:write makepay:settings:read",
    "state": "merchant_123",
    "codeChallenge": "PKCE_S256_CODE_CHALLENGE",
    "codeChallengeMethod": "S256"
  }
}

Приложение partner должно сохранить соответствующий code_verifier PKCE и заменить код, возвращенный с помощью POST /oauth/token.

Объект PaymentLink

Поле	Парень	Оценки
`id`	`string`	Внутренний UUID.
`uid`	`string`	Идентификатор общедоступной платежной ссылки, используемый в размещенных и встроенных маршрутах checkout.
`status`	`"active" \| "paused" \| "archived"`	Состояние канала, управляемого merchant.
`payload`	`PaymentLinkPayload`	Поля времени выполнения «Заказ», «Сумма», «Клиент», «Перенаправление», «metadata», «Бренд» и «merchant».
`created_at`	`string`	Временная метка ISO.
`updated_at`	`string`	Временная метка ISO.
`expires_at`	`string \| null`	Разрешенная временная метка истечения срока действия или `null` без истечения срока действия.
`publicUrl`	`string`	URL из checkout, размещенный MakePay, включенный в ответы создания, списка, подробностей и обновления статуса.

Платежная ссылкаПолезная нагрузка

Поле	Парень	Оценки
`title`	`string`	Видимая этикетка платежа.
`description`	`string`	Описание видно клиенту.
`amount`	`string`	Десятичная сумма, подлежащая сбору.
`fiatCurrency`	`string`	Дополнительная визуальная валюта, например `USD` или `EUR`.
`currency`	`string`	Символ расчета, например `USDT`, `USDC` или `BTC`.
`asset`	`string`	Точный идентификатор целевого актива. Используйте его, когда символ существует в нескольких строках.
`orderId`	`string`	Ссылка на заказ или счет-фактуру для merchant.
`customerEmail`	`string`	Используется для электронных писем и полезных данных webhook.
`clientId`	`string`	Необязательный идентификатор клиента на стороне merchant.
`returnUrl`	`string`	URL из merchant для общей обратной навигации.
`successUrl`	`string`	URL из merchant для завершенных платежей.
`failureUrl`	`string`	URL из merchant для неудавшихся или отмененных платежей.
`expirationTime`	`"15m" \| "1h" \| "12h" \| "24h" \| "72h" \| "never"`	Запрошенная продолжительность платежной ссылки.
`metadata`	`Record<string, unknown>`	Метаданные, определенные merchant и возвращаемые на информационных панелях и webhooks.
`runtimeMode`	`"merchant_target_net_v2"`	Введено API для новых платных ссылок.
`billingVersion`	`"v2"`	Введено API для новых платных ссылок.
`merchantName`	`string`	Введено от бренда компании, если таковое имеется.
`merchantPictureUrl`	`string`	Вводится из профиля компании, если он доступен.
`merchantLogoUrl`	`string`	Впрыскивается от бренда merchant, когда он доступен.
`merchantPaymentLinkTheme`	`"light" \| "dark" \| "system"`	Внедрено из конфигурации темы checkout merchant.

Объект клиента

Поле	Парень	Оценки
`id`	`string`	Внутренний UUID.
`uid`	`string`	Публичный идентификатор клиента MakePay, используемый в ссылках на портал.
`email`	`string`	Электронная почта клиента.
`name`	`string \| null`	Отображаемое имя клиента. Редактируется с портала.
`clientId`	`string \| null`	Идентификатор клиента merchant. Только чтение на портале.
`metadata`	`Record<string, unknown>`	Метаданные определены merchant.
`createdAt`	`string`	Временная метка ISO.
`updatedAt`	`string`	Временная метка ISO.
`urls`	`{ customerPortal: string }`	Присутствует в ответах на создание портала. Не сохраняйте этот URL.

Ответ клиентского портала

POST /api/partner/v1/makepay/customers/{customerId}/portal возвращает подписанный портал URL для сохраненного клиента.

json

{
  "ok": true,
  "companyId": "acct_123",
  "customer": {
    "id": "b834dd77-69b8-41a9-a4b6-95bc9dd14c2d",
    "uid": "cus_01hzy4k6p4w9y2x7e2z7n8a2xm",
    "email": "buyer@example.com",
    "name": "Ada Lovelace",
    "clientId": "client_1042",
    "metadata": {
      "source": "api"
    },
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z",
    "urls": {
      "customerPortal": "https://makepay.io/billing?company=acct_123&customer=cus_01hzy4k6p4w9y2x7e2z7n8a2xm&expires=1776765600&signature=8d1f..."
    }
  },
  "expiresAt": "2026-04-21T10:00:00.000Z"
}

URL действителен в течение 24 часов и использует проверенный компанией payment_link_domain, если он доступен. В противном случае это относится к общедоступному источнику MakePay.

Параметр запроса	Оценки
`company`	Идентификатор учетной записи компании MakeCrypto, которой принадлежит клиент.
`customer`	Клиент UID MakePay.
`expires`	Временная метка Unix в секундах.
`signature`	Подпись HMAC на `v1:{companyId}:{customerUid}:{expires}`.

Создает ссылки на портал по требованию, когда клиент открывает счет. Просроченные, измененные или другие URL-адреса клиентов отклоняются перед загрузкой данных с портала.

Объект подписки

Поле	Парень	Оценки
`id`	`string`	Внутренний UUID.
`uid`	`string`	Видимый идентификатор подписки для merchant.
`status`	`"active" \| "paused" \| "overdue" \| "cancelled"`	Текущий статус подписки.
`customerEmail`	`string`	Электронная почта клиента используется для напоминаний и сопоставления порталов.
`label`	`string`	Этикетка подписки видна покупателю.
`description`	`string \| null`	Необязательное описание.
`amountUsd`	`string`	Регулярная сумма в долларах США.
`settlementAsset`	`string`	Идентификатор целевого расчетного актива.
`cadence`	`"weekly" \| "biweekly" \| "monthly" \| "custom_months" \| "yearly"`	Визуальный ритм.
`billingIntervalUnit`	`"week" \| "month" \| "year"`	Единица расчетного интервала.
`billingIntervalCount`	`number`	Количество единиц между циклами.
`startAt`	`string`	Временная метка ISO первого платежного цикла.
`timezone`	`string`	Часовой пояс IANA, используемый для напоминаний.
`metadata`	`Record<string, unknown>`	Метаданные, определяемые merchant, и расширенные настройки перенаправления/допуска.
`cycles`	`SubscriptionCycle[]`	Сгенерированные циклы возвращаются путем перечисления маршрутов и вызовов информационной панели.

Подписки переходят на overdue, когда неоплаченный цикл превышает временную метку dueAt как минимум на 24 часа. MakePay отправляет подписанное сообщение webhook makepay.subscription.status_changed каждый раз, когда изменяется состояние подписки.

MakePayНастройки

Поле	Парень	Оценки
`status`	`"active" \| "paused"`	Доступность продукта для команды.
`defaultDestinationAsset`	`string \| null`	Идентификатор актива по умолчанию, используемый, когда ссылки отправляют только `currency`.
`feePaidBy`	`"client" \| "merchant"`	Определяет, получает ли клиент или merchant комиссионные MakePay.
`returnRedirectUrl`	`string \| null`	Резервное перенаправление после checkout.
`successRedirectUrl`	`string \| null`	Перенаправление после совершения платежа.
`failureRedirectUrl`	`string \| null`	Перенаправление после отмены или неудачного платежа.
`underpaymentPercentEnabled`	`boolean`	Включить процентный допуск.
`underpaymentPercentThreshold`	`number`	Допустимый процент недоплаты.
`underpaymentFixedEnabled`	`boolean`	Включить фиксированный допуск.
`underpaymentFixedThreshold`	`number`	Фиксированная сумма, разрешенная для недоплаты.

НазначениеАктив

Поле	Парень	Оценки
`assetIdentifier`	`string`	Каноническая строка, символ и идентификатор контракта.
`chainCode`	`string`	Код расчетной сети.
`chainName`	`string`	Читабельное имя строки.
`symbol`	`string`	Символ актива.
`name`	`string`	Имя актива.
`decimals`	`number`	Десятичные дроби токена.
`isDefault`	`boolean`	Указывает, является ли этот актив текущим дефолтным активом компании.

Значения статуса

active: Ссылку можно открыть и оплатить.
paused: ссылка по-прежнему видна для merchant, но не должна принимать новые платежи.
archived: ссылка скрыта от активных просмотров и должна считаться закрытой.

Значения статуса подписки:

active: подписка выставляет запланированные счета как обычно.
paused: merchant/напоминания и изменения клиента приостановили подписку.
overdue: по крайней мере один неоплаченный цикл просрочен на 24 часа или более.
cancelled: подписка завершена, и неоплаченные созданные циклы отменены.

Формат ошибки

Ошибки возвращают JSON с error и, если доступно, errorCode.

{
  "errorCode": "invalid_destination_asset",
  "error": "payload.asset ETH.USDT-... is not available for supported settlement routes."
}