SCA for funds transfers

Learn how to use our Authentication SDK to authenticate your users before they transfer funds.

Each time a user in the European Economic Area (EEA) wants to transfer funds, you must authenticate them using SCA. To do so:

Check SCA eligibility.
Initiate the transfer using the sdkOutput that you got when you checked the device for SCA eligibility.
Authenticate your user with the Authentication SDK.
Finalize the transfer using the sdkOutput from the authentication step.

Requirements

Make sure that you have installed the Authentication SDK.
Make sure that you have registered a device for your user.
Make sure that your API credential has the following role:
- TransferService Webservice Initiate role

Check SCA eligibility

Before initiating a transfer, you must check for SCA eligibility and initiate the process to authenticate your users.

The following tabs explain how to check for SCA eligibility and initiate authentication using Kotlin, Swift, or JavaScript.

To check if the Android device is eligible for SCA:

Initiate the AdyenAuthentication class in your Activity or Fragment.

Initiate authentication

 private lateinit var adyenAuthentication: AdyenAuthentication
 
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    adyenAuthentication = AdyenAuthentication(this)
}

Check if SCA is available on the device.

Check SCA eligibility

 lifecycleScope.launch {
    val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability()
    if (availabilityResult is AvailabilityResult.Available) {
        availabilityResult.sdkOutput
    }
}

The function returns an sdkOutput.

Pass the sdkOutput to your server.

You will use the sdkOutput when initiating the transfer.

Initiate transfer

The steps to initiate a transfer depend on whether you want to:

Authenticate the user when initiating a transfer request.
Authenticate the reviewer when approving a transfer request.

Because a reviewer can approve multiple transfers at the same time, performing SCA during approval allows you to satisfy the authentication requirements for multiple transfers with a single SCA process.

The following tabs explain both methods for initiating a transfer that requires SCA.

To initiate a funds transfer for your user and trigger SCA during approval, do the following:

Make a POST /transfers request, specifying the following parameters:

Parameter	Type	Description
amount	Body	The amount of the transfer.
balanceAccountId	Body	The unique identifier of the source balance account.
category	Body	Set to bank.
counterparty.bankAccount	Body	Contains information about the target bank account.
description	Body	A human-readable description for the transfer.
reference	Body	A reference of the transfer, only used internally within your balance platform.
referenceForBeneficiary	Body	A reference that is sent to the recipient.
review.numberOfApprovalsRequired	Body	Specifies the number of approvals required to process the transfer.
review.scaOnApproval	Body	Set to true.

Initiate funds transfer

 curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers \
-H 'x-api-key: YOUR_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
    "amount": {
        "currency": "EUR",
        "value": 1000
    },
    "balanceAccountId": "BA00000000000000000000001",
    "category": "bank",
    "description": "YOUR_DESCRIPTION_FOR_THE_TRANSFER",
    "reference": "YOUR_UNIQUE_REFERENCE_FOR_THE_TRANSFER",
    "referenceForBeneficiary": "YOUR_REFERENCE_SENT_TO_BENEFICIARY",
    "counterparty": {
        "bankAccount": {
            "accountHolder": {
                "fullName": "A. Klaassen"
            },
            "accountIdentification": {
                "type": "iban",
                "iban": "NL91ABNA0417164300"
            }
        }
    },
    "review": {
        "numberOfApprovalsRequired": 1,
        "scaOnApproval": true
    }
}'

Verify that you receive an HTTP 202 response that includes the following parameters:
- amount: You must show this data to your user during authentication.
- counterparty: You must show this data to your user during authentication.
- id: You must include the transfer ID in the POST /transfers/approve request.

Make a POST /transfers/approve request, specifying the following parameters:

Parameter name	Type	Required	Description
WWW-Authenticate	Header		`SCA realm`: ApproveTransfers. `auth-param1`: Base64-encoded value of sdkOutput you get when you initiate the SCA authentication process.
transferIds	Body		An array containing the unique identifiers of the transfers that you decide to approve. You can include the IDs of all transfers that have: — `status`: received — `reason`: pendingApproval

Approve funds transfer and trigger SCA

 curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers/approve \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-H 'WWW-Authenticate: SCA realm="ApproveTransfers" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl..."' \
-X POST \
-d '{
    "transferIds": [
        "APUFHASUFD4AS",
        "407ASFPUHASFA"
    ]
}'

Verify that the response header contains the following fields:

status: 401
auth-param1: Base64-encoded blob of data. You will need auth-param1 when you authenticate your user.

Response header

"WWW-Authenticate: SCA realm="ApproveTransfers" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl...""

Response for initiating the approval of a fund transfer

 {
  "type": "https://docs.adyen.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "response": {
      "transferIds": [
          "APUFHASUFD4AS",
          "407ASFPUHASFA"
      ]
  },
  "errorCode": "00_401"
}

Pass auth-param1 to the SDK as sdkInput.

Authenticate user

After initiating a transfer request, you have 10 minutes to complete the authentication process and finalize the transfer request.

When authenticating your user, PSD2 requires you to show to your user the amount and the counterparty (payee) of the transfer that the user is authenticating for. To comply with these regulations, we recommend that you implement a push notification and use the amount and counterparty fields from:

The response to the POST /transfers request you used to create the transfer.
The response to a GET /transfers/{id} request.

To authenticate your user with the Authentication SDK:

Trigger the SDK to start user authentication and pass the auth-param1 value from the previous step as sdkInput.

Authenticate with SCA SDK

 lifecycleScope.launch {
        if (adyenAuthentication.hasCredential("sdkInput")) {
            // Authenticate existing credential
            val authenticationResult: AuthenticationResult = adyenAuthentication.authenticate("sdkInput")
            when (authenticationResult) {
                is AuthenticationResult.AuthenticationSuccessful -> {
                    authenticationResult.sdkOutput
                }
                is AuthenticationResult.Canceled -> {
                    // User cancelled the authentication flow
                }
                is AuthenticationResult.Error -> {
                    // Unexpected error
                    authenticationResult.errorMessage
                }
                is AuthenticationResult.AuthenticationError -> {
                    // FIDO API Error
                    authenticationResult.authenticationError
                }
            }
        } else {
            // None of the existing credentials exist in this device
        }
    }

If successful, the SDK generates a Base64-encoded sdkOutput data blob.

Pass sdkOutput to your server.

Finalize transfer

The steps to initiate a transfer depend on whether you:

Authenticated the user when initiating a transfer request.
Authenticated the reviewer when approving a transfer request.

The following tabs explain both methods for finalizing a transfer after completing SCA.

To finalize the transfer:

Make a POST /transfers/approve request, specifying the following parameters:

The values of the body parameters must match the ones previously submitted to the /transfers/approve endpoint when initiating the transfer.

Parameter name	Type	Required	Description
WWW-Authenticate	Header		`SCA realm`: ApproveTransfers. `auth-param1`: Base64-encoded value of sdkOutput you get when you authenticate the user.
transferIds	Body		An array containing the unique identifiers of the transfers that you decide to approve.

Finalize approval of funds transfers

 curl https://balanceplatform-api-test.adyen.com/btl/v4/transfers/approve \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-H 'WWW-Authenticate: SCA realm="ApproveTransfers" auth-param1="CeCcEEJf2UPC7pB0K7AtEgLZX7cTvnqNznJF..."' \
-X POST \
-d '{
    "transferIds": [
        "APUFHASUFD4AS",
        "407ASFPUHASFA"
    ]
}'

Verify that you receive an HTTP 200 OK response with a header that contains status authorised.
Verify that you receive a balancePlatform.transfer.updated webhook with status authorised. This means that the authentication and transfer approval were successful.