logo
Trustly Docs
BETA

RegisterAccount

Store customers' bank account details to Trustly
Updated 8 days ago

Overview

Registers and verifies the format of an account to be used in AccountPayout.

A typical payout flow is:

  1. The merchant makes an API-call to RegisterAccount and receives an accountid in response.

  2. The merchant saves the accountid as a valid payout option for the end user.

  3. When it's time to actually do a payout the merchant makes an API-call to AccountPayout with the Amount, Currency and saved accountid.

Multiple calls to RegisterAccount with the same bank account details will result in the same accountid being returned.

Request parameters

Request example

If a RegisterAccount request is not accepted, an error message will be returned.

Request
{
  "method": "RegisterAccount",
  "params": {
    "Data": {
      "AccountNumber": "69706212",
      "Attributes": {
        "AddressCountry": "SE",
        "AddressPostalCode": "SE-11253",
        "AddressCity": "Stockholm",
        "AddressLine1": "Main street 1",
        "MobilePhone": "+46709876543",
        "NationalIdentificationNumber": "900219-1234",
        "Email": "test@trustly.com",
        "DateOfBirth": "1990-02-19"
      },
      "BankNumber": "6112",
      "ClearingHouse": "SWEDEN",
      "EndUserID": "123123",
      "Firstname": "Steve",
      "Lastname": "Smith",
      "Password": "merchant_password",
      "Username": "merchant_username"
    },
    "Signature": "zKwo[...]iTPMc14be138", 
    "UUID": "258a2184-2842-b485-25ca-293525152425"
  },
  "version": "1.1"
}

AccountNumber format

The format of the BankNumber and AccountNumber varies for different countries. For some counties the AccountNumber number should be provided in IBAN format, and in those cases the BankNumber should be provided as an empty string (our system can derive the BIC/SWIFT code from the IBAN).

For other countries the AccountNumber and BankNumber should be provided in the local country-specific format. AccountNumbers that start with 2 letters are IBAN numbers, while the ones starting with numbers are country-specific.

ClearingHouseBankNumber [regex]AccountNumber [regex]
AUSTRIA^AT[0-9]{18}$
BELGIUM^BE[0-9]{14}$
BULGARIA^BG[0-9]{2}[A-Z]{4}[0-9]{4}[0-9]{2}[A-Z0-9]{8}$
CROATIA^HR[0-9]{2}[0-9]{7}[0-9]{10}$
CYPRUS^CY[0-9]{10}[0-9A-Z]{16}$
CZECH_REPUBLIC^CZ[0-9]{22}$
DENMARK^DK[0-9]{16}$
ESTONIA^EE[0-9]{18}$
FINLAND^FI[0-9]{16}$
FRANCE^FR[0-9]{12}[0-9A-Z]{11}[0-9]{2}$
GERMANY^DE[0-9]{20}$
GREECE^GR[0-9]{25}$
HUNGARY^HU[0-9]{26}$
IRELAND^IE[0-9]{2}[A-Z]{4}[0-9]{14}$
ITALY^IT[0-9]{2}[A-Z][0-9]{10}[0-9A-Z]{12}$
LATVIA^LV[0-9]{2}[A-Z]{4}[0-9A-Z]{13}$
LITHUANIA^LT[0-9]{18}$
LUXEMBOURG^LU[0-9]{18}$
MALTA^MT[0-9]{2}[A-Z]{4}[0-9]{5}[0-9A-Z]{18}$
NETHERLANDS^NL[0-9]{2}[A-Z]{4}[0-9]{10}$
NORWAY^NO[0-9]{13}$
POLAND^PL[0-9]{26}$
PORTUGAL^PT[0-9]{23}$
ROMANIA^RO[0-9]{2}[A-Z]{4}[0-9A-Z]{16}$
SLOVAKIA^SK[0-9]{22}$
SLOVENIA^SI56[0-9]{15}$
SPAIN^ES[0-9]{22}$
SWEDEN *^[0-9]{4,5}$^[0-9]{1,15}$
UNITED_KINGDOM^[0-9]{6}$^[0-9]{8}$


The BankNumber for Swedish bank accounts should be the local "clearing number", and the AccountNumber parameter should contain the rest of the account number. Most Swedish banks have a 4-digit clearing number, but a 5-digit clearing number is used for Swedbank accounts when the clearing number starts with "8". Nordea accounts where the account number is the same as the person's national identification number always has "3300" as the clearing number.

IBAN for Swedish bank accounts is supported upon request. When making API calls with Swedish IBAN, ensure to include the Clearinghouse attribute as "IBAN" instead of "SWEDEN".

AccountNumber format example

IBAN specific
Country specific
{
    ...
    "ClearingHouse": "SPAIN",
    "BankNumber": "",
    "AccountNumber": "ES8701820004756386447000",
    ...
}

Response attributes

The result returned is a hash with the following attributes. New attributes may be added to the result in future versions of the API.

Response example

Response
{
    "result": {
        "signature": "R9+hjuMqbsH0Ku ... S16VbzRsw==",
        "uuid": "258a2184-2842-b485-25ca-293525152425",
        "method": "RegisterAccount",
        "data": {
            "accountid": "7653385737",
            "clearinghouse": "SWEDEN",
            "bank": "Handelsbanken",
            "descriptor": "**706212"
        }
    },
    "version": "1.1"
}


Error codes

These error codes can be returned for RegisterAccount calls. To handle errors, see Error handling.

Error NumberError CodeDescription
602ERROR_FUNCTION_ACCESS_DENIEDThe merchant does not have access to this function.
607ERROR_HOST_ACCESS_DENIEDThe IP address of the merchant has not been added to Trustly’s IP-whitelist.
616ERROR_INVALID_CREDENTIALSThe username and/or password used in the API call is incorrect.
620ERROR_UNKNOWNThere could be several reasons for this error, please reach out to your Trustly contact for details.
623ERROR_INVALID_PARAMETERSSome value or parameter in the API call does not match the expected format.
624ERROR_INVALID_BANK_ACCOUNT_NUMBERThe bank account details (BankNumber and AccountNumber) provided in the RegisterAccount are not valid. Please see the table above which describes the expected format for each ClearingHouse value. If the format matches the description and you still get this error, the bank account number is invalid (Trustly’s API performs a basic validation on check digits etc).
636ERROR_UNABLE_TO_VERIFY_RSA_SIGNATUREThe signature could not be verified using the merchant’s public key. Either the wrong private key was used to generate the signature, or the the data object used to create the signature was serialized incorrectly.
639ERROR_NO_PUBLIC_KEYNo public key has been configured for the merchant on Trustly’s side.
688ERROR_DUPLICATE_UUIDThis UUID has been used before.
717ERROR_INVALID_ORDER_ATTRIBUTEOne or more attributes are sent with the incorrect value. Please reach out to your Trustly contact for more information.
718ERROR_DISABLED_USERThe merchant’s user is disabled in Trustly’s system.