Integration Guide with Kukuruku
System Overview
Kukuruku is a platform that connects users with merchants through a unified wallet and authentication system.
Components
| Component | Description | URL |
|---|---|---|
| Kukuruku | Aggregator website — displays merchants, enables balance top-up and gameplay | kukuruku.win |
| KukuPay | Unified wallet for deposits, withdrawals and balance management | wallet.kukuruku.win |
| KukurukuID | OAuth 2.0 authentication server based on OpenID Connect | auth.kukuruku.win |
API Base URL
https://api.kukuruku.win
All API endpoints use this base URL. For local development: https://api.kukuruku.local.
Getting Started
Register your project with the Kukuruku team through the merchant dashboard or contact your account manager. The credentials you receive depend on the integration scenario you choose.
Integration Scenarios
Kukuruku supports three integration scenarios. Choose the one that fits your needs, or combine them for full functionality.
1. Payment Integration
Accept deposits from Kukuruku users and process withdrawals back to their KukuPay wallets.
Credentials required:
| Credential | Description | Where to find |
|---|---|---|
merchant_id | Your unique merchant identifier | Merchant dashboard → Profile (header) |
secret_key | Secret key for signing API requests | Merchant dashboard → Profile → "Api secret" |
What you get:
- Create payin orders (user deposits to your platform)
- Create payout orders (withdraw from your platform to KukuPay)
- Receive real-time callbacks on order status changes
- Query order status at any time
Authentication: HMAC-SHA512 request signature — no OAuth required.
2. KukurukuID (OAuth 2.0)
Add "Login with KukurukuID" to your website. Users authenticate through Kukuruku's OAuth 2.0 server and you receive their profile data.
Credentials required:
| Credential | Description | Where to find |
|---|---|---|
client_id | OAuth 2.0 client identifier | Request from support team via chat |
client_secret | OAuth 2.0 client secret (for server-side apps) | Request from support team via chat |
redirect_uri | Approved callback URL(s) for your application | Agreed with support team |
What you get:
- Single Sign-On for Kukuruku users
- Access to user profile (name, email, currency)
- Authorization Code flow (server-side) or PKCE (client-side)
Authentication: OAuth 2.0 access tokens — no merchant_id or secret_key required.
3. Auto-Login (Play Button)
When a user clicks "Play" on a merchant card in Kukuruku, they are automatically redirected to your platform with authentication and a pre-paid order. This combines Payment Integration and KukurukuID.
Credentials required: All credentials from both scenarios above:
| Credential | Used for | Where to find |
|---|---|---|
merchant_id | Order creation | Merchant dashboard → Profile |
secret_key | Request signature | Merchant dashboard → Profile → "Api secret" |
client_id | OAuth 2.0 authentication | Request from support team via chat |
client_secret | Token exchange | Request from support team via chat |
redirect_uri | Callback after authentication | Agreed with support team |
What you get:
- Seamless user experience — one click from Kukuruku to your platform
- Automatic order creation and payment
- User auto-login via KukurukuID
Requirements: Both Payment Integration and KukurukuID must be configured.
Authentication Methods
Kukuruku API uses two authentication methods depending on the context:
| Method | When to use | Details |
|---|---|---|
| Request Signature | Server-to-server API calls (orders, callbacks) | HMAC-SHA512 signature in signature HTTP header. Details |
| OAuth 2.0 Token | User context API calls (/api/v1/me) | Bearer token in Authorization header. Details |
Amount Format
All monetary amounts in the API are specified in the smallest currency unit (kopecks for RUB, cents for USD):
| Display amount | API value | Currency |
|---|---|---|
| 500 RUB | 50000 | RUB |
| 10.50 USD | 1050 | USD |
| 100 USDT | 10000 | USDT |
Order Statuses
| Status | Description |
|---|---|
created | Order created, awaiting payment |
processing | Payment is being processed |
paid | Payment completed successfully |
cancelled | Order cancelled |
expired | Order expired (not paid in time) |
failed | Payment failed |
Support
For integration questions, contact the Kukuruku team through your merchant dashboard or reach out to your account manager.