Skip to main content

Credentials on file & Recurring Transactions

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. 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.

Note: 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 following the above rules.

Note: 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 Transaction Cloning).

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).

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.

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 which transaction it is in the sequence will be expected to have a value of 0.

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). 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 higher 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:

  • Incremental: 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. The Gateway does not currently support incremental authorisations.
  • 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.

Types of MIT

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

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.

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 Note: For compatibility with existing practices, Instalment Payments and Recurring Payments MITs use Continuous Authority (CA) type transactions while other MITs Mail Order/Telephone Order (MOTO) type transactions. This use of MOTO is different to its use with a Consumer Initiated Transaction (CIT).

Request Fields

NameMandatoryDescription
xrefYesReference to initial CIT or previous MIT transaction.
typeYesThe type of transaction.

Possible values are:
1 – E-commerce (ECOM) (CIT).
2 – Mail Order/Telephone Order (MOTO (CIT).
9 – Continuous Authority (CA) (MIT).

Required differentiate between initial and subsequent recurring or instalment transaction.
rtAgreementTypeYesConsumer/Merchant agreement type.

Possible values are:
cardonfile – credential storage agreed (CIT/MIT).
recurring – recurring type agreed (CIT/MIT).
instalment – instalment type agreed (CIT/MIT).
unscheduled – ad hoc COF payment (MIT).
incremental – authorisation amount increment (MIT).
resubmission – failed authorisation retry (MIT).
reauthorisation – expired authorisation refresh (MIT).
delayedcharges – post authorisation charges (MIT).
noshow – missed reservation penalty (MIT).

Not required on the initial transaction for a subsequent Industry-Specific Business Practice MIT to be used.

MIT type incremental is not currently supported but reserved for future use.
rtSequenceCountNoNumber of transactions in a recurring sequence if known.

Mandatory for some Acquirers, its use is highly recommended with recurring transactions.
rtSequenceNumberNoTransaction number in a recurring sequence if known.
initiatorNoIndicate who initiated the transaction.

Possible values are:
consumer – consumer initiated (CIT)
merchant – merchant initiated (MIT)

If not provided the Gateway will attempt to determine the initiator from the other request values.

For backwards compatibility, the Gateway will try to automatically identify if a transaction is CIT or MIT from the values provided for the action, type and rtAgreementType fields.

You may also pass the initiator field in the request to force a classification. This can be used if the Gateway is unable to correctly classify the transaction. If, however, the requested classification is incompatible with the provided request fields then the transaction will fail with a of 66944 (INVALID INITIATOR).

The initiator field will be returned in the response with either the value passed in the request or the automatically identified value.

Credentials on File Matrix

ScenarioCIT/MITCNPCOFSCA (3D Secure)initiatortypertAgreementTypexref
Cardholder opts to store their card details on Merchant's website.CITECOMMERCEinitialRequiredconsumer1cardonfileOptional for cloning
Cardholder opts to store their card details provided to Merchant via mail or telephone.CITMOTOinitialExemptconsumer2cardonfileOptional for cloning
Cardholder pays using a card they previously stored on the Merchant's website.CITECOMMERCESubsequentRequiredconsumer1cardonfileReference to transaction that initially stored the card
Cardholder provides their card details to sign up to a subscription on the Merchant's website.CITECOMMERCEinitial or subsequentRequiredconsumer1recurringOptional for cloning or using previous stored card
Cardholder provides their card details when agreeing to purchase by instalments on the Merchant's website.CITECOMMERCEinitial or subsequentRequiredconsumer1instalmentOptional for cloning or using previous stored card
Cardholder provides their card details to sign up to a subscription via mail or telephone to the Merchant.CITMOTOinitial or subsequentExemptconsumer2recurringOptional for cloning or using previous stored card
Cardholder provides their card details when agreeing to purchase by instalments via mail or telephone to the Merchant.CITMOTOinitial or subsequentExemptconsumer2instalmentOptional for cloning or using previous stored card
Merchant/Gateway takes an automatic subscription payment at the interval agreed to by the Cardholder.MITContinuous AuthoritySubsequentExemptmerchant9recurringReference to initial or previous recurring payment
Merchant/Gateway makes an automatic instalment payment at the interval agreed to by the Cardholder.MITContinuous AuthoritySubsequentExemptmerchant9instalmentReference to initial or previous instalment payment
Merchant makes an unscheduled transaction, such as an account top-up, as previously agreed with the Cardholder when they stored their card details.MITMOTOSubsequentExemptmerchant2unscheduledReference to transaction that initially stored the card
Merchant resubmits a payment where the initial payment was declined due to insufficient funds, but the goods have already been provided to the Cardholder.MITMOTON/AExemptmerchant2resubmissionReference to initial payment that was declined
Merchant reauthorises a payment when the completion or fulfilment of the original order or service extends beyond the authorization validity limit set by the Card Scheme.MITMOTON/AExemptmerchant2reauthorisationReference to payment that is to be reauthorised
Merchant makes a payment to process a supplemental account charge after original services have been rendered and respective payment has been processed.MITMOTON/AExemptmerchant2Reference to original payment to which the delayed charges relate
Merchant makes a payment to charge the Cardholder a penalty according to the merchant’s reservation cancellation policy.MITMOTON/AExemptmerchant2noshowReference to an initial CIT payment or account verification payment made by Cardholder at time of booking

Recurring Transaction Agreements (RTA)

A Recurring Transaction Agreement (RTA) is used to request that the Gateway should perform repeat payments on your behalf, using pre-agreed amounts and schedules.

An RTA can be configured easily and quickly, using the Merchant Management System (MMS). An RTA can also be set up while performing the initial transaction request, by including the integration RTA request fields. The RTA is only set up in the transaction results in a successful payment authorisation. The initial transaction should be either SALE or VERIFY transaction and the rtAgreementType field should be provided to indicate whether the transactions are part of a recurring or instalment.

Merchants who use this system to implement billing or subscription type payments must use recurring or instalment type Continuous Authority (CA) transactions to comply with Card Payment Scheme practices. Your Acquirer may refuse to accept the recurring transactions if they are not subject to an agreement between yourself and your Customer.

The maximum period between recurring transactions is 13 months, however individual Acquirers may impose a shorter period.

Refer to the Credentials on File section for more information on the different types of repeat or recurring transactions.

Scheduling

There are two different types of scheduling available when requesting the Gateway to take recurring transactions automatically on the Merchant’s behalf. In addition, a start date can be provided to allow for a recurring subscription with an initial free trial period.

Fixed Scheduling

Fixed scheduling causes the subsequent transaction to be taken at fixed intervals of time and for fixed amounts. A different initial date and amount or final date and amount can be provided for use when the agreed payment term or amount doesn’t exactly divide by the fixed time intervals.

Fixed scheduling is specified by providing an rtScheduleType field with a value of ‘fixed’ and providing the rtCycleDuration, rtCycleAmount and rtCycleCount fields to define the interval at which transactions should be taken and the number of transactions to take.

An rtCycleCount field value of 0 can be provided to indicate that transactions should be taken ad-infinitum until the RTA is stopped.

Variable Scheduling

Variable scheduling causes the subsequent transaction to be taken on prespecified dates and for prespecified amounts.

Variable scheduling is specified by providing an rtScheduleType field with a value of ‘variable’ and providing the rtSchedule field with a value containing an array of one or more schedule records.

Each schedule record must contain the following fields:

NameMandatoryDescription
dateYesDate on which to take a payment.
amountYesAmount to take on the provided date.

The schedule records should be passed in a sequential array of records, either as nested records or serialised records as described in the format guide. The record field names are case sensitive.

Request Fields

NameMandatoryDescription
rtNameNoFree format short name for the agreement.
rtDescriptionNoFree format longer description for the agreement.
rtPolicyRefNoMerchant Policy Reference Number (MPRN).
rtAgreementTypeNoRecurring transaction agreement type. Indicates the type of Continuous Payment Authority or Repeat Billing agreement made with the Cardholder.

Possible values are:
recurring – recurring type CPA agreed.
instalment – instalment type CPA agreed.
rtMerchantIDNoMerchant Account ID to use for the recurring transactions (defaults to merchantID).
rtStartDateNoStart date of agreement (defaults to date received).
rtScheduleTypeNoSchedule type.

Possible values are:
fixed – fixed interval schedule (default).
variable – variable interval schedule.
rtScheduleYesNested array or serialised string containing payment schedule information as per the variable scheduling section.

For use with variable schedules only.
rtInitialDateNoDate of initial payment (defaults to rtStartDate).

For use with fixed schedules only.
rtInitialAmountNoAmount of initial payment (defaults to rtCycleAmount).

For use with fixed schedules only.
rtFinalDateNoDate of final payment.

For use with fixed schedules only.
rtFinalAmountNoAmount of final payment (defaults to rtCycleAmount).

For use with fixed schedules only.
rtCycleAmountNoAmount per cycle (defaults to amount).

For use with fixed schedules only.
rtCycleDurationYesLength of each cycle in rtCycleDurationUnit units.

For use with fixed schedules only.
rtCycleDurationUnitYesCycle duration unit. One of: day, week, month or year.

For use with fixed schedules only.
rtCycleCountYesNumber of cycles to repeat (zero to repeat forever).

For use with fixed schedules only.
rtMerchantDataNoFree format Merchant data field.
rtCloneFieldsNoFields to clone from one recurring transaction to the next. Refer to Transaction Cloning

Response Fields

NameReturnedDescription
rtIDAlwaysRecurring Transaction Agreement ID.
rtResponseCodeAlwaysResult of setting up RT Agreement.Refer to Response Codes for details.
rtResponseMessageAlwaysDescription of above response code.

Querying RTA (Recurring Transactions Agreements)

You might have to check the status of the last transaction or when the next payment will be. We have at your disposal an API to be able to consult all the information related to the RTA (Recurring Transactions Agreements).

HTTP Authentication

You will need the following information to integrate with Gateway’s REST interface.

NameDescription
User AccountAccess to the REST interface requires a valid user account. You should have received these details when your account was set up.
Integration URLhttps://commerce-api.handpoint.com/rest/

Each request must contain authentication data. The normal method of authentication is to send your username and password in a ‘Authorization’ request header using the HTTP Basic Auth authorization scheme. This can sometimes be easily achieved by using the ‘username:password’ addition to the base integration URL (eg. https://username:password@commerce-api.handpoint.com/rest/...).

Each successfully authenticated request will also return a x-p3-token response header which contains an authentication token. This token may be used to authenticate further requests by sending it in an Authorization header using the scheme name x-p3-token or in an x-p3-token header (as received). Each time you send in a token a new one is returned. Each returned token is valid for 1 hour.

To aid where custom authorization header schemes or custom headers cannot easily be sent or when manually typing the URL into a browser for testing etc. the token can also be sent using the HTTP Basic Auth authorization scheme by specifying a username of __token__ and then sending the tokens value as the password (the keyword is “token” surrounded by a double underscore “__”). The following HTTP headers passing the token are therefore identical;

x-p3-token: <token>
authorization: x-p3-token <token>
authorization: basic <base64token>

Where <base64token> is the string __token__:<token> base64 encoded, and <token> is the actual authentication token.

Recurring Transactions Agreement request example:

curl --location --request GET 'https://YourUser:P4$$w00rd@commerce-api.handpoint.com/rest/rtagreements/'

RTAgreements (Recurring Transaction Agreements) Resources

The RtAgreements (Recurring Transactions Agreements) resource contains information about all past, present and future RT agreements.

RtAgreements resources are child resources to the Customers resource they belong to.

An RtAgreements resource consists of the following fields;

Field NameDescriptionField NameDescription
idPrimary unique resource keypolicyRefRecurring Transaction Policy Reference
pidId of parent Customer resourcestartDateAgreement start date (YYYY-MM-DD)
typeType of resource (always ‘addons’)transactionUniqueUnique reference per transaction
ptypeType of parent resource (always ‘customers’)methodMethod (ECOM, MOTO or CA)
UriURI of resourceinitialDateInitial payment date (YYYY-MM-DD)
puriURI of parent Customer resourceinitialAmountInitial payment amount (YYYY-MM-DD)
pathHierarchical path to resourcefinalDateFinal payment date (YYYY-MM-DD)
textShort textual description of the resourcefinalAmountFinal payment amount (YYYY-MM-DD)
rtAgreementIDPrimary unique resource key (same as ‘id’)cycleAmountCost per billing cycle
rtAgreementUriURI of resource (same as ‘uri’)cycleDurationPlan cycle duration
rtAgreementNameName of agreementcycleDurationUnitPlan cycle duration unit. One of ‘day’, ‘week’, ‘month’, ‘year’
customerIDId of parent/ancestor Customer resourcecycleCountNumber of cycles plan last for
customerUriURI of parent/ancestor Customer resourcecycleRemainingCountNumber of cycles remaining in the current agreement
customerNameName of parent/ancestor Customer resourcecurrencyCodeCurrency the ‘amount’ are in (ISO 3 letter code, ie ‘GBP’)
resellerIDId of ancestor Reseller resourcecurrencyNameDescriptive name of the currency
resellerUriURI of ancestor Reseller resourcecurrencySymbolSymbol for the currency
resellerNameName of ancestor Reseller resourcecurrencyExponentExponent for the currency
merchantIDId of Merchants Resource used to take paymentscurrentCycleStartDateStart date of the current cycle
merchantNameName Merchants Resource used to take paymentscurrentCycleEndDateEnd date of the current cycle
merchantUriUri of Merchants Resource used to take paymentslastTrasactionIDID of last recurring transaction
cardIDId of Cards resource used to take paymentslastTransactionUriURI of last recurring transaction was sent
cardNameName of Cards resource used to take paymentslastTransactionXrefCross reference of last recurring transaction (and used as xref of next transaction)
cardUriUri of Cards resource used to take paymentslastTransactionDateDate the last recurring transaction was sent
walletIDId of Cards resource’s parent Wallets resourcepaymentFailCountNumber of times recurring transaction has been retried
walletNameName of Cards resource’s parent Wallets resourcepaymentFailMaxRetriesNumber of times recurring transaction will be retried before giving up.
walletUriUri of Cards resource’s parent Wallets resourcertusEnabledRecurring Transaction Update Service enabled. If enabled the card details will be checked for updates in card number and expiry date.
descriptionDescription of the agreementrtusMerchantIDId of Merchants Resource used to make RTUS enquiries
baseTrasactionIDTransaction id of base Transaction resourcertusMerchantUriUri of Merchants Resource used to make RTUS enquiries
baseTransactionUriURI of base Transaction resourcertusMerchantNameName Merchants Resource used to make RTUS enquiries
baseTransactionXrefCross reference of base Transaction resourcemerchantDataFree format data (for merchants use)
baseTransactionDateDate the base Transaction was sentstateState of the agreement. One of ‘pending’, ‘running’, ‘pastdue’, ‘expired’, ‘stopped’ or ‘aborted’
responseCodeResponse code of last recurring transactioncreateTimeTime the resource was created (UTC)
responseMsgResponse message of last recurring transactionmodifyTimeTime the resource was modified (UTC)
transactionCntNumber of transactions made as part of this SubscriptionstatusResource status ‘active’ or ‘inactive’
transactionsUriUri to Transactions resource collection contain transactions made as part of this SubscriptionpermsResource permissions (to this resource) for the authenticated user

RTUS (Recurring Transaction Update Service) Enquiries Resources

The RtusEnquiries (Recurring Transaction Update Service Enquiries) resource contains information about payment cards that should be submitted on behalf of a Merchant in the next Recurring Transaction Update Service enquiry. This service will query the card scheme for changes in the card number and expiry date and if any recurring transactions should be stopped on the card.

Wallet stored Cards can automatically be included in the next RTUS enquiry by setting their rtusEnabled property, they will not be shown in the RtusEnquiries resource. Likewise Wallet Cards stored used as payment for subscriptions will automatically be included. RtusEnquiries resources are child resources to the Merchants resource they belong to.

A RtusEnquiries resource consists of the following fields:

Field NameDescriptionField NameDescription
idPrimary unique resource keyresellerIDId of ancestor Reseller resource
pidId of parent Customer resourceresellerUriURI of ancestor Reseller resource
typeType of resource (always 'rtusenquiries')resellerNameName of ancestor Reseller resource
ptypeType of parent resource (always ‘customers’)cardsCsvCard records in CSV format (see below)
UriURI of resourcecardsCard records in native format (see below)
puriURI of parent Customer resourcetotalCountTotal number of cards included in this enquiry
pathHierarchical path to resourcecompletedCountNumber of cards whose status has been checked
textShort textual description of the resourceompletedPercentPercentage of cards whose status has been checked
rtusEnquiryIDPrimary unique resource key (same as ‘id’)updatedCountNumber of cards whose details have been updated
rtusEnquiryUriURI of resource (same as ‘uri’)updatedPercentPercentage of cards whose details have been updated
merchantIDId of parent Merchant resourcecreateTimeTimethe resource was created (UTC)
merchantUrlURI of parent Merchant resourcemodifyTimeTime the resource was modified (UTC)
merchantNameName of parent Merchant resourcepermsResource permissions (to this resource) for the authenticated user
customerIDId of ancestor Customer resourcecustomerUriURI of ancestor Customer resource
customerNameName of ancestor Customer resource

RtusEnquiries.CardsCsv Property

The payment cards can be included in the RtusEnquiries (Recurring Transaction Update Service Enquiries) resource using the cards property or the cardsCsv property. The cardsCsv property expects a single string of data containing the contents of the CSV file used to upload/download the card details in the Merchant Management System (MMS). The string should contain one or more CSV records separated by a new line character. The records should contain the following cells:

Cell NumberDescription
1Version identifier (always ‘C1.1’)
2Card number (full PAN – 13-19 digits)
3Card expiry date [MMYY]
4Recurring Transaction (RT) Policy Ref [up to 20 characters] (optional)
5Recurring Transaction (RT) Frequency [0-8] (optional)
6Currency Code [180-4217 3 letter currency code] (optional)
7Next transaction amount [11 digits implied 2 decimals] (optional)
8Next transaction date [YYYY-MM-DD] (optional)
9Originators data (free format)
11New Card Number (if updated)
12New Expiry Number [MMYY] (if updated)
13Gateway response code (if updated)
14Gateway response message (if updated)

RtusEnquiries.Cards Property

The payment cards can be included in the RtusEnquiries (Recurring Transaction Update Service Enquiries) resource using the cards property or the cardsCsv property. The cards property expects an array of card records. This is the more natural format for the interface as it allows a simple nested array type format.. The cards array should contain records with the follow fields:

Field NameDescription
numberVersion identifier (always ‘C1.1’)
expiryDateCard number (full PAN – 13-19 digits)
policyRefRecurring Transaction (RT) Policy Ref [up to 20 characters] (optional)
transasctionFrequencyRecurring Transaction (RT) Frequency [0-8] (optional)
currencyCodeISO-4217 3 character currency code
currencyNameISO-4217 currency name
currencySymbolISO-4217 currency symbol
currencyCodeCurrency Code [180-4217 3 letter currency code] (optional)
nextTranasctionAmountNext transaction amount [11 digits implied 2 decimals] (optional)
nextTransactionDateNext transaction date [YYYY-MM-DD] (optional)
dataOriginators data (free format)
newNumberNew Card Number (if updated)
newExpiryDateNew Expiry Number [MMYY]2 (if updated)
responseCodeGateway response code (if updated)
responseMessageGateway response message (if updated)

RTUS (Recurring Transaction Update Service) Files Resources

The RtusFiles (Recurring Transaction Update Service Files) resource contains information about communications with an Acquirer’s Recurring Transaction Update Service. This is a read only resource, the REST interface cannot be used to modify these resources.

RtusFiles resources are root resources and have no parent or child resources. A RtusFiles resource consists of the following fields:

Field NameDescription
idPrimary unique resource key
pidId of parent resource (always blank)
typeType of resource (always ‘rtusfiles’)
ptypeType of parent resource (always blank)
UriURI of resource
puriURI of parent Wallet resource
pathHierarchical path to resource
textShort textual description of the resource
rtusFileIDPrimary unique resource key (same as ‘id’)
rtusFileUriURI of resource (same as ‘uri’)
rtusFileNameName of resource
processorIDId of associated Processor resource
processorUrlURI of associated Processor resource
processorNameName of associated Processor resource
dateDate the communications started
totalValueValue of all amounts included
totalCountNumber of card enquiries included
updatedCountNumber of cards updated
outSentTimeTime the output file was successfully sent to the Acquirer
ackRecvTimeTime the acknowledgement file was received
rspRecvTimeTime the response file was received
dependentOnFileIDId of RtusFile resource this one is dependent on
dependentOnFileUriURI of RtusFile resource this one is dependent on
dependentOnFileNameName of RtusFile resource this one is dependent on
dependentOnFileStateState of RtusFile resource this one is dependent on
stateProcessing state (one of ‘out’, ‘ack’, ‘rep’, ‘fin’ or ‘err’)
responseCodeResponse code of last processing stage
responseMessageResponse message for above responseCode
createTimeTime the resource was created (UTC)
modifyTimeTime the resource was modified (UTC)
permsResource permissions (to this resource) for the authenticated user

Gateway Wallet

The Gateway supports an internal digital Wallet that is available to all Merchants using the Gateway.

The Gateway allows you to store your Customer’s payment card, billing and delivery address details and other information securely encrypted in its internal Wallet. You can then allow your Customer to select from stored payment cards to check out faster on your website.

Management of this Wallet is done using the Gateway’s REST API. However, you can use the Hosted, Direct or Batch Integrations to perform transactions, using cards and addresses stored in the Wallet; or to store new cards and address used with successful transactions.

Benefits

  • Details can be used from or added to the Wallet with just a few extra integration fields.
  • Customers can select from previously stored details, making the checkout process more streamlined, resulting in fewer abandoned carts and thus increasing sales.
  • Compatible with existing card base fraud solutions such as Address Verification Service (AVS), 3-D Secure and third-party fraud providers.
  • There are no extra costs to use the internal Gateway Wallet.
  • The Wallet transactions are controlled within the Merchant Management System (MMS) in the same manner as normal card transactions.
  • Stored cards are assigned a Card Token which is fully LUHN checkable PAN ending in the same last 4 digits as stored card and thus can be used to replace the PAN in any system that is expecting to store PANs and not arbitrary card identifiers.

Limitations

  • The payment details are stored internally by the Gateway and not available for use with other Gateway Merchants or other payment gateways.

Implementation

If a transaction is sent to the Direct Integration, then with the addition of a few extra integration fields, it can be instructed to use payment details stored in the Wallet and/or store the used payment details.

Using stored payment details is similar to performing cross-referenced transactions where the payment details are cloned from a previous transaction. However, in this case the payment details are taken from the Wallet and not a previous transaction.

The details are only saved if the transaction is successful, ensuring that the Wallet is not filled up with invalid payment details.

The details requiring to be stored in the Wallet are validated when the transaction is performed prior to any authorisation with the Acquirer. If any of the details are invalid, then the transaction will be aborted with a responseCode of 66304 (INVALID_REQUEST) and a responseMessage indicating which data could not be stored in the Wallet. Any failure that occurs post authorisation will not abort the transaction but will be available in the appropriate xxxxStoreResponseCode response fields.

The walletOwnerRef field can be used to assign a unique Customer reference to the Wallet allowing you to identify which of your Customers owns the Wallet. This could be the Customer reference you use within your own Customer accounts or Shopping Cart software. You must ensure that this value is less than 50 characters, or the transaction will be aborted with a responseCode of 65xxx (INVALID_WALLETCUSTOMERREF).

Request Fields

NameMandatoryDescription
walletIDNoIdentifier for an existing Wallet to use.
walletNameNoName for any new Wallet created.
walletDescriptionNoDescription for any new Wallet created.
walletOwnerRefNoOwner Reference for any new Wallet created.
walletDataNoMerchant Data for any new Wallet created.
walletStoreNoRequest that all payment details be stored in the Wallet. A new Wallet will be created if needed.

Possible values are:
Y- store all payment details.
N- store details according to their xxxStore value.
cardIDNoIdentifier for an existing card stored in a Wallet.
cardTokenNoIdentifier for an existing card stored in a Wallet represented as valid PAN ending with same last 4 digits as the stored PAN.
cardNameNoName for any new card stored.
cardDescriptionNoDescription for any new card stored.
cardDataNoMerchant Data for any new card stored.
cardStoreNoRequest that the payment card details be stored in the Wallet. A new Wallet will be created if needed.

Possible values are:
Y- store the card details.
N- do not store the card details.
customerAddressIDNoIdentifier for an existing address stored in a Wallet.
customerAddressNameNoName for any new address stored.
customerAddressDescriptionNoDescription for any new address stored.
customerAddressDataNoMerchant Data for any new address stored.
customerAddressStoreNoRequest that the customer address details be stored in the Wallet. A new Wallet will be created if needed.

Possible values are:
Y- store the customer address details.
N- do not store the customer address details.
deliveryAddressIDNoIdentifier for an existing address stored in a Wallet.
deliveryAddressNameNoName for any new address stored.
deliveryAddressDescriptionNoDescription for any new address stored.
deliveryAddressDataNoMerchant Data for any new address stored.
deliveryAddressStoreNoRequest that the delivery address details be stored in the Wallet. A new Wallet will be created if needed.

Possible values are:
Y- store the delivery address details.
N- do not store the delivery address details.

Response Fields

These fields will be returned in addition to the request fields from section.

NameMandatoryDescription
walletStoreResponseCodeNoResult of creating or updating the Wallet details. Refer to Response Codes for details.
walletStoreResponseMessageNoDescription of above response code.
cardStoreResponseCodeNoResult of creating or updating the card details. Refer to Response Codes for details.
cardStoreResponseMessageNoDescription of above response code.
customerAddresStoreResponseCodeNoResult of creating or updating the address details. Refer to Response Codes for details.
customerAddressStoreResponseMessageNoDescription of above response code.
deliveryAddressStoreResponseCodeNoResult of creating or updating the address details. Refer to Response Codes for details.
deliveryAddressStoreResponseMessageNoDescription of above response code.

If new items are stored in the Wallet, then their identifiers will be returned in the appropriate walletID, cardID, customerAddressID and deliveryAddressID together with any values provided for or assigned by default to the other item fields.

Failure to store any of the details in the Wallet will be reported using the appropriate xxxxStoreResponseCode response field.

Payment Tokenisation

All new transactions stored by the Gateway are assigned a unique reference number that is referred to as the cross reference and returned in the xref response field. This cross reference is displayed on the Merchant Management System (MMS) and used whenever a reference to a previous transaction is required.

The cross reference can be sent as part of a transaction request, in the xref request field, to tell the Gateway to perform an action on an existing transaction. This is usually for management actions such as CANCEL or CAPTURE.

The cross reference can also be sent with new transactions such as PREAUTH, SALE, and REFUND actions, to request that the Gateway uses the values from the existing transaction if they have not been specified in the new request. For more information on how the existing values are used, please refer to the transaction cloning section. This allows an existing transaction to be effectively repeated without you needing to know the original card number. The only exception to this is the card’s security code (CVV) which the Gateway cannot store, due to PCI DSS restrictions. Accordingly, it will have to be supplied in the new request (unless the new request is a Continuous Authority transaction, refer to the continuous authority section.

The use of cross references to perform repeat transactions is referred to as Payment Tokenisation and should not be confused with Card Tokenisation which is a separate service offered by the Gateway.

Refer to the credentials on file section for details on how to instruct the Gateway to repeat a payment automatically.

The Gateway will make transaction details available for a maximum period of 13 months, after this time the xref to the transaction will be invalid. The card number will be available during this time, but you may request that it is removed sooner. Once the card number has been removed the xref can no longer be used to provide the number to a future a transaction.

The way each action handles any supplied xref is as follows:

PREAUTH, SALE, REFUND, VERIFY requests

These requests will always create a new transaction.

The xref field can be provided to reference an existing transaction, which will be used to complete any missing fields in the current transaction. The previous transaction will not be modified. For more information on how the existing values are used, please refer to the transaction cloning section. If the existing transaction cannot be found, then an error will be returned and recorded against the new transaction.

The request is expected to contain any transaction information required.

The xref will only be used to complete any missing card and order details, relieving you from having to store card details and reducing your PCI requirements.

REFUND_SALE requests

These requests will always create a new transaction.

The xref field can be provided to reference an existing transaction that is going to be refunded. This existing transaction will be marked as have been fully or partially refunded and the amounts will be tallied to ensure that you cannot refund more than the original amount of this existing transaction. If the existing transaction cannot be found, then an error will be returned and recorded against the new transaction.

The request is expected to contain any transaction information required.

The xref will not only be used to find the transaction to be refunded: additionally, that transaction will be used to complete any missing card and order details, relieving you from having to store card details and reducing your PCI requirements.

CANCEL or CAPTURE requests

These requests will always modify an existing transaction.

The xref field must be provided to reference an existing transaction, which will be modified to the desired state. If the existing transaction cannot be found, then an error is returned but no record of the error will be recorded against any transaction.

The request must not contain any new transaction information any attempt to send any new transaction information will result in an error. The exception is that a CAPTURE request can send in a new lesser amount field when a lesser amount, than originally authorised, must be settled.

QUERY requests

These requests will not create or modify any transaction.

The xref field must be provided to reference an existing transaction, which will be returned as if it had just been performed. If the existing transaction cannot be found, then an error is returned but no record of the error will be recorded against any transaction.

The request must not contain any new transaction information and any attempt to send any new transaction information will result in an error.

SALE or REFUND Referred Authorisation requests

These will always create a new transaction.

The xref field must be provided to reference an existing transaction, which must be of the same request type and be in the referred state. A new transaction will be created based upon this transaction. If the existing transaction cannot be found or is not in the referred state, then an error will be returned and recorded against the new transaction.

The new transaction will be put in the approved state and captured when specified by the existing or new transaction details. It will not be sent for authorisation again first.

The request may contain new transaction details, but any card details or order amount must be the same as the existing transaction. Any attempt to send different card details or order details will result in an error.

NB: This usage is very similar to a normal SALE or REFUND request sent with an authorisationCode included. The difference is that the xref must refer to an existing referred transaction whose full details are used if required and not simply an existing transaction whose card details are used if required.

This means it is not possible to create a pre-authorised SALE or REFUND request and use a xref (ie to use the card and order details from an existing transaction). As a soon as the xref field is seen, the Gateway identifies that it is a referred transaction that you wish to authorise.