Currently set to Index
Currently set to Follow

Overview

Netcash – Pay Now eCommerce is a secure online payment service that can be integrated into various applications to receive payments. It is currently being used for online stores, quotations, statements, and invoices to receive payment. We currently offer 3D secure Credit Card payments through Mastercard, Visacard, American Express, and Diners Club*, instant EFT powered by iPay, bank EFT, cash payments powered by SCode, -and Masterpass. Additional payment options will be extended over time, but no further development will be required by yourself.

*Please note American Express / Diners Club available only on special request and by approval.

Also see:

See the service overview here.

Suggested Integration Process Flow


We highly recommend that you download the suggested API integration process flow document and keep it on hand while you develop.

Kindly adhere to the Netcash brand guidelines when developing.

Web Service Methods

The list of Netcash web service methods can be found here

QuickStart Guides

We have developed some Quick Start Guides to help you understand this service and to help you get started.

Programmers Guide

To start, refer our Programmers guide for more detail on how to apply the required methodology in this document.
Please ensure that the settings for Developers are correctly set before you proceed with the implementation below specification.

Service set up process

IMPORTANT: Do not process the form post in an iFrame -or embedded into any other page/system source; as certain services will not process unless opened in a parent window due to banking regulations -and/or security protocols.

Credit Card transaction processing notice

Please take note that any new Pay Now eCommerce service has a default transaction limit of R100.00. If the transaction limit (ZAR value) is exceeded – Credit Card payment options will not display. Contact your Netcash Payments Advisor for assistance.

The payment methods available on the Pay Now service is available here or see the visual representation here.

Read more about the different payment methods we offer.

Pay Now service key

The service key is used to authenticate access to the Pay Now service. It identifies the origin of the payment instruction. The service key determines the Netcash account to which the proceeds of the payment will be credited and what payment options are available to your customer/s.

NetConnector

Your NetConnector profile setting allows you to customize the Pay Now service according to your requirements:

  • Active: Indicates the service setting.
  • Email: This is the email address to which any errors in processing will be directed. It is also the address to which the service key will be sent. Notifications of transactions will also be sent to this address.
  • Service Key: This is the unique service key (field m1) which must be included in the POST to the Netcash URL.
  • Allow Master and Visa payments: This option is used to control whether your client may pay by credit card.
  • Accept url: Enter your accept URL here. If the URL changes for any reason, it can be updated on this page. This is the URL that the browser is sent to if the transaction is successful.
  • Decline url: Enter your decline URL here. If the URL changes for any reason, it can be updated on this page. This is the URL that the browser is sent to if the transaction is declined.
  • Notify url: This is the URL that Netcash will call for all transactions to indicate payment status. It is also used for offline transactions such as bank EFT and retail payments where the payment is not able to be captured in real time. These payments will be picked up when they are made and Netcash will notify your system through this URL.
  • Redirect url: This is the URL that the browser is sent to once the complete button is clicked on the EFT and Retail payment screens on Netcash. This could/would return the customer to your site while you are waiting for a payment to be made.
  • Make test mode active: use this setting while you are testing the system to simulate transactions. Once your development is complete, this box should be un-ticked
  • In TEST MODE use the following credit card numbers to test with:
Visa Successful
Visa Card Number 4000000000000002
Expiry Date Any future date (MMYY)
CVC/CVV/CVD 123
MasterCard Successful
Master Card Number 5200000000000015
Expiry Date Any future date (MMYY)
CVC/CVV/CVD 123
Visa Failed
Visa Card Number 4000000000000036
Expiry Date Any future date (MMYY)
CVC/CVV/CVD 123
MasterCard Failed
Master Card Number 5200000000000049
Expiry Date Any future date (MMYY)
CVC/CVV/CVD 123

Configure Netcash – Pay Now service key variables:

Select ACCOUNT PROFILE -> NetConnector -> PAY NOW in your Netcash merchant account to configure your Netcash – Pay Now variables.

Pre-defined postback URLs


The Pay Now configuration allows the configuration of pre-defined postback URL groups.

These postback URLs perform two (2) functions namely:

  1. They send data back to the host system about the transaction, especially useful for real-time notifications/allocation of credits.
    1. Once the transaction is processed, the status and the transactional data of the payment gets redirected to two pages:
      1. The Notify URL always receives all the transaction data but it is not client-facing -and
      2. The Accept -or Decline URL depending on the transaction status which;
  2. The Accept -or Decline URL redirects the person making the payment, to a visual display of the transaction status once the transaction is completed.

You will note a Redirect URL in the list as well. This URL is used for when the user click’s the CANCEL PAYMENT button on the payment page -or when the user selects a non-real-time payment; to remind the user of i.e. the payment reference to use.

Netcash offers several payment options which the user can enable/disable in the Pay Now configuration.

Read more about pre-defined postback URL groups here.

You will note that the URLs, in this case, were set up by the merchant as to where the notifications post the processing of the transaction, should be sent.

Pre-defined URLs not set

Netcash also has a facility whereby the merchant can select from a dropdown menu, rather than the input (possibly incorrectly) a pre-defined set of URLs, which has been pre-set by Netcash as defined by the ISV. This will minimize the risk of incorrect postbacks. It is only applicable if the ISV software allows for, and uses the same URLs for all its installations at all the merchants – where a central server handles the postbacks and sends the responses to the various installations.

Pre-defined URL selection

In such a case, Netcash will send the responses to the centralized server and the merchant simply selects the software from the drop-down list and Netcash handles the postback of data

Pre-defined URL selected

POST to the Pay Now page:

See the recommended implementation methodology here.
These parameters are required by the Pay Now system when submitting a transaction. Although data is not mandatory for all the fields; all the fields must be passed in the form post.

Field No: Field Name: Length: Alpha / Numeric Data Mandatory Description:
1 m1 36 AN Yes Pay Now service key.
2 m2 36 AN Yes The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)
3 p2 25 AN Yes This is a unique reference that you will assign to each transaction. This reference should only ever be USED ONCE.
4 p3* 50 AN Yes The description of the goods sent for payment for your internal reference.
(** see tip below)
5 p4 6.2 N Yes Transactional amount that is to be settled to the card. Amount must be in South African Rand (ZAR)
6 Budget 1 AN Yes Y/N
7 m4** 999 AN No This is an extra field that can contain any data that you require back once the settlement has been done.
(** see tip below)
8 m5 50 AN No This is an extra field that can contain any data that you require back once the settlement has been done.
9 m6 50 AN No This is an extra field that can contain any data that you require back once the settlement has been done.
10 m9 100 AN No Card holders email address should you want an email sent to the cardholder.
11 m11 10 N No Card holders mobile number.ie. 0812345678
12 m10 100 AN No Any text sent in this parameter is returned to the Accept and Decline return URL’s. This is usually used with basket products like OSCommerce and VirtueMart.
13 ! m14 1 N No Tokenize Credit Card
0 = do NOT return credit card token
1 = return credit card token
14 m15 36 AN No Credit card token for subscription cards
15 m16 1 N No Subscription indicator
0 = No
1 = Yes
16 m17 2 N No Number of cycles for a subscription payment
17 m18 1 N No Subscription frequency
1 = Monthly
2 = Weekly
3 = Bi-weekly
4 = Quarterly
5 = Six monthly
6 = Annually
18 m19 8 N No Subscription start date
CCYYMMDD
19 m20 N No Subscription recurring amount
Can differ from initiating 3D Secure  payment

The Netcash system will authenticate the Pay Now service key in field m1.
Only if the key is authenticated, will the payer be directed to the payment method selection page.

Tokenization will not occur if the Pay Now profile is set to TEST MODE active

TIPS

  • * Add the purchaser’s name -and the order/invoice number in brackets after the description to easily identify the transaction on your Netcash statement without looking at Pay Now transaction reports.
  • ** Add the debtor’s reference in this field, please note – this does not display on the Netcash on screen statement, but is downloadable using the Netcash statement download.

Additional data

  • See the recommended implementation methodology here.
  • Please make sure that there is a cent amount in your post i.e. Post 12.00 rather than 12 as your amount. This is so that the 3D secure process gets the amount correct. Also do not post more than 2 decimal places like 12.0000 as your amount.
  • Any data which you need to be returned to you in the Notify, Accept or Decline post should be included in m4, m5 or m6.
  • Data in these fields will be returned in the Extra1, Extra2 and Extra3 fields of the post.
  • Extra1, Extra2 and Extra3 fields will also be included in the export of your Netcash statement for reconciliation purposes.

Example

<form name="form" id="x1" method="POST" action="https://paynow.netcash.co.za/site/paynow.aspx" target="_top"> <!---Form POST **--->
  <input type="text" name="M1" value="7XXX34c4-XXX-40X8-9f1d-7fbXXXX830d3">  <!--- YOUR PAY NOW SERVICE KEY GOES IN HERE --->
  <input type="text" name="M2" value="24ade73c-98cf-47b3-99be-cc7b867b3080">  <!--- SOFTWARE VENDOR KEY GOES IN HERE --->
  <input type="text" name="p2" value="ID:123">                                <!---Unique ID for this / each transaction--->
  <input type="text" name="p3"  value="Test / Demo goods">                    <!---Description of goods being purchased--->
  <input type="text" name="p4" value="5.00">                                  <!---Amount to be settled / paid--->
  <input type="text" name="Budget" value="Y">                                 <!---Compulsory should be Y--->
  <input type="text" name="m4" value="Extra 1">                               <!---This is an extra field ***--->
  <input type="text" name="m5" value="Extra 2">                               <!---This is an extra field ***--->
  <input type="text" name="m6" value="Extra 3">                               <!---This is an extra field ***--->
  <input type="text" name="m9" value="myemail@email.net">                     <!---Card holders email address--->
  <input type="text" name="m11" value="0812345678">                           <!---Card holders mobile number--->
  <input type="text" name="m10" value="Demo attempt for testing">             <!---Dataset used by shopping carts i.e. OSCommerce--->
  <input type="text" name="m14" value="1">                                    <!---Request credit card subscription token 0 = no | 1 = yes--->
  <input type="text" name="m15" value="11ad173c-9d3f-43b3-19se-as7b865e3099"> <!---Credit card token for subscription cards--->
  <input type="text" name="m16" value="1">                                    <!---Subscription indicator 0 = no | 1 = yes--->
  <input type="text" name="m17" value="6">                                    <!---Number of cycles for subscription payment--->
  <input type="text" name="m18" value="1">                                    <!---Subscription frequency--->
  <input type="text" name="m19" value="20210101">                             <!---Subscription start date --->
  <input type="text" name="m20" value="15.00">                                <!---Subscription recurring amount--->
  <input name="submit" type="submit" value="PAY">                             <!---Submit button--->
</form>

VERY IMPORTANT

  • ** POST must be to a PARENT WINDOW – target=”_top” – not in an iFrame. Netcash offers some Pay Now services in an iFrame from our suppliers for security reasons. Modern browsers do not allow for iFrame within an iFrame on the same page. See Cross Frame Scripting article as to why not.
  • *** extra field – you can place any data in the extra field which will be returned

Shopping Cart Plugins

Your Netcash account is already integrated into various free online shopping cart plugins and we also support customised integration.

Pay Now payment selections


click image for a demonstration

 

  • The payer selects the method of payment (credit card in this example) and is directed to the payment input page.

The payer is now redirected to the bank 3D Secure input screen where he/she enters the OTP sent to his/her email and/or mobile device – depending on bank setup – to authorize the transaction.

If the user selects Retail, the following is displayed which the user can print, email or SMS to himself to make a retail payment-

-or BANK EFT the following is displayed to enable the payer to make a bank-on-bank EFT (selecting Netcash (PTY) Ltd as predefined bank beneficiary)

The EFT payment details are displayed with a unique payment reference which must be used to make the EFT payment.

Notify, Accept, Decline and Redirect pages

After the transaction is complete the following data is returned to these respective pages which was configured in the Pay Now configuration. Read more about the Postback URL’s.
It is highly advisable that all developers reconcile (indicate payment status) from the data sent to the NOTIFY url.
This URL is called for all transactions asynchronously. Unlike Instant EFT and Credit Card services, delayed services like Retail -and Bank EFT do not call the Accept and Decline URL, however, all the services do send a notification to the Notify URL.
There is also a retry plan built into the Notify URL allowing to retry a number of times before it is noted as not received.
This should be utilized for system updates whereas Accept and Decline URL’s should be used to synchronously update the Buyer on the status of the transaction.

TIP: Remove the [FromUri] attribute from your endpoint signature.

Acceptable URL Format


 

When the accept, decline or notify URLs are called, any data provided in the M10 field will be appended to the URL. URLs that already contain query parameters are not supported and may lead to invalid URLs being formed. Do not include query parameters in the URLs using the query separator (“?” in the URL).

Netcash PayNow appends a query separator (“?”) to the URL followed by the M10 field contents.

Example:

M10 field content: Value1=1&Value2=extra
Merchant URL: https://cart.merchant.site/complete.aspx
Final URL: https://cart.merchant.site/complete.aspx?Value1=1&Value2=extra

The M10 field can be used for any additional transaction identifying information. The merchant should ensure that the contents of the M10 field are acceptable URL query parameters. Also consider using the Extra1 (M4), Extra2 (M5) and/or Extra3 (M6) fields for similar information.

Notify URL


Data URL is form POST.

content-type: application/x-www-form-urlencoded

Field No: Field Name: Alpha / Numeric / Boolean Description:
1 TransactionAccepted B “true” means the transaction was successful
2 CardHolderIpAddr AN This is the original IP the request was made from
3 RequestTrace AN This is a unique trace id for the transaction. This id can be used to retrieve additional information from the 3rd Party transaction logs
4 Reference AN This is the unique reference that you sent Netcash in the original request
5 Extra1 AN This is the extra field you sent up in the m4 variable when you made the request that we return for you to integrate into your own system.
6 Extra2 AN This is the extra field you sent up in the m5 variable when you made the request that we return for you to integrate into your own system.
7 Extra3 AN This is the extra field you sent up in the m6 variable when you made the request that we return for you to integrate into your own system.
8 Amount N This is the amount that you sent Netcash in the original request
9 Method N 1 Credit card
2 Bank EFT
3 Retail
4 Ozow
5 MasterPass
6 Visa Checkout
7 Masterpass QR
10 ccToken AN Credit Card Vault GUiD
11 ccHolder AN Credit Cardholder name
12 ccMasked AN Masked Credit Card number
13 ccExpiry N Credit Card expiry date MMCCYY

Accept URL


Field No: Field Name: Alpha / Numeric / Boolean Description:
1 TransactionAccepted B “true” means the transaction was successful
2 CardHolderIpAddr AN This is the original IP the request was made from
3 RequestTrace AN This is a unique trace id for the transaction. This id can be used to retrieve additional information from the 3rd Party transaction logs
4 Reference AN This is the unique reference that you sent Netcash in the original request
5 Extra1 AN This is the extra field you sent up in the m4 variable when you made the request that we return for you to integrate into your own system.
6 Extra2 AN This is the extra field you sent up in the m5 variable when you made the request that we return for you to integrate into your own system.
7 Extra3 AN This is the extra field you sent up in the m6 variable when you made the request that we return for you to integrate into your own system.
8 Amount N This is the amount that you sent Netcash in the original request
9 Method N Returns 2 for EFT
Returns 3 for Retail
10 ccToken AN Credit Card Vault GUiD
11 ccHolder AN Credit Cardholder name
12 ccMasked AN Masked Credit Card number
13 ccExpiry N Credit Card expiry date MMCCYY

Decline URL


Field No: Field Name: Alpha / Numeric / Boolean Description:
1 TransactionAccepted B “false” means the transaction was not successful
2 CardHolderIpAddr AN This is the original IP the request was made from
3 RequestTrace AN This is a unique trace id for the transaction. This id can be used to retrieve additional information from the 3rd Party transaction logs
4 Reference AN This is the unique reference that you sent Netcash in the original request
5 Extra1 AN This is the extra field you sent up in the m4 variable when you made the request that we return for you to integrate into your own system.
6 Extra2 AN This is the extra field you sent up in the m5 variable when you made the request that we return for you to integrate into your own system.
7 Extra3 AN This is the extra field you sent up in the m6 variable when you made the request that we return for you to integrate into your own system.
8 Amount N This is the amount that you sent Netcash in the original request
9 Reason AN This is the unpaid reason

Redirect URL


Field No: Field Name: Alpha / Numeric / Boolean Description:
1 TransactionAccepted B “false” means the transaction was not successful
2 CardHolderIpAddr AN This is the original IP the request was made from
3 RequestTrace AN This is a unique trace id for the transaction. This id can be used to retrieve additional information from the 3rd Party transaction logs
4 Reference AN This is the unique reference that you sent Netcash in the original request
5 Extra1 AN This is the extra field you sent up in the m4 variable when you made the request that we return for you to integrate into your own system.
6 Extra2 AN This is the extra field you sent up in the m5 variable when you made the request that we return for you to integrate into your own system.
7 Extra3 AN This is the extra field you sent up in the m6 variable when you made the request that we return for you to integrate into your own system.
8 Amount N This is the amount that you sent Netcash in the original request
9 Reason AN “Pending EFT Payment” or “Pending Retail payment”
10 Method N Returns 2 for EFT
Returns 3 for Retail

Unpaid reason codes

Click here for a complete list of unpaid reason codes

Transaction trace

After the transaction has been delivered back to your servers you may want to check the result to make sure that what was posted back was in fact the same as the transaction data on the server. This can be done by sending a request that contains the ‘RequestTrace’ parameter to our severs that will return the transaction data to the calling service. You would call the following URL: https://ws.netcash.co.za/PayNow/TransactionStatus/Check?RequestTrace=114.228862205218 where 114.228862205218 represents the ‘RequestTrace’ parameter and it would reply with a JSON string with the data that would look like this:

{“RequestTrace”:”114.228862205218″,”Amount”:”4.00″,”TransactionAccepted”:false,”Reference”:”22″,”Reason”:”Invalid card number”}

Testing

See Testing section for more details. If you require any integration assistance contact our technical support team

Netcash may provide example/sample/demo ‘code snippets’ and/or external links in this Technical Document. Such are for guidance purposes only and may not function on every developer’s system/s. Netcash disclaims any and all liability for the usage of guidance resources provided -and you as the Developer; must accept full responsibility for the usage of such. While every possible effort has been taken to ensure compatibility across multiple system configurations, the contents of this document cannot be guaranteed to work on all systems, with all operating systems -and/or with all system configuration/s.

Version 2020.1

Copyright © 2020 Netcash (PTY) Ltd