Develop

  • 1
    Merchant
    Post
  • 2
    i-Pay
    Response
  • 3
    API
    Status

Merchant Post

Step 1 – Post From Merchant Website

After the user confirms his purchase and has chosen i-Pay as his preferred payment method, you will need to post the following variables to https://i-pay.co.za/Payment

Post Variables

PROPERTY TYPE REQUIRED DESCRIPTION
1. SiteCode String (50) Yes A unique code for the site currently in use. A site code is generated when adding a site in the i-Pay Merchant Admin section.
2. CountryCode String (2) Yes The ISO 3166-1 alpha-2 code for the user's country. The country code will determine which banks will be displayed to the customer. Please note only South African (ZA) banks are currently supported by i-Pay.
3. CurrencyCode String (3) Yes The ISO 4217 3 letter code for the transaction currency. Please note only South African Rand (ZAR) is currently supported by i-Pay, so any currency conversion would have to take place before posting to the i-Pay site.
4. Amount Decimal (9,2) Yes The transaction amount. The amount is in the currency specified by the currency code posted.
5. TransactionReference String (50) Yes The merchant's reference for the transaction
6. BankReference String (20) Yes The reference that will be prepopulated in the "their reference" field in the customers online banking site. This will be the payment reference that appears on your transaction history.
7. Optional1
8. Optional2
9. Optional3
10. Optional4
11. Optional5
String (50) No Optional fields the merchant can post for additional information they would need passed back in the response. These are also stored with the transaction details by i-Pay and can be useful for filtering transactions in the merchant admin section.
12. Customer String (100) No The customers name or identifier.
13. CancelUrl String (150) No The Url that we should post the redirect result to if the customer cancels the payment, this will also be the page the customer gets redirect back to. This Url can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if the payment is cancelled.
14. ErrorUrl String (150) No
The Url that we should post the redirect result to if an error occurred while trying to process the payment, this will also be the page the customer gets redirect back to. This Url can also be set for the applicable merchant site in the merchant admin section. . If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if an error occurred while processing the payment.
15. SuccessUrl String (150) No The Url that we should post the redirect result to if the payment was successful, this will also be the page the customer gets redirect back to. This Url can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the posted value will be redirected to if the payment was successful. Please note that it would not be sufficient to assume the payment was successful just because the customer was redirected back to this page, it highly recommended that you check the response fields and as well as check the transaction status using our check transaction status API call.
16. NotifyUrl String (150) No The Url that we should post the notification result to. The result will posted regardless of the outcome of the transaction. This Url can also be set for the applicable merchant site in the merchant admin section. If a value is set in the merchant admin and sent in the post, the notification result will be sent to the posted value. Find out more in the notification response section in step 2.
17. IsTest bool Yes Send true to test your request posting and response handling. If set to true you will be redirected to a page where you can select whether you would like a successful or unsuccessful redirect response sent back. Please note that notification responses are not sent for test transactions and the online banking payment is skipped. Accepted values are true or false.
HashCheck String (250) Yes SHA512 hash used to ensure that certain fields in the message have not been already after the hash was generated. Check the generate hash section below for more details on how to generate the hash.

Generate Post Hash Check

Follow these steps to generate the hash check:

  1. Concatenate the post variables (excluding HashCheck) in the order they appear in the post variables table
  2. Append your secret key to the concatenated string. Your secret key can be found in merchant details section of the merchant admin site.
  3. Covert the concatenated string to lowercase.
  4. Generate a SHA512 hash of the lowercase concatenated string.

i-Pay Response

Step 2 – Process I-Pay Response

i-Pay will send the following two posts back to the merchant:

Redirect Response

Depending on the status of completing the payment using i-Pay, we will post the response variables while redirect the user to the applicable page. Please note that if the applicable Url was not sent in the post variables or set for the merchant site in the merchant admin site, the user will not be redirected back to the merchant site along with the post containitusng the response variables.

The Url used will be determined as follows:

  • Error Url – An error occurred during the payment process and payment was NOT successful
  • Cancelled Url – The user opted to cancel during the payment process and payment was NOT successful
  • Success Url – The payment was successful

Use the Hash response variable to verify the validity of the response, this process is further described in the response hash check section below. It is recommended that you also use the notification response to verify the outcome of the transaction

Notification Response

We will post the response variables to the designated notification Url. Please note that if the notification Url (NotifyUrl) was not sent in the post variables or set for the merchant site in the merchant admin site, we will not be able to send the notification post containing the response variables.

Use the Hash response variable to verify the validity of the response, this process is further described in the response hash check section below.

Response Variables

PROPERTY TYPE DESCRIPTION
1. SiteCode String (50) The site code sent to i-Pay in the request post.
2. TransactionId String (50) The transaction identifier generated by i-Pay
3. TransactionReference String (50) The merchant's transaction reference sent in the request post's TransactionReference variable.
4. Amount Decimal (9,2) The transaction amount. The amount is in the currency specified by the currency code posted.
5. Status String (50) The transaction status. Possible values are:

  • Complete - The payment was successful

  • Cancelled - The payment was cancelled

  • Error - An error occurred while processing the payment
6. Optional1
7. Optional2
8. Optional3
9. Optional4
10. Optional5
String (50) Optional fields sent in the request post.
11. CurrencyCode String (3) The transaction currency code sent in the request post.
12. IsTest bool Whether or not the original request was a test request. Possible values are true or false.
13. StatusMessage String (150) Message regarding the status of the transaction. This field will not always have a value.
Hash String (100) SHA512 hash used to ensure that certain fields in the message have not been already after the hash was generated. Check the generate hash section below for more details on how to validate the response variables using the hash.

Response Hash Check

Follow these steps to validate the response:

  1. Concatenate the response variables (excluding Hash) in the order they appear in the post variables table
  2. Append your secret key to the concatenated string. Your secret key can be found in merchant details section of the merchant admin site.
  3. Covert the concatenated string to lowercase.
  4. Generate a SHA512 hash of the lowercase concatenated string.
  5. Compare generated hash to the Hash value in the response variables.

API Status

Step 3 – Check Transaction Status Using API

Even though this step is optional, we highly recommend it to ensure that responses received reflect the correct transaction status. This will eradicate any chance of anyone spoofing the i-Pay response to update a transaction status on the merchant site.

Each API call needs an http header value with the merchant’s API Key

There are two API methods you can use to check the transaction status currently:

GetTransactionByReference

https://i-pay.co.za/api/MerchantApiV1/GetTransactionByReference?siteCode={siteCode}&transactionReference={transactionReference}

This method is called when you want to query transactions using the merchant’s reference. This method can return multiple results as i-Pay does not restrict the merchant from sending duplicate merchant references even though we do advise that a unique reference is sent per transaction. The number of results returned are limited to 10.

Parameters

PROPERTY TYPE REQUIRED REQUIRED
ApiKey
(Http request header value)
String (50) Yes
Merchant's API key, this value is available in the i-Pay Merchant Admin section.
Accept
(Http request header value)
String (50) Yes Determines the format the response is returned in, available values:
application/json - Response is returned as json
application/xml - Response is returned as xml
SiteCode String (50) Yes A unique code for the each of the merchant's sites. A site code is generated when adding a site in the i-Pay Merchant Admin section.
TransactionReference String (50) Yes The merchant's reference for the transaction
IsTest bool No Defaults to false. Use true only to get results for test requests.

 

Response

Transaction[] – A successful call will return an array of the transaction object. The transaction object is described further down.

GetTransaction

https://i-pay.co.za/api/MerchantApiV1/GetTransaction?siteCode={siteCode}&transactionId={transactionId}

This method is called when you want to query transactions using i-Pay’s reference.

Parameters
PROPERTY TYPE REQUIRED DESCRIPTION
ApiKey
(Http request header value)
String (50) Yes Merchant's API key, this value is available in the i-Pay Merchant Admin section.
Accept
(Http request header value)
String (50) Yes Determines the format the response is returned in, available values:
application/json - Response is returned as json
application/xml - Response is returned as xml
SiteCode String (50) Yes A unique code for the each of the merchant's sites. A site code is generated when adding a site in the i-Pay Merchant Admin section.
TransactionId String (50) Yes i-Pay's reference for the transaction. This would be passed back to the merchant in the redirect and notification responses.
Response

Transaction – A successful call will return a single transaction object. The transaction object is described further down.

Transaction Object

This is the object referred to in the response of the 2 API calls above.

PROPERTY TYPE DESCRIPTION
TransactionId String (50) i-Pay's unique reference for the transaction.
MerchantCode String (50) Unique code assigned to each merchant.
SiteCode String (50) Unique code assigned to each merchant site.
TransactionReference String (50) Merchant's transaction reference.
CurrencyCode String (3) The transaction currency code
Amount Decimal (9,2) The transaction amount.
Status String (50) The transaction status. Possible values are:
Complete - The payment was successful
Cancelled - The payment was cancelled
Error - An error occurred while processing the payment
StatusMessage String (150) Message regarding the status of the transaction. This field will not always have a value.
CreatedDate DateTime Transaction created date and time
PaymentDate DateTime Transaction payment date and time

The convenience of making cashless payments via
PC, SMS, Email, QR or Push Payment methods.