Integration | Sage Pay | Payments Guide | Pay Now Invoice

Part 1 – Pay Now Invoice web service

Programmers guide

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

Introduction

A web service that allows a user to generate an invoice and receive a reference in return to print on the invoice.  Any software that allows for the printing of invoices that one would like to be paid through the Sage Pay Pay Now service and are producing invoices on a single invoice at a time basis should use this method. If you have multiple invoice that you would like generated please use the batch file upload service to do this same task.

This service is to be used on input of data into the application to render a reference that will be used to make the payment for an invoice.

Technical Information

PayNow is an online, synchronous web service which allows an external system to request an invoice reference for payment and receive an immediate response. This service permits only a single request per web service call.

From your application call:

Input

Submit the following parameters.

Service key Account service key issued by Sage Pay
M1 This would be your Pay Now Service Key
M2 Software Vendor Code if issued else use default value 24ade73c-98cf-47b3-99be-cc7b867b3080
Amount The amount of the invoice
P2 Unique reference for this invoice
P3 Invoice Description
M4 Extra data field 1
M5 Extra data field 2
M6 Extra data field 3
M9 Email of the person you are invoicing
M10 Additional return string data
IgnoreAmount True (call for amount to be paid) False (use amount in barcode)

Output

You will receive the following numeric code if there is an error in the service.

Numeric Response Description
100 Authentication failed
103 Invalid software vendor key
200 Web service error contact support@sagepay.co.za
301 Non unique reference provided

If there is no error you will receive an xml string response with the necessary data to populate your invoice that adheres to the following XSD

https://www.sagepay.co.za/sagepay/xsd/paynowinvoice.xsd

The web service will return only the payment types that have been activated in the back office of the system.

The retail / barcode product renders a barcode string that needs to be rendered in the following way:

Barcode standard: Code128C

Image type: SVG_VML

Image width: 400px

Image height: 50px

Part 2 – Pay Now Invoicing

Introduction

A web service called ‘NIWS_NIF’ used to send batched invoice files to be stored in the Sage Pay system for use with Pay Now payments made by clients.

Technical Information

NIWS_NIF is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to upload a batch file of invoices.

Once you have built the file call:

  • Web service: https://ws.sagepay.co.za/NIWS/niws_nif.svc
  • Method: BatchFileUpload
  • Service key: Pay Now service key

Input

Requests to the web service are sent as strings

Example:

public string BatchFileUpload(string ServiceKey, string File)

Output

Method: CreateInvoice

Submit the following parameters.

Service key Account service key issued by Sage Pay
M1 This would be your Pay Now Service Key
M2 Software Vendor Code if issued else use default value 24ade73c-98cf-47b3-99be-cc7b867b3080
Amount The amount of the invoice
P2 Unique reference for this invoice
P3 Invoice Description
M4 Extra data field 1
M5 Extra data field 2
M6 Extra data field 3
M9 Email of the person you are invoicing
M10 Additional return string data
IgnoreAmount True (call for amount to be paid) False (use amount in barcode)

If the invoice was originally created with IgnoreAmount=true, then sending the invoice again will simply update the amount at minimum send value for M1, M2, P2, IgnoreAmount and Amount.

Note – Invoice has to have been created with IgnoreAmount=true. It will not update the IgnoreAmount flag.

Successful request

If the method call was successful and the file is being processed, the web service will return a file token which is used to retrieve the load report

Example: 20000000.2550236530.0483.2.2

Unsuccessful request

If the method call fails, the web service will return an error code:

Code Description
100 Authentication failure. Ensure that the service key in the method call is correct
102 Parameter error. One or more of the parameters in the string is incorrect
200 General code exception. Please contact Sage Pay Technical Support.

Input File Structure

Each file has the following mandatory records:

H – Header record identifies the upload and passes instructions to the Sage Pay server to determine the purpose of the file.
K – Key record must follow the header record. The key record describes the transaction records which follow. The format defined in the key record is used to validate the record structure and content.
T – Transaction records follow the key record. The fields in the transaction records must conform to the layout defined in the key.
F – Footer record must be the last record in the file and confirms that the file is complete.

Header record (H)

Every file must contain a header record as the first record in the file.

Record Structure

Field Name Type Value
1 Record Identifier AN H
2 Service Key AN Pay Now Service Key
3 Version AN 1
4 Instruction AN Purpose of the file
5 Batch name AN Your identifier
6 Action date N CCYYMMDD
7 Software vendor code AN Your software vendor code if issued else use 24ade73c-98cf-47b3-99be-cc7b867b3080

Field explanations

Field Explanation
Record Id “H” – Identifies the record as a header
Service key Pay Now service key
Version “1” – This is the Sage Pay version of the file specification
Instruction Invoice – upload invoices to the Sage Pay system
Batch name Use this field as an identifier of your batch.
Action date Current date
Software vendor code This is a unique code issued by Sage Pay to Certified Sage Pay Systems Integrators.

Example

H C74EF975-1234-4663-9999-ABCDCA0FB9EF 1 Invoice My Test Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080

Key record (K)

  • The key record is mandatory and must appear in the file between the header record and the transaction records.
  • The key defines the content, order and length of the transactions records in the file. It can be likened to the column headings in a spreadsheet.
  • The key lists allthe possible fields contained in the subsequent transaction records, even if not every transaction record contains data in all the fields.
  • While the file is customizable, it is recommended that keys are listed in ascending numerical order for ease of debugging and support.

Example

K 138 162 165 201 253 254 301 302 303 304

Transaction record (T)

  • There must be at least one transaction record in the file.
  • The transaction records must conform to the order of the fields as described in the key record.
    (In the example above, the account reference (field id 138) is defined as the first field in the record therefore every transaction record MUST have the Budget as the first field or it will fail validation)
  • Every transaction record must have the same number of fields as defined in the key record (K).
  • Empty fields should be replaced by a blank tab or a default value, where one has been defined.
    Where fields are left empty, the Sage Pay system will assume spaces or zeroes for fields defined in the key record.

Mandatory field

The fields indicated by are mandatory for the specified instruction.

Key Field name Invoice
253 Unique Pay Now reference (p2)  tick
254 Description of goods (p3)  tick
162 Amount (p4)  tick
165 Ignore invoice amount
138 Budget  tick
301 Extra 1 (m4)
302 Extra 2 (m5)
303 Extra 3 (m6)
201 Email address (m9)
304 Additional Accept/Decline text (m10)

Optional fields

If the optional fields are to be included in the transaction records, they must be specified in the key record (K).

Transaction fields

Field Name Type Value
253 Unique Pay Now reference (p2) AN25 This is a unique reference that you will assign to each transaction. This reference should only ever be USED ONCE.
254 Description of goods (p3) AN50 The description of the goods sent for payment for your internal reference. (* see tip below)
162 Amount (p4) N6.2 Transactional amount that is to be settled to the card.(Invoice amount)
165 Ignore Invoice amount AN1  “Y” call for amount to be paid
“N” use the value contained in the barcode
138 Budget A1 “Y” will display the budget option in the card details page
“N” will not display the budget option in the card details page
301 Extra 1 (m4) AN50 This is an extra field that can contain any data that you require back once the settlement has been done.
302 Extra 2 (m5) AN50 This is an extra field that can contain any data that you require back once the settlement has been done.
303 Extra 3 (m6) AN50 This is an extra field that can contain any data that you require back once the settlement has been done.
201 Email address (m9) AN100 Card holders email address should you want an email sent to the cardholder.
304 Additional Accept/Decline text (m10) AN100 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.

* Add the purchaser’s name -and/or 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 purchaser’s name –and/or the order/invoice number in this field to easily identify the transaction on your Pay Now transaction report, please note – this field does not display on the Sage Pay statement.

Footer record (F)

The footer record indicates that the complete file has been received. It must be the last record in the file. If the record is not present, the system will fail the file without processing any transaction records.

Structure

Field Name Type Value
1 Record Identifier AN F
2 No of transactions N A count of the transaction records
3 Sum of amounts N The sum of the monetary fields (in cents)
4 End-of-file indicator N 9999

Field explanations

Field Explanation
Record Identifier “F” – Identifies the record as a footer
No of transactions This is the count of all the ‘T’ records in the file.
Sum of amounts This is the sum of all the values in the 161 fields.
If field 161 is not specified in the key record, this will be   the sum of all the 162 fields.
End-of-file indicator ‘9999’ – Indicates there are no more records.

Example

F 2 0 9999

Retrieving the Load Report

Postback option

Postback has not been activated in this version of the service

Polling option

If you have not activated the postback option, you will need to request the load report using the file token received from the BatchFileUpload method call.

Using the file token, call:

  • Web service: https://ws.sagepay.co.za/NIWS/niws_nif.svc
  • Method: RequestFileUploadReport
  • Service key:  Pay Now service key

Requests to the web service are sent as strings

Example:

public string RequestFileUploadReport(string ServiceKey, string FileToken)

Output file

File content

Only errors are reported in the file. If all the entries in the file are successfully validated, the Load report header will contain “SUCCESSFUL” and there will be no detail messages.

File structure

The report is tab delimited with a linefeed character as line terminator.

Load report header (occurs once at the start of each load report)

Field Name Type Value
1 Record identifier AN8 ###BEGIN
2 Batch name AN {your batch name}
3 Result of upload A13 SUCCESSFUL / UNSUCCESSFUL /
SUCCESSFUL WITH ERRORS
4 Start time of report AN8 HH:MM AM/PM

Load report message (occurs multiple times – once per error record)

Field Name Type Value
1 Unique reference AN25 The unique reference you supplied in (p2)
2 Line number AN Line :{line in your file where error was found}
3 Error message AN The error message
OR
1 Record identifier AN8 ###ERROR
2 Error message AN The error message

Load report trailer (occurs once – the last line in the report)

Field Name Type Value
1 Record identifier AN6 ###END
2 End time of report AN8 HH:MM AM/PM

Retrieving the XML Invoice file

Postback option

Postback has not been activated in this version of the service

Polling option

You will need to request the Invoice file using the file token received from the BatchFileUpload method call.

Using the file token, call:

  • Web service: https://ws.sagepay.co.za/NIWS/niws_nif.svc
  • Method: RequestPayNowInvoice
  • Service key:  Pay Now service key

Requests to the web service are sent as strings

Example:

public string RequestPayNowInvoice(string ServiceKey, string FileToken)

Output file

File content

Returns “FILE NOT READY” if the file is not yet available.

Returns all the invoices successfully loaded into the system.

Version 6/2015 last updated 27 Jun 2016