Suppliers

A supplier is a beneficiary, vendor or payee. Preloading suppliers lets you pay with only a supplier code, amount, date and reference — the payment processes against banking details already stored.

Every supplier is identified by a system-generated supplier code: six alphanumeric characters in the form AAA000.

Store the supplier code against your unique reference. When a supplier code is returned, link it in your database to the unique reference you sent. This prevents a later updateSuppliers call from updating the wrong supplier, and prevents duplicate suppliers being created by loadBatch.

---

addSuppliers

POST {server}/api/payments/v2/addSuppliers

Preloads suppliers so that payments can later be made with loadPayments. This step may be skipped by going directly to loadBatch, which creates suppliers from the payment data.

Skipping it does not prevent later use of the Account Verification Service, but the compulsory AVS fields will then need to be completed manually or through updateSuppliers.

Post fields

Name	Type	Required	Description
token	Text	Y	The signed JWT
test	Boolean	O	Set true when testing. Bypasses billing and only validates the test data
suppliers	Array	Y	1–n of supplier data

Supplier fields

Name	Type	Required	Description
uniqueReference	Text	Y	Your unique customer reference identifier
supplierType	Text	Y	Identifies the supplier — see listSupplierTypes
name	Text	Y	First name of the account holder where the supplier type is Individual; otherwise the entity name
lastName	Text	CY	Surname of the account holder. Required where supplier type is Individual
group	Text	O	Name of a group to assign the supplier to
cellNumber	Text	O	The supplier's cellphone number
emailAddress	Text	O	The supplier's email address, for payment advice
vatNo	Text	O	The supplier's VAT number
addressLine1 … addressLine4	Text	O	Supplier address
town	Text	O	Supplier address
postalCode	Text	O	Supplier address
paymentType	Text	Y	EFT, Debit Order or Cash — see listPaymentTypes
identificationType	Text	CY	SID South African ID · SPP passport number · SBR business registration number · TRN trust number. Required where payment type is EFT
identificationNumber	Text	CY	The account holder's identity, passport, company registration or trust number. Required where payment type is EFT
bank	Text	CY	The bank the account is held at — see listBankOptions. Required where payment type is EFT
accountType	Text	CY	See listAccountTypes. Required where payment type is EFT
accountNumber	Text	CY	Required where payment type is EFT
branchCode	Text	CY	Required where payment type is EFT
branchName	Text	O	The branch name

Do not duplicate or reuse unique references. Reusing a unique reference can cause a later update to be applied to the wrong supplier.

Response

Name	Type	Required	Description
jti	Text	Y	The unique JWT ID
status	Text	Y	Number of suppliers imported
suppliers	Array	Y	1–n of supplier results

Per supplier:

Name	Type	Required	Description
uniqueReference	Text	Y	Your unique customer reference identifier
status	Text	Y	Success or Failed
message	Text	O	Failure reason, where status is Failed
supplierCode	Text	N	Returned where the status is Success, or where a supplier already exists. Alphanumeric, format AAA000

Example

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "suppliers": [
    {
      "uniqueReference": "Ref1",
      "supplierType": "Individual",
      "name": "Joe",
      "lastName": "Soap",
      "group": "Test",
      "cellNumber": "0823456789",
      "emailAddress": "joesoap@example.com",
      "addressLine1": "21 Jump Street",
      "addressLine2": "Newlands",
      "town": "Cape Town",
      "postalCode": "7979",
      "paymentType": "EFT",
      "identificationType": "SID",
      "identificationNumber": "7410025102082",
      "bank": "Standard Bank",
      "accountType": "Cheque",
      "accountNumber": "700000000",
      "branchCode": "051001"
    }
  ]
}

{
  "jti": "{UNIQUE VALUE}",
  "status": "1 of 2 suppliers imported",
  "suppliers": [
    { "reference": "Ref1", "status": "Success", "supplierCode": "JOE002" },
    {
      "reference": "Ref2",
      "status": "Failed",
      "message": "Unique reference already exists",
      "supplierCode": "RON001"
    }
  ]
}

The response example returns reference where the field table specifies uniqueReference — see known issues.

---

updateSuppliers

POST {server}/api/payments/v2/updateSuppliers

Only the supplier code is required. Any additional field provided will be updated.

Post fields

Name	Type	Required	Description
token	Text	Y	The signed JWT
suppliers	Array	Y	1–n of account data

Supplier fields

supplierCode is required. The remaining fields are as for addSuppliers, and only those supplied are changed.

Name	Type	Required	Description
supplierCode	Text	Y	The system's six-character alphanumeric supplier code
uniqueReference	Text	Y	Your unique customer reference identifier
supplierType	Text	Y	See listSupplierTypes
name	Text	Y	As for addSuppliers
lastName	Text	CY	Required where supplier type is Individual
group, cellNumber, emailAddress, vatNo, address fields, branchName	Text	O	As for addSuppliers
paymentType	Text	Y	EFT, Debit Order or Cash
identificationType, identificationNumber, bank, accountType, accountNumber, branchCode	Text	CY	Required where payment type is EFT

Do not change, duplicate or reuse unique references when updating. Doing so may result in the wrong supplier's data being updated.

Response

Name	Type	Required	Description
jti	Text	Y	The unique JWT ID
status	Text	Y	Processed
suppliers	Array	Y	1–n of status results

Per supplier: supplierCode, status (Success or Failed), and message where failed.

---

listSuppliers

POST {server}/api/payments/v2/listSuppliers

Returns stored supplier details. Supplying supplierCodes restricts the result to those suppliers.

Post fields

Name	Type	Required	Description
token	Text	Y	The signed JWT
supplierCodes	Array	O	Array of six-character alphanumeric supplier codes

Result fields

Name	Type	Required	Description
supplierCode	Text	Y	The system's six-character alphanumeric supplier code
supplierType	Text	Y	Identifies the supplier
name	Text	Y	First name where the supplier type is Individual; otherwise the entity name
lastName	Text	CY	Surname, where supplier type is Individual
uniqueReference	Text	Y	Your unique customer reference identifier
group	Text	O	The assigned group
identificationType	Text	CY	The supplier identification type
identificationNumber	Text	CY	The supplier identity number
cellNumber	Text	O	The supplier's cellphone number
emailAddress	Text	O	The supplier's email address for payment advice
vatNo	Text	O	VAT number
addressLine1 … addressLine4, town, postalCode	Text	O	Supplier address
paymentType	Text	Y	Supplier payment type
bank, accountType, accountNumber, branchCode	Text	CY	Banking details
branchName	Text	O	The branch name
message	Text	O	Returned for invalid supplier codes

Example

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "supplierCodes": ["ABC001", "ABC002", "ABC003"]
}

A supplier code that does not exist is returned with a message of Does not exist rather than causing the call to fail.