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:
| parameter | description | requirement |
|---|---|---|
| status | approved, rejected | required |
{
"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:
| parameter | description |
|---|---|
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=10 |
| data.cardTransactionAuthentication.clientId | ID of client |
| data.cardTransactionAuthentication.cardId | ID of card |
| data.cardTransactionAuthentication.type | biometric |
| data.cardTransactionAuthentication.status | pending, approved, rejected, cancelled |
| data.cardTransactionAuthentication.serviceProvider | Service Provider of card transaction authentication |
| data.cardTransactionAuthentication.clientTitle | Client Title |
| data.cardTransactionAuthentication.clientNumber | Client 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:
| state | description |
|---|---|
| update-in-progress | The Card Transaction Authentication update is in progress. |
| completed-up-to-date | The Card Transaction Authentication connection has been successfully created / updated and is up to date. |
| completed-outdated | The 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": {}
}
Updated 4 months ago