Skip to main content

Integration Guide with Kukuruku

System Description​

Kukuruku is an aggregator website for merchants, allowing new clients to navigate to merchant websites and automatically top up their balance with a specific merchant.

System Components​

  • Kukuruku – the aggregator website enabling client redirection to merchant sites.
  • KukuPay – a unified wallet through which clients can top up their balance with merchants.
  • KukurukuID – OAuth 2.0 server for client authentication and authorization.

Core Features​

The system allows clients to: View information about connected merchants on Kukuruku, navigate to a merchant’s website, top up their balance in KukuPay, top up their balance with a merchant via KukuPay, and authenticate using KukurukuID.

Interaction Scenarios​

  1. Creating a top-up order on Kukuruku’s side: The client is on the Kukuruku website. They create an order through the Kukuruku interface to top up their balance with a merchant. The order is paid. Kukuruku sends a callback to the merchant confirming the transaction.

  2. Modifying balance via Kukuruku API: The client is on the merchant’s website and uses KukuPay to change the balance with the merchant. The merchant sends a request to create an order in Kukuruku. Kukuruku maps (or creates) the client in its system and sends a callback to the merchant.

  3. Integration via OAuth 2.0: The client is on the merchant's website and chooses KukurukuID as the authentication method. The client authenticates. The merchant creates a balance update order via the Kukuruku API using the client’s access_token on behalf of the user.

  4. Auto-registration and balance transfer: The client is on Kukuruku’s site. They click the "Play" button. Kukuruku automatically creates and pays the order. The client is redirected to the merchant’s site with the parameter auto_login=true (e.g., https://merchant1.kukuruku.win?auto_login=true&auth_url=https%3A%2F%2Fauth.kukuruku.pay%2Frealms%2Fpublic). The merchant checks for auto_login=true and initiates client authentication using auth_url via KukurukuID.

The merchant maps the incoming client to an existing client by the email obtained from the authentication token or creates a new client in their system. Kukuruku asynchronously sends a callback to the merchant confirming the transaction, including the client’s email.

On the merchant’s side, the client info is mapped either at the time of client creation or when receiving the callback about the successful payment.

Important: The merchant must trust the callback and update the client’s balance accordingly for it to be shown on their side.

Kukuruku API​

Each request to the Kukuruku API must either:

  1. Be without a client session – and include the signature in the HTTP headers (details on request signing).
  2. Be within a client session – and include an access token from KukurukuID (more on OAuth 2.0).

  • Create Payment Invoice POST /api/v1/orders/payins​

If a client wants to top up the balance from the Merchant’s page via KukuPay, get domain from tds-app-18.icu/api/v1/domains?type=api and then send a request using the domain:

Example URI

POST /api/v1/orders/payins

Request with body

Response 200

  • Create Payout Invoice POST /api/v1/orders/payouts​

If the client wants to withdraw funds from the Merchant balance to the KukuPay balance, get domain from tds-app-18.icu/api/v1/domains?type=api and then send a request using the domain:

Example URI

POST /api/v1/orders/payouts

Request with body

Response 200

Response 400

  • Retrieve Order Information GET /api/v1/orders/{id}​

Using the client token, you can retrieve the order status by calling the API with the following data:

Example URI

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

where id - string (required) - the identifier of the order.

Response 200

  • Payment Notification Callback POST /callback​

If a client topped up their balance via an invoice, we will send a request to your API with the following data:

  • Note! The request will be sent to the Merchant’s API: https://company.com

Example URI

POST /callback

Request with body

Response 200

Kukuruku User Context API​

User Context API provides endpoints that are accessed by merchants on behalf of end users using OAuth 2.0 access tokens.

All requests within this API are executed in the context of the authenticated user and allow merchants to retrieve or manage user-related data authorized by the user.

  • Get current user GET /api/v1/me​

Returns information about the currently authenticated user.​

This endpoint returns user data based on the provided OAuth access token. The request is executed in the context of the authenticated user and does not require a user identifier.

Example URI

GET /api/v1/me

Request with body

Response 200