logo
Trustly Docs

Azura Core Recurring

The API is designed to streamline the checkout process by allowing users to easily utilise a previously used bank account at a merchant’s checkout, aiming to enhance onboarding conversion, decrease onboarding time, and encourage repeat usage. One should always allow the consumer to bypass the suggested account in a way, then the consumer will go through the bank-selection etc, but in general it's good to highlight the last used account and bank-logo.
Updated 2 days ago
Please note that we currently only support Sweden for Azura Core Recurring


A full Azura Core Recurring flow includes these requests:

  • AzuraRecurring

  • RemoveAzuraAccount (optional)

  • DirectDebitMandate

The AzuraRecurring request provides an Azura SessionID, which must be included in subsequent requests to DirectDebitMandate.

Below is a sequence diagram of how to interact with Azura and recurring.

The AzuraRecurring request provides checkout components without needing to start an order with Trustly.

Legal requirements

In compliance with legal requirements, if a clickable bank account is presented during the checkout process, it is imperative to prominently display the terms and conditions and privacy policy. This ensures transparency and informs users of their rights and obligations before proceeding with the transaction.

It's important to note that the terms and conditions and privacy policy may vary between countries, as each country may have its own regulations governing these documents. Therefore, it is essential to display the terms and conditions and privacy policy relevant to the country to which the banks and bank accounts belong.

If no bank accounts or banks are presented in the merchant's checkout for selection, it is not necessary to display the terms and conditions and privacy policy.

Request example

AzuraRecurring
{
  "method": "AzuraRecurring",
  "params": {
    "Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
    "UUID": "258a2184-2842-b485-25ca-293525152425",
    "Data": {
      "Username": "merchant_username",
      "Password": "merchant_password",
      "MessageID": "your_unique_request_id",
      "Attributes": {
        "Email": "test@trustly.com",
        "MobilePhone": "+46709876543",
        "EndUserID": "12345",
        "NationalIdentificationNumber": "197106091111",
        "Country": "SE",
        "Locale": "sv_SE",
        "Currency": "SEK"
      }
    }
  },
  "version": "1.1"
}

The response provides an object with the following attributes:

Response examples

The response might include an end-user's bank accounts if they have previously used Trustly.

Note: When no accounts are found, the accounts array is empty.

Account found
No account found
{
  "result": {
    "signature": "4F8hjuMqbsH0Ku ... S16VbzRsw==",
    "uuid": "258a2184-2842-b485-25ca-293525152425",
    "method": "AzuraRecurring",
    "version": "1.1",
    "data": {
      "azurasessionid": "a7e1f6e8-67d4-4ea5-8d4b-36dbf6927e8f",
      "accounts":[
       {
        "accountid": "123456789",
        "accountnumbermasked": "**** 392",
        "accountnumberlastdigits": "392",
        "bank": {
          "bankcountry": "SE",
          "bankcode": "SWED",
          "bankname": "Swedbank",
          "banklogoround": "https://asset.trustly.com/assets/se/swed.svg"
        }       
       }
      ],
      "trustlyinfo": {
        "trustlylogo1": "https://assets.trustly.com/black-background-logo.svg",
        "trustlylogo2": "https://assets.trustly.com/white-background-logo.svg",
        "trustlylogo3": "https://assets.trustly.com/green-background-logo.svg",
        "trustlylogo4": "https://assets.trustly.com/no-background-logo.svg"
      },
      "countries": [
        {
          "countrycode": "SE",
          "termsandconditions": {
            "sv": "http://trustly.com/terms/SE/sv.pdf",
            "en": "http://trustly.com/terms/SE/en.pdf"
          },
          "privacypolicy": {
            "sv": "http://trustly.com/privacy/SE/sv.pdf",
            "en": "http://trustly.com/privacy/SE/en.pdf"
          },
          "banks": [
            {
              "bankcountry": "SE",
              "bankcode": "SWED",
              "bankname": "Swedbank", 
              "bankid": "se.swed",
              "outoforder": false, 
              "banklogoround": "https://asset.trustly.com/swed_round.svg"
            },
            {
              "bankcountry": "SE",
              "bankcode": "NDEA",
              "bankname": "Nordea",
              "bankid": "se.ndea",
              "outoforder": false, 
              "banklogoround": "https://asset.trustly.com/ndea_round.svg"
            }
          ]
        }
      ]
    }
  }
}

The RemoveAzuraAccount request removes the specified account from Azura (not just recurring). It's optional and is only enabling the removal of the end-user without navigating to the Trustly checkout.

Request example

RemoveAzuraAccount
{
  "method": "RemoveAzuraAccount",
  "version": "1.1",
  "params": {
    "Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
    "UUID": "258a2184-2842-b485-25ca-293525152425",
    "MessageID": "your_unique_request_id",
    "Data": {
      "Username": "merchant_username",
      "Password": "merchant_password",
      "MessageID": "your_unique_request_id",
      "Attributes": {
        "AzuraSessionID": "55410fc4-d4f4-4725-b5c6-62131761dc6e",
        "AccountID": "123456789"
      }
    }
  }
}

The response provides an object with the following attributes:

Response example

Account found
No account found
{
  "result": {
    "signature": "4F8hjuMqbsH0Ku ... S16VbzRsw==",
    "uuid": "258a2184-2842-b485-25ca-293525152425",
    "method": "RemoveAzuraAccount",
    "data": {
      "result": "1"
    }
  },
  "version": "1.1"
}

To utilise the information from the Azura network, when calling DirectDebitMandate, you also include the AzuraSessionID and if using the consumers account, the AccountID.

For more details on the deposit request, refer to: DirectDebitMandate.

This table lists only the Azura-specific parameters. Refer to the DirectDebitMandate. documentation for details on other parameters.

Please ensure that the parameters used in the DirectDebitMandate call exactly match those specified in the corresponding Azura recurring core call. For instance, if Azura was called with 'Country': 'SE' and 'Currency': 'SEK', the DirectDebitMandate call must use the same values.


Request examples

The deposit request must always include the Azura SessionID if an AzuraRecurring method has been called earlier. It can include either an account or a bank to use for the deposit or just start the onboarding without preselecting anything.

Mandate with accountid
Mandate with bank
Mandate without selection
{
  "method": "DirectDebitMandate",
  "params": {
    "Signature": "f4ThjuMqbsdG6u ... S16VbzD4h==",
    "UUID": "55410fc4-d4f4-4725-b5c6-62131761dc6e",
    "Data": {

      "Attributes": {
          "MerchantReference": "197310......",
          Azura {
            "AzuraSessionID": "55410fc4-d4f4-4725-b5c6-62131761dc6e",
            "AccountID": "12345678",
            "Action": "SELECT_ACCOUNT"
          }
        }
      }
    }
  }
}

The response includes the same data as a standard deposit. For more details on deposit responses, refer to: https://docs.trustly.com/api/deposit#response-attributes

Error NumError CodeDescription
620ERROR_UNKNOWNThere could be several reasons for this error, please reach out to your Trustly contact for details.
622ERROR_INVALID_CURRENCY_CODEThe currency code is invalid. See Currencies page for valid currencies.
623ERROR_INVALID_PARAMETERSSome value or parameter in the deposit call does not match the expected format.
737ERROR_INVALID_COUNTRYThe Country code sent in the API call is invalid.
755ERROR_INVALID_ACCOUNT_IDThe AccountID sent in the API call is invalid.
759ERROR_AZURA_SESSION_EXPIREDThe AzuraSessionID has expired. The session is only live for 30 minutes.
760ERROR_AZURA_ACCOUNT_NOT_FOUNDThe AccountID was not found.