---
title: "Long Term Tokens"
description: "Learn how to store payment details long-term using KOMOJU Customer objects, enabling use cases like subscriptions and card-on-file payments."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/long-term-tokens"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/long-term-tokens.md"
language: en
last_modified: "2026-03-26"
---

This document is about long-term storage of [Payment Details](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/payments-api-payment-details.md) 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](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/subscriptions/POST/customers) object.
3. Store Customer ID in your database.
4. Some time in the future, retrieve Customer ID and use it to [create Payments](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments).

# Collecting Customer Input

There are a few ways to collect customer input. The specific input you need is our standard [Payment Details](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/payments-api-payment-details.md) object.

## Method 1: Hosted Page

Our Hosted Page product includes a ["customer mode" feature](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-page-customer-mode.md) 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 or Paidy, 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](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-fields-customer-integration.md) 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](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/subscriptions/POST/customers).

```shell
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](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-fields-tokens-integration.md) to collect a token.

## Method 4: raw payment details

You can always simply call [Customer: Create](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/subscriptions/POST/customers) with [Payment Details](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/payments-api-payment-details.md). If you do this with credit card numbers, you'll be subject to PCI-DSS. Also, Komoju will validate the credit card info by default before storing it.

# 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](https://docs.priv.staging.komoju-dev.tools/en/api-reference#2025-01-28/tag/payments/POST/payments) endpoint.

To pay with Customer payment details, remove the `payment_details` request parameter and add a `customer` parameter equal to your Customer ID. If you want to make subscription using Paidy, you will need to get approval by contacting Komoju's account managers or customer support.

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

```