Payment Integration

This guide covers how to create payment orders (payins and payouts) through the Kukuruku API. All requests must include an HMAC-SHA512 request signature.

API Base URL

https://api.kukuruku.win

Create Payin Order

POST /api/v1/orders/payins

Creates an order for a user to deposit funds from KukuPay to your platform.

Request

Request Fields

Field	Type	Required	Description
merchant_id	string	Yes	Your merchant identifier
amount	integer	Yes	Amount in smallest currency unit (kopecks/cents). Must be > 0
currency	string	Yes	Currency code: RUB, USD, USDT
order_number	string	Yes	Unique payment identifier in your system
callback_url	string	No	URL to receive order status callbacks
redirect_success_url	string	No	URL to redirect user on successful payment
redirect_fail_url	string	No	URL to redirect user on failed payment
customer.client_id	string	Yes	User's email address

Response 200

Field	Type	Description
success	boolean	Operation result
token	string	Order identifier in the KukuPay system (UUID)
url	string	URL to redirect the user for payment

After receiving the response, redirect the user to url to complete the payment in KukuPay.

---

Create Payout Order

POST /api/v1/orders/payouts

Creates an order to withdraw funds from your platform to the user's KukuPay wallet.

Request

Request Fields

Field	Type	Required	Description
merchant_id	string	Yes	Your merchant identifier
amount	integer	Yes	Amount in smallest currency unit. Must be > 0
currency	string	Yes	Currency code: RUB, USD, USDT
order_number	string	Yes	Unique payment identifier in your system
callback_url	string	No	URL to receive order status callbacks
user_email	string	Yes	User's email address in the Kukuruku system

Response 200

Field	Type	Description
success	boolean	Operation result
uuid	string	Order identifier in the KukuPay system

Response 400

Returned when the user_email does not match any registered KukuPay user.

---

Get Order Status

GET /api/v1/orders/{uuid}

Retrieve the current status of an order. Requires a request signature in headers.

Request

GET /api/v1/orders/8d3cd240-dc72-4535-bf93-beed2878b593

Parameter	Type	Required	Description
uuid	string (path)	Yes	Order UUID from the create order response

Response 200

Response Fields

Field	Type	Description
id	string	Internal order identifier
uuid	string	Order UUID in KukuPay
user_id	string	User identifier in Kukuruku (may be null)
user_email	string	User's email (may be null)
user_phone	string	User's phone (may be null)
type_id	string	Order type: payin or payout
status	string	Order status: created, processing, paid, cancelled, expired, failed
external_order_id	string	Your order_number from the create request
amount	integer	Amount in smallest currency unit
currency	string	Currency code
created_at	string	ISO 8601 creation timestamp
expire_at	string	ISO 8601 expiration timestamp (may be null)

tip

The response includes a signature header that you should verify to ensure the response is authentic. See Signature Verification.

---

Payment Callback

POST {your_callback_url}

When an order status changes, Kukuruku sends an HTTP POST request to the callback_url you specified when creating the order.

Important

Your server must respond with HTTP 200 and {"success": true}. If the callback fails, Kukuruku will retry with exponential backoff.

Callback Request

Callback Fields

Field	Type	Description
uuid	string	Order UUID in KukuPay
type	string	Order type: payin or payout
status	string	Order status: paid, cancelled, expired, failed
order_number	string	Your payment identifier
amount	string	Amount in smallest currency unit (string in callbacks)
currency	string	Currency code
user_id	string	User identifier in Kukuruku
user_email	string	User's email — use this to map the payment to your customer
user_phone	string	User's phone number (may be null)
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp
finished_at	string	ISO 8601 completion timestamp (may be null)

Expected Response

Signature Verification

Always verify the signature header on incoming callbacks to ensure they are genuine. See Signature Verification.

---

Integration Flow

Payin Flow (User Deposits)

1. User initiates deposit on your site
2. Your server → POST /api/v1/orders/payins (with signature)
3. Kukuruku returns { url, token }
4. Redirect user to url (KukuPay payment page)
5. User completes payment in KukuPay
6. Kukuruku → POST {callback_url} (with signature)
7. Your server verifies signature, updates user balance
8. User redirected to redirect_success_url

Payout Flow (User Withdraws)

1. User requests withdrawal on your site
2. Your server → POST /api/v1/orders/payouts (with signature)
3. Kukuruku returns { uuid }
4. Kukuruku processes the withdrawal
5. Kukuruku → POST {callback_url} (with signature)
6. Your server verifies signature, confirms withdrawal

---

Error Handling

HTTP Code	Description
200	Success
400	Invalid request (missing fields, invalid amount, user not found)
401	Invalid or missing signature
404	Order not found
500	Internal server error

All error responses follow the format:

{
  "err": "error description"
}