Credential on File Agreements

(Previously called "Subscriptions")

A credential on file agreement allows the merchant to create an agreement with the cardholder, in order to store the credentials to process future purchases.

A credential is, including but not limited to, card number and payment token.

Due to the increase in the number of transactions where stored credentials are used, the Card Schemes want to be able to identify their storage and subsequent use to enable appropriate processing. This should lead to improved conversion rates.

The protocol has two types of initiation:

Initiation Type	Description
CIT Cardholder Initiated Transaction	Any transaction in which the cardholder is actively participating, and as such is part of the payment flow.
MIT Merchant Initiated Transaction	Any transaction initiated by the merchant in which the cardholder is not part of the payment flow.

There are three types of agreements available:

Agreement Type	Description
Recurring	Allows the merchant to charge the customer with a specific frequency and in most cases with a specific amount, in exchange for fixed goods or services.
Instalment	Allows the merchant to charge the customer instances that sum up to the total amount of goods or services, spread out over an agreed finite period of time, with a fixed frequency.
Unscheduled	Allows the merchant to charge the customer for goods or services that do not follow a specific frequency, neither have a fixed amount to be paid out.

AltaPay Implementation

Any payments issued for a specific agreement consists of two steps:

1. Setup the Agreement

   You can do this by calling the endpoint /setupSubscription + agreement_type.

   This is equivalent to /createPaymentRequest + type=subscription + agreement_type (agreement_type is optional).

   agreement_type	Initiation Type	Notes
   recurring	CIT	Default. If no unscheduled_type is provided, recurring will be used. SCA takes place
   instalment	CIT	SCA takes place
   unscheduled	CIT	SCA takes place

2. Charge the Agreement

   You can do this by calling:

   • /reserveSubscriptionCharge + /capture
   • /chargeSubscription

   You might need to specify unscheduled_type, based on the following table:

   agreement_type	unscheduled_type
   recurring	Not required
   instalment	Not required
   unscheduled	Required

   If an unscheduled agreement is being charged, you can define unscheduled_type as follows:

   unscheduled_type	Initiation Type	Notes
   incremental	MIT	No cardholder authentication required
   resubmission	MIT	No cardholder authentication required
   delayedCharges	MIT	No cardholder authentication required
   reauthorisation	MIT	No cardholder authentication required
   noShow	MIT	No cardholder authentication required
   charge	CIT	SCA takes place

VerifyCard as Unscheduled Charges

For backwards compatibility, it is possible to use the verifyCard to set up an unscheduled charges agreement.

Setup the Agreement

You can do this by sending a /verifyCard request. Please make sure you store both the paymentId and the credit card token in your system.

Charge the Agreement

You can do this by sending a /reservation + agreementId=paymentId + ccToken + unscheduled_type (as described above)

This is equivalent to /createPaymentRequest + type=payment|paymentAndCapture + ccToken + unscheduled_type

FAQ

• I was doing recurring payments before, how is my integration affected?

  In that case, you do not require to send any new parameter. All defaults are modelling the recurring flow. However, the recurring flow is not supposed to be used for instalment or unscheduled. If that is the case, you will have to setup a new agreement. If you are unsure, please contact support.

• Will you deprecate verifyCard?

  It is not our plan, but we are looking into an agreement API, which will function in the same way as the current subscription API. We recommend you integrate to the latter instead.