If you choose to enroll your Adyen-issued card in 3D Secure through the one-time password (OTP) flow, the cardholder goes through the following process when making an online payment:
- The cardholder is redirected to a 3D Secure authentication page. In this page, they must provide:
- Their password.
- A one-time password (OTP) sent through a text message to their mobile phone number.
- The cardholder's credentials are validated against the authentication data that you set for the card.
- If the authentication is successful, the payment is sent to Adyen for authorisation.
- If the authentication fails, the payment fails.
- If the payment authorisation is approved, the payment is completed.
Add authentication data
To enroll the Adyen-issued card in 3D Secure, add the cardholder's mobile phone number and a password when issuing cards.
When creating or updating the card, include the authentication object containing:
Adyen enrolls the card with the phone number and password in 3D Secure.
Here is an example of how you can create a card with authentication data to support 3D Secure authentication.
curl https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"type": "card",
"issuingCountryCode": "NL",
"balanceAccountId": "BA3227C223222B5CTBLR8BWJB",
"status": "inactive",
"card": {
"formFactor": "physical",
"brand": "mc",
"brandVariant": "mcdebit",
"cardholderName": "Sam Hopper",
"authentication": {
"password": "CARDUSERPASSWORD$1",
"phone":
{
"number": "31611223344",
"type": "Mobile"
}
},
"deliveryContact": {
"address": {
"city": "Amsterdam",
"country": "NL",
"stateOrProvince": "NH",
"street": "274 Brannan Street, Suite 600",
"houseNumberOrName": "50",
"postalCode": "1020CD"
},
"name": {
"firstName": "Sam",
"lastName": "Hopper"
}
},
"configuration": {
"configurationProfileId": "YOUR_CONFIGURATION_PROFILE_ID"
}
},
"description": "YOUR_DESCRIPTION"
}'You can also add the object at a later time or change the cardholder's phone number and password by sending a PATCH /paymentInstruments/{id} request to update the card.
curl --request PATCH https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments/{id} \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
"card": {
"authentication": {
"password": "CARDUSERPASSWORD$1",
"phone":
{
"number": "31611223344",
"type": "Mobile"
}
}
}
}'Get updates
We will notify you of the status and outcome of the authentication once the cardholder has completed 3D Secure authentication. Regardless of whether the authentication process was successfully completed, failed, or expired, we send the balancePlatform.authentication.created webhook.
To keep track of webhooks, make sure that your server can receive and accept webhooks.
The balancePlatform.authentication.created webhook contains the following information.
{
"data": {
"authentication": {
"acsTransID": "6a4c1709-a42e-4c7f-96c7-1043adacfc97",
"challengeIndicator": "01",
"createdAt": "2022-12-22T15:45:03+01:00",
"deviceChannel": "app",
"dsTransID": "a3b86754-444d-46ca-95a2-ada351d3f42c",
"exemptionIndicator": "lowValue",
"inPSD2scope": true,
"messageCategory": "payment",
"messageVersion": "2.2.0",
"riskScore": 0,
"threeDSServerTransID": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
"transStatus": "Y",
"type": "frictionless"
},
"balancePlatform": "YOUR_BALANCE_PLATFORM",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"paymentInstrumentId": "PI3227C223222B5BPCMFXD2XG",
"purchase": {
"date": "2022-12-22T15:49:03+01:00",
"merchantName": "TeaShop_NL",
"originalAmount": {
"currency": "EUR",
"value": 1000
}
},
"status": "authenticated"
},
"environment": "test",
"type": "balancePlatform.authentication.created"
}