Link bank account

POST

/link

curl --request POST \
  --url https://api.banklink.co.za/v1/link \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "bankId": "fnb", "credentials": { "username": "12345678", "password": "s3cr3t" }, "saveCredentials": true, "syncTransactions": false, "nickname": "FNB Business Account" }'

• Production (use an sk_live_ key)
• Sandbox (same URL — use an sk_test_ key)

Links a bank account by verifying the provided credentials against the bank portal. On success, creates a bank_profile entry and returns the profile ID and account number. The link completes in a single call.

By default only the login is checked and no transactions are read. Set syncTransactions to also fetch the account’s transactions in the same login and store them, as a manual sync would.

Supported bank IDs: fnb, absa, nedbank, standard_bank, discovery.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

bankId

required

Identifier of the bank to link

string

Allowed values: fnb absa nedbank standard_bank discovery

Example

fnb

credentials

required

Bank-specific login credentials as key-value pairs (e.g. for FNB: { username, password }).

object

key

additional properties

string

Example

{
  "username": "12345678",
  "password": "s3cr3t"
}

saveCredentials

Set false to connect without storing login credentials. Provide fresh credentials on every subsequent sync.

boolean

default: true

syncTransactions

Also fetch and store the account’s transactions while linking. Without it, the link only verifies the login.

boolean

nickname

Optional display name for the account (defaults to the bank ID)

string

<= 100 characters

Example

FNB Business Account

Responses

200

Link result. The type field distinguishes between outcomes:

• success — account linked successfully
• error — credential verification failed

Media typeapplication/json

object

data

required

One of: discriminator: type

object

object

type

required

string

Allowed values: success

profile_id

required

ID of the newly created bank profile

string format: uuid

account_number

Bank account number, if learned while linking. Omitted when not yet available.

string

synced

Only when syncTransactions was set. Number of new transactions stored.

integer

sync_failed

Only when syncTransactions was set. The account is linked, but its transactions could not be stored; sync it again later.

boolean

object

object

type

required

string

Allowed values: error

message

required

Human-readable reason for the failure

string

Example

{
  "data": {
    "type": "success",
    "profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "account_number": "62012345678",
    "synced": 42
  }
}

400

Missing or invalid request fields

Media typeapplication/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

Human-readable error description

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Account not found"
  }
}

401

Missing or invalid API key

Media typeapplication/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

Human-readable error description

string

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}