Stripe

Configuring Kiwi for Stripe

We assume for this manual that your application is already configured on Stripe. This step should be performed prior to configuring Kiwi. We will only go through the interface settings.

1. Access your application on Kiwi Admin

2. On Monetization, check if you have Stripe configured and click on "New Subscription Platform" if needed. Remember that only WEB applications can configure Stripe integration.

3. Edit the Stripe platform configuration and enter the informations asked:

   • secret key: Your secret key on Stripe. This value can be retrieved under Account Settings -> API Keys.

4. Click "Save" to complete this part of the process.

5. On the platform listing click on "SKU Configuration" on the actions column for Stripe

6. Create a new sku configuration, by clicking on "New Configuration"

7. Fill the sku name with the plan id of the corresponding plan on Stripe

8. Set Share Type to SHARE_ACROSS_PRODUCT. product.

9. Select the renew period.

10. Select if the SKU has a trial period and enter the trial period in days.

11. Select the currency code for this SKU and enter the price.

12. Click save to complete the proccess

Creating a subscription

The process of creating a subscription on Stripe on Kiwi consists on 3 steps, all triggered by one create subscription request. The steps are: 1. Create subscription on Stripe 2. Register subscription on Kiwi 3. Link subscription with a given kiwi account

In order to create a subscription one must perform the following request:

Method: POST

URL: https://purchase.kwsdk.io/api/1.0/subscription/stripe/create

Content-Type: application/json

x-kiwi-application-key: Your application's key, as described in settings

Body: Json object with the following fields

• userId: identifier of the user on Kiwi

• appInstallId: identifier of the install of the application on Kiwi

• accountUuid: identifier of the target account on Kiwi. The subscription will be linked to this account

• planId: identifier of the plan on Stripe, and sku of the subscription on Kiwi

• customerEmail: email of the customer that will own this subscription

• stripeToken: token that identifies the customer's credit card information on Stripe. Kiwi will not hold credit card sensitive information, the stripe token must be generated before calling Kiwi.

• sessionMediaInfo (optional): if you want to relate the subscription creation to a certain media campaign, this object should be sent. It should be filled with 3 attributes:

  • campaignId: The campaign ID on the external campaign integrator

  • campaignNetwork: The AD Network of the campaign (i.e. Facebook, FBiz, Twitter, AppLovvin, etc.)

  • raw: raw information about the media attribution (optional)

Example:

{
 "userId":"9C88CA8F-B1A7-45D9-9D58-C76D00E97C38",
 "appInstallId":"2AE634C5-EC17-4CCF-91A5-012CEDE522D4",
 "accountUuid":"1ba2ad11-c487-4805-9e69-89e45be8555d",
 "planId":"Plan 01",
 "customerEmail":"[e-mail]",
 "stripeToken":"tok_16llF7LYcYOLDALw2TJueJFx",
 "sessionMediaInfo":{
    "campaignId":"123",
    "campaignNetwork":"1234",
    "raw":"raw"
   }
}

Response: Json object with the following fields

• status: indicates the id of the status of the operation. Can be one of the following

  • 0 - SUCCESS: Subscription was created on Stripe, registered on Kiwi and linked to the target account

  • 1 - INVALID_PARAMETERS: One or more of the mandatory parameters was invalid or missing

  • 2 - INVALID_CONFIGURATION: Missing Stripe's configuration on Kiwi (missing secret key)

  • 3 - ERROR_REGISTERING_SUBSCRIPTION_ON_KIWI: Subscription was created on Stripe, but an error happened while registering the subscription on Kiwi

  • 4 - ERROR_LINKING_SUBSCRIPTION_ON_KIWI: Subscription was created on Stripe and registered on Kiwi, but an error happened while linking the subscription with the given account

  • 5 - STRIPE_CARD_ERROR: Stripe returned error of invalid stripe token

  • 6 - STRIPE_API_ERROR: Stripe returned that an error called while calling the API to register subscription

  • 7 - STRIPE_AUTHENTICATION_ERROR: Stripe returned that the given secret key is invalid

  • 8 - STRIPE_INVALID_REQUEST_ERROR: Stripe informed that the request made to create a subscription was invalid. Probably the given plan id does not exist on Stripe

  • 9 - STRIPE_API_CONNECTION_ERROR: Error connecting with Stripe to create subscription

  • 10 - ERROR_UNKNOWN: Unknown error happened while processing request

• message: text describing the result of the operation. In case of an error will contain a better description of what happened

Example:

{
    "status": 0,
    "message": "Subscription Created successfully"
}

Canceling a subscription

In order to cancel a Stripe subscription on Kiwi one must have both stripe's customer id and stripe's subscription id.

These values can be extracted from a Kiwi's subscription extra data field. The key's are stripe_customer_id and stripe_subscription_id.

Request description:

Method: POST

URL: https://purchase.kwsdk.io/api/1.0/subscription/stripe/cancel

Content-Type: application/json

x-kiwi-application-key: Your application's key, as described in settings

Body: Json object with the following fields

• userId: identifier of the user on Kiwi

• appInstallId: identifier of the install of the application on Kiwi

• stripeSubscriptionId: identifier of the subscription on Stripe

• stripeCustomerId: identifier of the subscription's owner on Stripe

Example:

{ 
    "userId":"9C88CA8F-B1A7-45D9-9D58-C76D00E97C38",
    "appInstallId":"2AE634C5-EC17-4CCF-91A5-012CEDE522D4",
    "stripeSubscriptionId":"sub_709hTVINcgBNp6", 
    "stripeCustomerId":"cus_709hUlGVwal5GI" 
}

Response: Json object with the following fields:

• status: indicates the status of the operation. Can be one of the following

  • 0 - SUCCESS: Subscription was created on Stripe, registered on Kiwi and linked to the target account

  • 1 - INVALID_PARAMETERS: One or more of the mandatory parameters were invalid or missing

  • 2 - INVALID_CONFIGURATION: Missing Stripe's configuration on Kiwi (missing secret key)

  • 3 - STRIPE_SUBSCRIPTION_NOT_FOUND: Could not find any subscription with the given parameters

  • 4 - STRIPE_API_ERROR: Stripe returned that an error called while calling the API to register subscription

  • 5 - STRIPE_AUTHENTICATION_ERROR: Stripe returned that the given secret key is invalid

  • 6 - STRIPE_INVALID_REQUEST_ERROR: Stripe informed that the request made to create a subscription was invalid. Probably the given plan id does not exist on Stripe

  • 7 - STRIPE_API_CONNECTION_ERROR: Error connecting with Stripe to create subscription

  • 8 - CANCELED_ON_STRIPE_ERROR_SYNCING_SUBSCRIPTION_ON_KIWI: Subscription was canceled successfully on Stripe, but it's status was not synced on Kiwi

  • 9 - ERROR_UNKNOWN: Unknown error happened while processing request

• message: text describing the result of the operation. In case of an error will contain a better description of what happened

Example:

{
    "status": 0,
    "message": "Subscription Canceled successfully"
}