Transaction Lifecycle

This page describes the card transaction lifecycle. All events across all your created cards will be reported under View card activities API

You can review example API output here: Example Card Activities (API response)

Online Card Verification (3DS)

As per PSD2 SCA requirements, Modulr cards support 2-Factor online transaction authentication via:

• SMS One Time Passcode (SMS OTP)
• Knowledge-Based Authentication (KBA)

All Modulr cards are automatically enrolled to 3DS service to ensure the best merchant acceptance. SMS OTP enrolment is done on the phone number and KBA fields are taken from the authentication object provided as part of the card creation request. Unless cards have been set up to be SCA exempt, cardholders will be occasionally asked to enter the code they have received to their mobile and to input one of the memorable answers in order to prove the ownership of the card.

📘

3DS management is done by Modulr

3DS step is performed before an authorisation is generated, which means that in case of 3DS step failure or cart abandonment, you will not be able to see the transaction under the card activities. 3DS rule and general card management are done solely by Modulr as a card issuer - if your client has issues with 3DS, they will be shown a Modulr number to call to verify their identity and Modulr support team will be able to then investigate and resolve any issues in relation to 3DS.

Authorisation (Card activity type: "AUTHORISATION")

When someone makes a purchase using a card, an authorisation record will be created.
The authorisation will be successful if:

• Card is in "ACTIVE" state
• Transaction amount does not exceed the card limit
• Transaction amount does not exceed the "available" account balance under which this card has been created.
• The transaction is done for the merchant which has been "allowed" by your Merchant Category Code (MCC) filter. MCC whitelist will be set-up as part of your production onboarding process to make sure that you are protected against transactions from the unwanted merchant types
• The transaction is in allowed currency(-ies) / amount (this restriction can set this at the point of card creation)

📘

Account Balances

If you wish to check the current available account balance, please use Get an account endpoint.

Authorisation Statuses

Status	Description	What else happens?
APPROVED	Successful authorisations will have a status of "APPROVED"	Your account "available" balance is reduced by the authorisation amount
DECLINED	If a transaction gets declined, the status will be set as "DECLINED" and a reason for the decline will be returned.	No amount will be reserved. Please note that in some cases, it may take up to 30 minutes for the authorisation to be updated with the failure reason (e.g. when the decline is related to the external payment gateway time-out)
EXPIRED	If an authorisation does not settle within 7 days (please refer to the section below on the settlement), then authorisation status will change to "EXPIRED", indicating that while merchant has put an initial block on the account, they have never then taken the funds.	Your account "available" balance is increased by the original authorisation amount and you can then use those funds to make new purchases
SETTLED	Once the merchant receives the funds and settlement is processed, then the authorisation status changes to "SETTLED" At this point, we will also create a new activity called "SETTLEMENT" which will be linked to the Authorisation using the same "ORDER ID" value	Your account "available" balance will now match the actual account balance. We will replace the amount reserved at the point of authorisation with the actual transaction amount (normally it will be the same) and you will now see a card transaction on your account transactions list Get Transactions for a specific Account

Authorisation Information

As part of an authorisation, there will be a type and input method provided (please note this may not be available for historical transactions that pre-date Modulr implementing these fields).

Type shows the environment in which the transaction was made and can be one of the following:

• ATM
• CP
• CNP_UNSPECIFIED
• CNP_MOTO
• CNP_RECURRING
• CNP_ECOMM
• UNKNOWN

Input method details how the card was read as part of the transaction and can be one of the following values:

• UNSPECIFIED
• KEYED
• KEYED_BY_ACQUIRER
• MAG_STRIPE_SWIPED
• MAG_STRIPE_CONTACTLESS
• OCR
• EMV_PIN
• EMV_CONTACTLESS
• ECOMM
• CARD_ON_FILE
• QR
• OTHER

📘

Authorisation Information abbreviations explained

ATM - Automated Teller Machine (also known as a cash machine)
CP - Card Present
CNP - Card Not Present
MOTO - Mail/Telephone Order
ECOMM - Ecommerce
OCR - Optical Character Recognition
EMV- the term used to refer to chip technology as part of a payment card
QR - Quick Response

📘

Pre-Auth

A pre-authorisation applies a reservation on a card to ensure there are enough funds to cover potential additional charges, such as a hotel or a Petrol Station. So works just like a standard authorisation. However, the final settlement can vary up or down from the Original Authorisation

This is usually down to additional Charges. During a pre-authorisation, the merchant may not know the final amount of your purchase. So, they place a hold for an estimated amount, and the final settlement reflects the actual total, which can be higher or lower than the original auth

Hold Period: The pre-authorisation hold can last up to 10 days.

Pre-authorisation ensures cardholder can cover potential expenses, but the final settlement reflects the actual cost, which can differ due to various factors relating to the service or goods been paid for

Reversal (Card activity type: "REVERSAL")

Merchant may reverse some or all of the original authorisation amount before it settles, creating a REVERSAL card activity. An example would be when you purchase your flight tickets and then immediately call for it to be cancelled.

All reversal activities will be linked to the original authorisation record using "ORDER ID", allowing you to compare the original amount which has been reserved and the amount which has been reversed.

📘

Some facts about the reversals

• When we get a reversal, we will increase your "available" account balance by the amount which has been reversed and will reduce the card "spend" value
• You may receive more than one "partial" reversal for the same authorisation.
• Reversal amount will never exceed the original authorisation amount.
• If authorisation does not settle within 7 (Normal Authorisation) or 10 (Pre-Authorisation) days an automated system reversal will be created on the following day at midnight to release the reserved funds.

Settlement (Card activity type: "SETTLEMENT")

Settlement is processed when a merchant receives money from your transaction. In 98% of cases, all transactions will "settle" by the 3rd working day.

As with reversals, all settlements will normally be linked to the original authorisation using the same "ORDER ID" value.

We have recently updated our settlement processing to run daily, at 06:30 BST (previously this was 16:00 BST). If you wish to monitor your cards or accounts for settlements, we would advise checking once a day, not earlier than 07:00 BST

🚧

Something to keep in mind

• Some transactions may take longer than 3 days to settle
• While we automatically expire authorisations after 7 days (10 days for pre-authorisations), you may still get a settlement after we have already marked the original authorisation as "EXPIRED". The status of such Authorisation will then change to "SETTLED"
• You may get multiple settlements for the same authorisation ("incremental settlement"). We are not always able to match them all using the same Order ID, but the total amount of all Settlements normally never exceed the original authorisation(s) amount(s)
• To make things even more interesting, you may even get a settlement for the transaction which never had an original authorisation (while this is very unlikely to happen, it could well happen with the likes of subscription services)
• Settlement amount may not match the original authorisation amount. This is more than likely to happen when a purchase has been made in a foreign currency and the scheme conversion rate is not known until the end of that trading day

Original Credits (Card activity type: "ORIGINAL CREDIT")

Original credits are transactions that credit the cardholders account via their card, these are different from other credit types as the transaction doesn't relate to another transaction like in refunds and reversals, they are their own individual transaction.

For the transaction to qualify as an Original Credit, the account where the funds are coming from are to be in the same name as the account the funds are to be paid into, they are also required to be in the same currency.

There will be two statuses on the transaction that will be seen, APPLIED and SETTLED. APPLIED is where the funds have been requested by the cardholder and Modulr have credited the account in near real-time, SETTLED is where the transactions have been reconciled like the normal process for refunds.

🚧

Something to keep in mind

• These transactions will be applied to the account in near-real time on day 1 based on notification from scheme
• The transactions will reconcile on day 3 as per the normal refund process
• In the event of a time out or a reversal requirement, we will recall the funds from the cardholder and adjust the balances accordingly

Last but not least...

Refund (Card activity type: "REFUND")

Refund is when a merchant credits your card as opposed to debiting. One key difference between the reversal and refund is that refunds are independent activities and are never linked to any previous card activity (i.e. no link to existing settlement or authorisation).

Refund will also most likely relate to a previous purchase which has already settled in the past, e.g. you already paid for a flight, but then received a refund because meal service was not available on the plane for which you have already prepaid. However, as this is processed as a separate transaction, we would not know whether it does relate to anything you have purchased in the past.

📘

Refunds and card spend calculation

• When we get a refund, we will increase your "available" account balance by the amount which has been reversed and will reduce the card "spend" value