Skip to main content

Credentials on File

You may need to repeat a payment or perform a new payment using payment details previously requested from the Customer and stored by either yourself or the Gateway. These payment details could be stored in previous transaction or in the Gateway wallet. These repeat payments could be one off payments, scheduled recurring payments, or repeats due to authorisation problems or industry requirements. All must be correctly flagged to allow the payment network to process them.

The stored details, or credentials, are termed Credentials on File (COF) and refer to any payment details (including, but not limited to, an account number or payment token) that the Consumer has authorised you to store to perform future transactions without the need for them to enter their payment details again.

These transactions must always be identified with the reason for storing or using the stored credentials and who initiated the transaction – the Consumer (CIT) or the Merchant (MIT).

You may store the credentials and send them with the future transaction, or you may store the details in the Gateway’s Wallet or by taking advantage of the Payment Tokenisation feature of the Gateway[1]. Either way you must tell the Gateway of your intentions, it will not assume that just because you have asked, for example, to store credentials in the Wallet that those are legitimate stored credentials and follow all the requirements laid out below.

If you store credentials on file, then you must:

· Disclose to consumers how those credentials will be used.

· Obtain consumers’ consent to store the credentials.

· Notify consumers when any changes are made to the terms of use.

· Inform the card issuer via a transaction that payment credentials are now stored on file.

· Identify transactions with appropriate rtAgreementType when using stored credentials.

· Perform a PREAUTH, SALE or VERIFY transaction during the initial credential setup.

[1] Card numbers will be stored as part of any transaction details for a period of 13 months or less at your request. Once the card number has been removed a transaction xref can no longer be used to provide the original card number. If you wish to store credentials for longer then you may store them in the Gateway’s Wallet.

info

Credentials stored to complete a single transaction (or a single purchase) for a Consumer, including multiple authorisations related to that particular transaction or future refunds are not considered stored credentials and can be stored and used without the following the above rules.

info

A new recurring transaction will be a clone of the cross-referenced transaction, including any stored credentials details except for any new data provided in the new transaction. If the new transaction provided different payment details, then any stored credentials in the cross-referenced transaction cannot be used. The cloneFields request field can also be used to control which fields in the cross-referenced transaction are used in the repeat transaction (refer to the Transaction Cloning section).

Consumer Initiated Transactions (CIT)​

Consumer Initiated Transactions (CIT) are any transaction where the Consumer is actively participating in the transaction. This can be either through a checkout experience online, via a mail order or telephone order, with or without the use of an existing stored credential.

A Consumer Initiated Transaction is one whose action field is one of PREAUTH, SALE or VERIFY and whose type is one of 1 (ECOM) or 2 (MOTO) and initiator is 'consumer'.

To indicate that the card details are to be stored as, or were stored as, Credentials on File then send the rtAgreementType field as one of the following values:

· cardonfile – card details stored as Credential on File

· recurring – initial payment as the start of a recurring payment agreement.

· instalment – initial payment as the start of an instalment payment agreement.

If the card details are cloned from an existing transaction or loaded from a Gateway Wallet which also stored the Credentials on File, then the transaction will be flagged as subsequent use of stored credentials rather than first use of them[2].

If the transaction is the first in a recurring or instalment sequence then the optional rtSequenceCount field can be used to specify how many transactions will be taken in total, with a value greater than 1, and any optional rtSequenceNumber field specifying the which transaction it is in the sequence will be expected to have a value of 0.

Mastercard require you to indicate if recurring payments will be for fixed or variable amounts. This can be indicated using the rtAmountFixed field, which can have a value of Y if the payments will be the same in each subsequent transaction, or N if the payments will be variable. If not provided, then variable payments will be assumed. We advise you send this field for all fixed payment sequences, regardless of the card scheme in use. The field should be sent, with the same value, for each payment in the recurring sequence.

[2] For flagging of subsequent use, the existing credentials will usually need to have been stored with the same Acquirer.

Merchant Initiated Transactions (MIT)​

Merchant Initiated Transactions (MIT) are any transaction where you have performed the transaction without the active participation of the Consumer. This would normally always be as a follow-up to a previous Consumer Initiated Transaction (CIT).

Refer to the Recurring Transaction Agreements section for information on how the Gateway can be instructed to take Merchant Initiated recurring transactions automatically, according to a pre-determined schedule.

Merchant Initiated Transactions are broken down in to two categories as follows.

Standing Instruction MITs​

Merchant Initiated Transactions defined under this category are performed to address pre-agreed standing instructions from the Consumer for the provision of goods or services.

The following transaction types are standing instructions transactions:

· Instalment Payments: A transaction in a series of transactions that use a stored credential and that represent Consumer agreement for the merchant to initiate one or more future transactions over a period for a single purchase of goods or services. An example of such a transaction is a hire purchase repayment.

· Recurring Payments: A transaction in a series of transactions that use a stored credential and that are processed at fixed, regular intervals (not to exceed one year between transactions), representing Consumer agreement for the merchant to initiate future transactions for the purchase of goods or services provided at regular intervals. An example of such a transaction is a gym membership subscription.

· Unscheduled Credential on File (UCOF): A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date, where the Consumer has provided consent for the merchant to initiate one or more future transactions. An example of such a transaction is an account auto-top up transaction.

The Gateway classifies the first two types of instalment and recurring payments as Continuous Authority (CA) payments and the third type as a normal Cardholder not present payments. Different Acquirers may use different classifications, but the Gateway will handle this and send the classification expected by the Acquirer.

The maximum period between each transaction is 13 months, however individual Card Schemes or Acquirers may impose shorter periods.

Industry-Specific Business Practice MIT​

Merchant Initiated Transactions defined under this category are performed to fulfil a business practice as a follow-up to an original Consumer-Merchant interaction that could not be completed with one single transaction. Not every industry practice Merchant Initiated Transaction requires a stored credential, for example, if you store card details for a single transaction or a single purchase, it is not considered as a stored credential transaction.

The following transaction types are industry specific transactions[3]:

· Incremental**[44]**: Incremental authorizations can be used to increase the total amount authorised if the authorised amount is insufficient. An incremental authorization request may also be based on a revised estimate of what the Consumer may spend.

· Resubmission: You can perform a resubmission in cases where it requested an authorization but received a decline due to insufficient funds; however, the goods or services were already delivered to the Consumer. In such scenarios, you can resubmit the request to recover outstanding debt from Consumers.

· Reauthorization: You can initiate a reauthorization when the completion or fulfilment of the original order or service extends beyond the authorization validity limit set by the Card Scheme.

· Delayed Charges: Delayed charges are performed to make a supplemental account charge after original services have been rendered and payment has been processed.

· No Show: Consumers can use their payment credentials to make a guaranteed reservation with certain merchant segments. A guaranteed reservation ensures that the reservation will be honoured and allows you to perform a No Show transaction to charge the Consumer a penalty according to your cancellation policy. If no payment is made to guarantee a reservation, then it is necessary to perform a VERIFY Consumer Initiated Transaction at the time of reservation to be able perform a No Show transaction later.

[3] Not all Acquirers support all transaction types.

[4] The Gateway does not currently support incremental authorisations.

A Merchant Initiated Transaction is one whose action field is one of PREAUTH, SALE or VERIFY and whose type is one of 2 (CNP) or 9 (CA) depending on the category, and initiator is 'merchant'.

To indicate the type of MIT, send the rtAgreementType field as one of the following values:

· recurring – subsequent payment as the start of a recurring payment agreement (CA).

· instalment – subsequent payment as the start of an instalment payment agreement (CA).

· unscheduled – subsequent payment not to a fixed schedule (MOTO)

· incremental – subsequent payment to increment initial amount authorised (MOTO)

· resubmission – subsequent payment due to failed initial payment (MOTO)

· reauthorisation – subsequent payment to refresh expired initial payment (MOTO)

· delayedcharges – subsequent payment for additional charges (MOTO)

· noshow – subsequent payment as penalty for missed reservation (MOTO)

In addition, the optional rtSequenceCount field can be used to specify how many transactions will be taken in total, with a value greater than 1, and the optional rtSequenceNumber field can be used to specify which transaction this is in the sequence, with a value greater than 0.

If the rtAmountFixed field was sent in the initial transaction in a recurring sequence, then it must be sent with the same value in each subsequent transaction.

The xref of the initial Consumer Initiated Transaction, or previous Merchant Initiated Transaction must be provided as follows:

· For standing order MITs the initial authorisation must have been a successful Consumer Initiated Transaction with Credentials on File. This MIT will be a subsequent use of those Credentials on File. For recurring and instalment MITs the initial authorisation must have used the same rtAgreementType. The xref can be to the previous MIT in which case the Gateway will follow the chain of transactions back to the initial CIT. An xref is only valid for 13 months and so there cannot be longer between recurring payments, however the Card Scheme or Acquirer may impose a shorter period.

· For industry practice MITs the initial authorisation must be successful (apart from for a resubmission) but need not have Credentials on File. For example, it may not be known at the time of the initial authorisation that the MIT would be required and so the initial authorisation would not necessarily have stored the Credentials on File. This is an example of when an industry practice Merchant Initiated Transaction does not require a stored credential.

info

For compatibility with existing practices, Instalment Payments and Recurring Payments MITs use Continuous Authority (CA) type 9 transactions while other MITs use Card Not Present (CNP) type 2 transactions. This use of type 2 is different to its use with a Consumer Initiated Transaction (CIT) where it indicates a Mail Order or Telephone Order transaction.

Footnotes​

  1. Card numbers will be stored as part of any transaction details for a period of 13 months or less at your request. Once the card number has been removed a transaction xref can no longer be used to provide the original card number. If you wish to store credentials for longer then you may store them in the Gateway’s Wallet. ↩

  2. For flagging of subsequent use, the existing credentials will usually need to have been stored with the same Acquirer. ↩

  3. Not all Acquirers support all transaction types. ↩

  4. The Gateway does not currently support incremental authorisations. ↩