Credential-on-File (COF)/Stored Credential Support

Introduction

Credentials-on-File allows the billing party to store consumer card information for future use. The API user must do this compliantly by following the steps outlined for COF.

• Cardholder must give permission to store card for future use.
• The stored credential is only stored through an initial successful transaction, where the InitialTransactionID should be stored by the user.
• The InitialTransactionID must referenced when StoredCredentialIndicator is ‘Used’.

Customer vs Merchant Initiated

• Customer initiated - Customer is actively engaged in the order process and can controls the specific scheduled charge.
• Merchant initiated - Customer isn’t actively engaged but has agreed with the merchant to be charged at a future date, where the merchant controls the schedule of charges.

Stored Credential vs Used Credential

• Considered 'stored' when processing the initial transaction in which you are storing a customer's payment details (customer credentials) in the Customer Vault or other third-party payment storage system.
  1. Additional Parameters required
     1. InitiatedBy
     2. StoredCredentialIndicator
     3. ScheduleIndicator
     4. MarketSegment
• Considered 'used' when processing a subsequent or follow-up transaction using the customer payment details (customer credentials) you have already stored to the Customer Vault or third-party payment storage method.
  1. Additional Parameters required
     1. InitiatedBy
     2. StoredCredentialIndicator
     3. ScheduleIndicator
     4. MarketSegment

Supported COF scenarios

• Straight Sale/One Time Sale, Unscheduled.
  • Consumer orders product from merchant, ad hoc. The terms and conditions of the order are specific to the order itself. There are no related or subsequent orders related to the ad hoc, unscheduled order. Consumer is in complete control and has not given the merchant permission to bill them in the future.
• Recurring.
  • Consumer enters into an agreement with the merchant where consumer is expected to be billing on a recurring/regular basis until subscription period ends or cancels.
• Free Trial.
  • Consumer enters into an agreement with the merchant where consumer tries a product and upon trial period expiry, is expecting to be billing on a recurring/regular basis until subscription period ends or cancels.

Notes

• COF Fields in API methods are highlighted by double asterisk, **.
• COF fields are optional however, if submitting as credentials-on-file, ALL COF related fields must be sent with valid values. If COF fields are missing or do not contain the correct value combination, the transaction request will be submitted as a regular, non-credential-on-file transaction.
• COF is supported on Ecommerce or MOTO at this time.

Request

Parameters		Description
InitiatedBy	Who initiated the transaction. Values: 'customer' or 'merchant'	Required to qualify for COF
StoredCredentialIndicator	The indicator of the stored credential. Values: 'stored' or 'used' Use 'stored' when processing the initial transaction in which you are storing a customer's payment details (customer credentials) in the Customer Vault or other third-party payment storage system. Use 'used' when processing a subsequent or follow-up transaction using the customer payment details (customer credentials) you have already stored to the Customer Vault or third-party payment storage method.	Required to qualify for COF
ScheduleIndicator	Values: 'Scheduled' or 'Unscheduled'	Required to qualify for COF
MarketSegment	Values: 'Ecommerce' or 'Retail' or 'Moto'	Required to qualify for COF
InitialTransactionID	Original PXP payment gateway transaction id, from the transaction response.	InitialTransactionID is required when StoredCredentialIndicator = ‘Used’ Transactions sent in without a valid InitialTransactionID where StoredCredentialIndicator = ‘Used’ will be sent to the processor as a regular, non-COF transaction.

Response

Parameters		Description
IsStoredCredentialEnabled	Values: True or False	Parameter indicating if a transaction was accepted by the processor as credential-on-file (True) or regular transaction (False).

Examples

Notes

• Examples provided are the most common credential on file scenarios supported. This does not cover ALL possible scenarios.

Case #	Scenario Description	Example	Credential Store Phase	Amount	CRM Billing Model	Billing Method**	Initiated By**	Stored Credential Indicator**	Schedule Indicator**	Initial Transaction Id**	Market Segment**	Is Recurring
1	Consumer initiates first txn, then maintains control of re-order, non-recurring.	Buying a TV.	When storing credential for the first time.	$55.00	StraightSale	NULL	Customer	Stored	Unscheduled	NULL	Ecommerce Moto	0
1a	Consumer initiates first txn, then maintains control of re-order, non-recurring.	Buying a shirt, separate from the TV order.	Subsequent transaction with already stored .	$10.00	StraightSale	NULL	Customer	Used	Unscheduled	NULL	Ecommerce Moto	0
2	Consumer initiates free trial, then merchant maintains rebills.	Consumer consents to free trial for 'T Shirts'.	Storing Credentials for the first time.	$6.25	Freetrial	initial_recurring	Customer	Stored	Unscheduled	NULL	Ecommerce Moto	0
2a	Consumer initiates free trial, then merchant maintains rebills.	Company 'T Shirts' charges cardholder on a recurring basis with stored credentials.	Recurring – subsequent transaction with already stored credential on file.	$55.11	Freetrial	firstrecurring	Merchant	Used	Scheduled	Required	Ecommerce Moto	1
2b	Consumer initiates free trial, then merchant maintains rebills.	Company 'T Shirts' charges cardholder on a recurring basis with stored credentials.	Recurring – subsequent transaction with already stored credential on file.	$55.11	Freetrial	recurring	Merchant	Used	Scheduled	Required	Ecommerce Moto	1
3	Consumer initiates order where, then merchant maintains re-order, but order is spontaneous and separate.	Consumer opts into a gym membership with initiation fees.	Unscheduled – first transaction.	$87.44	Recurring	initial_recurring NULL	Customer	Stored	Unscheduled	NULL	Ecommerce Moto	0
3a	Consumer initiates order where, then merchant maintains re-order, but order is spontaneous and separate.	Gym company charges consumer for a gym add-on, palates one-time special, NON recurring.	Unscheduled – subsequent transaction with already stored credential on file.	$11.44	Recurring	recurring firstrecurring	Merchant	Used	Unscheduled	Required	Ecommerce Moto	1
4	Consumer initiates order and agrees to terms where they are billed at a fixed amount and frequency, the merchant maintains first order and rebills.	Consumer locks into a $30 monthly subscription of beef products at Stanley’s Meat Mart. Consumer is scheduled to be billed exactly $30 a month every month until the subscription expires/cancels.	Storing Credentials for the first time (Can be Ecommerce or MOTO).	$30.00	Recurring	initial_recurring	Customer	Stored	Unscheduled	NULL	Ecommerce Moto	0
4a	Consumer initiates order and agrees to terms where they are billed at a fixed amount and frequency, the merchant maintains first order and rebills.	Consumer locks into a $30 monthly subscription of beef products at Stanley’s Meat Mart. Consumer is scheduled to be billed exactly $30 a month every month until the subscription expires/cancels.	First Recurring - using credentials that were previously stored.	$30.00	Recurring	firstrecurring	Merchant	Used	Scheduled	Required	Ecommerce Moto	1
4b	Consumer initiates order and agrees to terms where they are billed at a fixed amount and frequency, the merchant maintains first order and rebills.	Consumer locks into a $30 monthly subscription of beef products at Stanley’s Meat Mart. Consumer is scheduled to be billed exactly $30 a month every month until the subscription expires/cancels.	Subsequent Recurring – using credentials that were previously stored.	$30.00	Recurring	recurring	Merchant	Used	Scheduled	Required	Ecommerce Moto	1