Find account transaction list statement
Create Account
This Create Account endpoint is responsible for creating a new account for a client (merchant or company) under a specific provider.
POST
https://your_connector_url/customers/{customerId}/clients/{clientId}/accounts
Path Params
customerId (Path Variable): The ID of the customer.
clientId (Path Variable): The ID of the client (merchant) the account will belong to.
Body Params
name (String): The name of the client (merchant or company). It is a company name, not a name of a user. Obligatory parameter.
clientId (String): The ID of the client (merchant or company). Obligatory parameter.
address (String): The address field of the client (merchant or company), sending primary address information like street name and street number. It is a company address, not an address of a user. Obligatory parameter.
address2 (String): an address field allowing to add secondary address information, like apartments, suites, and PO Boxes. Optional parameter.
city (String): The city field of the address of the client (merchant or company). Obligatory parameter.
postalCode (String): The postal code field of the address of the client (merchant or company). Obligatory parameter.
assetType (String): The currency of the account. The currency is set by the provider or is chosen by the user during the account creation process if multiple options are enabled by the provider. Obligatory parameter.
partnerProduct (String): The code of the product offered by a partner that is associated with the account being created. This value is requested also via the endpoint Get Partner Product in the field “code”(string). Obligatory parameter.
countryCode (String): The country code of the client (merchant or company). Obligatory parameter.
legislationCountry (String): The legislation country of the client (merchant or company). Optional parameter.
readOnly(boolean): Defines if the account is requested in the read-only format. I set as true, the user will not be able to make any payments.Obligatory parameter.
signUpRequest (Object): This object contains the data a client (merchant or company) is required to provide when creating an account. Obligatory parameter.
signUpRequest fields:
id (String): The unique identifier for the sign-up request. Obligatory parameter.
cif (String): The CIF (Tax Identification Code) of the client (merchant or company). Obligatory parameter.
clientType (ClientType): The type of client - BUSINESS or CONSUMER. Obligatory parameter.
subOrganisationType (OrganisationType): The organisation type of the client (merchant or company). Obligatory parameter.
OrganisationType Enum
The OrganisationType enum represents the different types of organisations.
Values:
SOLE_TRADER
LIMITED
PARTNERSHIP
CHARITY
PUBLIC_LIMITED
ASSOCIATION
SUPPORT_GROUP
NON_REG_PARTNERSHIP
NOT_YET_REGISTEREDRead more about organisation type here.
endUserId(String):The ID of the merchant user who has submitted the account creation request
shareholders (list of objects): The list of shareholder objects. The shareholder object includes the following parameters:
name(String): The first name of the shareholder
surname(String): The last name of the shareholder
birthDate:The date of birth of the shareholder
country(String): The country of residence of the shareholder
percentageOfShares(String): The percentage of the shares belonging to the shareholder
city(String): The city of residence of the shareholder
address(String): The main line of the address of the shareholder
address2(String): an address field allowing to add secondary address information, like apartments, suites, and PO Boxes.
postalCode(String): The postcode of the Shareholder
directors (list of objects): This object contains objects with the information about each of the directors of the merchant (client or company). It can be one or more. The director object includes the following parameters:
documentType(String): The verification document. (One document per director)
documentNumber(String): The number of the verification document
documentExpirationDate(YYYY-mm-dd): The expiration date of document
documentIssueDate(YYYY-mm-dd): The issue date of the document
documentIssuerCountry(String): The country that has issued the document
tin(String): The Tax Identification Number
postalCode(String): The postal code of the Director
address(String): The address of the Director
address2(String): An address field allowing to add secondary address information, like apartments, suites, and PO Boxes.
city(String): The city of residence of the director
email(String): An Email of the director
phone (object): A Phone number of the director
phoneNumber(String): A phone number without the country code
countryCode (countryCode): Country code
intnlPhoneNumber: An international phone number with the country code
firstName(String): First name of the director
lastName(String): Last name of the Director
dateOfBirth(yyyy-MM-dd HH:mm:ss.SSS): The date of birth of the director
appointmentDate: The appointment date of the director
countryOfResidence(countryCode): The country of residence of the director
accountPurposes(A set of strings): The intended purpose use of the account
expectedVolume(Object): The expected volume of transactions. The object contains:
Currency (currency): The currency
Range (range): The range reflecting the volume
type (string): Type of transactions
registrationDate(YYYY-mm-dd): The registration date of the company of the merchant (client)
industryCode(industryCode): The code of the industry the merchant’s company belongs to
phone(object): The phone number of the merchant(client or company)
phoneNumber (String): The phone number without the country code
countryCode (countryCode)
intnlPhoneNumber(String): The phone number with the country code
email (String): The email of the merchant(client or company)
alias(string): This is the account alias, a descriptive identifier(name) given to an account.
Response
Returns a response containing the details of the created account.
The response body has the following fields:
"accountId": "string"(obligatory): The unique id of the account created
"iban": "string"(obligatory): The IBAN
"bicSwiftForSEPA": "string"(obligatory): This field represents the bank identification code(BIC) for SEPA.
"bicSwiftForSWIFT": "string",(obligatory):This field represents the bank identification code(BIC) for SWIFT.
If you have the same bank identification code for SEPA and SWIFT then bicSwiftForSEPA field can have the same value as bicSwiftForSWIFT.
Specific for UK accounts:
"ukAccountNumber": "string"(obligatory)
"ukSortCode": "string"(obligatory)
Specific for USA accounts:
"accountNumber": "string"(obligatory)
"routingNumber": "string"(obligatory)
"internationalEnabled": "boolean" (obligatory): This indicates to Toqio if the account has the international payments capability
The fields below are related to a correspondent bank and relate to international accounts. If you are not able to pass these details and return null, these fields will be shown empty in the account details section.
"correspondentBank": "string",(obligatory if international)
"correspondentBankAddress": "string",(obligatory if international)
"correspondentBankSWIFT": "string",(obligatory if international)
"assetType": "assetType"(obligatory): The currency of the account. The currency is set by the provider or is chosen by the user during the account creation process if multiple options are enabled by the provider.
"createdAt": “Date-time”(obligatory): This represents the date of the account creation by the provider
"status": (obligatory): This represents the status of the account.
"totalBalance": a double with two decimals ,(obligatory): This field represent the total balance on the account
"availableBalance": a double with two decimals,(obligatory)
If a provider only offers a single balance, for example current balance, please use the same value for these two parameters.
"countryCode": "string",(obligatory): This represents the country code of the country where the account has been created.
"holderName": "string",(obligatory): This field represents the name of the account owner which will be the name of the client (merchant or company), not the name of a user who applied for the account.
Toqio does not store this information, Toqio calls the provider integration connector to retrieve this information using the Get Account endpoint.
"holderAddress": "string",(optional and deprecated, please use holderAddress object instead ): This field represents the address of the account owner which will be the address of the client (merchant or company), not the address of a user who applied for the account.
Toqio does not store this information, Toqio calls the provider integration connector to retrieve this information using the getAccount endpoint.
"holderAddress" (object),(obligatory) : This field represents the address of the account owner which will be the address of the client (merchant or company), not the address of a user who applied for the account.
Toqio does not store this information, Toqio calls the provider integration connector to retrieve this information using the getAccount endpoint.
The holderAddress object includes the following fields:
"address" (String): The address field of the client (merchant or company), sending primary address information like street name and street number. It is a company address, not an address of a user. Obligatory parameter.
"address2" (String): an address field allowing to add secondary address information, like apartments, suites, and PO Boxes. Optional parameter.
"city" (String): The city field of the address of the client (merchant or company). Obligatory parameter.
"postalCode" (String): The postal code field of the address of the client (merchant or company). Obligatory parameter.
"alias": "string": This is the account alias, a descriptive identifier(name) given to an account. Optional parameter.
"holderBank": "string",(obligatory) - The name of the bank providing the account.
"holderBankAddress": "string",(obligatory) - The address of the bank providing the account.
"bankCountry": "string",(obligatory) This represents the country where the banking provider is registered
"partnerProduct": "string",(obligatory) The code of the product offered by a banking provider that is associated with the account being created. This code is defined in the provider integration connector.
These parameters are for routing numbers and are optional:
"wireRoutingNumber": "string",
"achRoutingNumber": "string",
Account creation automated notifications
If your banking provider supports account holder creation simultaneously with account creation, you can leverage account creation automated notifications. These email notifications will alert the Customer's admin user in two cases:
- If the account holder creation fails on the BaaS side, the account will be marked with a "Quarantine" status. The Customer's admin user will need to review the account application in the admin portal to either approve or stop the account creation process.
- If there is an error in the banking provider's database related to the account holder, the Customer's admin user will receive an email notification detailing the error.
To set up this logic you will need to use signUpResponse
SignupResponse Parameter
"signUpResponse":(optional parameter) includes:
"sendQuarantinedEmail": boolean,(obligatory) : If enabled, this will trigger an email to the Customer admin user informing them that a Merchant(Client or Company) intended to create an account but the account creation is on hold due to the Merchant’s quarantine status. The admin user is asked in the email to review the application in the admin portal using a link and to allow or stop the account creation.
The email content for your reference:
“The creation of a new account for {companyName} has been quarantined in the firewall. Please, review the application to allow or prevent the account to be created. You can follow the case and get additional details in the admin portal by following this link {linkUrl}”
"sendKycCheckEmail": true,(obligatory): If enabled, this will trigger an email to the Customer admin user informing them that a Merchant(Client or Company) intended to create an account but was not able to do so due to an error related to checking this account holder in the banking provider database
"kycCheckEmailMessage": "string"(obligatory if "sendKycCheckEmail" is set as true ) : Represents an actual email message you would like to send to the Customer admin user.
Enabling Provider Capabilities related to this endpoint
If your banking provider requires a signature for account creation, consider enabling the needAccountSignature provider capability.
When needAccountSignature is set to true, it indicates that the banking provider mandates an account signature during the account creation process. Setting this parameter to true will enable a custom user flow that incorporates the account signature feature. Read more about capabilities.
Get Account
The Get Account endpoint is responsible for retrieving an account of a merchant (client or company) under a specific provider.
GET
https://your_connector_url/customers/{customerId}/clients/{clientId}/accounts/{accountId}
Path Params
customerId (Path Variable): The ID of the customer.
clientId (Path Variable): The ID of the client (merchant) the account will belong to.
accountId (Path Variable): The ID if the account
Response body
“accountId” : “string”(obligatory): The id of the account
Specific for UK accounts:
"ukAccountNumber": "string"(obligatory)
"ukSortCode": "string"(obligatory)
"iban": "string"(obligatory)
"bicSwiftForSEPA": "string"(obligatory): This field represents the bank identification code(BIC) for SEPA.
"bicSwiftForSWIFT": "string",(obligatory):This field represents the bank identification code(BIC) for SWIFT.
If you have the same bank identification code for SEPA and SWIFT then bicSwiftForSEPA field can have the same value as bicSwiftForSWIFT.
"assetType": "assetType"(obligatory): The currency of the account. The currency is set by the provider or is chosen by the user during the account creation process if multiple options are enabled by the provider.
"createdAt": “Date-time”(obligatory): This represents the date of the account creation by the provider
"status": (obligatory): This represents the status of the account.
"totalBalance": a double with two decimals ,(obligatory): This field represent the total balance on the account
"availableBalance": a double with two decimals,(obligatory)
If a provider only offers a single balance, for example current balance, the same value will be used for these two parameters
"countryCode": "string",(obligatory): This represents the country code of the country where the account has been created.
"holderName": "string",(obligatory): This field represents the name of the account owner which will be the name of the client (merchant or company), not the name of a user who applied for the account.
Toqio does not store this information, Toqio calls the provider integration connector to retrieve this information.
"holderAddress": "string",(optional and deprecated, please use holderAddress object instead ): This field represents the address of the account owner which will be the address of the client (merchant or company), not the address of a user who applied for the account.
Toqio does not store this information, Toqio calls the provider integration connector to retrieve this information.
"holderAddress" (object),(obligatory) : This field represents the address of the account owner which will be the address of the client (merchant or company), not the address of a user who applied for the account.
Toqio does not store this information, Toqio calls the provider integration connector to retrieve this information using the getAccount endpoint.
The holderAddress object includes the following fields:
"address" (String): The address field of the client (merchant or company), sending primary address information like street name and street number. It is a company address, not an address of a user. Obligatory parameter.
"address2" (String): an address field allowing to add secondary address information, like apartments, suites, and PO Boxes. Optional parameter.
"city" (String): The city field of the address of the client (merchant or company). Obligatory parameter.
"postalCode" (String): The postal code field of the address of the client (merchant or company). Obligatory parameter.
"internationalEnabled": true,(obligatory) - This indicates to Toqio if the account has international payments capability
"correspondentBank": "string",(obligatory if international)
"correspondentBankAddress": "string",(obligatory if international)
"correspondentBankSWIFT": "string",(obligatory if international)
"holderBank": "string",(obligatory) - The name of the bank providing the account.
"holderBankAddress": "string",(obligatory) - The address of the bank providing the account.
"bankCountry": "string",(obligatory) - This represents the country where the banking provider is registered
"partnerProduct": "string",(obligatory) - The code of the product offered by a banking provider that is associated with the account being created. This code is defined in the provider integration connector. A partner product should always have a name and a code as minimum requirements. This value is passed in the public API endpoint Get Partner Product in the field “code”(string). Obligatory parameter.
These parameters are for routing numbers and are optional:
"wireRoutingNumber": "string",
"achRoutingNumber": "string",
signUpResponse object - Read more about it here.
Get Accounts
The Get Accounts endpoint is responsible for retrieving all accounts of a merchant (client or company) under a specific provider. The endpoint is mapped to the following URL pattern:
GET
https://your_connector_url/customers/{customerId}/clients/{clientId}/accounts
Path Params
customerId (Path Variable): The ID of the customer.
clientId (Path Variable): The ID of the client (merchant) the account will belong to.
Response
The response will be an array of account response objects.
Delete Account
The Delete Account endpoint is responsible for deleting an existing account for a merchant (client or company) under a specific provider.
On the Toqio's side this action can be executed only if the account has no funds and it is not the main account.
CANCEL account button will trigger this endpoint.
The endpoint is mapped to the following URL patterns:
DELETE
https://your_connector_url/customers/{customerId}/clients/{clientId}/accounts/{accountId}
Path Params
customerId (Path Variable): The ID of the customer.
clientId (Path Variable): The ID of the client (merchant) the account will belong to.
accountId (Path Variable): The ID if the account
Response body
Returns a response indicating the result of the delete operation.
Enabling Provider Capabilities related to this endpoint
canCancelAccounts: Defines whether the provider allows cancelling accounts.
When an account is cancelled the account holder users can no longer use the account but are able to view its details. The status will change to CLOSED in the integration and in Toqio database it will change to CANCELLED.canRemoveAccounts: Defines whether the provider allows removing accounts. If an account is removed, it will not be visible to the account holder users. Only available for accounts which do not have balance and are not main accounts . The status will change to REMOVED in Toqio database.
Update Account
The Update Account endpoint is responsible for updating the details of an existing account of a merchant (client or company) under a specific provider. The endpoint is mapped to the following URL patterns:
PUT
https://your_connector_url/customers/{customerId}/clients/{clientId}/accounts/{accountId}
Path Params
customerId (Path Variable): The ID of the customer.
clientId (Path Variable): The ID of the client (merchant) the account will belong to.
accountId (Path Variable): The ID if the account
Body Params
alias (String): The alias of the account in Toqio
address (String): The address field of the client (merchant or company), sending primary address information like street name and street number. It is a company address, not an address of a user. Obligatory parameter.
address2 (String): an address field allowing to add secondary address information, like apartments, suites, and PO Boxes. Optional parameter.
city (String): The city field of the address of the client (merchant or company).Obligatory parameter.
postalCode (String): The postal code field of the address of the client (merchant or company).Obligatory parameter.
status (ToqioAccountStatus): The status of the account in Toqio
ToqioAccountStatus enum
The ToqioAccountStatus enum represents the different statuses an account can have. Read more.
Values:
CLOSED
ACTIVE
PENDING
HIDE
QUARANTINE
FAILED
SUSPENDED
Response
The response will contain the same parameters as the account response.
Find account transaction list statement
The Find account transaction list statement endpoint is responsible for retrieving a list of transactions for a particular date range of an existing account for a merchant (client or company) under a specific provider. The endpoint is mapped to the following URL patterns:
POST
https://your_connector_url/customers/{customerId}/clients/{clientId}/accounts/{accountId}/bankStatement
Path Params
customerId (Path Variable): The ID of the customer.
clientId (Path Variable): The ID of the client (merchant) the account will belong to.
accountId (Path Variable): The ID if the account
Body Params
start (Date): The start date of the statement period.
end (Date): The end date of the statement period.
Response
Returns a response containing the list of transactions within the specified date range.
Response body
The response returns the arrays of objects.
Object:
balance (a double with two decimals), obligatory: Represent balance corresponding to the transaction
date(yyyy-MM-dd'T'HH:mm:ss.SSS'Z), obligatory: The date and time of the transaction - will be shown as “Completed” field in the statement
transactionNumber (string), obligatory: The number of the transaction
The response allows us to provide an account transaction list statement.
The Merchant user can access this feature by clicking the "Download PDF" button on the account details page. This functionality allows the user to select a custom date range, and based on this selection, a PDF document will be generated, reflecting the list of transactions that occurred within the specified date range.
Enabling Provider Capabilities related to this endpoint
When configuring this feature, please verify if the banking provider permits users to select today's date as the end date for the desired range. If this is allowed, ensure that you enable the allowTodayStatement capability as true for this banking provider. When this capability is not enabled, users can only download statements up to two days prior to today's date.
You can also define whether users can access account statements older than 6 months by setting the allowSixMonthsStatements capability. If allowSixMonthsStatements is set to true, users will be able to retrieve account statements beyond the 6-month timeframe. Read more about capabilities.