This document outlines an extension to our payments API 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).

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.

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

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

Stored Credential Compliance

API Inputs

Examples

Using a subscription customer

Using raw card details