Card Transaction Authentications (3DS)

Overview

3D Secure Authentication, also known as cardholder transaction authentication, is a security protocol that helps to prevent fraud in online (via e-commerce) credit and debit card transactions. This security feature is supported by Visa and Mastercard.

3DS Card Transaction Authentication happens before payment authorization. If the cardholder passes authentication, the transaction is sent to IF for authorization.

Card Transaction Authentication Statuses

  • Pending: Initial state, the card transaction authentication created by the cardholder.
  • Approved: The cardholder was successfully authenticated.
  • Rejected: The cardholder could not be successfully authenticated.
  • Cancelled: The cardholder canceled the transaction authentication via the challenge screen.

Update a Card Transaction Authentication

PATCH /card-transaction-authentications/{cardTransactionAuthenticationId}

Updatable features of a Card Transaction Authentication:

parameterdescriptionrequirement
statusapproved, rejectedrequired
{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "cardTransactionAuthentication": {
      "status": "approved" 
    }
  },
  "connect": {},
  "metadata": {}
}
{
 "workflow": {
        "code": "direct"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "3ccfcd31-1bf7-4935-9b25-7985f085a590",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "approved",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "http://admired-juice.name",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-18T11:34:01",
                "amount": 2224,
                "currency": "GBP"
            },
            "connection": {
                "id": "9c5dc5a3-0191-4eae-a824-f3614f0436ea",
                "serviceProvider": "thredd",
                "reference": "e8b8c635-2f40-43d9-8fe0-6927619a85b3",
                "state": "update-in-progress",
                "status": "pending"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
{
 "workflow": {
    "code": "direct"
  },
  "data": {
    "cardTransactionAuthentication": {
      "status": "rejected"
    }
  },
  "connect": {},
  "metadata": {}
}
{
 "workflow": {
        "code": "direct"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "fdfb1624-ff51-46b4-9c75-d7ccdff65b09",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "rejected",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://breakable-chairperson.info",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-18T11:19:06",
                "amount": 2223,
                "currency": "GBP"
            },
            "connection": {
                "id": "c7d7f515-15dc-4e65-9f47-066f9d464c4b",
                "serviceProvider": "thredd",
                "reference": "0358b1ef-3638-486d-b301-adc8dd8452e2",
                "state": "update-in-progress",
                "status": "pending"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

Get a Card Transaction Authentication

GET /card-transaction-authentications/{cardTransactionAuthenticationId}

{
 "workflow": {},
    "data": {
        "cardTransactionAuthentication": {
            "id": "fdfb1624-ff51-46b4-9c75-d7ccdff65b09",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "rejected",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://breakable-chairperson.info",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-18T11:19:06",
                "amount": 2223,
                "currency": "GBP"
            },
            "connection": {
                "id": "c7d7f515-15dc-4e65-9f47-066f9d464c4b",
                "serviceProvider": "thredd",
                "reference": "0358b1ef-3638-486d-b301-adc8dd8452e2",
                "state": "completed-up-to-date",
                "status": "failure"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

List Card Transaction Authentications

GET /card-transaction-authentications

Supported query parameters:

parameterdescription
metadata.page.number0-indexed, default=0
metadata.page.sizedefault=10
data.cardTransactionAuthentication.clientIdID of client
data.cardTransactionAuthentication.cardIdID of card
data.cardTransactionAuthentication.typebiometric
data.cardTransactionAuthentication.statuspending, approved, rejected, cancelled
data.cardTransactionAuthentication.serviceProviderService Provider of card transaction authentication
data.cardTransactionAuthentication.clientTitleClient Title
data.cardTransactionAuthentication.clientNumberClient Number
{
 "workflow": {},
    "data": {
        "cardTransactionAuthentications": [
            {
                "id": "70475d93-1e44-4d85-86ab-f9e488e773cd",
                "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
                "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
                "type": "biometric",
                "status": "approved",
                "serviceProvider": "thredd",
                "merchant": {
                    "acquirer": null,
                    "id": "MERCHANT 000001",
                    "name": "ASDA GROCERIES",
                    "url": "https://better-yard.info",
                    "categoryCode": null,
                    "country": "032",
                    "appRedirectUrl": null
                },
                "transaction": {
                    "creationDateTime": "2024-03-08T12:55:26",
                    "amount": 99,
                    "currency": "EUR"
                },
                "connection": {
                    "id": "00000000-0000-0000-0000-000000000000",
                    "serviceProvider": "thredd",
                    "reference": "00000000-0000-0000-0000-000000000000",
                    "state": "completed-up-to-date",
                    "status": "success"
                }
            },
            {
                "id": "bebdc3f0-0a1a-4090-85b0-0726a09069f0",
                "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
                "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
                "type": "biometric",
                "status": "pending",
                "serviceProvider": "thredd",
                "merchant": {
                    "acquirer": null,
                    "id": "MERCHANT 000001",
                    "name": "ASDA GROCERIES",
                    "url": "https://first-missile.com",
                    "categoryCode": null,
                    "country": "032",
                    "appRedirectUrl": null
                },
                "transaction": {
                    "creationDateTime": "2024-03-08T12:52:09",
                    "amount": 77,
                    "currency": "EUR"
                },
                "connection": {
                    "id": "00000000-0000-0000-0000-000000000000",
                    "serviceProvider": "thredd",
                    "reference": "00000000-0000-0000-0000-000000000000",
                    "state": "completed-up-to-date",
                    "status": "pending"
                }
            }
        ]
    },
    "connect": {},
    "metadata": {
        "page": {
            "size": 20,
            "number": 1,
            "totalElements": 50,
            "totalPages": 3
        }
    }
}

Webhooks

Card Transaction Authentication webhooks have "card-transaction-authentications" in the module field in the webhook container object.

There are 7 different types of webhooks for card transaction authentications, 4 of which show changes on the card transaction authentication and 3 of which show changes on the service provider of the card transaction authentication:

Card Transaction Authentication

  • card-transaction-authentication-created
  • card-transaction-authentication-approved
  • card-transaction-authentication-rejected
  • card-transaction-authentication-cancelled

Card Transaction Authentication Connection

  • connection-update-instructed
  • connection-updated
  • connection-update-failed

These types are exposed in the webhook.type field.

{
 "webhook": {
        "module": "card-transaction-authentications",
        "type": "card-transaction-authentication-created"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "3bde4775-437c-45ed-83bb-8ce86463962c",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "pending",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://past-transmission.biz",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-15T13:27:58",
                "amount": 1100,
                "currency": "GBP"
            },
            "connection": {
                "id": "af21379d-fe37-4beb-afd4-8e6aa7bb6b86",
                "serviceProvider": "thredd",
                "reference": "187c2177-f532-4a0b-bdc3-5476833e9f33",
                "state": "completed-up-to-date",
                "status": "pending"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
{
 "webhook": {
        "module": "card-transaction-authentications",
        "type": "card-transaction-authentication-approved"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "3bde4775-437c-45ed-83bb-8ce86463962c",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "approved",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://past-transmission.biz",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-15T13:27:58",
                "amount": 1100,
                "currency": "GBP"
            },
            "connection": {
                "id": "af21379d-fe37-4beb-afd4-8e6aa7bb6b86",
                "serviceProvider": "thredd",
                "reference": "187c2177-f532-4a0b-bdc3-5476833e9f33",
                "state": "completed-up-to-date",
                "status": "success"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
{
 "webhook": {
        "module": "card-transaction-authentications",
        "type": "card-transaction-authentication-rejected"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "fdfb1624-ff51-46b4-9c75-d7ccdff65b09",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "rejected",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://breakable-chairperson.info",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-18T11:19:06",
                "amount": 2223,
                "currency": "GBP"
            },
            "connection": {
                "id": "c7d7f515-15dc-4e65-9f47-066f9d464c4b",
                "serviceProvider": "thredd",
                "reference": "0358b1ef-3638-486d-b301-adc8dd8452e2",
                "state": "completed-up-to-date",
                "status": "failure"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
{
 "webhook": {
        "module": "card-transaction-authentications",
        "type": "card-transaction-authentication-cancelled"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "98e11a77-9316-40ad-a794-d484dc62a23c",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "cancelled",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "http://parched-crush.net",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-18T11:12:19",
                "amount": 2222,
                "currency": "GBP"
            },
            "connection": {
                "id": "c15ddf9c-e7a9-4a90-8ac9-517e93980003",
                "serviceProvider": "thredd",
                "reference": "64a49b34-42bf-4081-b2df-ebadb4ffbe35",
                "state": "completed-up-to-date",
                "status": "cancelled"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

The connection section is optional. Once the card transaction authentication creation process has been initiated at the service provider, the current connection information can also be displayed.

Connection can have the following states:

statedescription
update-in-progressThe Card Transaction Authentication update is in progress.
completed-up-to-dateThe Card Transaction Authentication connection has been successfully created / updated and is up to date.
completed-outdatedThe Card Transaction Authentication connection update failed.
{
 "webhook": {
        "module": "card-transaction-authentications",
        "type": "connection-update-instructed"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "3bde4775-437c-45ed-83bb-8ce86463962c",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "approved",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://past-transmission.biz",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-15T13:27:58",
                "amount": 1100,
                "currency": "GBP"
            },
            "connection": {
                "id": "af21379d-fe37-4beb-afd4-8e6aa7bb6b86",
                "serviceProvider": "thredd",
                "reference": "187c2177-f532-4a0b-bdc3-5476833e9f33",
                "state": "update-in-progress",
                "status": "pending"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
{
 "webhook": {
        "module": "card-transaction-authentications",
        "type": "connection-updated"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "3bde4775-437c-45ed-83bb-8ce86463962c",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "approved",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://past-transmission.biz",
                "categoryCode": null,
                "country": "826",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-15T13:27:58",
                "amount": 1100,
                "currency": "GBP"
            },
            "connection": {
                "id": "af21379d-fe37-4beb-afd4-8e6aa7bb6b86",
                "serviceProvider": "thredd",
                "reference": "187c2177-f532-4a0b-bdc3-5476833e9f33",
                "state": "completed-up-to-date",
                "status": "success"
            }
        }
    },
    "connect": {},
    "metadata": {}
}
{
 "webhook": {
        "module": "card-transaction-authentications",
        "type": "connection-update-failed"
    },
    "data": {
        "cardTransactionAuthentication": {
            "id": "70475d93-1e44-4d85-86ab-f9e488e773cd",
            "clientId": "4d0cfc09-75ad-4ccc-a7d1-30a36393124b",
            "cardId": "5640c5b2-94a6-476e-8cfb-8e01b9cb8821",
            "type": "biometric",
            "status": "approved",
            "serviceProvider": "thredd",
            "merchant": {
                "acquirer": null,
                "id": "MERCHANT 000001",
                "name": "ASDA GROCERIES",
                "url": "https://better-yard.info",
                "categoryCode": null,
                "country": "032",
                "appRedirectUrl": null
            },
            "transaction": {
                "creationDateTime": "2024-03-08T12:55:26",
                "amount": 99,
                "currency": "EUR"
            },
            "connection": {
                "id": "af21379d-fe37-4beb-afd4-8e6aa7bb6b86",
                "serviceProvider": "thredd",
                "reference": "reference",
                "state": "completed-outdated",
                "status": "pending",
                "error": {
                    "category": "technical",
                    "origin": "platform",
                    "code": "unknown_error",
                    "message": "Unknown Error",
                    "attributes": {
                        "key": "value"
                    }
                }
            }
        }
    },
    "connect": {},
    "metadata": {}
}