Stored Credential Compliance

How to increase auth rates when using stored credit cards.

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 nameTypeDescription
initiatorenumWho initiated the payment. This can be customer or merchant. The default value if unset is customer.
intentenumThe nature of the payment. This can be one_time, card_on_file, subscription, or installment. The default value is one_time.
usageenumUsed 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_referencestringA 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

Scenario

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