API Reference
Help & SupportSign in日本語

Subscriptions

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 protected]" \
  -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 protected]" \
  -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 ParameterDescriptionValue
customerThe customer who is being subscribed.A customer resource id either from the dashboard or the customer API.
amountThe 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
currency3 letter ISO currency code of the transaction."JPY"
periodThe interval at which payment will occur.A value of either "weekly", "monthly", or "yearly".
metadataA set of configurable key/value pairs.Optional
Response ParameterDescription
statusCurrent state of Subscription. See Life Cycle below for more information.
payment_detailsSummary of payment source, useful for debugging why a payment is failing (ie. expired credit card)
retry_countNumber of times payment capture has failed for current Subscription interval.
retry_atIf payment failed, it will be retried again in 1 day. This give you time to fix issues.
next_capture_atTime at which next interval starts and payment is due.
ended_atTime that Subscription was either suspended or deleted.
paymentsKOMOJU id of past payments associated with this Subscription.

Life Cycle

A Subscription can be in one of 5 states:

StatusDescription
pendingInitialized and ready to capture first payment.
activeCaptured previous payment and waiting for next interval.
retryingFailed to capture payment for interval.
suspendedSuspended due to too many payment failures.
deletedDeleted 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_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

  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 the id of Subscription you would like to update.
  2. Use the Subscription API to delete the Subscription before its next_capture_date.
  3. Use the Subscription API to create new Subscription with updated values.

Stopping a Subscription

  1. Find the id of Subscription you would like to stop.
  2. Delete the Subscription.
  3. 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.