Server-to-server notification

Server-to-server notifications allow you to receive payment or registration details after each payment or registration is made. This is done via a HTTPS POST from QuickStream to your server. QuickStream posts the details as form parameters or as XML. This is also known as the server-to-server postback.

To receive a server to server notification

1. Your website must provide the serverReturnUrl parameter in a secure token request, or configure your server to server notifications in the QuickStream portal.
2. Configure the domain whitelist in the QuickStream portal.
3. Have a valid SSL certificate issued by a trusted certificate authority. Sending the notification over SSL ensures that the encrypted notification cannot be read by a malicious third-party. As your SSL certificate was issued by a trusted certificate authority, it also guarantees that QuickStream is connecting to your web server (and not another fraudulent server as in the case of DNS attacks).
4. Have a dynamic backend which can receive and parse HTTPS requests with parameters or can parse XML.

A server to server notification is sent after a successful payment or registration attempt.

When you receive a server to server notification

Your system perform these steps:

Note:

• If you are sending an account token preregistrationCode to make a payment, save a copy of the account token in your database or update that it was successfully registered.
• If your system will calculate a card surcharge during payment, you may need to store the card scheme in your database now. This is only necessary if you intend to apply different surcharges to different card schemes.
• If your system is going to report expiring cards you will need to store the card expiry date.

Web payment notification parameters

These parameters can be sent for:

• QuickWeb
• QuickWeb Invoicing
• QuickVoice
• QuickStream portal - Make a card payment

If you choose to receive the data as XML, the parameters listed below will instead be built into an XML document. This document will be passed to your server in the body of the request. The request will have a content-type of application/xml.

Example HTTPS POST request

POST /payments HTTP/1.1
Authorization: Basic QVZURVNUOlFWVEXTVA==
Host: yourwebsite.com.au
Accept: text/html, text/xml, image/gif, image/jpeg, *; q=.2, */*; q=.2
User-Agent: Qvalent iConnect 7.0
Connection: close
Content-Type: application/x-www-form-urlencoded
Content-Length: 436

surchargeAmount=0.03&cardScheme=VISA&paymentReference=123456&createdDateTime=06+Mar+2019+11%3A44%3A33&settlementDate=20190306&paymentAmount=32.11&summaryCode=0&responseCode=08&successFlag=true&sourceCode=net&responseDescription=Approved+or+completed+successfully&supplierBusinessCode=YOURBUSINESS&id_batch_entry=1241373591&receiptNumber=1241373591&communityCode=YOURCOMMUNITY&username=QUICKSTREAM_USERNAME&password=QUICKSTREAM_PASSWORD

Example XML POST request

POST /payments HTTP/1.1
Authorization: Basic QVZURVNUOlFWXEVTVA==
Host: yourwebsite.com.au
Accept: text/html, text/xml, image/gif, image/jpeg, *; q=.2, */*; q=.2
User-Agent: Qvalent iConnect 7.0
Connection: close
Content-Type: application/xml
Content-Length: 749

<PaymentResponse><sourceCode>net</sourceCode><receiptNumber>1241373591</receiptNumber><communityCode>YOURCOMMUNITY</communityCode><supplierBusinessCode>YOURBUSINESS</supplierBusinessCode><customerReferenceNumber></customerReferenceNumber><paymentReference>123456</paymentReference><paymentAmount>32.11</paymentAmount><surchargeAmount>0.03</surchargeAmount><cardScheme>VISA</cardScheme><settlementDate>20190306</settlementDate><createdDateTime>06 Mar 2019 11:44:33</createdDateTime><responseCode>08</responseCode><responseDescription>Approved or completed successfully</responseDescription><summaryCode>0</summaryCode><successFlag>true</successFlag><username>QUICKSTREAM_USERNAME</username><password>QUICKSTREAM_PASSWORD</password></PaymentResponse>

Web recurring payment notification parameters

These parameters can be sent for:

• QuickWeb Recurring

Web invoice payment notification parameters

These parameters can be sent for:

• QuickWeb Invoicing

Web tokenisation notification parameters

These parameters can be sent for QuickVault Web registration.

If you choose to receive the data as XML, the parameters listed in the table above will instead be built into an xml document. This document will be passed to your server in the body of the request. The request will have a content-type of application/xml.

Example HTTPS POST request

POST /accounts HTTP/1.1
Authorization: Basic QVZURVNUOlFWXEVTVA==
Host: yourwebsite.com.au
Accept: text/html, text/xml, image/gif, image/jpeg, *; q=.2, */*; q=.2
User-Agent: Qvalent iConnect 7.0
Connection: close
Content-Type: application/x-www-form-urlencoded
Content-Length: 338

product=QUICKVAULT&customerReferenceNumber=123456&cardScheme=VISA&cardholderName=Jane+Smith&supplierBusinessCode=YOURBUSINESS&expiryDateYear=2022&preregistrationCode=1WKRMZ4242&connectionType=QUICKWEB&maskedCardNumber=424242...242&expiryDateMonth=01&communityCode=YOURCOMMUNITY&username=QUICKSTREAM_USERNAME&password=QUICKSTREAM_PASSWORD

Example XML POST request

POST /accounts HTTP/1.1
Authorization: Basic QVZURVNUOlFWXEVTVA==
Host: yourwebsite.com.au
Accept: text/html, text/xml, image/gif, image/jpeg, *; q=.2, */*; q=.2
User-Agent: Qvalent iConnect 7.0
Connection: close
Content-Type: application/xml
Content-Length: 594

<PaymentResponse><connectionType>QUICKWEB</connectionType><product>QUICKVAULT</product><communityCode>YOURCOMMUNITY</communityCode><supplierBusinessCode>YOURBUSINESS</supplierBusinessCode><customerReferenceNumber>123456</customerReferenceNumber><cardScheme>VISA</cardScheme><cardholderName>Jane Smith</cardholderName><maskedCardNumber>424242...242</maskedCardNumber><expiryDateMonth>01</expiryDateMonth><expiryDateYear>2022</expiryDateYear><preregistrationCode>1WKRMZ4242</preregistrationCode><username>QUICKSTREAM_USERNAME</username><password>QUICKSTREAM_PASSWORD</password></PaymentResponse>

Sample code for consuming the notification

Sample for consuming the notification

public class NotificationConsumer extends HttpServlet 
{
    ...
    @Override
    protected void doPost( final HttpServletRequest request, 
                           final HttpServletResponse response ) throws IOException
    {
        try 
        {
            if( !request.getRemoteAddr().equals( QUICKSTREAM_IP_ADDRESS ) ) {
                response.sendError( HttpServletResponse.SC_FORBIDDEN );
                return;
            }
            final String authorization = request.getHeader( "Authorization" );
            if( authorization == null ) {
                return;
            }
            String base64Credentials = authorization.substring( "Basic".length() ).trim();
            String credentials = new String( Base64.getDecoder().decode( base64Credentials ), Charset.forName( "UTF-8" ) );
            final String[] values = credentials.split(":",2);
            if( !QUICKSTREAM_USERNAME.equals( values[0] ) || !QUICKSTREAM_PASSWORD.equals( values[1] ) )  {
                response.sendError( HttpServletResponse.SC_FORBIDDEN );
                return;
            }
            response.setStatus( HttpServletResponse.SC_OK );
            for( final String name : request.getParameterMap().keySet() ) {
                for( final String value : request.getParameterMap().get( name ) ) {
                    // Consume
                }
            }
        }
        catch( final Exception e  ) {
            response.sendError( HttpServletResponse.SC_INTERNAL_SERVER_ERROR );
        }
        return;
    }
}

<?php
    header( "Content-Type: text/plain" );
    if ( $_SERVER["REMOTE_ADDR"] != QUICKSTREAM_IP_ADDRESS ) {
        header("HTTP/1.1 403 FORBIDDEN");
        return;
    }
    if ( !isset($_SERVER['PHP_AUTH_USER'] ) || !isset( $_SERVER['PHP_AUTH_PW'] ) ) {
        header("HTTP/1.1 401 UNAUTHORIZED");
        return;
    }
    if ( $_SERVER['PHP_AUTH_USER'] != QUICKSTREAM_USERNAME || $_SERVER['PHP_AUTH_PW'] != QUICKSTREAM_PASSWORD ){
        header("HTTP/1.1 403 FORBIDDEN");
        return;
    }
    if( $_SERVER["REQUEST_METHOD"] === "POST" ) {
        try {
            foreach( $_POST as $key => $value ) {
                // consume
            }
            header("HTTP/1.1 200 OK");
        } catch (Exception $e) {
            header("HTTP/1.1 500 INTERNAL SERVER ERROR");
        }
    }
    return;
?>