Long-term Tokens

This document is about long-term storage of Payment Details that can be used any number of times. One example use case for this feature would be building your own subscriptions engine.

The overall flow will be something like:

  1. Collect customer input.
  2. Create a Customer object.
  3. Store Customer ID in your database.
  4. Some time in the future, retrieve Customer ID and use it to create Payments.

Collecting Customer Input

There are a few ways to collect customer input. The specific input you need is our standard Payment Details object.

Method 1: Hosted Page

Our Hosted Page product includes a "customer mode" feature that allows customers to input their payment details on KOMOJU, then KOMOJU will pass you a Customer ID.

This has the added advantage of supporting most mobile app payment methods. If you want to store a long-term token for PayPay, LINE Pay, or auPay, then hosted page is currently the only way.

Method 2: Hosted Fields

The same "customer mode" session you'd use for method 1 above can be used with KOMOJU Fields.

See the Hosted Fields customer mode guide for how to get a Customer ID. Then see the next section on this page for how to use it.

Method 3: Token

You can "convert" a short-term Token into a long-term Customer object by simply passing the Token ID string as payment_details when calling Customer: Create.

curl -X POST https://komoju.com/api/v1/customers \
  --user sk_live_xxxxxxxxxxxxxxxx \
  --data payment_details='tok_donqjgn5pzgaeepqztogwdjdu'

This also means you can use Hosted Fields Token Mode to collect a token.

Method 4: raw payment details

You can always simply call Customer: Create with Payment Details. If you do this with credit card numbers, you'll be subject to PCI-DSS.

Using Customer Objects

Once you have a Customer ID, you'll want to use it to make payments. Currently, this is only supported on our Payment: Create endpoint.

To pay with Customer payment details, remove the payment_details request parameter and add a customer parameter equal to your Customer ID.

curl -X POST https://komoju.com/api/v1/payments \
  --user sk_live_xxxxxxxxxxxxxxxx \
  --data amount=5000 \
  --data currency=JPY \
  --data customer=boc2hxvmyl497eekihyrwmmgm