RegisterAccount

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:

Parameter nameDescriptionReq.TypeExample
UsernameThe username.YesTextjoe
PasswordThe password.YesTextsecret
EndUserIDID, username, hash or anything uniquely identifying the end-user holding this account.

Preferably the same ID/username as used in the merchant's own backoffice in order to simplify for the merchant's support department.
YesText123123
ClearingHouseThe clearing house of the end-user's bank account. Typically the name of a country in uppercase letters. See table* below.YesTextSWEDEN
BankNumberThe bank number identifying the end-user's bank in the given clearing house. For bank accounts in IBAN format you should just provide an empty string (""). For non-IBAN format, see table* below.YesText6112
AccountNumberThe account number, identifying the end-user's account in the bank. Can be either IBAN or country-specific format, see table* below.YesText69706212
FirstnameThe account holders firstname.YesTextSteve
LastnameThe account holders lastname.YesTextSmith
AttributesAttributes for this method.NoHash{ "DateOfBirth": "1990-01-20", ... }

* 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^[0-9]{4}$^[0-9]{16}$
DENMARK^[0-9]{4}$^[0-9]{4,10}$
ESTONIA^[0-9]{2}$^[0-9]{4,14}$
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^[0-9]{8}$^[0-9]{24}$
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^[0-9]{4}$^[0-9]{7}$
POLAND^PL[0-9]{26}$
PORTUGAL^[0-9]{8}$^[0-9]{13}$
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.

Examples:

{
    ...
    "ClearingHouse": "SPAIN",
    "BankNumber": "",
    "AccountNumber": "ES8701820004756386447000",
    ...
}
{
    ...
    "ClearingHouse": "SWEDEN",
    "BankNumber": "83279",
    "AccountNumber": "9048832662",
    ...
}

The parameter Attributes is a hash of attributes. New attributes may be added in future versions of the API but existing attributes will never be removed.

The attributes to this method are:

Attribute nameDescriptionReq.TypeExample
DateOfBirthThe date of birth of the account holder (ISO 8601).NoText1990-01-20
MobilePhoneThe mobile phonenumber to the account holder in international format. This is used for KYC and AML routines.NoText+46709876543
NationalIdentificationNumberThe account holder's social security number / personal number / birth number / etc. Useful for some banks for identifying transactions and KYC/AML.NoText790131-1234
AddressCountryThe ISO 3166-1-alpha-2 code of the account holder's country.NoChar(2)SE
AddressPostalCodePostal code of the account holder.NoTextSE-11253
AddressCityCity of the account holder.NoTextStockholm
AddressLine1Street address of the account holder.NoTextMain street 1
AddressLine2Additional address information of the account holder.NoTextApartment 123, 2 stairs up
AddressThe entire address of the account holder. This attribute should only be used if you are unable to provide the address information in the 5 separate attributes above (AddressCountry, AddressPostalCode, AddressCity, AddressLine1 and AddressLine2).NoTextBirgerstreet 14, SE-11411 Stockholm, Sweden
EmailThe email address of the account holder.NoText[email protected]

The result returned is a hash with the following elements:

Hash keyDescriptionTypeExample
accountidThe globally unique AccountID the account was assigned in our system.BigInt7653385737
clearinghouseThe clearinghouse for this account.TextSWEDEN
bankThe name of the bank for this account.TextSkandiabanken
descriptorA descriptor for this account that is safe to show to the end user.Text***4057

New parameters may be added to the result in future versions of the API.

Example of request and response:

{
  "method": "RegisterAccount",
  "params": {
    "Data": {
      "AccountNumber": "69706212",
      "Attributes": {
        "AddressCountry": "SE",
        "AddressPostalCode": "SE-11253",
        "AddressCity": "Stockholm",
        "AddressLine1": "Main street 1",
        "MobilePhone": "+46709876543",
        "NationalIdentificationNumber": "900219-1234",
        "Email": "[email protected]",
        "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"
}
{
    "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"
}

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

RegisterAccount Error Messages

Error NumError 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.