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 are currently only available for Credit Card.

Getting Started

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"

From the response we will use the id. You should keep store the customers email in your system in order to contact them if payments fail.

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 / MultiPay)

If you are already using the Tokens API endpoint or KOMOJU Multipay 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

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:

  1. Subscription is created in pending state.
  2. Immediately tries to capture payment for interval and set status to active.
  3. If fails in pending state, immediately suspend the Subscription.
  4. Make next payment attempt when next_capture_date 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

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

Updating a Subscription

  1. Find id of Subscription you would like to update.
  2. Use Subscription API to delete the Subscription before it's next_capture_date
  3. Use Subscription API to create new Subscription with updated values.
Note: Subscriptions start right away.

Stopping a Subscription

  1. Find id of Subscription you would like to update.
  2. Use Subscription API to delete the Subscription.
  3. You can still view payments and information about 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.