Statement of Confidentiality Disclaimer Overview Testing ... API - Guide V1.0.pdf · Statement of Confidentiality The recipient of this document agrees to keep this document confidential

PAYACCSYS SERVICES (PTY) LTD HEAD OFFICE Unit 59, The Sanctuary, 10 Niblick Way, Somerset West, 7130 - Tel 010 593 4800 Fax +27 86 455 2400 [email protected] www.payaccsys.co.za REGISTRATION NUMBER 2000/026575/07

Statement of Confidentiality The recipient of this document agrees to keep this document confidential and not to use its contents

in any form or by any means without permission from PayAccSys Services Ltd. Moreover, the

recipient agrees not to place this document at the disposal of any third party without permission

from PayAccSys. If such permission is granted, it will be subject to the condition that the recipient

ensures that any third party recipient of this document, or of information contained therein, is held

responsible to PayAccSys Services Ltd for the confidentiality of that document or information.

Disclaimer The material and information contained on this guide is for general information purposes only.

Whilst we endeavour to keep the information in this guide up to date and correct, PayAccSys

Services Ltd makes no representations or warranties of any kind, express or implied about the

completeness, accuracy, reliability, suitability or availability with respect to the guide or the

information, products, services or related graphics contained in the guide for any purpose. Any

reliance you place on such material or information is therefore strictly at your own risk.

Overview The PayAccSys web API allows clients access to the basic payment functions provided on the

platform. The API is RESTful and JSON-based. The API is accessed over the secure HTTPS protocol.

The full specification for the API can be found at https://api.payaccsys.com/help

Testing and Live Calls The API contains methods with a MOCK postfix which indicates they are for testing purposes. These

methods do not communicate with the PayAccSys backend and will retrieve preset data on GET calls.

These methods can be used for instance to see if the calls to the API are successful and too validate

the formatting of the payload. Predefined test credentials (username test and password test) are

used to authenticate and access these methods.

The other methods which are all calls to the LIVE system will require the credentials of a valid client

user account with permissions to the API for authentication.

In this guide we will be looking at the functionality of the LIVE API methods.

Testing and Live Environments The PayAccSys API is available and running online on both testing and live environments. During the

testing phase we recommended developers use the test environment to test their LIVE API calls so

as to not be concerned about inadvertently creating data in the live system. Bear in mind that no

payment and fund matching will occur on the testing environment, so the status on batches

submitted will not progress past the InProgress phase in that environment. Additionally, when you

are issued with your API access credentials, you will be informed for which environment(s) they are

valid.

LIVE URL: https://api.payaccsys.com (Availability : 24 / 7)

TESTING URL: http://uat.payaccsys.com:8443 (Availability : 10:00 – 16:00)

http://www.payaccsys.co.za/

https://api.payaccsys.com/help

https://api.payaccsys.com/

http://uat.payaccsys.com:8443/


Sample Data For this guide we will use the following test data below as our example for the rest of the guide.

PAYEES:

Name : Roland Deschain

Account Number : 4063812494

Branch Code : 632005

Amount : 413.50

Name : Wade Watts



Amount : 14 550.21

Name : Jack Torrance



Amount : 7 134.76

Name : John Carmack



Amount : 44 000.00

Name : Joe Dever



Amount : 26 544.33

Batch Payment Services The PaymentType field in your batch creation will indicate the service payment type you would like

to use for your batch. Below are the payment service types offered with their description (For more

information regarding the pricing on each service, please contact your PayAccSys representative).

OneDay : Payments made through this service will clear to destination accounts on 00:00 on

the specified action date (aka payment date). Therefore the action date for this service can

only be a date from tomorrow onwards. No Public holidays or Sundays are allowed as an

action date.

SSVS : Payments made through this service will clear to destination accounts between 19:00

and 20:00 on the specified action. The action date for this service can be from today

onwards. No Public holidays or Sundays are allowed as an action date.

RTC : Real time clearance payments are processed in real time through the banks. Allowable

action dates are from today’s date onwards. Payments will clear to destination accounts at

the latest between 30 minutes and one hour from the moment the funds have been

received in our bank accounts. No Public holidays or Sundays are allowed as an action date.



Hash Value Calculation The batch field data in your payment and validation submissions will contain a HashValue field which

is a hash calculation on all the transactions that make up that batch. It is calculated as follows:

The transaction amount multiplied by 100 and then multiplied by the integer value of the

account number.

These values are then summed up for each transaction line

The total of previous step is added to the Total Amount of all transactions multiplied by 100.

The hash value is the 12 least significant digits of previous step (If less than 12 digits, pad

with zeroes).

So the hash value calculation for our Sample Data would be:

(413.50 * 100 * 4063812494) = 168038646626900

(14550.21 * 100 * 62031349758) = 90256916556234918

(7134.76 * 100 * 52265587) = 37290241950412

(44000.00 * 100 * 1648049621) = 7251418332400000

(26544.33 * 100 * 9254259749) = 24564812468317317

168038646626900 + 90256916556234918 + 37290241950412 + 7251418332400000 +

24564812468317317 = 122278476245529547

122278476245529547 + [(413.50 + 14550.21 + 7134.76 + 44000.00 + 26544.33) *

100] = (122278476245529547 + 9264280) = 122278476254793827

122278476254793827

Hash Value = 476254793827

Authentication The API uses basic access authentication. This is done by populating the Authorization field in the

header when making calls.

The Authorization field is constructed as follows:

The username and password are combined with a single colon. (:)

The resulting string is encoded to Base64.

The authorization method and a space is then prepended to the encoded string, separated

with a space (e.g. "Basic ").

You can use the following online link to assist in converting the string to the necessary Base64

encoding : https://www.base64encode.org/

When making calls to the Mock API methods, use the username test and password test. This would

equate to the header 'Authorization: Basic dGVzdDp0ZXN0'


https://www.base64encode.org/


For calls to the LIVE API, you will encode the username and password provided to you by your

PayAccSys representative. Example:



So in this example above with username John and password pass123 you would use 'Authorization:

Basic Sm9objpwYXNzMTIzc' in your header.

Should authentication fail, the API will return 401 Unauthorized.

Validate This is used to validate the batch and the containing transactions. Amongst the checks performed

would be date compatibility with the service type, amount and record totals, hash value

calculation and check digit verification on the account and branch numbers. Please note that all

leading zeroes should be removed from numeric fields.

(Bank Account Types: 1=Current[default];2=Savings;3=Transmission;4=Bond;6=Subscription/Share)

(Current Date for Example API Calls : 28 SEPT 2017)

(BankBranchCode, BankAccountNumber, Amount,BankAccountHoldersName, Reference are required

fields on all transactions)

POST api/1/transactions/validate

https://api.payaccsys.com/api/1/transactions/validate

Header

Authorization: Basic Sm9objpwYXNzMTIzc

Content-Type: application/json


https://api.payaccsys.com/api/1/transactions/validate


Payload (Valid Data)

{ "ClientCode": "TEST1APIFN",

"ActionDate": "2017-09-28",

"PaymentType": "SSVS",

"TotalAmount": 92642.80,

"Records": 5,

"HashValue": "476254793827",

"TransactionRecords": [

{ "BankBranchCode": 632005,

"BankAccountNumber": 4063812494,

"Amount": 413.50,

"BankAccountHoldersName": "Roland Deschain",

"Reference": "MYTESTRECORD1",

"SupplierCode": "S123",

"EmailAddress": "[email protected]",

"BankAccountType": 1

},



"Amount": 14550.21,

"BankAccountHoldersName": "Wade Watts",


"SupplierCode": null,

"EmailAddress": null,


},



"Amount": 7134.76,

"BankAccountHoldersName": "Jack Torrance",





},



"Amount": 44000.00,

"BankAccountHoldersName": "John Carmack",





},



"Amount": 26544.33,

"BankAccountHoldersName": "Joe Dever",







}

]

}

Response (Valid)

200 OK

Payload (Invalid Data)

To demonstrate invalid response messages returned and how they relate to the payload data, some

data has been altered below (in red) to be incorrect.

{ "ClientCode": "TEST1APIFN",

"ActionDate": "2017-09-27",



"Records": 4,

"HashValue": "376254793827",




"Amount": -413.50,






},



"Amount": 14550.21,






},



"Amount": 7134.76,








},



"Amount": 44000.00,






},



"Amount": 26544.33,






}

]

}

Response (Invalid)

400 Bad Request

'ActionDate' invalid, 'Records' invalid, 'TotalAmount' invalid, 'HashValue' invalid, TransactionRecord 1 : 'Amount' invalid, TransactionRecord 5 : 'CDV' invalid"

From the errors introduced in the payload data, you can see from the response above that the

validation was rejected and the appropriate response descriptions returned pertaining to the

erroneous data. You will need to check your data against this validation method and once you get a

return status code of 200 OK your batch data is ready to be submitted to the system.

Validation Validation will perform the exact same validation checks as Validate above, but will return the next

Batch Number to be allocated. On a successful validation it will return 201 Created together with the

next generated Batch Number for the client. The created return status should not be confused with

an actual batch being created, but is only an indication that the next batch number was calculated

(“created”). Subsequent calls to this method without having submitted a batch should result in the

same batch number being generated until that batch number actually gets used in a submission.

POST api/1/transactions/validation

https://api.payaccsys.com/api/1/transactions/validation


https://api.payaccsys.com/api/1/transactions/validation


Header




[Same as Validate above]

Response (Valid)

201 Created

"TEST1APIFN000001"

Creating a Batch Once your data has passed validation you are then ready to submit your batch. With this step your

batch, together with its transactions, will get created and submitted to the Payaccsys backend.

POST api/1/transactions/transactions

https://api.payaccsys.com/api/1/transactions

Header




{

"TransactionCode": "TEST1APIFN000001",

"Reference": "TEST1APIFN000001",

"DepositReference": null,

"DepositBank": 0,

"ClientCode": "TEST1APIFN",

"ActionDate": "2017-09-28",



"Records": 5,

"HashValue": "476254793827",


{

"BankBranchCode": 632005,


"Amount": 413.50,






},

{



"Amount": 14550.21,


https://api.payaccsys.com/api/1/transactions







},

{



"Amount": 7134.76,






},

{



"Amount": 44000.00,






},

{



"Amount": 26544.33,






}

]

}

Response (Valid)

201 Created

{

"Id": 280099,



"DepositReference": "TEST1APIFN",

"DepositBank": 0,


"ActionDate": "2017-09-28T00:00:00",



"Records": 5,

"HashValue": null,




{

"Id": 20549568,



"Amount": 413.5,





"BankAccountType": "1",

"Status": "0"

}

,

{

"Id": 20549569,



"Amount": 14550.21,






"Status": "0"

}

,

{

"Id": 20549570,



"Amount": 7134.76,






"Status": "0"

}

,

{

"Id": 20549571,



"Amount": 44000,






"Status": "0"

}

,

{

"Id": 20549572,





"Amount": 26544.33,






"Status": "0"

}

],

"CreationDate": "2017-09-28T00:00:00",

"FeesIncludingVat": 31.35,

"FeesExcludingVat": 27.5,

"TotalAmountWithFees": 92674.15,

"IsAuthorized": false,

"Status": "AuthorizationRequired"

}

As you can see, the system returned 201 Created, which means our batch was submitted and has

been created in the backend. Also notice the IDs for both the Batch and each individual transaction

have been returned. We have also received the total amount (batch amount + fees) needed to fund

and process this batch. Further take note that the current status of this batch is

“AuthorizationRequired”, which indicates that this batch will still need to be authorized by the client

before any further action will be taken by the system.

Batch Status Definitions

AuthorizationRequired : The Batch has been created and is now awaiting authorisation from the client’s side.

InProgress : The Batch has been authorized and submitted to the PayAccSys system. The system will now await the deposit of the client funds or use existing client funds to allocate to this batch to enable payment. Please ensure your funds reflect in our accounts before 15:00.

MatchedToFunds : Funds have been successfully allocated to the batch by the PayAccSys system.

Completed : The batch has been successfully submitted for processing to the banking systems from PayAccSys.

Cancelled : This indicated that the specific batch was cancelled from either PayAccSys or the client’s side.

Error : An error status on the would indicate that there was an error importing your batch data into the PayAccSys backend. Please contact your PayAccSys representative if this error persists or if the reason for the error should not be evident.

Authorization and Submission Authorization is required on each batch before it is released to be processed. This is introduced

where additional parties on the client’s side may need to review the details of the batch before the



final submission of the batch takes place. By using the Batch ID we received on batch creation, we

call the authorization method to authorise the batch for submission. The status of the batch will

change from AuthorizationRequired to InProgress. Once authorization is completed, your batch is

then submitted for processing.

PUT api/1/transactions/{id}/authorise

https://api.payaccsys.com/api/1/transactions/280099/authorise

Header



Response (Valid)

200 OK

{

"Id": 280099,




"DepositBank": 0,


"ActionDate": "2017-09-28T00:00:00",



"Records": 5,

"HashValue": null,


{

"Id": 20549568,



"Amount": 413.5,






"Status": "0"

}

,

{

"Id": 20549569,



"Amount": 14550.21,






"Status": "0"

}

,


https://api.payaccsys.com/api/1/transactions/280099/authorise


{

"Id": 20549570,



"Amount": 7134.76,






"Status": "0"

}

,

{

"Id": 20549571,



"Amount": 44000,






"Status": "0"

}

,

{

"Id": 20549572,



"Amount": 26544.33,






"Status": "0"

}

],

"CreationDate": "2017-09-28T00:00:00",




"IsAuthorized": true,

"Status": "InProgress"

}

Funding your Batch For your batch to be processed by us we will need the total deposit amount for the batch (total

batch amount plus total batch fees) to be deposited into any one of our PayAccSys banking accounts.

For single batch deposits please use the Batch Number as the Reference and for combined batch

deposits please use your Client Code. In our example this amount would be 92674.15 (92642.80 +

31.35) and our reference would be TEST1APIFN000001. All funds need to be deposited and have

cleared into our accounts before 15:00 for any batches to be processed that day. Any late deposits



after the cut-off time will not be able to be processed and will lead to the bumping of action dates

to the next available processing date if the batch was actioned for the current day on the SSVS and

RTC service or the following day on the OneDay service. Should you have any queries in regards to

funding or transfers please contact our PayAccSys admin team on 010 593 4800 for assistance.

Our bank account details are as follows (Please confirm details below with your representative

before making any initial payments) :

ABSA



FNB



Nedbank



Standard Bank



Query Batch We can get the current batch status of the batch using the relevant Batch Number. There is also an

upload status on each transaction where a 0 indicates a valid transaction and any non-zero value

would indicate an invalid transaction.

GET api/1/transactions?transactionCode={transactionCode}

https://api.payaccsys.com/api/1/transactions?transactioncode=TEST1APIFN000001

Header



Response (Valid)

200 OK

{

"Id": 280099,


"Reference": " TEST1APIFN000001",


"DepositBank": 0,


"ActionDate": "2017-09-28T00:00:00",



"Records": 5,

"HashValue": null,



http://localhost:56572/Help/Api/GET-api-1-transactions_transactionCode




{

"Id": 20549568,



"Amount": 413.5,






"Status": "0"

}

,

{

"Id": 20549569,



"Amount": 14550.21,






"Status": "0"

}

,

{

"Id": 20549570,



"Amount": 7134.76,






"Status": "0"

}

,

{

"Id": 20549571,



"Amount": 44000,






"Status": "0"

}

,

{

"Id": 20549572,





"Amount": 26544.33,






"Status": "0"

}

],

"CreationDate": "2017-09-28T00:00:00",




"IsAuthorized": true,

"Status": "MatchedToFunds"

}

Rejections After transactions are submitted and accepted by the banking systems, all payments are then

considered to be successful, except if at a later stage we are informed otherwise. What this means is

that if a rejection on a payment occurs (for example a frozen account, closed account, etc.), this

rejection feedback from the target bank only occurs after a period of time and not on submission. As

PayAccSys receives this information, our backend will be updated with the rejection data. Although

the period from sending the transaction to receiving the rejection information usually takes between

1 and 3 business days, there have been rare instances where this period was up to 20 business days.

Considering this, developers might want to consider running a rejection query once again after the

initial rejection checks have been done to reconcile any possible late stage rejections. We can return

all rejections that have occurred on a specific batch by quering the API using the Batch Number.

Unfortunately at this stage the rejection data received does not link the transactionid back directly

to the original id. We therefore urge developers to use unique reference data in either the reference

or suppliercode fields to automatically link back the rejection to the original transaction.

GET api/1/rejections?transactionCode={transactionCode}

https://api.payaccsys.com/ api/1/rejections?transactionCode=TEST1APIFN000001

Header



Response (Valid)

200 OK

{

"Id": 79345,

"TransactionId": 0,



"Amount": 44000,




https://api.payaccsys.com/%20api/1/rejections?transactionCode=TEST1APIFN000001

https://api.payaccsys.com/%20api/1/rejections?transactionCode=TEST1APIFN000001


"DateRefunded": "2017-09-30T00:00:00",

"UnpaidReason": "NO SUCH ACCOUNT",

"SupplierCode": ""

}

As we can see from the response above, one of the transactions in our batch was rejected and the

reason was that the account did not exist at the target bank. The Id field is the unique reference for

the rejection and as stated above the TransactionId does not link back to our original transaction Id

and is therefore 0. We can also see that the funds have been refunded to the client by PayAccSys on

the 30th.


Documents

Statement of Confidentiality Disclaimer Overview Testing ... API - Guide V1.0.pdf · Statement of Confidentiality The recipient of this document agrees to keep this document confidential