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.

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.

ScenarioInitiatorIntentUsage3DSCVVScenarioScheme Reference
# 1customerone_timeN/AYesYesA 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
# 2customercard_on_filefirstYesYesFirst interaction with the customer when collecting payment details and storing them for later usage.No
# 3customersubscriptionfirstYesYesFirst interaction with the customer when collecting payment details and storing them for later usage for the purpose of a subscription.No
# 4customerinstallmentfirstYesYesFirst interaction with the customer when collecting payment details and storing them for later usage for the purpose of a installment plan.No
# 5customercard_on_fileusedYesYesN-th interaction when customer lands on the page and re-uses the stored card credentials previously kept on file by the user.No
# 6customersubscriptionusedYesYesN-th interaction with the customer when renewing their subscription. In this scenario the customer is present during the transaction.No
# 7customerinstallmentusedYesYesN-th interaction with the customer when renewing their installment. In this scenario the customer is present during the transaction.No
# 8merchantcard_on_fileN/ANoNoMerchant charges the card on file without the consumer being present during the transaction.Yes
# 9merchantsubscriptionN/ANoNoMerchant charges the card on file without the consumer being present during the transaction in connection to a subscription.Yes
# 10merchantinstallmentN/ANoNoMerchant charges the card on file without the consumer being present during the transaction in connection to a installment plan.Yes

About scheme reference