Integration | Sage Pay | Payments Guide | Pay Now Gateway

Programmers guide

To start, please refer our programmer’s guide for more detail on how to apply the required methodology.

Please note: 

Sage Pay may provide example/sample/demo code snippets in this technical document. Such snippets are for guidance purposes only and may not function on every developer’s system/s. Sage Pay disclaims any and all liability for the usage of any of the example/sample/demo code snippets provided -and you as the developer must accept full responsibility for the usage of any example/sample and/or demo code.

While every possible effort has been taken to ensure compatibility across multiple system configurations, the example/sample/demo code cannot be guaranteed to work on all systems, with all operating systems and or with all system configuration/s.

Testing

Please note that testing with live transactional data will incur charges.  Please speak to your Sage Pay account manager for more details as some of the services in Pay Now can be placed in a ‘test mode’. We have created several shopping cart plugins to make your life easier. If you would like to first look at the free shopping cart plugins we have available; click here.

Overview

Pay Now is an online payment service that can be integrated to various applications to receive payments. It is currently being used for online stores and invoices. We currently offer credit card payments, however payment options will be extended over time.

Click here for the quick start guides for;
Sage One Setup
Sage One Pay Now setup

Service set up process

  • Specify the payment options you require on application for the service. (Additional payment options can be added or removed at any time by request via your account manager)
  • Sage Pay will issue a Pay Now service key and make the payment options available on your Sage Connect profile.
  • Log in to your Sage Pay account and set the Sage connect profile.
  • Develop the form POST on your system to send the payment instruction to https://paynow.sagepay.co.za/site/paynow.aspx
    (It is not recommended to process the form post in an iFrame)
  • Develop the Approve, Decline, Notify and Redirect URLs on your system where Sage Pay will POST data back to you.
  • Download the Pay Now logos to use on your payment gateway pages in your eCommerce store.

Pay Now payment options

The following payment channels are available on the Pay Now service. Your customer will be directed to the Pay Now page to select one of the options.

  • Visa and MasterCard
  • EFT
  • Retail barcode

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 Sage Pay account to which the proceeds of the payment will be credited.

Sage Connect

The Sage Connect profile allows you to customize the service according to your requirements:

  • Active: This field is non-editable.
  • 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 Sage Pay URL.
  • Allow Master and Visa payments: This field is used to control whether your client may pay by credit card (master/visa only).
  • 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. If a card transaction is cancelled by the card holder during the payment process, the page will redirect to the decline url page.
  • Notify url: This is the URL that Sage Pay will call for transactions like EFT and Retail where the payment is not able to be captured in real time. These payments will be picked up when they are made and Sage Pay 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 Sage Pay. 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 numbers to test with:
    4000000000000002 – Returns “Approved”
    4000000000000028 – Returns VISA “Declined”
    5200000000000049 – Returns MasterCard “Declined”

Please note:

Use “123” as CVC value and expiry date; any month and year in the future for all test transactions.

Sage Pay edit Pay Now service key settings

POST to the Pay Now page:

Please note:

It is not recommended to process the form post in an iFrame. Open the page in a new window/tab.

These parameters are required by the Pay Now system when submitting a transaction.

Field No: Field Name: Length: Alpha / Numeric Mandatory Description:
1 m1 36 AN Yes Pay Now service key.
2 m2 36 AN Yes Software vendor key
(only used by Sage Pay business partners and Sage OpCo’s
else use 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.
6 Budget 1 AN Yes “Y” will display the budget option in the card details page
“N” will not display the budget option in the card details page
7 m4** 50 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 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.

The Sage Pay system will authenticate the Pay Now service key in field m1. If the key is authenticated the payer will be directed to the payment method selection page.

Tips

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

Additional data

  • It is not recommended to process the form post in an iFrame. Open the page in a new window/tab.
  • 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 Accept or Decline post (see section 7) should be included in m4, m5 or m6.
  • Data in these fields will be returned in the Extra1, Extra2 and Extra 3 fields of the post.
  • Extra1, Extra2 and Extra 3 fields will also be included in the export of your Sage Pay statement for reconciliation purposes.

Pay Now payment method selection

The methods of payment displayed on this page are controlled from the Sage connect menu on the Sage Pay web front-end. (See Pay Now service key settings)

Sage Pay ecommerce check out screen

Pay Now payment confirmation

The payer selects the method of payment and is directed to the payment confirmation page.

Sage Pay ecommerce check out screen fill in credit card details

On “Submit” the cardholder is directed to the 3rd Party PCI Compliant system to enter the card details.

If the user selects Retail -or EFT the following is displayed

Sage Pay Pay Now eCommerce cash payment screen
Sage Pay Pay Now eCommerce Bank EFTpayment screen

Accept, Decline, Notify and Redirect pages

After the transaction is complete the following data is returned:

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 Sage Pay 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 Sage Pay in the original request
9 AN Any parameters passed in m10 will be appended to the end of a return to the accept page.

After a transaction has been confirmed on the Sage Pay System the following data is returned for EFT and Retail transactions:

Notify 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 Sage Pay 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 Sage Pay in the original request
9 AN Any parameters passed in m10 will be appended to the end of a return to the accept page.
10 Method N Returns 2 for EFT
Returns 3 for Retail

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 Sage Pay 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 Sage Pay in the original request
9 Reason AN This is the unpaid reason
10 AN Any parameters passed in m10 will be appended to the end of a return to the accept page.

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 Sage Pay 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 Sage Pay in the original request
9 Reason AN “Pending EFT Payment” or “Pending Retail payment”
10 AN Any parameters passed in m10 will be appended to the end of a return to the accept page.
11 Method N Returns 2 for EFT
Returns 3 for Retail

Please note:

If a transaction is cancelled by the card holder, the page will be redirected to your Decline url.

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.sagepay.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”}

Version 1.3/2015 last updated 30 November 2015