# Card on File
When card details are stored to streamline the checkout process for returning customers. This can be used for one-click payments, pay-per use services, or any recurring payment that follows or does not follow a fixed schedule.
Fixed Scheduled recurring payment is referred to as subscription.
Unscheduled card-on-file payment are used for transactions that occur on a non-fixed schedule and/or have variable amounts.
If you are performing a payment using full card and that these details originated from customer's card details stored on your server, you need to flag the payment transaction with payer.funding_instrument.credit_card.stored: true
Note
Card details can only be stored by merchants if they are PCI Compliant Level 1/Level 2. Otherwise, the merchants must use OMPay vault to store card details.
There are two types of stored credential transactions:
- Cardholder-initiated Transaction (CIT)
- Merchant-initiated Transaction (MIT)
# Cardholder-initiated Transaction (CIT)
A Cardholder Initiated Transaction (CIT) is where the cardholder actively selects the card to use, and completes the transaction using previously stored details. For example, a registered customer return to your store to buy an item and using a card previously stored with the merchant.
To satisfy the requirements of Cardholder Initiated Transaction using full card API (i.e. Merchant is PCI Compliant Level 1/Level 2), you will need to flag the second payment transaction with payer.funding_instrument.credit_card.stored: true.
If you are performing the Cardholder Initiated Transaction using card Id, you do not need to flag the transaction, as this is dealt internally.
# Merchant-initiated Transaction (MIT)
Merchants commonly initiate MITs without the active participation of the cardholder provided they previously consented to you carrying out such payments. These may be scheduled (such as subscription payment) or unscheduled (like automatic top-ups when a cardholder's balance drops below a certain amount).
OMPay securely store payment details to enable MITs. For this, the cardholder must either initiate a payment or a card verification transaction. In response, the merchant will get a reference to the payment transaction (attribute reference_id). The merchant can use this payment reference in the future. For this, a merchant passes the payment reference with the authorisation call every time a shopper should be charged for subscription or initiates an unscheduled MIT. The attribute previous_payment_id is used for this.
# Scheduled Merchant-Initiated Transaction
Recurring payments that occur on a fixed schedule and with a fixed amount. Popular examples of subscription payments are music and TV streaming services.
To satisfy the requirement of Scheduled MIT:
| Initial cardholder-initiated transaction attributes | Subsequent payment |
|---|---|
merchant_initiated: false transaction.type: 2 | merchant_initiated: true previous_payment_id: <reference_id> transaction.type: 2 |
If the merchant is sending full card details (i.e. Merchant is PCI Compliant Level 1/Level 2), you will need to flag the second payment transaction with payer.funding_instrument.credit_card.stored: true.
# Unscheduled Merchant-Initiated Transaction
An unscheduled merchant-initiated payment occur on a non-fixed schedule and/or have variable amounts. For example, automatic top-ups when a cardholder's balance drops below a certain amount.
To satisfy the requirement of unscheduled MIT:
| Initial cardholder-initiated transaction attributes | Subsequent payment |
|---|---|
merchant_initiated: false | merchant_initiated: true previous_payment_id: <reference_id> |
If the merchant is sending full card details (i.e. Merchant is PCI Compliant Level 1/Level 2), you will need to flag the second payment transaction with payer.funding_instrument.credit_card.stored: true.
Note
You should send proper identifiers in your payment request to distinguish between these two types of merchant-initiated transactions as card schemes handle scheduled and unscheduled payments differently.