SCA for transaction data retrieval

SCA will be enforced when a platform user attempts to access sensitive data such as the account balance or transaction data generated within the last 90 days unless SCA exemptions apply.

After the user successfully completes two-factor authentication, Airwallex will issue a short-lived SCA token (expires in five minutes), which the user can use multiple times to perform one or more sensitive operations until it expires.

The following Airwallex transaction data endpoints are subject to SCA.

• Get current balance
  • GET /api/v1/balances/current
• Get payment transactions
  • GET /api/v1/balances/history
  • GET /api/v1/financial_transactions
  • GET /api/v1/financial_transactions/{id}
  • GET /api/v1/issuing/card_transactions
  • GET /api/v1/issuing/card_transactions/{id}
  • GET /api/v1/issuing/card_transaction_events
  • GET /api/v1/issuing/card_transaction_events/{id}
  • GET /api/v1/issuing/lifecycles
  • GET /api/v1/issuing/lifecycles/{id}
  • GET /api/v1/issuing/transactions
  • GET /api/v1/issuing/transactions/{id}
  • GET /api/v1/issuing/transaction_lifecycles
  • GET /api/v1/issuing/transaction_lifecycles/{id}
  • GET /api/v1/issuing/transaction_lifecycles/{id}/events
  • GET /api/v1/issuing/transaction_lifecycles/{id}/events/{eventId}
  • GET /api/v1/transfers
  • GET /api/v1/transfers/{transfer_id}
  • GET /api/v1/wallet_transfers
  • GET /api/v1/wallet_transfers/{wallet_transfer_id}
  • GET /api/v1/batch_transfers
  • GET /api/v1/batch_transfers/{id}
  • GET /api/v1/connected_account_transfers
  • GET /api/v1/connected_account_transfers/{id}

This integration guide describes how to handle SCA enforcement for account balance or transaction retrieval using Airwallex's Embedded SCA component.

Step 1: Initialize the Components SDK

Initialize the Components SDK to handle SCA for the user. For information, see Embedded SCA component.

Step 2: Retrieve the SCA token from the SDK

Before adding the SCA component for two-factor authentication, check whether the SDK can retrieve a valid SCA token from a previous SCA flow. Airwallex automatically handles the process of exchanging a refresh token for a new SCA token. Use the returned short-lived SCA token in the account balance or transaction data request. See Step 4.

If a valid SCA token cannot be retrieved from the SDK, i.e., if it's a new device or the refresh token has expired, add the SCA component to re-authenticate the user. See Step 3.

1import { init } from '@airwallex/components-sdk'
2
3const { sca }= await init();
4// get the short-lived SCA token, which may be obtained via a refresh token
5if (await sca.getScaToken()) {
6  // call client API with scaToken, handling possible 403 errors (see step 5)
7} else {
8  // launch the SCA component to re-authenticate the user
9}

Step 3: Add the SCA component to your page

Embed the SCA verify flow into your page by specifying type as scaVerify in createElement(type, options) method. For more information on how to add the component to your page, see Embedded SCA component.

After the user is successfully authenticated using two-factor authentication, the SDK will return a success event verificationSucceed. The client side receives a short-lived SCA token and a refresh token. Retrieve the SCA token and use it in the account details and transaction data requests to complete the action.

1const scaElement = await createElement('scaVerify', {
2 userEmail: '<user_email>'
3});
4
5// mount the element with container DOM id
6scaElement.mount('<container_dom_id>');
7
8scaElement.on('ready', () => {
9 // remove loading state
10 setLoading(false);
11});
12scaElement.on('verificationSucceed', ({token}) => {
13 // Retrieve the SCA token and use in the API request to complete the action
14});
15scaElement.on('verificationFailed', ({reason}) => {
16 // Handle event on failed
17});
18
19scaElement.on('error', e => {
20 // Handle event on error
21});

Step 4: Retrieve account balance and transactions using SCA token

Call Get current balances API by specifying the short-lived SCA token in the x-sca-token request header to view the connected account's current balance.

1curl -G https://api.sandbox.airwallex.com/api/v1/balances/current \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'x-on-behalf-of: {{CONNECTED_ACCOUNT_OPENID}}' \
4  -H 'x-sca-token: {{YOUR_SCA_TOKEN}}'

Call Get balance history API by specifying the short-lived SCA token in the x-sca-token request header to view the connected account's transaction history.

1curl -G https://api.sandbox.airwallex.com/api/v1/balances/history \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'x-on-behalf-of: {{CONNECTED_ACCOUNT_OPENID}}' \
4  -H 'x-sca-token: {{YOUR_SCA_TOKEN}}'

Step 5: Handle stricter SCA enforcement for historical transaction data

For 180 days after the user completes SCA verification, getScaToken() can use the refresh token to obtain a short-lived SCA token. This token can retrieve transaction data from the previous 90 days.

To fetch transaction data older than 90 days, the user must have completed SCA verification within the previous five minutes, rather than obtaining a token through the refresh mechanism. Otherwise, the request returns the following error:

1Error code: 403
2body:
3{
4    "code": "sca_token_insufficient",
5    "message": "The SCA token in the request header `x-sca-token` is insufficient for this request. Please specify a stronger SCA token."
6}

Be prepared to handle this error in your integration code by launching the SCA component to re-authenticate the user.
Once re-authenticated, this grants a five minute window of time where the token is valid to fetch historical transactions.

1import { init } from '@airwallex/components-sdk';
2
3const { sca } = await init();
4// get the short-lived SCA token, which may be obtained via a refresh token
5const scaToken = await sca.getScaToken();
6if (scaToken) {
7  // call client API with scaToken
8  const response = await getTransactionData({ scaToken });
9  if (response.status === 403 && response.body?.code === 'sca_token_insufficient') {
10    // launch the SCA component again to re-authenticate the user, then retry
11  }
12} else {
13  // launch the SCA component to re-authenticate the user
14}