Getting started

Endpoint

{server}/api/payments/v2/

The {server} URL is the same as your portal login. Append each function name to the endpoint — for example {server}/api/payments/v2/loadPayments.

Content types

The API accepts both URL-encoded and JSON content type posts. All responses are JSON.

Authentication

Every call requires a signed JSON Web Token. The token payload comprises:

Claim	Description
apiKey	Provided by customer support
accessToken	Provided by customer support
jti	A unique JWT ID — must differ on every call
iat	Issued-at time
exp	Expiry time — a future time after which the token is no longer valid

{
  "apiKey": "{PROVIDED API KEY}",
  "accessToken": "{PROVIDED ACCESS TOKEN}",
  "jti": "{UNIQUE VALUE}",
  "iat": 1589990902,
  "exp": 1589991502
}

Sign the token with the secret configured against your console login. Any HMAC algorithm may be used. For libraries in your language, see jwt.io.

Where credentials are configured

Your API key and access tokens are in the console under Setup → General Settings → API Settings, or may be requested from customer support.

The same screen sets your JWT secret, origin domain or IP, post-back URL and post-back content type, selected against the corresponding token. These may also be sent to customer support for updating.

Lock the origin before going live

Once testing is complete the calling origin should be locked in, to prevent API calls from unauthorised origins or IP addresses. Specify your origin as part of your HTTP header; if it is not set, your server IP can be used.

Field conventions

Every field table in this reference uses the following markers:

Marker	Meaning
Y	Compulsory
O	Optional
CY	Conditional — required in the circumstances stated in the description

Testing

addSuppliers accepts a test boolean. When set to true, billing is bypassed and the call only validates the test data.

Errors

Where a submission fails on authentication or a missing field, the response contains:

Field	Description
status	Error
error	The error message

{
  "status": "Error",
  "error": "Token secret verify fail"
}

Errors relating to individual records within an otherwise valid submission are returned per record, in the status and message fields of that record, rather than as a top-level error.

Known issues in the source guide

The following discrepancies exist in the API guide as issued. They are recorded here so that integrators verify against live behaviour rather than assume, and so that they can be corrected at source.

Where	Issue
cancelPayments, cancelBatches — post fields	The first field is listed as supplier Code with the description "The signed JWT". This appears to be token
listBankOptions — response	bankOptions is typed Decimal; the description says "1-n of banks and branches", which indicates an array
listBankOptions, listSupplierTypes — response	status is described as "List of Account Types"
listPaymentTypes — response	status is described as "Number of payments cancelled out of the number of requests submitted"
loadPayments — post fields	payments is typed Text and marked optional, though it carries the payment array
addSuppliers — example	The example uses cell and email; the field table specifies cellNumber and emailAddress
addSuppliers — example	The second supplier object is missing a comma after branchCode, and includes contactName and contactLastName, which do not appear in the field table
listSuppliers — example response	Uses idType, idNumber, type, cellphone and email, where the field table specifies identificationType, identificationNumber, supplierType, cellNumber and emailAddress
loadBatch — example response	custom and product keys are enclosed in typographic quotation marks, which is not valid JSON
Participating bank tables	Standard Bank's universal branch code is given as 51001 in the real-time clearance table and 051001 in the PayShap table

Where a field table and an example disagree, the field table is the more likely to be correct, but confirm with customer support before relying on either.