---
title: "Stored Credential Compliance"
description: "Learn how to use stored credential compliance fields to reduce decline rates for card-on-file and subscription payments."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/stored-credential-compliance"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/stored-credential-compliance.md"
language: en
last_modified: "2026-03-26"
---

This document outlines an extension to [our payments API](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/payments-api-overview.md) that can help reduce decline rates for card-on-file and subscription payments. We will go over a few API fields that can help us and the issuer understand the nature of stored card usage in cases where 3DS cannot be performed.

# API Inputs

There are four API fields that comprise our stored credential compliance feature. These belongs inside of `payment_details` (see [Payment Details](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/payments-api-payment-details.md)).

| Field name | Type | Description |
| --- | --- | --- |
| `initiator` | enum | Who initiated the payment. This can be `customer` or `merchant`. The default value if unset is `customer`. |
| `intent` | enum | The nature of the payment. This can be `one_time`, `card_on_file`, `subscription`, or `installment`. The default value is `one_time`. |
| `usage` | enum | Used to determine whether or not this is the first in a chain of payments. Permitted values are `first` or `used`. This field is only useful for non-one-time customer-initiated transactions. |
| `scheme_reference` | string | A special ID that's used to understand which payments are related to one another. A `scheme_reference` can be retrieved by creating a customer-initiated payment. Then, you can pass it back when creating the next payment to create a chain. |

The following table might give you an idea of what different combinations of the above fields might mean.

| Scenario | Initiator | Intent | Usage | 3DS | CVV | Description | Scheme Reference |
| --- | --- | --- | --- | --- | --- | --- | --- |
| #1 | customer | one_time | N/A | Yes | Yes | A one time payment, such as a checkout of e-commerce or other one-off payment. These payments are often 3DS verified and have a CVV. This is the default if you do not specify any stored credential compliance parameters. | No |
| #2 | customer | card_on_file | first | Yes | Yes | First interaction with the customer when collecting payment details and storing them for later usage. | No |
| #3 | customer | subscription | first | Yes | Yes | First interaction with the customer when collecting payment details and storing them for later usage for the purpose of a subscription. | No |
| #4 | customer | installment | first | Yes | Yes | First interaction with the customer when collecting payment details and storing them for later usage for the purpose of a installment plan. | No |
| #5 | customer | card_on_file | used | Yes | Yes | N-th interaction when customer lands on the page and re-uses the stored card credentials previously kept on file by the user. | No |
| #6 | customer | subscription | used | Yes | Yes | N-th interaction with the customer when renewing their subscription. In this scenario the customer is present during the transaction. | No |
| #7 | customer | installment | used | Yes | Yes | N-th interaction with the customer when renewing their installment. In this scenario the customer is present during the transaction. | No |
| #8 | merchant | card_on_file | N/A | No | No | Merchant charges the card on file without the consumer being present during the transaction. | Yes |
| #9 | merchant | subscription | N/A | No | No | Merchant charges the card on file without the consumer being present during the transaction in connection to a subscription. | Yes |
| #10 | merchant | installment | N/A | No | No | Merchant charges the card on file without the consumer being present during the transaction in connection to a installment plan. | Yes |

# Examples

## Using a subscription customer

See [Long Term Tokens](https://docs.priv.staging.komoju-dev.tools/en/docs/development/long-term-tokens.md).

```shell
curl -X POST https://komoju.com/api/v1/payments \
	-u sk_xxxxxxxxxxxxxxxxxxxx: \
  -d amount=1000 \
  -d currency=JPY \
  -d customer=yyyyyyyyyyyyyyy \
  -d payment_details[initiator]=merchant \
  -d payment_details[intent]=subscription \
  -d payment_details[usage]=used

```

## Using raw card details

```shell
curl -X POST https://komoju.com/api/v1/payments \
	-u sk_xxxxxxxxxxxxxxxxxxxx: \
  -d amount=1000 \
  -d currency=JPY \
  -d payment_details[type]=credit_card \
  -d payment_details[number]=4111111111111111 \
  -d payment_details[name]="Taro Test" \
  -d payment_details[month]=01 \
  -d payment_details[year]=28 \
  -d payment_details[verification_value]=123
  -d payment_details[initiator]=customer \
  -d payment_details[intent]=card_on_file \
  -d payment_details[usage]=first

```