Subscriptions are a quick and simple way to provide products to your customers that involve recurring payments. By using Subscriptions you can confidently charge customers at fixed intervals with no extra hassle other than the initial setup.

Subscriptions work with already existing KOMOJU API endpoints. You can retain your implementation of our Token API to quickly integrate recurring payments into your platform.

Note, Subscriptions may not support all payment methods.

Example (Quick Start)

The quickest way to begin a Subscription involves two api calls.

The first is to create a customer resource on KOMOJU. This customer can be used for any number of your Subscriptions. Creating a customer can help you keep track of the status of an individuals recurring payments.

POST /api/v1/customers

curl -X POST https://komoju.com/api/v1/customers \
  -u sk_123456: \
  -d "email=test@example.com" \
  -d "payment_details[family_name]=Yamada" \
  -d "payment_details[given_name]=Taro" \
  -d "payment_details[month]=1" \
  -d "payment_details[number]=4111111111111111" \
  -d "payment_details[type]=credit_card" \
  -d "payment_details[year]=2018"

🚧
PCI-DSS Warning
This request requires sending raw credit card information. Unless you are PCI-DSS compliant, we recommend you instead use the Hosted Page, Hosted Fields, or Tokens to safely collect payment details.

Please save the customer's id from the response. We also recommend storing their email address so that you can contact them when payment fails.

Using the customer id we can make the actual Subscription API call.

POST /api/v1/subscriptions

curl -X POST https://komoju.com/api/v1/subscriptions \
  -u sk_123456: \
  -d "customer=3lz38k1d12sr5e4ggchnhxdgk" \
  -d "amount=2000" \
  -d "currency=JPY" \
  -d "period=monthly"

Example (Token)

If you are already using the Tokens API endpoint or Hosted Fields you can easily start creating Subscriptions.

curl -X POST https://komoju.com/api/v1/customers \
  -u sk_123456: \
  -d "email=foo@example.com" \
  -d "payment_details=tok_d7d3b7ea7a6910f1076bf025ad3276dac9360c9b3307cb92d77c93b62556077f3ifq39h3wnrlgkttrjm8c6g2e"

curl -X POST https://komoju.com/api/v1/subscriptions \
  -u sk_123456: \
  -d "customer=3lz38k1d12sr5e4ggchnhxdgk" \
  -d "amount=2000" \
  -d "currency=JPY" \
  -d "period=monthly"

Parameters

When creating a subscription, here are the parameters available.

Request Parameter	Description	Value
`customer`	The customer who is being subscribed.	A customer resource id either from the dashboard or the customer API.
`amount`	The amount to be charged on every occurrence. Must be equal or greater than 0. Use a '.' as a decimal separator, and no thousands separator.	Example: 1234.56
`currency`	3 letter ISO currency code of the transaction.	`"JPY"`
`period`	The interval at which payment will occur.	A value of either `"weekly"`, `"monthly"`, or `"yearly"`.
`metadata`	A set of configurable key/value pairs.	Optional

Response Parameter	Description
`status`	Current state of Subscription. See Life Cycle below for more information.
`payment_details`	Summary of payment source, useful for debugging why a payment is failing (ie. expired credit card)
`retry_count`	Number of times payment capture has failed for current Subscription interval.
`retry_at`	If payment failed, it will be retried again in 1 day. This give you time to fix issues.
`next_capture_at`	Time at which next interval starts and payment is due.
`ended_at`	Time that Subscription was either suspended or deleted.
`payments`	KOMOJU id of past payments associated with this Subscription.

Life Cycle

A Subscription can be in one of 5 states:

Status	Description
`pending`	Initialized and ready to capture first payment.
`active`	Captured previous payment and waiting for next interval.
`retrying`	Failed to capture payment for interval.
`suspended`	Suspended due to too many payment failures.
`deleted`	Deleted by merchant.

Here is a summary of how Subscriptions transition between states:

Subscription is created in pending state.
Immediately tries to capture payment for interval and set status to active.
If fails in pending state, immediately suspend the Subscription.
Make next payment attempt when next_capture_at arrives.

If payment is captured stay in active state.
If payment fails set status to retrying and attempt again in 24 hours.
If payment fails more than 3 times (with each attempt spanning 24 hours), set status to suspended and no longer process it.
If merchant deletes Subscription set status to deleted and no longer process it.

Handling Failed Payments

Receive the webhooks that a Subscription payment has failed.
Ensure customer payment details are up to date and not expired.
Contact customer to update their information if payments continue to fail.

Updating a Subscription

Find the id of Subscription you would like to update.
Use the Subscription API to delete the Subscription before its next_capture_date.
Use the Subscription API to create new Subscription with updated values.

Stopping a Subscription

Find the id of Subscription you would like to stop.
Delete the Subscription.
You can still view past payments from the Subscription but it will no longer charge the customer.

Webhooks

You will need to setup a webhook to receive Subscription notifications from KOMOJU. When a Subscription is created or processed KOMOJU will send a webhooks to your application. Your application must process these webhook and record the status of the Subscriptions.