Placing an order

The Kigo API allows partners to place orders for products that are tokenized and claimed inside a user's Kigo-powered wallet. This guide walks a developer through integrating with the place order API.

Prerequisites

Before making an API call to create a user-level session token, obtain a partner-level session token following the Authentication Guide.

Steps to Implement

1. Receive a Product ID

   • A partner can obtain the product_id specific to their integration from their primary contact at Kigo. Note the id will be different in the UAT and production environments.

2. Place an Order

   • Endpoint: Create a claim code for a product.
   • Purpose: This endpoint places an order for the associated product. The endpoint returns a claim_code and deeplink_url which are used as the mechanism for fulfilling the order.
   • Usage: Use the deeplink_url to redirect the user to a Kigo-powered wallet. As an optional addition, display the claim_code to the user as a backup in case the deeplink_url doesn't work or for customized fulfillment flows.

3. Using the SSO Session ID

   • URL Example:

     https://partner-hub.kigo.io?claim-code=${claim_code}
     

Key Considerations

1. The Product ID is specific to a product within Kigo's systems. Products at Kigo can be thought of as "token templates". This means the type of token the user will receive in their Kigo-powered wallet is determined by the product_id passed to the endpoint for ordering a product. Since the product depends on a partner's specific use case, partners should coordinate with their contact at Kigo to create products and tokens to suite their use case. Several common use cases are "boosted" offer bundles, gift cards, and merchandise vouchers.
2. SSO Session Integrations with Kigo require that the deeplink also contain a session_id in the url parameters. Obtain the session_id by following the Creating an SSO Session Guide. Then append the session_id to the end of the deeplink_url:

https://partner-hub.kigo.io?claim-code=${claim_code}&session-id=${session_id}

Example Workflow

1. End-user clicks a boost button inside a partner's web application.
2. The application makes an API call to the partner's server.
3. Obtain a partner-level session token using the provided endpoint in the server.
4. Make an API call to make an order to receive a deeplink_url and claim_code that can to authenticate the user into a Kigo-powered experience.
   1. (Optional) Create an SSO session by making an API call to receive a session_id, which authenticates the user into a Kigo-powered experience. Append a url parameter for the session_id to the end of the deeplink_url.
5. Pass the deeplink_url to the web application.
6. Redirect the user to a Kigo-hosted wallet at the deeplink_url

Best Practices

• Idempotency: The external_order_id is idempotent in the place order endpoint. This means that subsequent API calls for a partner using the same external_order_id will return the previously created order, and retry logic can be safely implement with the place order endpoint.
• Secure Handling: The deeplink_url grants the holder the right to claim the token associated with the claim_code. Therefore, it should only be accessible to the correct user.