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 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.
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
Updated 6 days ago