RegisterAccount
Overview
Registers and verifies the format of an account to be used in AccountPayout.
A typical payout flow is:
The merchant makes an API-call to RegisterAccount and receives an accountid in response.
The merchant saves the accountid as a valid payout option for the end user.
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.
{
"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.
| ClearingHouse | BankNumber [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
{
...
"ClearingHouse": "SPAIN",
"BankNumber": "",
"AccountNumber": "ES8701820004756386447000",
...
}{
...
"ClearingHouse": "SWEDEN",
"BankNumber": "83279",
"AccountNumber": "9048832662",
...
}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
{
"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 Number | Error Code | Description |
|---|---|---|
| 602 | ERROR_FUNCTION_ACCESS_DENIED | The merchant does not have access to this function. |
| 607 | ERROR_HOST_ACCESS_DENIED | The IP address of the merchant has not been added to Trustly’s IP-whitelist. |
| 616 | ERROR_INVALID_CREDENTIALS | The username and/or password used in the API call is incorrect. |
| 620 | ERROR_UNKNOWN | There could be several reasons for this error, please reach out to your Trustly contact for details. |
| 623 | ERROR_INVALID_PARAMETERS | Some value or parameter in the API call does not match the expected format. |
| 624 | ERROR_INVALID_BANK_ACCOUNT_NUMBER | The 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). |
| 636 | ERROR_UNABLE_TO_VERIFY_RSA_SIGNATURE | The 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. |
| 639 | ERROR_NO_PUBLIC_KEY | No public key has been configured for the merchant on Trustly’s side. |
| 688 | ERROR_DUPLICATE_UUID | This UUID has been used before. |
| 717 | ERROR_INVALID_ORDER_ATTRIBUTE | One or more attributes are sent with the incorrect value. Please reach out to your Trustly contact for more information. |
| 718 | ERROR_DISABLED_USER | The merchant’s user is disabled in Trustly’s system. |