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 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 if unset 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 customer-initiated transactions that are not one-time.
`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 details the set of valid combinations of stored credentials inputs you can supply. We do not guarantee the behavior of any combinations not listed below.

Scenario	Initiator	Intent	Usage	3DS	CVV	Scenario	Scheme Reference
# 1	customer	one_time	-	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 an installment plan.	No
# 5	customer	card_on_file	used	No	No	N-th interaction when customer lands on the page and re-uses the stored card credentials previously kept on file in scenario #2.	Yes
# 6	merchant	card_on_file	-	No	No	Merchant charges the card on file from scenario #2 without the consumer being present during the transaction.	Yes
# 7	merchant	subscription	-	No	No	Merchant charges the card on file from scenario #3 without the consumer being present during the transaction in connection to a subscription.	Yes
# 8	merchant	installment	-	No	No	Merchant charges the card on file from scenario #4 without the consumer being present during the transaction in connection to a installment plan.	Yes

About Scheme Reference

The scheme reference is an identifier connected to a single customer's chain of payments. The value is returned from payment API endpoints in the payment_details object as scheme_reference. You should save this value along with the customer's payments details to send in subsequent requests.

🚧
The scheme reference may change after subsequent payments so please keep your stored payment details up to date by saving the returned scheme reference after each payment

Example

Let's say that your service provides a subscription plan where the customer is charged a static amount once per month. For the initial payment, your customer will input their payment details on your service's UI and submit the form. Your service would then follow the steps in 3D Secure Without a Session to create a 3DS authenticated payment with the following stored credential values in the payment details.

payment #1

Initiator	Intent	Usage	Scheme Reference
customer	subscription	first	-

If the payment is successful, it will have a scheme reference in its response. You can now save the scheme reference along with the customer's payment details in your system.

At the next scheduled payment, your system will reuse the stored payment details without the customer being involved directly. In this case, you can make a request to Payment: Create with the following stored credential values.

payment #2

Initiator	Intent	Usage	Scheme Reference
merchant	subscription	-	{scheme reference from payment #1}

The scheme reference may change so be sure to update your stored payment details with the new value from the response.

All subsequent payments will be similar to payment #2 except supplying the scheme reference from the previous payment's response.

payment #N

Initiator	Intent	Usage	Scheme Reference
merchant	subscription	-	{scheme reference from payment #N-1}