Developer

H2H API — Host-to-Host интеграция

Описание

Документ описывает три эндпоинта H2H API: создание счёта, получение информации о счёте и список доступных методов оплаты.
Поддерживаемые валюты: RUB, UZS, KGS, KZT, AZN, TJS.
Для теста используйте Postman. Файл настроек: скачать коллекцию.

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

Все запросы требуют заголовки Client-Id и Client-Secret.
Ключи доступны в разделе «Кассы» → иконка шестерни рядом с нужным мерчантом.

POST https://crocopay.tech/api/v2/h2h/invoices

Эндпоинт 1 — Создать счёт

Создаёт новый счёт на оплату. В ответ возвращает ID счёта и платёжные реквизиты (номер карты или телефона).

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


POST /api/v2/h2h/invoices HTTP/1.1
Host: crocopay.tech
Client-Id: GnHqauRCUVtB8sECR7m
Client-Secret: vpBpXo7REyApkDnLIOpMR3lk1ndaLmY2qoZptV9cHOtjJLUDsW26GBSe2kda1IVQIMR758Z
Content-Type: application/json

{
    "amount": 500000,
    "currency": "RUB",
    "payment_option": "TO_CARD",
    "callback_url": "https://example.com/payment?user_id=42"
}

Параметры запроса

Параметр	Описание	Обязательный	Тип	Пример
`Client-Id` (Header)	Идентификатор кассы	Да	String	GnHqauRCUVtB8sECR7m
`Client-Secret` (Header)	Секретный ключ кассы	Да	String	vpBpXo7RE…MR758Z
`amount`	Сумма в минимальных единицах валюты (копейки для RUB, тийины для UZS и т.д.)	Да	Integer	500000 (= 5000.00 RUB)
`currency`	Валюта платежа (ISO 4217)	Да	String	RUB, UZS, KGS, KZT, AZN, TJS
`payment_option` ^*	Способ оплаты — зависит от валюты	Да	String	TO_CARD, SBP, QR_NSPK…
`callback_url` ^**	URL для уведомления об успешной оплате. GET-параметры сохраняются.	Да	String	https://example.com/pay?user_id=42

^* Доступные значения payment_option по валютам

payment_option	Описание	Реквизит	Валюта
🇷🇺 RUB — Россия
TO_CARD	Перевод на банковскую карту (любой банк РФ)	Номер карты	RUB
SBP	Перевод по СБП — любой банк РФ	Номер телефона	RUB
SBP_ALFA	Перевод по СБП — Альфа-Банк	Номер телефона	RUB
SBP_TBANK	Перевод по СБП — Т-Банк	Номер телефона	RUB
QR_NSPK	Оплата по QR-коду НСПК	QR-код	RUB
MOBILE_PHONE	Пополнение мобильного телефона	Номер телефона	RUB
TO_CARD_TRANSGRAN	Трансграничный перевод на карту (любой банк)	Номер карты	RUB
SBP_TRANSGRAN	Трансграничный перевод по СБП (любой банк)	Номер телефона	RUB
TRANSGRAN_ALFA	Трансграничный — Альфа-Банк	Номер карты / телефона	RUB
TRANSGRAN_VTB	Трансграничный — ВТБ	Номер карты / телефона	RUB
TRANSGRAN_SBER	Трансграничный — SberPay	Номер телефона	RUB
TRANSGRAN_TPAY	Трансграничный — TPay (Т-Банк)	Номер карты / телефона	RUB
🇺🇿 UZS — Узбекистан
UZCARD	Перевод на карту UzCard	Номер карты	UZS
HUMO	Перевод на карту Humo	Номер карты	UZS
PAYME	Перевод через PayMe	Номер карты / телефона	UZS
CLICK	Перевод через Click	Номер карты / телефона	UZS
🇰🇿 KZT — Казахстан
BANK_TRANSFER	Банковский перевод (Казахстан)	Номер карты	KZT
🇦🇿 AZN — Азербайджан
BANK_TRANSFER	Банковский перевод (Азербайджан)	Номер карты	AZN
🇹🇯 TJS — Таджикистан
KORTI_MILLI	Перевод — Корти Милли	Номер карты	TJS
DUSHANBE_CITY	Перевод — Душанбе Сити Банк	Номер карты	TJS
🇰🇬 KGS — Кыргызстан
TO_CARD	Перевод на банковскую карту (Кыргызстан)	Номер карты	KGS

^** В callback_url можно передавать произвольные GET-параметры (например, user_id, order_id). При успешной оплате они будут возвращены в callback.

Пример ответа — реквизиты карты (TO_CARD)


HTTP/1.1 200 OK

{
    "id": "911c2823-f55b-43b5-9881-d5653107f7dc",
    "status": "Pending",
    "amount": 500000,
    "currency": "RUB",
    "payment_option": "TO_CARD",
    "card": "4276 1234 5678 9012",
    "bank_receiver": "Сбербанк",
    "card_owner": "IVAN PETROV",
    "expires_at": "2025-01-15T12:30:00Z"
}

Пример ответа — реквизиты телефона (SBP / TRANSGRAN_SBER)


HTTP/1.1 200 OK

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "Pending",
    "amount": 500000,
    "currency": "RUB",
    "payment_option": "SBP",
    "card": "+79001234567",
    "bank_receiver": "Альфа-Банк",
    "card_owner": "ANNA SIDOROVA",
    "expires_at": "2025-01-15T12:30:00Z"
}

Пример ответа — ошибка


HTTP/1.1 422 Unprocessable Entity

{
    "status": "error",
    "message": "payment_option TO_CARD is not enabled for currency UZS"
}

GET https://crocopay.tech/api/v2/h2h/invoices/{invoice_id}

Эндпоинт 2 — Получить информацию о счёте

Возвращает текущий статус и реквизиты счёта по его UUID. Используйте для polling'а до момента оплаты.

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


GET /api/v2/h2h/invoices/911c2823-f55b-43b5-9881-d5653107f7dc HTTP/1.1
Host: crocopay.tech
Client-Id: GnHqauRCUVtB8sECR7m
Client-Secret: vpBpXo7REyApkDnLIOpMR3lk1ndaLmY2qoZptV9cHOtjJLUDsW26GBSe2kda1IVQIMR758Z

Параметр	Описание	Обязательный	Тип
`invoice_id` (URL)	UUID счёта, полученный при создании	Да	UUID
`Client-Id` (Header)	Идентификатор кассы	Да	String
`Client-Secret` (Header)	Секретный ключ кассы	Да	String

Возможные статусы счёта

Статус	Описание
`Pending`	Ожидает оплаты
`Success`	Оплачен
`Expired`	Истёк срок оплаты
`Cancelled`	Отменён
`Failed`	Ошибка при оплате

GET https://crocopay.tech/api/v2/h2h/payment-method/available

Эндпоинт 3 — Доступные методы оплаты

Возвращает список методов оплаты, доступных для вашей кассы. Используйте перед созданием счёта, чтобы показать плательщику корректный список вариантов.

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


GET /api/v2/h2h/payment-method/available HTTP/1.1
Host: crocopay.tech
Client-Id: GnHqauRCUVtB8sECR7m
Client-Secret: vpBpXo7REyApkDnLIOpMR3lk1ndaLmY2qoZptV9cHOtjJLUDsW26GBSe2kda1IVQIMR758Z

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


HTTP/1.1 200 OK

{
    "methods": [
        { "currency": "RUB", "payment_option": "TO_CARD",      "name": "Карта (любой банк РФ)" },
        { "currency": "RUB", "payment_option": "SBP",           "name": "СБП (любой банк РФ)" },
        { "currency": "RUB", "payment_option": "SBP_ALFA",      "name": "СБП Альфа-Банк" },
        { "currency": "RUB", "payment_option": "QR_NSPK",       "name": "QR НСПК" },
        { "currency": "RUB", "payment_option": "TRANSGRAN_SBER","name": "Трансгран · SberPay" },
        { "currency": "UZS", "payment_option": "TO_CARD",       "name": "Карта (Узбекистан)" },
        { "currency": "TJS", "payment_option": "TO_CARD",       "name": "Карта (Таджикистан)" },
        { "currency": "AZN", "payment_option": "TO_CARD",       "name": "Карта (Азербайджан)" },
        { "currency": "KZT", "payment_option": "TO_CARD",       "name": "Карта (Казахстан)" },
        { "currency": "KGS", "payment_option": "TO_CARD",       "name": "Карта (Кыргызстан)" }
    ]
}

Webhook (Callback)

После успешной оплаты CrocoPAY отправляет POST-запрос на ваш callback_url.


POST /payment?user_id=42 HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "timestamp": 1734617868,
    "subtotal": 500000,
    "percentage": 0,
    "charge_percentage": 0,
    "charge_fixed": "0.00000000",
    "total": 500000,
    "sign": "0162f16847ceb010dfc0e754475d09e27c88b8c0fe23829efd3b04876dd230d2"
}

Проверка подписи (PHP)


$expected = hash_hmac('sha256',
    "{$_POST['timestamp']}|{$_POST['subtotal']}|{$_POST['percentage']}|" .
    "{$_POST['charge_percentage']}|{$_POST['charge_fixed']}|{$_POST['total']}",
    $yourClientSecret
);

if (!hash_equals($expected, $_POST['sign'])) {
    http_response_code(403);
    exit('Invalid signature');
}
// платёж подтверждён