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.