Skip to content

Usage

For a brief overview of the latest changes in the API, please check out the changelog.

Initializing the SDK

Before you begin, make sure you either import BittiqSDK or import MockBittiqSDK.

You'll need to initialize the SDK before use. Initialization of the SDK should only be done once during the lifetime of your app. The way the SDK is initialized depends on whether you're using BittiqSDK or MockBittiqSDK:

BittiqSDK

BittiqSDK.initialize("https://{subdomain}.api.bittiq.cloud", "[API_KEY]", tokenResolver)

For more information on how to use the TokenResolver see the API Reference, or see the example code below.

Good to know
The resolve(_:) method will always be called on a background thread.

MockBittiqSDK

MockBittiqSDK.initialize(consentReturnURL: "yourapp://myreturnurl")

The consent return URL is only required for testing the consent flow. You can just use a placeholder URL instead until you start implementing the consent flow. For more information about the consent flow, please see this page.

SDK instance
The initialize method will return an instance of the SDK that you can refer to in subsequent use. Another way is to call (Mock)BittiqSDK.instance, but make sure that the initialize method has been called first, or else a fatal error will be thrown.

Using the Result object

All API requests are done asynchronously on a background thread, therefore the result of the call will be returned to you in a completion handler, wrapped in a Result object. In case of a successful call, this object will contain a (list of) model object(s). When no data is returned from the server, an Empty placeholder object will be returned. In case of an error, an Error is returned. Please see the API Reference for an overview of all models.

Good to know
The completion handler will always be called on the main thread.

More on Swift's Result enum
https://developer.apple.com/documentation/swift/result

Error handling

If the Result object (see previous section) is a failure, an error will always be available. The error will typically be one of the following error types:

  • BittiqClientError - Something went wrong while processing the request or response, or one or more input parameters are invalid.
  • BittiqApiError - The Bittiq server returned an error response.
  • BittiqURLError - A network error occurred, or the request was canceled.

Pagination

Some SDK calls return a paginated response, in the form of a PagedData object. This object contains a cursor to the previous result set (if available), a cursor to the next result set (if available) and the items for the current result set.

Calls that return a paginated response will also support a cursor parameter for which you can supply either the cursor for the previous or next result set. An example of a paginated call is getTransactions(accountIds:startAt:endAt:search:limit:cursor:completion:).

Canceling an SDK call

Each call to the SDK will return an optional BittiqTask object with a cancel() method.

Example code

Because some example code is worth more than a thousand words...

import BittiqSDK

private struct Resolver: TokenResolver {

    func resolve(_ completion: @escaping (Tokens?) -> Void) {

        // You can do any work here in order to acquire the tokens, 
        // as long as you call the completion handler when you're done.

        let tokens = Tokens(accessToken: "[ACCESS_TOKEN]", refreshToken: "[REFRESH_TOKEN]")
        completion(tokens)
   }
}

let resolver = Resolver()
let baseUrl = URL(string: "https://{subdomain}.api.bittiq.cloud")!

guard let sdk = try? BittiqSDK.initialize(baseUrl: baseUrl, apiKey: "[YOUR_API_KEY]", tokenResolver: resolver) else {
    fatalError("Failed to initialize the Bittiq SDK")
}

// From here on you can reference the SDK with sdk or BittiqSDK.instance.

sdk.findBankAccounts { result in
    switch result {
    case .success(let bankAccounts):
        print(bankAccounts)
    case .failure(let error):
        print(error)
    }
}