Grindrod BankAPI REST Documentation

Grindrod BankAPI REST Documentation - 4.1.0, 2022-01-11T16:14:56Z

Overview

This page is geared towards developers giving detailed information for all the end points available on the Grindrod BankAPI.

Message Formats

The Grindrod BankAPI is designed around REST, and uses standard HTTP verbs and status codes to communicate requests and responses.

  • The JSON encoded data uses camelCase properties.

  • String properties are encoded using UTF-8

Security Considerations

Grindrod BankAPI is a RESTful API, secured by OAuth2 and OpenID Connect (OIDC).

Versioning

This API is versioned using a version identifier in the endpoint URI. With the latest version always being on URL with no version identifier https://api.grindrodbank.co.za/api/docs/apidocs.
The API version number in the URL indicates the major version of the API. There can be minor/patch updates to the APIs which do not change the major version number. The major version will only change when large changes are made which break backward compatibility severely.

Versions

Version URL

4.1 (latest)

https://api.grindrodbank.co.za/4.1/api/docs/apidocs

4.0 (deprecated)

https://api.grindrodbank.co.za/4.0/api/docs/apidocs

3.1 (deprecated)

https://api.grindrodbank.co.za/3.1/api/docs/apidocs

3.0 (deprecated)

https://api.grindrodbank.co.za/3.0/api/docs/apidocs

2.1 (deprecated)

https://api.grindrodbank.co.za/2.1/api/docs/apidocs

2.0 (deprecated)

https://api.grindrodbank.co.za/2.0/api/docs/apidocs

1.3

https://api.grindrodbank.co.za/1.3/api/docs/apidocs

Sandbox

A sandbox environment is available for integration testing.
The latest version is available on https://sandbox.grindrodbank.co.za/api/docs/apidocs or refer to below for a specific version.

Version URL

4.1 (latest)

https://sandbox.grindrodbank.co.za/4.1/api/docs/apidocs

4.0 (deprecated)

https://sandbox.grindrodbank.co.za/4.0/api/docs/apidocs

3.1 (deprecated)

https://sandbox.grindrodbank.co.za/3.1/api/docs/apidocs

3.0 (deprecated)

https://sandbox.grindrodbank.co.za/3.0/api/docs/apidocs

2.1 (deprecated)

https://sandbox.grindrodbank.co.za/2.1/api/docs/apidocs

2.0 (deprecated)

https://sandbox.grindrodbank.co.za/2.0/api/docs/apidocs

1.3

https://sandbox.grindrodbank.co.za/1.3/api/docs/apidocs

Contact us on api@grindrodbank.co.za to obtain access.

Swagger Specification

The Grindrod BankAPI specification is also available in the swagger format which can be downloaded from:

URI Naming Convention

As REST has no strict naming rule, we’ve based our URI naming on best practice guidelines.

  • We use nouns to represent resources, as a noun refers to a thing and not an action (verb).

  • We use plurals in node names to keep the API URIs consistent across all HTTP methods.

    • /banks represent all banks.

    • /banks/{id} represents a specific bank under this resource.

The following references were used to setup this convention

Getting Started With the API using Postman

In this section, we take a look how to get started with the API by using Postman. If you are new to Postman, see the Learning Center.

The URLs needed for getting a Token include:

Field Value

AUTH_URL

https://AUTH-ENVIRONMENT-URL/auth/realms/grindrod/protocol/openid-connect/auth

ACCESS_TOKEN_URL

https://AUTH-ENVIRONMENT-URL/auth/realms/grindrod/protocol/openid-connect/token

CLIENT_CODE

The client code you where given when signing up

CLIENT_SECRET

The client secret you where given when signing up

SCOPE

openid

Below is an example using Postman selecting OAuth2 Authentication Type

postman authtype oauth2

Below is an example using Postman getting a new access token

postman getnewaccesstoken

Pagination

Almost all endpoints for listing include a way to preform server side pagination. The default page size is 10. Pagination facilities offer the following request parameters that will influence the page size and starting page number of list results:

Table 1. Request parameters
Path Type Optional Description

page

Integer

true

Page you want to retrieve, 0 indexed and defaults to 0.

size

Integer

true

Size of the page you want to retrieve, defaults to 10.

Pagination response has following structure:

Table 2. Response structure
Path Type Optional Description

Array[Object]

false

Actual items.

totalElements

Integer

false

Total count.

totalPages

Integer

false

Total pages with current page size.

last

Boolean

false

If this page is the last one.

numberOfElements

Integer

false

Actual size of content array (number of items).

first

Boolean

false

If this page is the first one.

pageSize

Integer

false

Requested size of the page.

page

Integer

false

Page number.

Account

The API provides real-time access to account information, allowing the user to create and read account data.

Get Account

Authentication is required.

GET /api/accounts/{accountId}

Returns account details for accountId.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Unique id of the account.

Must have at most 16 integral digits and 0 fractional digits.

Response fields

Path Type Optional Description

id

String

true

Unique id of the account.

number

String

true

Account number of the queried account.

agentId

Integer

true

Id of logged in agent querying the accounts.

bankId

String

true

Bank Identity number.

branchCode

String

true

Branch code.

accountType

String

true

Account type.

customers

Array[Object]

true

Customers of the account.

customers[].customerId

String

true

Id of the customer holding the account.

customers[].displayName

String

true

Descriptive name of the account customer holding the account.

customers[].provider

String

true

Institution or bank providing the account services.

label

String

true

Label of the account.

type

String

true

The type of account.

balance

Object

true

Composition of the current balance in the account.

balance.currency

String

true

The currency of the current balance in the account.

balance.amount

Decimal

true

The amount of the current balance in the account.

swiftBic

String

true

Global account Swift BIC number.

openedDate

String

true

Date account was created.

closedDate

String

true

Date account was closed.

Example request

GET /api/accounts/11002238456 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 409

{
  "id" : "11002238456",
  "number" : "11002238456",
  "agentId" : 1692,
  "bankId" : "584000",
  "customers" : [ {
    "customerId" : "312512",
    "displayName" : "TEST CLIENT NAME",
    "provider" : "GRINDROD BANK"
  } ],
  "label" : "",
  "type" : "63 DAY PRIME LINKED DEPOSIT",
  "balance" : {
    "currency" : "R",
    "amount" : 888888.0
  },
  "swiftBic" : "GRIDZAJJ",
  "openedDate" : "2017-01-01"
}

Get Accounts

Authentication is required.

GET /api/accounts

By default returns accounts for the agent.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Query parameters

Supports standard paging query parameters.

Parameter Type Optional Description

customerId

String

true

When present returns accounts for given customerId.

Must have at most 19 integral digits and 0 fractional digits.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

accounts

Array[Object]

true

An array of accounts.

accounts[].id

String

true

Unique id of the account.

accounts[].number

String

true

Account number of the queried account.

accounts[].agentId

Integer

true

Id of logged in agent querying the accounts.

accounts[].bankId

String

true

Bank Identity number.

accounts[].branchCode

String

true

Branch code.

accounts[].accountType

String

true

Account type.

accounts[].customers

Array[Object]

true

Customers of the account.

accounts[].customers[].customerId

String

true

Id of the customer holding the account.

accounts[].customers[].displayName

String

true

Descriptive name of the account customer holding the account.

accounts[].customers[].provider

String

true

Institution or bank providing the account services.

accounts[].label

String

true

Label of the account.

accounts[].type

String

true

The type of account.

accounts[].balance

Object

true

Composition of the current balance in the account.

accounts[].balance.currency

String

true

The currency of the current balance in the account.

accounts[].balance.amount

Decimal

true

The amount of the current balance in the account.

accounts[].swiftBic

String

true

Global account Swift BIC number.

accounts[].openedDate

String

true

Date account was created.

accounts[].closedDate

String

true

Date account was closed.

Example request

GET /api/accounts?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1531

{
  "page" : {
    "page" : 0,
    "pageSize" : 3,
    "numberOfElements" : 3,
    "totalElements" : 3,
    "totalPages" : 1,
    "first" : true,
    "last" : true
  },
  "accounts" : [ {
    "id" : "11002238555",
    "number" : "11002238555",
    "agentId" : 1729,
    "bankId" : "584000",
    "customers" : [ {
      "customerId" : "312512",
      "displayName" : "TEST CLIENT 312512",
      "provider" : "GRINDROD BANK"
    } ],
    "label" : "",
    "type" : "63 DAY PRIME LINKED DEPOSIT",
    "balance" : {
      "currency" : "R",
      "amount" : 220.0
    },
    "swiftBic" : "GRIDZAJJ",
    "openedDate" : "2014-06-01"
  }, {
    "id" : "11777238456",
    "number" : "11777238456",
    "agentId" : 1729,
    "bankId" : "584000",
    "customers" : [ {
      "customerId" : "312512",
      "displayName" : "TEST CLIENT NAME312512",
      "provider" : "GRINDROD BANK"
    } ],
    "label" : "",
    "type" : "63 DAY PRIME LINKED DEPOSIT",
    "balance" : {
      "currency" : "R",
      "amount" : 3330.0
    },
    "swiftBic" : "GRIDZAJJ",
    "openedDate" : "2010-12-04"
  }, {
    "id" : "11002888886",
    "number" : "11002888886",
    "agentId" : 1729,
    "bankId" : "584000",
    "customers" : [ {
      "customerId" : "312512",
      "displayName" : "CLIENT NAME312512",
      "provider" : "GRINDROD BANK"
    } ],
    "label" : "",
    "type" : "63 DAY PRIME LINKED DEPOSIT",
    "balance" : {
      "currency" : "R",
      "amount" : 5550.0
    },
    "swiftBic" : "GRIDZAJJ",
    "openedDate" : "1995-04-23"
  } ]
}

Create Account

Authentication is required.

POST /api/accounts

Create an account for a customer.

Create Account — Will create an account for a given customer.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Request fields

Path Type Optional Description

customerId

String

false

The ID of the customer for which you want to create another account for.

Must have at most 19 integral digits and 0 fractional digits.

productCode

String

true

A call account will be created by default when the product is not specified.

Size must be between 1 and 256 inclusive.

Response fields

Path Type Optional Description

id

String

true

Unique id of the account.

number

String

true

Account number of the queried account.

agentId

Integer

true

Id of logged in agent querying the accounts.

bankId

String

true

Bank Identity number.

branchCode

String

true

Branch code.

accountType

String

true

Account type.

customers

Array[Object]

true

Customers of the account.

customers[].customerId

String

true

Id of the customer holding the account.

customers[].displayName

String

true

Descriptive name of the account customer holding the account.

customers[].provider

String

true

Institution or bank providing the account services.

label

String

true

Label of the account.

type

String

true

The type of account.

balance

Object

true

Composition of the current balance in the account.

balance.currency

String

true

The currency of the current balance in the account.

balance.amount

Decimal

true

The amount of the current balance in the account.

swiftBic

String

true

Global account Swift BIC number.

openedDate

String

true

Date account was created.

closedDate

String

true

Date account was closed.

Example request

POST /api/accounts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 54

{
  "customerId" : "312512",
  "productCode" : "101"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 384

{
  "id" : "11002238456",
  "number" : "11002238456",
  "agentId" : 1729,
  "bankId" : "584000",
  "customers" : [ {
    "customerId" : "312512",
    "displayName" : "CLIENT NAME",
    "provider" : "GRINDROD BANK"
  } ],
  "label" : "",
  "type" : "CALL DEPOSIT",
  "balance" : {
    "currency" : "R",
    "amount" : 0.0
  },
  "swiftBic" : "GRIDZAJJ",
  "openedDate" : "2019-02-01"
}

Bank

Get a list of valid local banks by integrating with our Get Banks function.

Get Banks

Authentication is required.

GET /api/banks

Returns List of local banks.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

banks

Array[Object]

false

An array of local banks available for transacting with.

banks[].id

String

false

Bank unique member number.

Size must be between 1 and 10 inclusive.

banks[].shortName

String

false

The bank member short name.

Size must be between 1 and 30 inclusive.

banks[].fullName

String

false

The bank member full name.

banks[].defaultBranchCode

String

false

Bank default branch code.

Size must be between 1 and 6 inclusive.

banks[].swiftBic

String

false

Bank BIC code.

Size must be between 1 and 255 inclusive.

banks[].defaultBranchName

String

false

Bank default branch name.

Size must be between 1 and 255 inclusive.

banks[].foreign

Boolean

true

Indicates if bank is local bank in South Africa or Foreign.

Example request

GET /api/banks?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 675

{
  "banks" : [ {
    "id" : "STD",
    "shortName" : "STD",
    "fullName" : "STANDARD BANK",
    "defaultBranchCode" : "051001",
    "swiftBic" : "SBZAZAJJ",
    "defaultBranchName" : "STANDARD BANK SOUTH AFRICA  ",
    "foreign" : false
  }, {
    "id" : "NED ",
    "shortName" : "NED ",
    "fullName" : "NEDBANK",
    "defaultBranchCode" : "198765",
    "swiftBic" : "BIC ",
    "defaultBranchName" : "ALL BRANCHES",
    "foreign" : false
  }, {
    "id" : "FNB",
    "shortName" : "FNB",
    "fullName" : "FIRSTRAND BANK",
    "defaultBranchCode" : "250655",
    "swiftBic" : "FIRNZAJJ ",
    "defaultBranchName" : "First National Bank ",
    "foreign" : false
  } ]
}

Beneficiaries

The API allows users to create and retrieve account beneficiaries to simplify transactions.

Get Beneficiaries

Authentication is required.

GET /api/customers/{customerId}/beneficiaries

Returns list of beneficiaries for the agent’s client.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

customerId

String

false

Must have at most 19 integral digits and 0 fractional digits.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

beneficiaries

Array[Object]

false

A list of beneficiaries available for the user to transact with.

beneficiaries[].beneficiaryId

String

false

Beneficiary unique id.

beneficiaries[].name

String

false

Beneficiary name.

beneficiaries[].bankCode

String

false

Bank unique member number.

Size must be between 1 and 10 inclusive.

beneficiaries[].bankName

String

false

Bank name.

Size must be between 1 and 30 inclusive.

beneficiaries[].branchCode

String

false

Branch code.

Size must be between 1 and 6 inclusive.

beneficiaries[].branchName

String

false

Name of the branch.

beneficiaries[].accountType

String

false

Account type description.

beneficiaries[].accountNumber

String

false

Account number.

beneficiaries[].beneficiaryReference

String

false

Reference that must appear on beneficiary’s transaction.

Size must be between 1 and 30 inclusive.

beneficiaries[].clientReference

String

false

Reference that must appear on client’s transaction.

Size must be between 1 and 30 inclusive.

beneficiaries[].accountCategory

String

true

Account category description.

Example request

GET /api/customers/8543256436/beneficiaries?page=1&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1109

{
  "beneficiaries" : [ {
    "beneficiaryId" : "4",
    "name" : "Delta",
    "bankCode" : "000004",
    "bankName" : "D Bank",
    "branchCode" : "100004",
    "branchName" : "D Branch",
    "accountType" : "SAVINGS",
    "accountNumber" : "11000000004",
    "beneficiaryReference" : "Client 1 Payment",
    "clientReference" : "Paid Delta",
    "accountCategory" : "BUSINESS"
  }, {
    "beneficiaryId" : "5",
    "name" : "Echo",
    "bankCode" : "000005",
    "bankName" : "E Bank",
    "branchCode" : "100005",
    "branchName" : "E Branch",
    "accountType" : "BENEFICIARY",
    "accountNumber" : "11000000005",
    "beneficiaryReference" : "Client 1 Payment",
    "clientReference" : "Paid Echo",
    "accountCategory" : "TRUST"
  }, {
    "beneficiaryId" : "6",
    "name" : "Foxtrot",
    "bankCode" : "000006",
    "bankName" : "F Bank",
    "branchCode" : "100006",
    "branchName" : "F Branch",
    "accountType" : "CURRENT",
    "accountNumber" : "11000000006",
    "beneficiaryReference" : "Client 1 Payment",
    "clientReference" : "Paid Foxtrot",
    "accountCategory" : "BUSINESS"
  } ]
}

Get Beneficiary

Authentication is required.

GET /api/customers/{customerId}/beneficiaries/{beneficiaryId}

Returns beneficiary matching id if available on the agent for the customer.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

customerId

String

false

Must have at most 19 integral digits and 0 fractional digits.

beneficiaryId

String

false

The requested beneficiary id.

Must have at most 19 integral digits and 0 fractional digits.

Response fields

Path Type Optional Description

beneficiaryId

String

false

Beneficiary unique id.

name

String

false

Beneficiary name.

bankCode

String

false

Bank unique member number.

Size must be between 1 and 10 inclusive.

bankName

String

false

Bank name.

Size must be between 1 and 30 inclusive.

branchCode

String

false

Branch code.

Size must be between 1 and 6 inclusive.

branchName

String

false

Name of the branch.

accountType

String

false

Account type description.

accountNumber

String

false

Account number.

beneficiaryReference

String

false

Reference that must appear on beneficiary’s transaction.

Size must be between 1 and 30 inclusive.

clientReference

String

false

Reference that must appear on client’s transaction.

Size must be between 1 and 30 inclusive.

accountCategory

String

true

Account category description.

Example request

GET /api/customers/8543256436/beneficiaries/2 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 338

{
  "beneficiaryId" : "2",
  "name" : "Bravo",
  "bankCode" : "000002",
  "bankName" : "B Bank",
  "branchCode" : "100002",
  "branchName" : "B Branch",
  "accountType" : "BENEFICIARY",
  "accountNumber" : "11000000002",
  "beneficiaryReference" : "Client 1 Payment",
  "clientReference" : "Paid Bravo",
  "accountCategory" : "BUSINESS"
}

Create Beneficiary

Authentication is required.

POST /api/customers/{customerId}/beneficiaries

Creates a beneficiary.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

customerId

String

false

Must have at most 19 integral digits and 0 fractional digits.

Request fields

Path Type Optional Description

name

String

false

The name of the beneficiary.
Valid input is uppercase Latin letters, numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

bankCode

String

false

Bank unique member number.

Size must be between 1 and 10 inclusive.

branchCode

String

true

Branch code.

Size must be between 1 and 6 inclusive.

accountType

String

false

Valid account types are:
C: CURRENT
S: SAVINGS
T: TRANSMISSION
B: BOND ACCOUNT.

Size must be between 1 and 1 inclusive.

accountNumber

String

false

Account number.

Must match the regular expression [0-9]+.
Size must be between 1 and 16 inclusive.

beneficiaryReference

String

false

Reference that must appear on beneficiary’s transaction.
Valid input is uppercase Latin letters, numbers, space and punctuation.

Size must be between 1 and 30 inclusive.

clientReference

String

false

Reference that must appear on client’s transaction.
Valid input is uppercase Latin letters, numbers, space and punctuation.

Size must be between 1 and 30 inclusive.

accountCategory

String

false

Valid account categories are:
3RD PARTY
MANDATED.

Size must be between 1 and 10 inclusive.

Response fields

Path Type Optional Description

beneficiaryId

String

false

Beneficiary unique id.

name

String

false

Beneficiary name.

bankCode

String

false

Bank unique member number.

Size must be between 1 and 10 inclusive.

bankName

String

false

Bank name.

Size must be between 1 and 30 inclusive.

branchCode

String

false

Branch code.

Size must be between 1 and 6 inclusive.

branchName

String

false

Name of the branch.

accountType

String

false

Account type description.

accountNumber

String

false

Account number.

beneficiaryReference

String

false

Reference that must appear on beneficiary’s transaction.

Size must be between 1 and 30 inclusive.

clientReference

String

false

Reference that must appear on client’s transaction.

Size must be between 1 and 30 inclusive.

accountCategory

String

true

Account category description.

Example request

POST /api/customers/8543256436/beneficiaries HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 267

{
  "name" : "Beneficiary Name",
  "bankCode" : "STD",
  "branchCode" : "584000",
  "accountType" : "C",
  "accountNumber" : "1234567890",
  "beneficiaryReference" : "Beneficiary Reference",
  "clientReference" : "Client Reference",
  "accountCategory" : "MANDATED"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 280

{
  "beneficiaryId" : "676",
  "name" : "Beneficiary Name",
  "bankCode" : "STD",
  "branchCode" : "584000",
  "branchName" : "SANDTON",
  "accountType" : "C",
  "accountNumber" : "1234567890",
  "beneficiaryReference" : "Beneficiary Reference",
  "accountCategory" : "MANDATED"
}

Customer

Our customer endpoints allow users to create and retrieve customer profiles.

Create Customer

Authentication is required.

POST /api/customers

Create an instance for given default customer.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Request fields

Path Type Optional Description

customerReference

String

true

Customers unique reference number. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

agentReference

String

true

Agent reference number. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

adminFeePercent

String

true

Administration fee percentage.

Must have at most 2 integral digits and 2 fractional digits.

createCallAccount

Boolean

true

Deprecated.

Indicator to create call account.

defaultCustomer

Object

false

defaultCustomer.entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

defaultCustomer.name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

defaultCustomer.name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

defaultCustomer.mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

defaultCustomer.email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

defaultCustomer.kycStatus

Boolean

true

Status of customer being KYC’d.

defaultCustomer.identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

defaultCustomer.taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

defaultCustomer.address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

defaultCustomer.investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

otherCustomers

Array[Object]

true

List of all the clients to be created for the account or matter. The default customer should NOT be included in this list.

otherCustomers[].entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

otherCustomers[].name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

otherCustomers[].name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

otherCustomers[].mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

otherCustomers[].email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

otherCustomers[].kycStatus

Boolean

true

Status of customer being KYC’d.

otherCustomers[].identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

otherCustomers[].taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

otherCustomers[].address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

otherCustomers[].investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

Response fields

Path Type Optional Description

customerId

String

false

Customer unique id.

defaultAccountNumber

String

true

The default account number for this account.

customerReference

String

true

Customers unique reference number.

Size must be between 1 and 255 inclusive.

agentReference

String

true

Agent reference number.

Size must be between 1 and 255 inclusive.

adminFeePercent

String

true

Administration fee percentage.

defaultCustomer

Object

true

Details of the main client of this account.

defaultCustomer.entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

defaultCustomer.name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

defaultCustomer.name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

defaultCustomer.mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

defaultCustomer.email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

defaultCustomer.kycStatus

Boolean

true

Status of customer being KYC’d.

defaultCustomer.identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

defaultCustomer.taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

defaultCustomer.address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

defaultCustomer.investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

otherCustomers

Array[Object]

true

List of all other clients connected to this account.

otherCustomers[].entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

otherCustomers[].name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

otherCustomers[].name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

otherCustomers[].mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

otherCustomers[].email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

otherCustomers[].kycStatus

Boolean

true

Status of customer being KYC’d.

otherCustomers[].identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

otherCustomers[].taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

otherCustomers[].address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

otherCustomers[].investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

Example request

POST /api/customers HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 826

{
  "customerReference" : "TESTREFC1",
  "agentReference" : "AGENTTESTREFC1",
  "adminFeePercent" : "12",
  "createCallAccount" : true,
  "defaultCustomer" : {
    "entityTypeId" : "1",
    "name1" : "ROD",
    "name2" : "GRIND",
    "mobilePhoneNumber" : "0783452314",
    "email" : "TESTMAIL@GRINDROD.CO.ZA",
    "kycStatus" : true,
    "identifyingNumber" : "8906255579088",
    "taxNumber" : "6787788811111",
    "address" : "GRINDROD TOWERS",
    "investmentTypeId" : 1
  },
  "otherCustomers" : [ {
    "entityTypeId" : "1",
    "name1" : "GRIND",
    "name2" : "ROD",
    "mobilePhoneNumber" : "0783452314",
    "email" : "TESTMAIL@GRINDROD.CO.ZA",
    "kycStatus" : true,
    "identifyingNumber" : "8906255579088",
    "taxNumber" : "6787788811111",
    "address" : "GRINDROD PARTY",
    "investmentTypeId" : 1
  } ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 831

{
  "customerId" : "77748489490",
  "defaultAccountNumber" : "11002238456",
  "customerReference" : "TESTREFC1",
  "adminFeePercent" : "12",
  "defaultCustomer" : {
    "entityTypeId" : "1",
    "name1" : "GRIND",
    "name2" : "ROD",
    "mobilePhoneNumber" : "0783452314",
    "email" : "TESTMAIL@GRINDROD.CO.ZA",
    "kycStatus" : true,
    "identifyingNumber" : "8906255579088",
    "taxNumber" : "6787788811111",
    "address" : "GRINDROD TOWERS",
    "investmentTypeId" : 1
  },
  "otherCustomers" : [ {
    "entityTypeId" : "1",
    "name1" : "GRIND",
    "name2" : "ROD",
    "mobilePhoneNumber" : "0783452314",
    "email" : "TESTMAIL@GRINDROD.CO.ZA",
    "kycStatus" : true,
    "identifyingNumber" : "8906255579088",
    "taxNumber" : "6787788811111",
    "address" : "GRINDROD PARTY",
    "investmentTypeId" : 1
  } ]
}

Get Customer

Authentication is required.

GET /api/customers/{customerId}

Returns customer details for customerId.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

customerId

String

false

The unique id of the customer to get details for.

Must have at most 19 integral digits and 0 fractional digits.

Response fields

Path Type Optional Description

customerId

String

false

Customer unique id.

defaultAccountNumber

String

true

The default account number for this account.

customerReference

String

true

Customers unique reference number.

Size must be between 1 and 255 inclusive.

agentReference

String

true

Agent reference number.

Size must be between 1 and 255 inclusive.

adminFeePercent

String

true

Administration fee percentage.

defaultCustomer

Object

true

Details of the main client of this account.

defaultCustomer.entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

defaultCustomer.name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

defaultCustomer.name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

defaultCustomer.mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

defaultCustomer.email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

defaultCustomer.kycStatus

Boolean

true

Status of customer being KYC’d.

defaultCustomer.identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

defaultCustomer.taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

defaultCustomer.address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

defaultCustomer.investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

otherCustomers

Array[Object]

true

List of all other clients connected to this account.

otherCustomers[].entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

otherCustomers[].name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

otherCustomers[].name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

otherCustomers[].mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

otherCustomers[].email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

otherCustomers[].kycStatus

Boolean

true

Status of customer being KYC’d.

otherCustomers[].identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

otherCustomers[].taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

otherCustomers[].address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

otherCustomers[].investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

Example request

GET /api/customers/2 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 501

{
  "customerId" : "2",
  "defaultAccountNumber" : "12345000002",
  "customerReference" : "Reference 1",
  "adminFeePercent" : "1.0",
  "defaultCustomer" : {
    "entityTypeId" : "1",
    "name1" : "Surname 1",
    "name2" : "FirstName 1",
    "mobilePhoneNumber" : "0990000001",
    "email" : "kycemail1@Testkyc.com",
    "kycStatus" : true,
    "identifyingNumber" : "9511025037083",
    "taxNumber" : "111/1111/111/1",
    "address" : "1 Street,1 Suburb,1 City,1001"
  },
  "otherCustomers" : [ ]
}

Get Customers

Authentication is required.

GET /api/customers

Returns list of customers for the agent.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

customers

Array[Object]

true

An array of customers.

customers[].customerId

String

false

Customer unique id.

customers[].defaultAccountNumber

String

true

The default account number for this account.

customers[].customerReference

String

true

Customers unique reference number.

Size must be between 1 and 255 inclusive.

customers[].agentReference

String

true

Agent reference number.

Size must be between 1 and 255 inclusive.

customers[].adminFeePercent

String

true

Administration fee percentage.

customers[].defaultCustomer

Object

true

Details of the main client of this account.

customers[].defaultCustomer.entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

customers[].defaultCustomer.name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

customers[].defaultCustomer.mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

customers[].defaultCustomer.email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

customers[].defaultCustomer.kycStatus

Boolean

true

Status of customer being KYC’d.

customers[].defaultCustomer.identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

customers[].otherCustomers

Array[Object]

true

List of all other clients connected to this account.

customers[].otherCustomers[].entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

customers[].otherCustomers[].name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

customers[].otherCustomers[].mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

customers[].otherCustomers[].email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

customers[].otherCustomers[].kycStatus

Boolean

true

Status of customer being KYC’d.

customers[].otherCustomers[].identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

Example request

GET /api/customers?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1800

{
  "page" : {
    "page" : 0,
    "pageSize" : 3,
    "numberOfElements" : 3,
    "totalElements" : 3,
    "totalPages" : 1,
    "first" : true,
    "last" : true
  },
  "customers" : [ {
    "customerId" : "1",
    "defaultAccountNumber" : "12345000001",
    "customerReference" : "Reference 1",
    "adminFeePercent" : "1.0",
    "defaultCustomer" : {
      "entityTypeId" : "1",
      "name1" : "Surname 1",
      "name2" : "FirstName 1",
      "mobilePhoneNumber" : "0990000001",
      "email" : "kycemail1@Testkyc.com",
      "kycStatus" : true,
      "identifyingNumber" : "9511025037083",
      "taxNumber" : "111/1111/111/1",
      "address" : "1 Street,1 Suburb,1 City,1001"
    },
    "otherCustomers" : [ ]
  }, {
    "customerId" : "2",
    "defaultAccountNumber" : "12345000002",
    "customerReference" : "Reference 1",
    "adminFeePercent" : "1.0",
    "defaultCustomer" : {
      "entityTypeId" : "1",
      "name1" : "Surname 1",
      "name2" : "FirstName 1",
      "mobilePhoneNumber" : "0990000001",
      "email" : "kycemail1@Testkyc.com",
      "kycStatus" : true,
      "identifyingNumber" : "9511025037083",
      "taxNumber" : "111/1111/111/1",
      "address" : "1 Street,1 Suburb,1 City,1001"
    },
    "otherCustomers" : [ ]
  }, {
    "customerId" : "3",
    "defaultAccountNumber" : "12345000003",
    "customerReference" : "Reference 1",
    "adminFeePercent" : "1.0",
    "defaultCustomer" : {
      "entityTypeId" : "1",
      "name1" : "Surname 1",
      "name2" : "FirstName 1",
      "mobilePhoneNumber" : "0990000001",
      "email" : "kycemail1@Testkyc.com",
      "kycStatus" : true,
      "identifyingNumber" : "9511025037083",
      "taxNumber" : "111/1111/111/1",
      "address" : "1 Street,1 Suburb,1 City,1001"
    },
    "otherCustomers" : [ ]
  } ]
}

Get Customers For Current User

Authentication is required.

GET /api/users/current/customers

Gets all customers linked to the current authenticated user.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

customers

Array[Object]

true

An array of customers.

customers[].customerId

String

false

Customer unique id.

customers[].defaultAccountNumber

String

true

The default account number for this account.

customers[].customerReference

String

true

Customers unique reference number.

Size must be between 1 and 255 inclusive.

customers[].agentReference

String

true

Agent reference number.

Size must be between 1 and 255 inclusive.

customers[].adminFeePercent

String

true

Administration fee percentage.

customers[].defaultCustomer

Object

true

Details of the main client of this account.

customers[].defaultCustomer.entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

customers[].defaultCustomer.name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

customers[].defaultCustomer.mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

customers[].defaultCustomer.email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

customers[].defaultCustomer.kycStatus

Boolean

true

Status of customer being KYC’d.

customers[].defaultCustomer.identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

customers[].defaultCustomer.investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

customers[].otherCustomers

Array[Object]

true

List of all other clients connected to this account.

customers[].otherCustomers[].entityTypeId

String

false

Entity type id.

Valid Entity Type Ids are: 1 = Individual, 3 = Trust, 4 = CC, 5 = Pty (Ltd), 6 = Ltd.

Must be at least 1.
Must have at most 2 integral digits and 0 fractional digits.

customers[].otherCustomers[].name1

String

false

Name1 of the customer. If individual then surname else companies name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Must contain alphabets.
Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].name2

String

true

Name2 of the customer. Mandatory if entity type individual(1) and must be the individual’s name(s). Optional for all other entity types. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 0 and 255 inclusive.

customers[].otherCustomers[].mobilePhoneNumber

String

true

Customer mobile contact number.

Must have at most 14 integral digits and 0 fractional digits.

customers[].otherCustomers[].email

String

true

Customer email address. Valid input is Uppercase Latin letters , numbers and punctuation.

Must be a well-formed email address.

customers[].otherCustomers[].kycStatus

Boolean

true

Status of customer being KYC’d.

customers[].otherCustomers[].identifyingNumber

String

false

Identification Number.

Format specific to entity type:
1 = Individual, must be a valid SA ID number YYMMDDNNNNNNN.
3 = Trust, format not applicable
4 = CC, 5 = Pty (Ltd) or 6 = Ltd, must be YYYY/NNNNNN/NN.
YYYY, year must be greater or equal to 1800.
NN can be any one of:
06 = Public company Ltd,
07 = Private company (Pty) Lty,
08 = Non-profit company,
09 = Limited By Guarantee,
10 = External company,
12 = Non Profit External Company
21 = Personal liability company (Inc),
22 = Unlimited,
23 = Close Corporation (CC),
24 = Primary Co-Operative,
25 = Secondary Co-Operative,
26 = Tertiary Co-Operative
30 = State-owned company
31 = Statutory Body.

Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].taxNumber

String

false

Tax number.

Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].address

String

true

Customer address. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

customers[].otherCustomers[].investmentTypeId

Integer

true

Investment Type Id number. Defaults to ITF when not specified.

Example request

GET /api/users/current/customers?page=1&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1801

{
  "page" : {
    "page" : 1,
    "pageSize" : 3,
    "numberOfElements" : 3,
    "totalElements" : 6,
    "totalPages" : 2,
    "first" : false,
    "last" : true
  },
  "customers" : [ {
    "customerId" : "4",
    "defaultAccountNumber" : "12345000004",
    "customerReference" : "Reference 1",
    "adminFeePercent" : "1.0",
    "defaultCustomer" : {
      "entityTypeId" : "1",
      "name1" : "Surname 1",
      "name2" : "FirstName 1",
      "mobilePhoneNumber" : "0990000001",
      "email" : "kycemail1@Testkyc.com",
      "kycStatus" : true,
      "identifyingNumber" : "9511025037083",
      "taxNumber" : "111/1111/111/1",
      "address" : "1 Street,1 Suburb,1 City,1001"
    },
    "otherCustomers" : [ ]
  }, {
    "customerId" : "5",
    "defaultAccountNumber" : "12345000005",
    "customerReference" : "Reference 1",
    "adminFeePercent" : "1.0",
    "defaultCustomer" : {
      "entityTypeId" : "1",
      "name1" : "Surname 1",
      "name2" : "FirstName 1",
      "mobilePhoneNumber" : "0990000001",
      "email" : "kycemail1@Testkyc.com",
      "kycStatus" : true,
      "identifyingNumber" : "9511025037083",
      "taxNumber" : "111/1111/111/1",
      "address" : "1 Street,1 Suburb,1 City,1001"
    },
    "otherCustomers" : [ ]
  }, {
    "customerId" : "6",
    "defaultAccountNumber" : "12345000006",
    "customerReference" : "Reference 1",
    "adminFeePercent" : "1.0",
    "defaultCustomer" : {
      "entityTypeId" : "1",
      "name1" : "Surname 1",
      "name2" : "FirstName 1",
      "mobilePhoneNumber" : "0990000001",
      "email" : "kycemail1@Testkyc.com",
      "kycStatus" : true,
      "identifyingNumber" : "9511025037083",
      "taxNumber" : "111/1111/111/1",
      "address" : "1 Street,1 Suburb,1 City,1001"
    },
    "otherCustomers" : [ ]
  } ]
}

Customer Message

Our Customer Message endpoints allow users to create and retrieve messages to the customer

Create Customer Message

Authentication is required.

POST /api/customers/{customerId}/messages

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

customerId

String

false

Must have at most 19 integral digits and 0 fractional digits.

Request fields

Path Type Optional Description

message

String

false

Size must be between 0 and 256 inclusive.

fromDepartment

String

false

Size must be between 0 and 100 inclusive.

fromPerson

String

false

Size must be between 0 and 100 inclusive.

Response fields

Path Type Optional Description

message

String

false

Size must be between 0 and 256 inclusive.

fromDepartment

String

false

Size must be between 0 and 100 inclusive.

fromPerson

String

false

Size must be between 0 and 100 inclusive.

id

String

true

dateCreated

String

true

Example request

POST /api/customers/1234-5678/messages HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 116

{
  "message" : "Hello and welcome, valued customer",
  "fromDepartment" : "Business",
  "fromPerson" : "John Doe"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 179

{
  "message" : "Hello and welcome, valued customer",
  "fromDepartment" : "Business",
  "fromPerson" : "John Doe",
  "id" : "1234-5678",
  "dateCreated" : "2019-11-22T10:34:00"
}

Get Customer Messages

Authentication is required.

GET /api/customers/{customerId}/messages

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

customerId

String

false

Must have at most 19 integral digits and 0 fractional digits.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

messages

Array[Object]

true

messages[].message

String

false

Size must be between 0 and 256 inclusive.

messages[].fromDepartment

String

false

Size must be between 0 and 100 inclusive.

messages[].fromPerson

String

false

Size must be between 0 and 100 inclusive.

messages[].id

String

true

messages[].dateCreated

String

true

Example request

GET /api/customers/123-456/messages?page=0&size=10 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 615

{
  "messages" : [ {
    "message" : "Hello and welcome, valued customer",
    "fromDepartment" : "Business",
    "fromPerson" : "John Doe",
    "id" : "1234-5678",
    "dateCreated" : "2019-11-22T10:34:00"
  }, {
    "message" : "Please review your personal information",
    "fromDepartment" : "Business",
    "fromPerson" : "John Doe",
    "id" : "1234-5679",
    "dateCreated" : "2019-11-30T12:11:00"
  }, {
    "message" : "You are eligible for a loan of up to R10'000",
    "fromDepartment" : "Business",
    "fromPerson" : "John Doe",
    "id" : "1234-6589",
    "dateCreated" : "2020-02-15T10:55:00"
  } ]
}

Guarantees

Our Guarantee endpoints allow you to create and access loan guarantee data that exists on Grindrod Bank System

Get Guarantee State

Authentication is NOT required.

GET /api/guarantees/{guaranteeID}/state

Returns guarantee state by guaranteeID.

Path parameters

Parameter Type Optional Description

guaranteeID

String

false

The guarantee ID used to query state.

Size must be between 1 and 255 inclusive.

Response fields

Path Type Optional Description

state

String

true

State of the Guarantee either VALID or INVALID.

Example request

GET /api/guarantees/123/state HTTP/1.1
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 23

{
  "state" : "VALID"
}

Investment Types

Get a list of investment types offered to API users

Get Investment Types

Authentication is required.

GET /api/investment-types

Returns a list of investment types.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

investmentTypes

Array[Object]

false

investmentTypes[].id

Integer

false

Investment Type id.

investmentTypes[].description

String

false

Description of the Investment Type.

Example request

GET /api/investment-types?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 130

{
  "investmentTypes" : [ {
    "id" : 0,
    "description" : "ITF"
  }, {
    "id" : 1,
    "description" : "ESTATE LATE"
  } ]
}

Public Accounts

Our Public Accounts endpoint allows users to view the banking details of public entities listed with the bank

Get Public Accounts

Authentication is required.

GET /api/accounts/public

Returns public account details.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Query parameters

Supports standard paging query parameters.

Parameter Type Optional Description

name

String

true

When present returns the public account for the given name.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

publicAccounts

Array[Object]

true

An array of public accounts.

publicAccounts[].accountId

String

true

ID of the public account.

publicAccounts[].name

String

true

Name of the public account.

Example request

GET /api/accounts/public?page=0&size=3 HTTP/1.1
Agent-Id: 32
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 250

{
  "page" : {
    "page" : 0,
    "pageSize" : 3,
    "numberOfElements" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "first" : true,
    "last" : true
  },
  "publicAccounts" : [ {
    "accountId" : "1911915",
    "name" : "SARS"
  } ]
}

Products

The Api allows users to retrieve products offered by the logged in agent .

Get Product

Authentication is required.

GET /api/products/{code}

Returns a product specific to the agent and the product code

Only products offered by the agent can be viewed

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

code

String

false

The code used to identify the product specfic to the agent.

Size must be between 1 and 255 inclusive.

Response fields

Path Type Optional Description

code

String

false

The unique code of the product offered by the bank.

description

String

false

The Description of the product.

Example request

GET /api/products/3456 HTTP/1.1
Agent-Id: 32
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 58

{
  "code" : "3456",
  "description" : "CURRENT ACCOUNT"
}

Get Products

Authentication is required.

GET /api/products

Returns a list of products per agent

Will return a list of products specific to the agent logged in

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

products

Array[Object]

false

A list of products available for use by a Grindrod bank client.

products[].code

String

false

The unique code of the product offered by the bank.

products[].description

String

false

The Description of the product.

Example request

GET /api/products?page=0&size=10 HTTP/1.1
Agent-Id: 32
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 286

{
  "products" : [ {
    "code" : "3456",
    "description" : "CURRENT ACCOUNT"
  }, {
    "code" : "3457",
    "description" : "TRANSMISSION ACCOUNT"
  }, {
    "code" : "3458",
    "description" : "SAVING ACCOUNT"
  }, {
    "code" : "3459",
    "description" : "BOND ACCOUNT"
  } ]
}

Role

Our entitlement endpoints allow users to add, remove and view user entitlements

Add Entitlement For User

Authentication is required.

POST /api/users/{userId}/entitlements

Adds an entitlement to an API user.

Requires administrator privileges.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

userId

String

false

User to add entitlement to.

Size must be between 1 and 255 inclusive.

Request fields

Path Type Optional Description

roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

list

Array[Object]

true

list[].roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

list[].id

String

true

Entitlement id.

Example request

POST /api/users/1234/entitlements HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 35

{
  "roleName" : "create_account"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 77

{
  "list" : [ {
    "roleName" : "create_account",
    "id" : "1234"
  } ]
}

Delete User Entitlement

Authentication is required.

DELETE /api/users/{userId}/entitlements/{entitlementId}

Removes an entitlement from an API user.

Requires administrator privileges.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

userId

String

false

User to remove entitlement from.

Size must be between 1 and 255 inclusive.

entitlementId

String

false

Entitlement to remove.

Size must be between 1 and 255 inclusive.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

list

Array[Object]

true

list[].roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

list[].id

String

true

Entitlement id.

Example request

DELETE /api/users/9405235555555/entitlements/1a2b-3c4d-5e6f-7g8h9i HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 94

{
  "list" : [ {
    "roleName" : "create_account",
    "id" : "1a2b-3c4d-5e6f-7g8h9i"
  } ]
}

Get Entitlements

Authentication is required.

GET /api/entitlements

Returns all roles that can be assigned to API users.

Requires administrator privileges.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

list

Array[Object]

true

list[].roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

list[].id

String

true

Entitlement id.

Example request

GET /api/entitlements?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 176

{
  "list" : [ {
    "roleName" : "create_account"
  }, {
    "roleName" : "create_customer"
  }, {
    "roleName" : "create_fica"
  }, {
    "roleName" : "update_fica"
  } ]
}

Get Entitlements For Current User

Authentication is required.

GET /api/users/current/entitlements

Get entitlements for the current API user

Requires administrator privileges.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

list

Array[Object]

true

list[].roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

list[].id

String

true

Entitlement id.

Example request

GET /api/users/current/entitlements?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 320

{
  "list" : [ {
    "roleName" : "create_account",
    "id" : "1a2b-3c4d-5e6f-7g8h9i"
  }, {
    "roleName" : "create_customer",
    "id" : "1a2b-7g8h9i-3c4d-5e6f"
  }, {
    "roleName" : "create_fica",
    "id" : "1a2b-e6f-7g8h9i-3c4d5"
  }, {
    "roleName" : "update_fica",
    "id" : "e6f-1a2b-3c4d5-7g8h9i"
  } ]
}

Get Entitlements For User

Authentication is required.

GET /api/users/{userId}/entitlements

Get entitlements for the specified user

Requires administrator privileges.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

userId

String

false

User to get entitlements for.

Size must be between 1 and 255 inclusive.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

list

Array[Object]

true

list[].roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

list[].id

String

true

Entitlement id.

Example request

GET /api/users/ABC-123/entitlements?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 320

{
  "list" : [ {
    "roleName" : "create_account",
    "id" : "1a2b-3c4d-5e6f-7g8h9i"
  }, {
    "roleName" : "create_customer",
    "id" : "1a2b-7g8h9i-3c4d-5e6f"
  }, {
    "roleName" : "create_fica",
    "id" : "1a2b-e6f-7g8h9i-3c4d5"
  }, {
    "roleName" : "update_fica",
    "id" : "e6f-1a2b-3c4d5-7g8h9i"
  } ]
}

Transactions

Account activity can be retrieved and viewed through our transaction endpoints.

Get Transactions

Authentication is required.

GET /api/accounts/{accountId}/transactions

Returns transactions between the dates specified by fromDate and toDate, for the account specified by accountId.

This must be an account owned by the agent of the user you are logged in with.

To calculate the opening balance use the logic of: '1st transactions.balance – 1st transaction.amount'.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Unique id of the account.

Must have at most 16 integral digits and 0 fractional digits.

Query parameters

Supports standard paging query parameters.

Parameter Type Optional Description

customerId

String

false

Id of the customer holding the account.

Must have at most 19 integral digits and 0 fractional digits.

fromDate

Object

false

Transaction start date.

Must be a valid date in the format of yyyy-MM-dd.

toDate

Object

false

Last transaction date.

Must be a valid date in the format of yyyy-MM-dd.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

transactions

Array[Object]

true

An array of transactions for an account between the specified dates.

transactions[].id

String

true

Unique id of the transaction.

transactions[].thisAccount

Object

true

Account against which transaction was made.

transactions[].thisAccount.id

String

true

Unique id of the account.

transactions[].thisAccount.number

String

true

Account number of the queried account.

transactions[].thisAccount.agentId

Integer

true

Id of logged in agent querying the accounts.

transactions[].thisAccount.bankId

String

true

Bank id.

transactions[].thisAccount.branchCode

String

true

Branch code.

transactions[].thisAccount.accountType

String

true

Account type.

transactions[].thisAccount.customers

Array[Object]

true

Customers of the account.

transactions[].thisAccount.customers[].customerId

String

true

Id of the customer holding the account.

transactions[].thisAccount.customers[].displayName

String

true

Descriptive name of the account customer holding the account.

transactions[].thisAccount.customers[].provider

String

true

Institution or bank providing the account services.

transactions[].otherAccount

Object

true

Account to which transaction was made.

transactions[].otherAccount.id

String

true

Unique id of the account.

transactions[].otherAccount.number

String

true

Account number of the queried account.

transactions[].otherAccount.agentId

Integer

true

Id of logged in agent querying the accounts.

transactions[].otherAccount.bankId

String

true

Bank id.

transactions[].otherAccount.branchCode

String

true

Branch code.

transactions[].otherAccount.accountType

String

true

Account type.

transactions[].otherAccount.customers

Array[Object]

true

Customers of the account.

transactions[].otherAccount.customers[].customerId

String

true

Id of the customer holding the account.

transactions[].otherAccount.customers[].displayName

String

true

Descriptive name of the account customer holding the account.

transactions[].otherAccount.customers[].provider

String

true

Institution or bank providing the account services.

transactions[].details

Object

true

Details of the transaction.

transactions[].details.type

String

true

WITHDRAWAL, DEPOSIT or TRANSFER.

transactions[].details.description

String

true

Description of transaction which will appear on statements.

transactions[].details.fromReference

String

true

Customer fromReference for transaction.

transactions[].details.toReference

String

true

Customer toReference for transaction.

transactions[].details.systemReference

String

true

System generated reference for transaction.

transactions[].details.posted

String

true

Date transaction was posted.

transactions[].details.completed

String

true

Date transaction was completed.

transactions[].details.newBalance

Object

true

Balance of the account after transaction.

transactions[].details.newBalance.currency

String

true

Currency.

transactions[].details.newBalance.amount

Decimal

true

Amount.

transactions[].details.value

Object

true

Amount that this transaction is for.

transactions[].details.value.currency

String

true

Currency.

transactions[].details.value.amount

Decimal

true

Amount.

Example request

GET /api/accounts/11000260041/transactions?customerId=8543256436&fromDate=2017-01-01&toDate=2017-07-18&page=0&size=3 HTTP/1.1
Agent-Id: 208
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 942

{
  "transactions" : [ {
    "id" : "1",
    "thisAccount" : {
      "id" : "11000260041",
      "agentId" : 208,
      "customers" : [ {
        "customerId" : "8543256436",
        "displayName" : "TEST CLIENT NAME178676"
      } ]
    },
    "otherAccount" : {
      "id" : "1234",
      "agentId" : 0,
      "bankId" : "Test Bank Id 12345",
      "branchCode" : "Test Branch Code 12345",
      "accountType" : "C",
      "customers" : [ {
        "displayName" : "TEST Payment Name 3054975"
      } ]
    },
    "details" : {
      "type" : "DEPOSIT",
      "description" : "TEST DEPOSIT",
      "fromReference" : "fromDEP",
      "toReference" : "toDEP",
      "systemReference" : "sysDEP",
      "posted" : "2017-06-06",
      "completed" : "2017-06-06",
      "newBalance" : {
        "currency" : "ZAR",
        "amount" : 14500.0
      },
      "value" : {
        "currency" : "ZAR",
        "amount" : 14500.0
      }
    }
  } ]
}

Get Transaction By Id

Authentication is required.

GET /api/accounts/{accountId}/transactions/{transactionId}

Returns a transaction based on a transaction id, for the account specified by accountId.

This must be an account owned by the agent of the user you are logged in with.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Unique id of the account.

Must have at most 16 integral digits and 0 fractional digits.

transactionId

String

false

The transaction id of a transaction.

Must have at most 16 integral digits and 0 fractional digits.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

transactions

Array[Object]

true

An array of transactions for an account between the specified dates.

transactions[].id

String

true

Unique id of the transaction.

transactions[].thisAccount

Object

true

Account against which transaction was made.

transactions[].thisAccount.id

String

true

Unique id of the account.

transactions[].thisAccount.number

String

true

Account number of the queried account.

transactions[].thisAccount.agentId

Integer

true

Id of logged in agent querying the accounts.

transactions[].thisAccount.bankId

String

true

Bank id.

transactions[].thisAccount.branchCode

String

true

Branch code.

transactions[].thisAccount.accountType

String

true

Account type.

transactions[].thisAccount.customers

Array[Object]

true

Customers of the account.

transactions[].thisAccount.customers[].customerId

String

true

Id of the customer holding the account.

transactions[].thisAccount.customers[].displayName

String

true

Descriptive name of the account customer holding the account.

transactions[].thisAccount.customers[].provider

String

true

Institution or bank providing the account services.

transactions[].otherAccount

Object

true

Account to which transaction was made.

transactions[].otherAccount.id

String

true

Unique id of the account.

transactions[].otherAccount.number

String

true

Account number of the queried account.

transactions[].otherAccount.agentId

Integer

true

Id of logged in agent querying the accounts.

transactions[].otherAccount.bankId

String

true

Bank id.

transactions[].otherAccount.branchCode

String

true

Branch code.

transactions[].otherAccount.accountType

String

true

Account type.

transactions[].otherAccount.customers

Array[Object]

true

Customers of the account.

transactions[].otherAccount.customers[].customerId

String

true

Id of the customer holding the account.

transactions[].otherAccount.customers[].displayName

String

true

Descriptive name of the account customer holding the account.

transactions[].otherAccount.customers[].provider

String

true

Institution or bank providing the account services.

transactions[].details

Object

true

Details of the transaction.

transactions[].details.type

String

true

WITHDRAWAL, DEPOSIT or TRANSFER.

transactions[].details.description

String

true

Description of transaction which will appear on statements.

transactions[].details.fromReference

String

true

Customer fromReference for transaction.

transactions[].details.toReference

String

true

Customer toReference for transaction.

transactions[].details.systemReference

String

true

System generated reference for transaction.

transactions[].details.posted

String

true

Date transaction was posted.

transactions[].details.completed

String

true

Date transaction was completed.

transactions[].details.newBalance

Object

true

Balance of the account after transaction.

transactions[].details.newBalance.currency

String

true

Currency.

transactions[].details.newBalance.amount

Decimal

true

Amount.

transactions[].details.value

Object

true

Amount that this transaction is for.

transactions[].details.value.currency

String

true

Currency.

transactions[].details.value.amount

Decimal

true

Amount.

Example request

GET /api/accounts/11000260041/transactions/1 HTTP/1.1
Agent-Id: 208
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 942

{
  "transactions" : [ {
    "id" : "1",
    "thisAccount" : {
      "id" : "11000260041",
      "agentId" : 208,
      "customers" : [ {
        "customerId" : "8543256436",
        "displayName" : "TEST CLIENT NAME178676"
      } ]
    },
    "otherAccount" : {
      "id" : "1234",
      "agentId" : 0,
      "bankId" : "Test Bank Id 12345",
      "branchCode" : "Test Branch Code 12345",
      "accountType" : "C",
      "customers" : [ {
        "displayName" : "TEST Payment Name 3054975"
      } ]
    },
    "details" : {
      "type" : "DEPOSIT",
      "description" : "TEST DEPOSIT",
      "fromReference" : "fromDEP",
      "toReference" : "toDEP",
      "systemReference" : "sysDEP",
      "posted" : "2017-06-06",
      "completed" : "2017-06-06",
      "newBalance" : {
        "currency" : "ZAR",
        "amount" : 14500.0
      },
      "value" : {
        "currency" : "ZAR",
        "amount" : 14500.0
      }
    }
  } ]
}

Transaction Request

The functionality of how to initiate a payment/transaction on the Grindrod BankAPI has been based on that provided by the Open Bank Project (OBP). More information on the OBP transaction requests can be found at : https://github.com/OpenBankProject/OBP-API/wiki/Transaction-Requests

For the Grindrod BankAPI (similar to OBP):

  • Transactions are items in a bank statement that represent the movement of money.

  • A Transaction Requests serve to initiate movement of money, which may or may not result in a successful Transaction.

  • Transaction Request can have statuses INITIATED, COMPLETED, FAILED

  • Where as a Transaction can only every have one possible state COMPLETED

  • A Transaction Requests can be one of several Transaction Request Types.

  • There are currently three different Transaction Request Types. (More types will be introduced in future, you can always call the 'Get Transaction Request Types' end point to get the latest list to types.)

    • FREE_FORM

    • BENEFICIARY

    • TRANSFER_TO_ACCOUNT

For all Transaction Request end points - The payer is set in the URL using {accountId}. Money comes out of the {accountId} specified in the URL.

Get Transaction Request Types

Authentication is required.

GET /api/accounts/{accountId}/transaction-request-types

Returns the Transaction Request Types that the account specified by accountId has access to.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Id of the account.

Must have at most 16 integral digits and 0 fractional digits.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

transactionRequestTypes

Array[Object]

true

List of Transaction Request Types.

transactionRequestTypes[].value

String

true

Transaction type code.

Example request

GET /api/accounts/312512/transaction-request-types?page=0&size=3 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 147

{
  "transactionRequestTypes" : [ {
    "value" : "BENEFICIARY"
  }, {
    "value" : "FREE_FORM"
  }, {
    "value" : "TRANSFER_TO_ACCOUNT"
  } ]
}

Create Transaction Request

Information related to the creation of Transaction Request Types.

Free Form

Authentication is required.

POST /api/accounts/{accountId}/transaction-requests/FREE_FORM

Initiate a Payment to a recipient by creating a Transaction Request where all of the recipient’s account details need to be populated.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Account id of payer account.

Must have at most 16 integral digits and 0 fractional digits.

Request fields

Path Type Optional Description

fromReference

String

false

Payer reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

requestDate

String

false

Payment date.

value

Object

false

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

to

Object

false

to.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

to.bankCode

String

false

Bank unique member number.

Size must be between 1 and 10 inclusive.

to.branchCode

String

false

Branch code.

Size must be between 1 and 6 inclusive.

to.accountId

String

false

Account number.

Must have at most 16 integral digits and 0 fractional digits.

to.name

String

false

Beneficiary name. Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

to.accountType

String

false

Account type description.

Size must be between 1 and 255 inclusive.

Response fields

Path Type Optional Description

id

String

true

Unique id for transaction request.

type

String

true

Transaction type.

Must be one of [BENEFICIARY, FREE_FORM, PUBLIC_ACCOUNT, TRANSFER_TO_ACCOUNT].

from

Object

true

Payment originator.

from.bankId

String

true

Bank unique id.

from.accountId

String

true

Account number.

from.fromReference

String

true

Payment reference.

to

Object

true

Recipient of Payment.

to.bankCode

String

true

Bank unique member number.

to.branchCode

String

true

Branch code.

to.accountId

String

true

Account number.

to.toReference

String

true

Beneficiary reference.

to.name

String

true

Beneficiary name.

to.accountType

String

true

Account type description.

to.beneficiaryId

String

true

Beneficiary unique id.

details

Object

true

Original Request Details.

details.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

value

Object

true

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

requestDate

String

true

Transaction request date.

transactionId

String

true

Unique id for transaction.

status

String

true

Transaction status.

Must be one of [INITIATED, COMPLETED, FAILED].

Example request

POST /api/accounts/0123456700/transaction-requests/FREE_FORM HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1234
Host: api.grindrodbank.co.za
Content-Length: 339

{
  "fromReference" : "Free Form From Reference",
  "requestDate" : "2019-10-16T10:47:26",
  "value" : {
    "currency" : "ZAR",
    "amount" : 123.45
  },
  "to" : {
    "toReference" : "testToRef",
    "bankCode" : "STD",
    "branchCode" : "012345",
    "accountId" : "0123456700",
    "name" : "testName",
    "accountType" : "C"
  }
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 710

{
  "id" : "76657657c-78679878",
  "type" : "FREE_FORM",
  "from" : {
    "bankId" : "584000",
    "accountId" : "0123456700",
    "fromReference" : "pay for outing"
  },
  "to" : {
    "bankCode" : "STD",
    "branchCode" : "123456",
    "accountId" : "11002238423",
    "toReference" : "testToRef",
    "name" : "testName",
    "accountType" : "C"
  },
  "details" : {
    "toReference" : "testToRef",
    "bankCode" : "GBL",
    "branchCode" : "123456",
    "accountId" : "11002238456",
    "name" : "testName",
    "accountType" : "C"
  },
  "value" : {
    "currency" : "ZAR",
    "amount" : 10
  },
  "requestDate" : "2019-10-16T10:47:26",
  "transactionId" : "237e823e23h78h",
  "status" : "COMPLETED"
}

Beneficiary

Authentication is required.

POST /api/accounts/{accountId}/transaction-requests/BENEFICIARY

Initiate a Payment to a recipient by creating a Transaction Request for an account listed as a beneficiary of the initiation account.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Account id of payer account.

Must have at most 16 integral digits and 0 fractional digits.

Request fields

Path Type Optional Description

fromReference

String

false

Payer reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

requestDate

String

false

Payment date.

value

Object

false

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

to

Object

false

to.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

to.beneficiaryId

String

false

Beneficiary unique id.

Must have at most 19 integral digits and 0 fractional digits.

Response fields

Path Type Optional Description

id

String

true

Unique id for transaction request.

type

String

true

Transaction type.

Must be one of [BENEFICIARY, FREE_FORM, PUBLIC_ACCOUNT, TRANSFER_TO_ACCOUNT].

from

Object

true

Payment originator.

from.bankId

String

true

Bank unique id.

from.accountId

String

true

Account number.

from.fromReference

String

true

Payment reference.

to

Object

true

Recipient of Payment.

to.bankCode

String

true

Bank unique member number.

to.branchCode

String

true

Branch code.

to.accountId

String

true

Account number.

to.toReference

String

true

Beneficiary reference.

to.name

String

true

Beneficiary name.

to.accountType

String

true

Account type description.

to.beneficiaryId

String

true

Beneficiary unique id.

details

Object

true

Original Request Details.

details.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

value

Object

true

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

requestDate

String

true

Transaction request date.

transactionId

String

true

Unique id for transaction.

status

String

true

Transaction status.

Must be one of [INITIATED, COMPLETED, FAILED].

Example request

POST /api/accounts/0123456700/transaction-requests/BENEFICIARY HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1234
Host: api.grindrodbank.co.za
Content-Length: 236

{
  "fromReference" : "Beneficiary From Reference",
  "requestDate" : "2019-10-16T10:47:26",
  "value" : {
    "currency" : "ZAR",
    "amount" : 123.45
  },
  "to" : {
    "toReference" : "testToRef",
    "beneficiaryId" : "0987"
  }
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 609

{
  "id" : "76657657c-78679878",
  "type" : "BENEFICIARY",
  "from" : {
    "bankId" : "584000",
    "accountId" : "0123456700",
    "fromReference" : "pay for outing"
  },
  "to" : {
    "bankCode" : "STD",
    "branchCode" : "123456",
    "accountId" : "11002238423",
    "toReference" : "testToRef",
    "name" : "testName",
    "accountType" : "C"
  },
  "details" : {
    "toReference" : "to-reference",
    "beneficiaryId" : "0987"
  },
  "value" : {
    "currency" : "ZAR",
    "amount" : 10
  },
  "requestDate" : "2019-10-16T10:47:26",
  "transactionId" : "237e823e23h78h",
  "status" : "INITIATED"
}

Public Account

Authentication is required.

POST /api/accounts/{accountId}/transaction-requests/PUBLIC_ACCOUNT

Initiate a Payment to a recipient by creating a Transaction Request for a public account of the initiation account.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Account id of payer account.

Must have at most 16 integral digits and 0 fractional digits.

Request fields

Path Type Optional Description

fromReference

String

false

Payer reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

requestDate

String

false

Payment date.

value

Object

false

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

to

Object

false

to.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

to.accountId

String

false

Public Account id.

Must have at most 16 integral digits and 0 fractional digits.

Response fields

Path Type Optional Description

id

String

true

Unique id for transaction request.

type

String

true

Transaction type.

Must be one of [BENEFICIARY, FREE_FORM, PUBLIC_ACCOUNT, TRANSFER_TO_ACCOUNT].

from

Object

true

Payment originator.

from.bankId

String

true

Bank unique id.

from.accountId

String

true

Account number.

from.fromReference

String

true

Payment reference.

to

Object

true

Recipient of Payment.

to.bankCode

String

true

Bank unique member number.

to.branchCode

String

true

Branch code.

to.accountId

String

true

Account number.

to.toReference

String

true

Beneficiary reference.

to.name

String

true

Beneficiary name.

to.accountType

String

true

Account type description.

to.beneficiaryId

String

true

Beneficiary unique id.

details

Object

true

Original Request Details.

details.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

value

Object

true

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

requestDate

String

true

Transaction request date.

transactionId

String

true

Unique id for transaction.

status

String

true

Transaction status.

Must be one of [INITIATED, COMPLETED, FAILED].

Example request

POST /api/accounts/0123456700/transaction-requests/PUBLIC_ACCOUNT HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1234
Host: api.grindrodbank.co.za
Content-Length: 238

{
  "fromReference" : "Public Account From Reference",
  "requestDate" : "2019-10-16T10:47:26",
  "value" : {
    "currency" : "ZAR",
    "amount" : 123.45
  },
  "to" : {
    "toReference" : "testToRef",
    "accountId" : "1911915"
  }
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 611

{
  "id" : "76657657c-78679878",
  "type" : "PUBLIC_ACCOUNT",
  "from" : {
    "bankId" : "584000",
    "accountId" : "0123456700",
    "fromReference" : "pay for outing"
  },
  "to" : {
    "bankCode" : "STD",
    "branchCode" : "123456",
    "accountId" : "11002238423",
    "toReference" : "testToRef",
    "name" : "testName",
    "accountType" : "C"
  },
  "details" : {
    "toReference" : "to-reference",
    "accountId" : "1911915"
  },
  "value" : {
    "currency" : "ZAR",
    "amount" : 10
  },
  "requestDate" : "2019-10-16T10:47:26",
  "transactionId" : "237e823e23h78h",
  "status" : "INITIATED"
}

Transfer To Another Account

Authentication is required.

POST /api/accounts/{accountId}/transaction-requests/TRANSFER_TO_ACCOUNT

Initiate Moving funds from one Grindrod Bank account to another by creating a Transaction Request.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Account id of payer account.

Must have at most 16 integral digits and 0 fractional digits.

Request fields

Path Type Optional Description

fromReference

String

false

Payer reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

requestDate

String

false

Payment date.

value

Object

false

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

to

Object

false

to.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

to.accountId

String

false

To Account unique id.

Must have at most 16 integral digits and 0 fractional digits.

Response fields

Path Type Optional Description

id

String

true

Unique id for transaction request.

type

String

true

Transaction type.

Must be one of [BENEFICIARY, FREE_FORM, PUBLIC_ACCOUNT, TRANSFER_TO_ACCOUNT].

from

Object

true

Payment originator.

from.bankId

String

true

Bank unique id.

from.accountId

String

true

Account number.

from.fromReference

String

true

Payment reference.

to

Object

true

Recipient of Payment.

to.bankCode

String

true

Bank unique member number.

to.branchCode

String

true

Branch code.

to.accountId

String

true

Account number.

to.toReference

String

true

Beneficiary reference.

to.name

String

true

Beneficiary name.

to.accountType

String

true

Account type description.

to.beneficiaryId

String

true

Beneficiary unique id.

details

Object

true

Original Request Details.

details.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

value

Object

true

Transaction amount.

value.currency

String

false

Transaction currency.

value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

requestDate

String

true

Transaction request date.

transactionId

String

true

Unique id for transaction.

status

String

true

Transaction status.

Must be one of [INITIATED, COMPLETED, FAILED].

Example request

POST /api/accounts/0123456700/transaction-requests/TRANSFER_TO_ACCOUNT HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1234
Host: api.grindrodbank.co.za
Content-Length: 250

{
  "fromReference" : "transfer to another acc From Reference",
  "requestDate" : "2019-10-16T10:47:26",
  "value" : {
    "currency" : "ZAR",
    "amount" : 123.45
  },
  "to" : {
    "toReference" : "testToRef",
    "accountId" : "0123456700"
  }
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 618

{
  "id" : "76657657c-78679878",
  "type" : "TRANSFER_TO_ACCOUNT",
  "from" : {
    "bankId" : "584000",
    "accountId" : "0123456700",
    "fromReference" : "pay for outing"
  },
  "to" : {
    "bankCode" : "STD",
    "branchCode" : "123456",
    "accountId" : "11002238423",
    "toReference" : "testToRef",
    "name" : "testName",
    "accountType" : "C"
  },
  "details" : {
    "toReference" : "to-reference",
    "accountId" : "accountId"
  },
  "value" : {
    "currency" : "ZAR",
    "amount" : 10
  },
  "requestDate" : "2019-10-16T10:47:26",
  "transactionId" : "237e823e23h78h",
  "status" : "INITIATED"
}

Get Transaction Requests

Authentication is required.

GET /api/accounts/{accountId}/transaction-requests

Returns transaction requests for account specified by accountId for a specified or unspecified period.

Transaction Requests serve to initiate transactions that may or may not proceed and can have a status of: INITIATED, COMPLETED,FAILED.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

accountId

String

false

Id of the account.

Must have at most 16 integral digits and 0 fractional digits.

Query parameters

Supports standard paging query parameters.

Parameter Type Optional Description

fromDate

Object

true

Transaction request start date.

Must be a valid date in the format of yyyy-MM-dd.

toDate

Object

true

Last transaction request date.

Must be a valid date in the format of yyyy-MM-dd.

Response fields

Standard paging response with list of following:

Path Type Optional Description

page

Object

false

transactionRequests

Array[Object]

true

List of Transaction Requests.

transactionRequests[].id

String

true

Unique id for transaction request.

transactionRequests[].type

String

true

Transaction type.

Must be one of [BENEFICIARY, FREE_FORM, PUBLIC_ACCOUNT, TRANSFER_TO_ACCOUNT].

transactionRequests[].from

Object

true

Payment originator.

transactionRequests[].from.bankId

String

true

Bank unique id.

transactionRequests[].from.accountId

String

true

Account number.

transactionRequests[].from.fromReference

String

true

Payment reference.

transactionRequests[].to

Object

true

Recipient of Payment.

transactionRequests[].to.bankCode

String

true

Bank unique member number.

transactionRequests[].to.branchCode

String

true

Branch code.

transactionRequests[].to.accountId

String

true

Account number.

transactionRequests[].to.toReference

String

true

Beneficiary reference.

transactionRequests[].to.name

String

true

Beneficiary name.

transactionRequests[].to.accountType

String

true

Account type description.

transactionRequests[].to.beneficiaryId

String

true

Beneficiary unique id.

transactionRequests[].details

Object

true

Original Request Details.

transactionRequests[].details.toReference

String

false

Beneficiary reference Valid input is Uppercase Latin letters , numbers, space and punctuation.

Size must be between 1 and 255 inclusive.

transactionRequests[].value

Object

true

Transaction amount.

transactionRequests[].value.currency

String

false

Transaction currency.

transactionRequests[].value.amount

Decimal

false

Transaction amount.

Must be a numeric amount.

transactionRequests[].requestDate

String

true

Transaction request date.

transactionRequests[].transactionId

String

true

Unique id for transaction.

transactionRequests[].status

String

true

Transaction status.

Must be one of [INITIATED, COMPLETED, FAILED].

Example request

GET /api/accounts/312512/transaction-requests?page=0&size=10&fromDate=2010-06-01&toDate=2018-06-01 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2133

{
  "transactionRequests" : [ {
    "id" : "76657657c-78679878",
    "type" : "FREE_FORM",
    "from" : {
      "bankId" : "584000",
      "accountId" : "312512",
      "fromReference" : "pay for outing"
    },
    "to" : {
      "bankCode" : "STD",
      "branchCode" : "123456",
      "accountId" : "11002238423",
      "toReference" : "testToRef",
      "name" : "testName",
      "accountType" : "C"
    },
    "details" : {
      "toReference" : "testToRef",
      "bankCode" : "GBL",
      "branchCode" : "123456",
      "accountId" : "11002238456",
      "name" : "testName",
      "accountType" : "C"
    },
    "value" : {
      "currency" : "ZAR",
      "amount" : 10
    },
    "requestDate" : "2010-06-01T01:02:03",
    "transactionId" : "237e823e23h78h",
    "status" : "COMPLETED"
  }, {
    "id" : "76657657c-78679878",
    "type" : "BENEFICIARY",
    "from" : {
      "bankId" : "584000",
      "accountId" : "312512",
      "fromReference" : "pay for outing"
    },
    "to" : {
      "bankCode" : "STD",
      "branchCode" : "123456",
      "accountId" : "11002238423",
      "toReference" : "testToRef",
      "name" : "testName",
      "accountType" : "C"
    },
    "details" : {
      "toReference" : "to-reference",
      "beneficiaryId" : "0987"
    },
    "value" : {
      "currency" : "ZAR",
      "amount" : 10
    },
    "requestDate" : "2010-06-01T01:02:03",
    "transactionId" : "237e823e23h78h",
    "status" : "INITIATED"
  }, {
    "id" : "76657657c-78679878",
    "type" : "TRANSFER_TO_ACCOUNT",
    "from" : {
      "bankId" : "584000",
      "accountId" : "312512",
      "fromReference" : "pay for outing"
    },
    "to" : {
      "bankCode" : "STD",
      "branchCode" : "123456",
      "accountId" : "11002238423",
      "toReference" : "testToRef",
      "name" : "testName",
      "accountType" : "C"
    },
    "details" : {
      "toReference" : "to-reference",
      "accountId" : "accountId"
    },
    "value" : {
      "currency" : "ZAR",
      "amount" : 10
    },
    "requestDate" : "2010-06-01T01:02:03",
    "transactionId" : "237e823e23h78h",
    "status" : "INITIATED"
  } ]
}

User

Our user endpoints allow users to create and retrieve user information.

Create User

Authentication is required.

POST /api/users

Creates an API user

Requires administrator privileges.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Request fields

Path Type Optional Description

username

String

false

Username must be lowercase latin letter and numbers.

Must match the regular expression [0-9a-z]+(@[0-9]+)?.
Size must be between 3 and 20 inclusive.

password

String

false

Password.

Size must be between 1 and 100 inclusive.

email

String

false

User email.

Must be a well-formed email address.

phone

String

false

Mobile number.

Size must be between 1 and 15 inclusive.

firstName

String

false

First name.

Size must be between 1 and 30 inclusive.

lastName

String

false

Last name.

Size must be between 1 and 30 inclusive.

ficaNumber

String

false

Approved FICA number.

Size must be between 1 and 15 inclusive.

idNumber

String

false

Identification number must be a valid SA ID number YYMMDDNNNNNNN.

Must match the regular expression \d{13}.

Response fields

Path Type Optional Description

username

String

false

Username must be lowercase latin letter and numbers.

Must match the regular expression [0-9a-z]+(@[0-9]+)?.
Size must be between 3 and 20 inclusive.

password

String

false

Password.

Size must be between 1 and 100 inclusive.

email

String

false

User email.

Must be a well-formed email address.

phone

String

false

Mobile number.

Size must be between 1 and 15 inclusive.

firstName

String

false

First name.

Size must be between 1 and 30 inclusive.

lastName

String

false

Last name.

Size must be between 1 and 30 inclusive.

ficaNumber

String

false

Approved FICA number.

Size must be between 1 and 15 inclusive.

idNumber

String

false

Identification number must be a valid SA ID number YYMMDDNNNNNNN.

Must match the regular expression \d{13}.

userId

String

true

System generated user id.

entitlements

Array[Object]

true

The user’s entitlements.

entitlements[].roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

entitlements[].id

String

true

Entitlement id.

Example request

POST /api/users HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 285

{
  "username" : "johnsmith",
  "password" : "5E884898DA28047151D0E56F8DC6292773603D0D6AABBDD62A11EF721D1542D8",
  "email" : "johnsmith@company.com",
  "phone" : "0123456789",
  "firstName" : "John",
  "lastName" : "Smith",
  "ficaNumber" : "F9876543",
  "idNumber" : "8906255579088"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 247

{
  "username" : "johnsmith",
  "email" : "johnsmith@company.com",
  "phone" : "0123456789",
  "firstName" : "John",
  "lastName" : "Smith",
  "ficaNumber" : "F9876543",
  "idNumber" : "8906255579088",
  "userId" : "1234",
  "entitlements" : [ ]
}

Get User By Id

Authentication is required.

GET /api/users/{userId}

Get API user details.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Path parameters

Parameter Type Optional Description

userId

String

false

User to get details for.

Size must be between 1 and 255 inclusive.

Response fields

Path Type Optional Description

username

String

false

Username must be lowercase latin letter and numbers.

Must match the regular expression [0-9a-z]+(@[0-9]+)?.
Size must be between 3 and 20 inclusive.

password

String

false

Password.

Size must be between 1 and 100 inclusive.

email

String

false

User email.

Must be a well-formed email address.

phone

String

false

Mobile number.

Size must be between 1 and 15 inclusive.

firstName

String

false

First name.

Size must be between 1 and 30 inclusive.

lastName

String

false

Last name.

Size must be between 1 and 30 inclusive.

ficaNumber

String

false

Approved FICA number.

Size must be between 1 and 15 inclusive.

idNumber

String

false

Identification number must be a valid SA ID number YYMMDDNNNNNNN.

Must match the regular expression \d{13}.

userId

String

true

System generated user id.

entitlements

Array[Object]

true

The user’s entitlements.

entitlements[].roleName

String

false

Role name.

Size must be between 1 and 255 inclusive.

entitlements[].id

String

true

Entitlement id.

Example request

GET /api/users/1234 HTTP/1.1
Agent-Id: 1729
Host: api.grindrodbank.co.za

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 306

{
  "username" : "johnsmith",
  "email" : "johnsmith@company.com",
  "phone" : "0123456789",
  "firstName" : "John",
  "lastName" : "Smith",
  "ficaNumber" : "F9876543",
  "idNumber" : "8906255579088",
  "userId" : "1234",
  "entitlements" : [ {
    "roleName" : "create_account",
    "id" : "1234"
  } ]
}

Validation and Verification

We offer validation endpoints which ensure that the data you send us is correct and valid.

Validate Account Number

Authentication is required.

POST /api/validate/accountnumber

The Account Validation Service allows you to check that an account is correctly formed and matches the account number formulation rules for most banks in South Africa.
This process is also known as a CDV (Check Digit Verification) check.
You can request a CDV on a provided bank account number, branch code and account type
This happens in real-time and the results will assist in the screening process of a client’s account details.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Request fields

Path Type Optional Description

accountId

String

false

Account number to validate.

Must have at most 16 integral digits and 0 fractional digits.

accountType

String

false

Valid options are:
C: CURRENT
S: SAVINGS
T: TRANSMISSION
B: BOND ACCOUNT.

Size must be between 1 and 1 inclusive.

branchCode

String

false

Branch code.

Size must be between 1 and 6 inclusive.

Response fields

Path Type Optional Description

result

String

false

Must be one of [VALID, INVALID].

description

String

true

Error description for INVALID outcome.

Example request

POST /api/validate/accountnumber HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 82

{
  "accountId" : "0123456700",
  "accountType" : "C",
  "branchCode" : "584000"
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 24

{
  "result" : "VALID"
}

Account Verification

Authentication is required.

POST /api/verifications/account

Our AVS endpoint allow users to verify account and client information.

Request headers

Header Type Optional Description

Agent-Id

String

false

Agent identifier.

Request fields

Path Type Optional Description

customer

Object

true

customer.idNumber

String

true

This field contains the customer ID number, Company registration number (without the ‘/’), Passport number or Trust Number.

Size must be between 1 and 13 inclusive.

customer.initials

String

true

Customer initials to be checked.

Size must be between 0 and 255 inclusive.

customer.name

String

true

Customer Surname or Entity name to be checked.

Size must be between 0 and 255 inclusive.

customer.email

String

true

Customer email address to be checked.

Must be a well-formed email address.

customer.mobileNumber

String

true

Customer mobile number to be checked.

Size must be between 0 and 255 inclusive.

account

Object

false

account.branchCode

String

false

Customer account branch code.

Size must be between 6 and 6 inclusive.

account.accountNumber

Integer

false

Customer Account number.

account.accountType

String

true

Type of Account to be checked.

Must be one of [CURRENT, SAVINGS, TRANSMISSION, BOND, SUBSCRIPTION_SHARE, UNKNOWN].

accountChecks

Object

true

accountChecks.acceptsDebits

Boolean

true

Check if account can accept debits.

accountChecks.acceptsCredits

Boolean

true

Check if account can accept credits.

accountChecks.age

Boolean

true

Check account meets age requirements.

Response fields

Path Type Optional Description

respondingBank

String

true

Name of responding bank.

accountFound

String

true

Indicates if account has been found.

Must be one of [YES, NO, UNKNOWN].

accountOpen

String

true

Indicates if account is open.

Must be one of [YES, NO, UNKNOWN].

accountAge

String

true

Account Age Check Result.

Must be one of [YES, NO, UNKNOWN].

accountType

String

true

Indicates if account of specified type.

Must be one of [YES, NO, UNKNOWN].

accountAcceptsDebits

String

true

Indicates if account accepts debits.

Must be one of [YES, NO, UNKNOWN].

accountAcceptsCredits

String

true

Indicates if account accepts credits.

Must be one of [YES, NO, UNKNOWN].

customerID

String

true

Customer ID Check Result.

Must be one of [YES, NO, UNKNOWN].

customerInitials

String

true

Customer Initials Check Result.

Must be one of [YES, NO, UNKNOWN].

customerName

String

true

Customer Name Check Result.

Must be one of [YES, NO, UNKNOWN].

email

String

true

Customer eMail Check Result.

Must be one of [YES, NO, UNKNOWN].

mobile

String

true

Customer Mobile Number Check Result.

Must be one of [YES, NO, UNKNOWN].

reasonMessage

String

true

Indicates reason in case of failure.

Example request

POST /api/verifications/account HTTP/1.1
Content-Type: application/json;charset=UTF-8
Agent-Id: 1729
Host: api.grindrodbank.co.za
Content-Length: 404

{
  "customer" : {
    "idNumber" : "9405235555555",
    "initials" : "M",
    "name" : "Surname/EntityName",
    "email" : "CustomerEmail@Email.com",
    "mobileNumber" : "0795555555"
  },
  "account" : {
    "branchCode" : "520001",
    "accountNumber" : 246813579,
    "accountType" : "CURRENT"
  },
  "accountChecks" : {
    "acceptsDebits" : true,
    "acceptsCredits" : true,
    "age" : true
  }
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 328

{
  "respondingBank" : "GRINDROD BANK",
  "accountFound" : "YES",
  "accountOpen" : "YES",
  "accountAge" : "YES",
  "accountType" : "YES",
  "accountAcceptsDebits" : "YES",
  "accountAcceptsCredits" : "YES",
  "customerID" : "YES",
  "customerInitials" : "YES",
  "customerName" : "YES",
  "email" : "YES",
  "mobile" : "YES"
}