Developer

Express API — платёжная форма CrocoPAY

Описание

Создайте платёжную ссылку через один POST-запрос. Плательщик будет перенаправлен на форму CrocoPAY, выберет страну / способ оплаты и завершит платёж.
Для теста используйте Postman: скачать коллекцию.

Мульти-гео. Если у вашей кассы подключено несколько валют (например, RUB + UZS + TJS), на платёжной форме автоматически появится выбор страны. Плательщик выбирает свою страну — форма пересчитывает сумму по курсу и выдаёт реквизиты в его валюте.

POST https://www.crocopay.tech/api/v2/initiate-payment

Эндпоинт — Создать платёжную ссылку

Инициирует платёж и возвращает redirect_url — ссылку на платёжную форму, на которую нужно перенаправить плательщика.

Пример запроса (form-data)


POST /api/v2/initiate-payment HTTP/1.1
Host: crocopay.tech
Content-Type: application/x-www-form-urlencoded

client_id=GnHAFAZsT1ktFYqauUVtB8sECR7m
&client_secret=vpBpXN40yaWQWicAobl...R758Z
&amount=5000.00
¤cy=RUB
&successUrl=https://example.com/success
&cancelUrl=https://example.com/cancel
&callbackUrl=https://example.com/payment?user_id=42

Параметр	Описание	Обязательный	Тип	Пример
`client_id`	Идентификатор кассы. Кассы → шестерня	Да	String	GnHAFAZsT1ktFYqauUVtB8sECR7m
`client_secret`	Секретный ключ кассы. Кассы → шестерня	Да	String	vpBpXN40ya…R758Z
`amount`	Сумма платежа в базовой валюте кассы (не в копейках)	Да	Double	5000.00
`currency`	Валюта платежа (ISO 4217). Определяет базовую валюту формы.	Да	String	RUB, UZS, KGS, KZT, AZN, TJS
`successUrl`	URL для редиректа после успешной оплаты	Да	String	https://example.com/success
`cancelUrl`	URL для редиректа при отмене / ошибке	Да	String	https://example.com/cancel
`callbackUrl`	URL для webhook-уведомления об успешной оплате. GET-параметры сохраняются.	Да	String	https://example.com/payment?user_id=42

Пример ответа — успех


HTTP/1.1 200 OK

{
    "status": "success",
    "message": "Initiated payment successfully.",
    "redirect_url": "https://crocopay.tech/restapi/payment?grant_id=78784424&token=DuMJThhEimrrdiCKrW2A"
}

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


// Валюта не подключена у мерчанта
{ "status": "error", "message": "Currency UAH is not supported by this merchant." }

// Сумма равна нулю
{ "status": "error", "message": "Amount cannot be 0 or less than 0." }

// Неверные ключи
{ "status": "error", "message": "Merchant not found or credentials are invalid." }

Платёжная форма — что видит плательщик

После перехода по redirect_url плательщик попадает на форму CrocoPAY:

Ситуация	Поведение формы
Одна валюта в кассе	Сразу показываются методы оплаты для этой валюты
Несколько валют (мульти-гео)	Появляются вкладки со странами (RU / UZ / TJ…). Плательщик выбирает свою страну — сумма автоматически пересчитывается по курсу в его валюту
Смена страны	Сумма пересчитывается в валюту выбранной страны. Платёж зачисляется в валюте плательщика

Пример: Касса настроена на RUB + UZS. Сумма в запросе — 5 000 RUB. Плательщик из Узбекистана выбирает UZ — форма покажет ≈ 700 000 UZS (по текущему курсу). Мерчант получает уведомление в UZS.

Webhook (Callback)

После успешной оплаты CrocoPAY отправляет POST-запрос на ваш callbackUrl. Callback отправляется только при успешной оплате.


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

{
    "timestamp": 1753282096,
    "subtotal": 500000,
    "percentage": 0,
    "charge_percentage": 0,
    "charge_fixed": 0,
    "total": 500000,
    "sign": "ef5954715c663e3f96194a03981a0b04dd0772bfa5164afcdb507470c9c5078d"
}

Поле	Описание	Пример
`timestamp`	Unix-время платежа	1753282096
`subtotal`	Сумма платежа в минимальных единицах валюты	500000
`total`	Итоговая сумма (с учётом комиссий)	500000
`sign`	HMAC-SHA256 подпись для верификации	ef5954…078d
`percentage`, `charge_percentage`, `charge_fixed`	Зарезервированы для будущих обновлений	0

Проверка подписи (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');
}

// Платёж подтверждён — обрабатываем