Nav
php shell
  • Authentication
  • PayWeb 3
  • PayHost
  • PayBatch
  • PaySubs
  • Result Codes
  • Transaction Status
  • Authentication Indicators
  • Payment Method Codes
  • Locale Codes
  • Country Codes
  • Authentication

    For all DPO PayGate products, unless otherwise stated, use a combination of PayGate ID and an encryption key for authentication.

    The PayGate ID is supplied when signing up with us, but is also shown in the Merchant Access Portal .

    The Encryption Key is setup on a per-product basis and can be set in our Merchant Access Portal.

    PayWeb 3

    Introduction

    PayWeb is a secure payment system hosted by PayGate. A single integration to PayWeb gives you access to multiple payment methods. PayGate is a PCI compliant payment service provider.

    PayGate is continually adding to the list of available payment methods. Please contact the PayGate Support team (email: support@paygate.co.za) to confirm which payment methods are available in your locale.

    Benefits of PayWeb

    Configuration

    The following parameters can be configured for each PayGate account (i.e. per PayGateID). These are agreed and pre-set during the application process and are configured when our Support team sets up your PayGate account, or can be configured via the Back-Office merchant administration website once the account is live.

    Password & Card Types Accepted

    Merchants are given access to the PayWeb configuration page (via the Merchant Access Portal) where they set the following options:

    Auto-Settle

    With this option enabled, you do not need to send a Settlement transaction for an approved Authorisation. As soon as the bank approves the Authorisation, PayGate immediately and automatically creates the Settlement transaction on your behalf. This option is enabled by default.

    PayProtector

    PayProtector is PayGate’s fraud and risk system, designed to help the merchant minimize the risk of loss from fraudulent transactions. Fraud has become a serious problem and often adds significant costs for internet merchants. PayProtector scrutinizes transactions from several angles combining internal, local and international information to identify, report on, and / or block fraudulent transactions.

    Payment Confirmation

    By default, PayGate will send a Payment Confirmation email to the customer’s email address for each approved transaction. If this functionality is not required, it can be switched off per PayGateID. By default, nobody is blind copied (Bcc) on payment confirmation emails, but if required a merchant may provide an email address which will be Bcc’d on each payment confirmation email sent.

    PayVault

    PayVault is PayGate’s credit card tokenisation service. When tokenisation of a credit card is requested the card’s PAN and Expiry Date is stored in PayGate’s PCI-compliant database and a PayVault ‘token’ (a GUID) is issued for the card. This token can then be re-used in place of the card number to process payments on that card via the PayGate system. By default, only credit cards for which the initial payment is approved will be added to the PayVault database and a token for the card issued. On request a terminal parameter can be set to allow for all cards to be added to the PayVault database and tokens issued, whether the initial payment is accepted or declined/failed.

    Setup options when more than one payment method is activated

    Each PayGate ID has access to the Merchant Access Portal and all transactions processed by PayGate using a PayGate ID are visible in the Merchant Access Portal. Reports can be viewed in the Merchant Access Portal or downloaded into MS Excel (or similar) applications for offline reporting.

    A merchant with multiple payment methods can choose to either:

    1. Have multiple payment methods all activated on a single PayGate ID or
    2. Have multiple PayGate ID’s with a single payment method active per PayGate ID or
    3. Have multiple payment methods activated on a single PayGate ID and specify for each transaction which payment methods should be visible to the client (using the PAY_METHOD and PAY_METHOD_DETAIL fields to control this).

    If option 1 is chosen, then PayWeb will display a menu of payment options to the client. The client will choose how (s)he wants to pay and select the relevant menu option.

    If option 2 is chosen, then the client will be taken directly to the relevant payment page.

    If option 3 is chosen, then a menu of payment options will be shown only if more than one payment method meets the criteria specified in the PAY_METHOD and PAY_METHOD_DETAIL fields for the transaction.

    Process Flow

    PayWeb3 Process Flow

    Process flow description

    1. The merchant begins the process by posting a detailed ‘Request’ to PayWeb.
    2. PayWeb responds immediately with a unique PAY_REQUEST_ID field.
    3. The merchant re-directs the client to PayWeb and passes limited information including the PAY_REQUEST_ID field returned by PayWeb in step 1. PayWeb displays a menu of active payment methods to the client (if appropriate) and processes the transaction to the relevant financial service provider.
    4. If the merchant places a value in the ‘NOTIFY_URL’ field in step 1 then PayWeb will post the ‘Response’ data back to the ‘NOTIFY_URL’ provided. This is done immediately, and before redirecting the client back to the ‘RETURN_URL’ in step 6.
    5. If the NOTIFY_URL is specified by the merchant in step 1, then when PayWeb posts the ‘Response’ data to the NOTIFY_URL in step 4, the merchant must respond with ‘OK’ when the post is received.
    6. PayWeb redirects the client back to the ‘RETURN_URL’ provided by the merchant in step 1.
    7. The merchant can ‘Query’ PayWeb and post the PAY_REQUEST_ID field to PayWeb.
    8. PayWeb replies immediately to step 6 by posting back detailed ‘Response’ data.
    9. In some cases, the payment method chosen will be more suited to an ‘asynchronous’ process. For instance, when the client is given payment instructions by PayWeb and these instructions will take some time (possibly days) to complete. If/when PayWeb receives a response from the financial service provider stating that the transaction has been completed, then PayWeb will post the ‘Response’ data back to the ‘NOTIFY_URL’ provided by the merchant in step 1.

    The Landing Pages

    Payment menu page

    The menu page is only displayed to the client if more than one payment method is activated on the PayGateID. Only active payment methods are displayed. This page is customisable and an iFrame can be used to maintain the look and feel of the merchant system as far as possible.

    Example of a (non customised) payment menu page PayWeb3 Payment Menu

    Payment page

    The payment page will vary depending on the payment method.

    This page is customisable and an iFrame can be used to maintain the look and feel of the merchant system as far as possible.

    Example of a (non customised) credit card payment page PayWeb3 Payment Page

    Request and Response data

    This section describes in detail the fields sent to PayWeb and the fields returned by PayWeb. Please refer to the process flow diagram.

    Legend

    Type Description
    Mandatory Field
    Optional field depending on context
    Not required

    Endpoints

    Step Url
    Initiate https://secure.paygate.co.za/payweb3/initiate.trans
    Redirect https://secure.paygate.co.za/payweb3/process.trans
    Query https://secure.paygate.co.za/payweb3/query.trans

    Initiate

    The merchant begins the process by posting a detailed ‘Request’ to PayWeb.

    Request

    curl --data "PAYGATE_ID=10011072130&REFERENCE=pgtest_123456789&AMOUNT=3299&CURRENCY=ZAR&RETURN_URL=https%3A%2F%2Fmy.return.url%2Fpage&TRANSACTION_DATE=2018-01-01+12%3A00%3A00&LOCALE=en-za&COUNTRY=ZAF&EMAIL=customer%40paygate.co.za&CHECKSUM=59229d9c6cb336ae4bd287c87e6f0220" https://secure.paygate.co.za/payweb3/initiate.trans
    
    <?php
    
    //encryption key set in the Merchant Access Portal
    $encryptionKey = 'secret';
    
    $DateTime = new DateTime();
    
    $data = array(
        'PAYGATE_ID'        => 10011072130,
        'REFERENCE'         => 'pgtest_123456789',
        'AMOUNT'            => 3299,
        'CURRENCY'          => 'ZAR',
        'RETURN_URL'        => 'https://my.return.url/page',
        'TRANSACTION_DATE'  => $DateTime->format('Y-m-d H:i:s'),
        'LOCALE'            => 'en-za',
        'COUNTRY'           => 'ZAF',
        'EMAIL'             => 'customer@paygate.co.za',
    );
    
    $checksum = md5(implode('', $data) . $encryptionKey);
    
    $data['CHECKSUM'] = $checksum;
    
    $fieldsString = http_build_query($data);
    
    //open connection
    $ch = curl_init();
    
    //set the url, number of POST vars, POST data
    curl_setopt($ch, CURLOPT_URL, 'https://secure.paygate.co.za/payweb3/initiate.trans');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_NOBODY, false);
    curl_setopt($ch, CURLOPT_REFERER, $_SERVER['HTTP_HOST']);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $fieldsString);
    
    //execute post
    $result = curl_exec($ch);
    
    //close connection
    curl_close($ch);
    

    POST https://secure.paygate.co.za/payweb3/initiate.trans

    Field Description Type Required
    PAYGATE_ID Your PayGateID – assigned by PayGate varchar(20)
    REFERENCE This is your reference number for use by your internal systems varchar(110)
    AMOUNT Transaction amount in cents. e.g. 32.99 is specified as 3299 varchar(20)
    CURRENCY Currency code of the currency the customer is paying in. (refer to Currency Codes) varchar(5)
    RETURN_URL Once the transaction is completed, PayWeb will return the customer to a page on your web site. The page the customer must see is specified in this field varchar(255)
    TRANSACTION_DATE This is the date that the transaction was initiated on your website or system. The transaction date must be specified in 'Coordinated Universal Time' (UTC) e.g. 2016-05-30 09:30:10 datetime
    LOCALE The locale code identifies to PayGate the customer’s language, country and any special variant preferences (such as Date/Time format) which may be applied to the user interface. Not all the locales in the [locale table][#locales] are supported by PayGate. Please confirm with Support if the locale(s) you are using is supported. If the locale passed is not supported, then PayGate will default to the “en” locale. varchar(5)
    COUNTRY Country code of the country the customer is paying from. Refer to Country Codes varchar(5)
    EMAIL If the transaction is approved, PayWeb will email a payment confirmation to this email address – unless this is overridden at a gateway level by using the Payment Confirmation setting. This field remains compulsory but the sending of the confirmation email can be blocked varchar(255)
    PAY_METHOD Refer to PAY_METHOD varchar(5)
    PAY_METHOD_DETAIL The PAY_METHOD_DETAIL field should be left blank unless the merchant has more than one active payment method and wants to make sure that the client is presented with a specific payment method. Refer to the PAY_METHOD field above for more information varchar(45)
    NOTIFY_URL If the notify URL field is populated, then PayWeb will post the fields as specified in the Response table to the notify URL immediately when the transaction is completed. PayWeb will expect a plain-text response of 'OK'. If for any reason PayWeb cannot post to the notify URL successfully or if PayWeb doesn't receive the expected response of 'OK', then it will retry 3 times at 30 minute intervals before giving up. We only allow PORT 443 (HTTPS) secure and PORT 80 (HTTP) non-secure Text
    USER1 This field is optional and has been included as a placeholder for merchant specific requirements. If this field is populated, then it must be included in the CHECKSUM calculation described below varchar(255)
    USER2 This field is optional and has been included as a placeholder for merchant specific requirements. If this field is populated, then it must be included in the CHECKSUM calculation described below varchar(255)
    USER3 This field is optional and has been included as a placeholder for merchant specific requirements. If this field is populated, then it must be included in the CHECKSUM calculation described below varchar(255)
    VAULT This field is optional but should only be included if PayVault credit card tokenisation is enabled on the merchant profile. This field is used to indicate whether a PayVault token should be issued for the credit card used to make the payment. If True (1) the credit card number will be added to PayVault and the associated Token will be returned in the response to the merchant. 0 = false, 1 = true tinyint(3)
    VAULT_ID This field is optional and should only be included if PayVault credit card tokenisation is enabled. If a PayVault token GUID is sent the credit card transaction will be processed using the credit card associated with the token. The cardholder will be shown the last 4 digits and expiry date of the credit card on the PayWeb page and will need to enter Cardholder Name and Credit Card CVV, as well as 3D Secure OTP if needed varchar(40)
    CHECKSUM This field contains a calculated MD5 hash based on the values of ALL the above-mentioned fields and a key. Refer to the section on Security below for more detail regarding the MD5 hash. varchar(40)

    Response

    The Initiate returns standard HTTP POST data structured like this:

    PAYGATE_ID=10011072130&PAY_REQUEST_ID=23B785AE-C96C-32AF-4879-D2C9363DB6E8&REFERENCE=pgtest_123456789&CHECKSUM=b41a77f83a275a849f23e30b4666e837
    
    Field Description Type
    PAYGATE_ID This should be the same PayGate ID that was passed in the request; if it is not, then the data has been altered varchar(20)
    PAY_REQUEST_ID The PAY_REQUEST_ID is a GUID allocated by PayWeb to the transaction request varchar(36)
    REFERENCE The reference that was passed in the request is returned unaltered varchar(110)
    CHECKSUM This field contains a calculated MD5 hash based on the values of ALL the above-mentioned fields and a key. Refer to CHECKSUM for more detail regarding the MD5 hash varchar(32)

    Redirect

    REDIRECT https://secure.paygate.co.za/payweb3/process.trans

    Re-direct client to PayWeb with PAY_REQUEST_ID

    The merchant redirects the client to the secure PayWeb payment page and passes only the PAY_REQUEST_ID and CHECKSUM fields.

    An example redirect form

    <form action="https://secure.paygate.co.za/payweb3/process.trans" method="POST" >
        <input type="hidden" name="PAY_REQUEST_ID" value="23B785AE-C96C-32AF-4879-D2C9363DB6E8">
        <input type="hidden" name="CHECKSUM" value="b41a77f83a275a849f23e30b4666e837">
    </form>
    
    Field Description Type Required
    PAY_REQUEST_ID The PAY_REQUEST_ID returned by PayWeb in the Initiate varchar(36)
    CHECKSUM This field contains a calculated MD5 hash based on the values of the PAYGATE_ID, PAY_REQUEST_ID, REFERENCE fields and a key. Refer to the section on Security below for more detail regarding the MD5 hash. varchar(32)

    Notify

    The Notify sends a standard HTTP POST data structured like this:

    PAYGATE_ID=10011072130&PAY_REQUEST_ID=23B785AE-C96C-32AF-4879-D2C9363DB6E8&REFERENCE=pgtest_123456789&TRANSACTION_STATUS=1&RESULT_CODE=990017&AUTH_CODE=5T8A0Z&CURRENCY=ZAR&AMOUNT=3299&RESULT_DESC=Auth+Done&TRANSACTION_ID=78705178&RISK_INDICATOR=AX&PAY_METHOD=CC&PAY_METHOD_DETAIL=Visa&CHECKSUM=f57ccf051307d8d0a0743b31ea379aa1
    

    ‘Response’ data sent back to NOTIFY_URL (optional)

    If the merchant places a value in the ‘NOTIFY_URL’ field in step 1 then PayWeb will post the ‘Response’ data back to the ‘NOTIFY_URL’ provided. This is done immediately, and before re-directing the client back to the ‘RETURN_URL’ in step 5. (Please note, we only allow PORT 443 (HTTPS) secure and PORT 80 (HTTP) non-secure).

    Field Description Type
    PAYGATE_ID This should be the same PayGate ID that was passed in the request; if it is not, then the data has been altered. varchar(20)
    PAY_REQUEST_ID The PAY_REQUEST_ID returned by PayWeb in the initiate. varchar(36)
    REFERENCE This should be the same reference that was passed in the request; if it is not, then the data has been altered. varchar(110)
    TRANSACTION_STATUS The final status of the transaction. Refer to the Transaction Status table for a list of possible values. tinyint(3)
    RESULT_CODE This field contains a code indicating the result of the transaction. Refer to the Result Code table for a complete list. The description corresponding to this code is in the RESULT_DESC field. int(11)
    AUTH_CODE If the bank or financial institution approves the transaction, then the authorisation code will be placed in this field. For non-card payment methods, this field is populated with “999999”. varchar(10)
    CURRENCY Currency code of the currency the customer is paying in. Refer to Currency Codes for valid currency codes. varchar(5)
    AMOUNT This should be the same amount that was passed in the request. If it is not, then the data has been altered. int(11)
    RESULT_DESC This field contains a description for the result of the transaction. Refer to the Result Code table for a complete list. The numeric code corresponding to this description is in the RESULT_CODE field. int(11)
    TRANSACTION_ID This field contains the PayGate unique reference number for the transaction. int(11)
    RISK_INDICATOR This is a 2-character field containing a risk indicator for this transaction. The first character describes the Verified-by-Visa / MasterCard SecureCode authentication; refer to the Authentication Indicator table for the possible values. The second character is for future use and will be set to ‘X’. Please refer to the MasterCard SecureCode & Verified by Visa section for more info. varchar(10)
    PAY_METHOD This field contains a code describing/confirming the payment method used to process the transaction. It is especially useful where the merchant has more than one payment method activated. Refer to the Payment Method Codes table for a complete list. varchar(5)
    PAY_METHOD_DETAIL This field may contain a description of the PAY_METHOD code. For instance, if the PAY_METHOD is ‘CC’ to indicate credit card, then the PAY_METHOD_DETAIL will contain the type of credit card used ‘MasterCard’, ‘Visa’ etc. If the PAY_METHOD is something generic such as ‘EW’ = eWallet, then the PAY_METHOD_DETAIL field will contain the name of the eWallet. varchar(45)
    USER1 This field is optional and has been included as a placeholder for merchant specific requirements. If this field was populated in ‘the Request’ then the response will either contain the exact data sent in the Request or specific data as agreed with the merchant. varchar(255)
    USER2 This field is optional and has been included as a placeholder for merchant specific requirements. If this field was populated in ‘the Request’ then the response will either contain the exact data sent in the Request or specific data as agreed with the merchant. varchar(255)
    USER3 This field is optional and has been included as a placeholder for merchant specific requirements. If this field was populated in ‘the Request’ then the response will either contain the exact data sent in the Request or specific data as agreed with the merchant. varchar(255)
    VAULT_ID This is the PayVault token associated to the card used to make the payment. This Vault ID can be re-used to process payments on the card either via PayWeb or PayBatch. Only the PAN and Expiry Date are linked to this token. This is an optional field and is only returned if PayVault tokenisation is requested. varchar (40)
    PAYVAULT_DATA_1 This field contains information on the credit card or e-wallet account linked to the PayVault token for managing the use of the token. This is an optional field and is only returned if PayVault tokenisation is requested. varchar(50)
    PAYVAULT_DATA_2 This field contains information on the credit card or e-wallet account linked to the PayVault token for managing the use of the token. This is an optional field and is only returned if PayVault tokenisation is requested. varchar(50)
    CHECKSUM This field contains a calculated MD5 hash based on the values of ALL the above-mentioned fields and a key. Refer to the section on Security for more detail regarding the MD5 hash. varchar(32)

    Merchant responds with ‘OK’

    If the NOTIFY_URL is specified by the merchant in the Initiate, then when PayWeb posts the ‘Response’ data to the NOTIFY_URL, the merchant must respond with ‘OK’ when the post is received. (Please note, we only allow PORT 443 (HTTPS) secure and PORT 80 (HTTP) non-secure).

    Return to Merchant

    PayWeb redirects the client back to the ‘RETURN_URL’ provided by the merchant in the Initiate.

    Field Description Type
    PAY_REQUEST_ID The PAY_REQUEST_ID returned by PayWeb in the Initiate varchar(36)
    TRANSACTION_STATUS The final status of the transaction. Refer to the Transaction Status table for a list of possible values. tinyint(3)
    CHECKSUM This field contains a calculated MD5 hash based on the values of the PAYGATE_ID, PAY_REQUEST_ID, TRANSACTION_STATUS, REFERENCE fields and a key. Refer to the section on Security below for more detail regarding the MD5 hash.

    Query

    POST https://secure.paygate.co.za/payweb3/query.trans

    The merchant posts the below fields to PayWeb to retrieve the detailed response data.

    This step is optional in that it does not affect the result of the transaction in any way, but it provides the merchant with a mechanism to retrieve detailed response data. This step can be done many times (if necessary) and can be used by the merchant to query transaction response data at any time. PayGate will make this data available for at least 6 months from the date of the transaction.

    Request

    curl --data "PAYGATE_ID=10011072130&REFERENCE=pgtest_123456789&PAY_REQUEST_ID=23B785AE-C96C-32AF-4879-D2C9363DB6E8&CHECKSUM=b41a77f83a275a849f23e30b4666e837" https://secure.paygate.co.za/payweb3/initiate.trans
    
    <?php
    
    //encryption key set in the Merchant Access Portal
    $encryptionKey = 'secret';
    
    $data = array(
        'PAYGATE_ID'        => 10011072130,
        'PAY_REQUEST_ID'    => '23B785AE-C96C-32AF-4879-D2C9363DB6E8',
        'REFERENCE'         => 'pgtest_123456789'
    );
    
    $checksum = md5(implode('', $data) . $encryptionKey);
    
    $data['CHECKSUM'] = $checksum;
    
    $fieldsString = http_build_query($data);
    
    //open connection
    $ch = curl_init();
    
    //set the url, number of POST vars, POST data
    curl_setopt($ch, CURLOPT_URL, 'https://secure.paygate.co.za/payweb3/query.trans');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_NOBODY, false);
    curl_setopt($ch, CURLOPT_REFERER, $_SERVER['HTTP_HOST']);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $fieldsString);
    
    //execute post
    $result = curl_exec($ch);
    
    //close connection
    curl_close($ch);
    
    Field Description Type Required
    PAYGATE_ID Your PayGateID – assigned by PayGate varchar(20)
    PAY_REQUEST_ID The PAY_REQUEST_ID returned by PayWeb in the Initiate varchar(36)
    REFERENCE The REFERENCE field passed to PayWeb in the Initiate varchar(110)
    CHECKSUM This field contains a calculated MD5 hash based on the values of the PAYGATE_ID, PAY_REQUEST_ID, REFERENCE fields and a key. Refer to the section on Security below for more detail regarding the MD5 hash. varchar(32)

    Response

    The Query returns standard HTTP POST data structured like this:

    PAYGATE_ID=10011072130&PAY_REQUEST_ID=23B785AE-C96C-32AF-4879-D2C9363DB6E8&REFERENCE=pgtest_123456789&TRANSACTION_STATUS=1&RESULT_CODE=990017&AUTH_CODE=5T8A0Z&CURRENCY=ZAR&AMOUNT=3299&RESULT_DESC=Auth+Done&TRANSACTION_ID=78705178&RISK_INDICATOR=AX&PAY_METHOD=CC&PAY_METHOD_DETAIL=Visa&CHECKSUM=f57ccf051307d8d0a0743b31ea379aa1
    
    

    When PayWeb receives a post containing a valid PAY_REQUEST_ID then the relevant transaction ‘Response’ data is posted back immediately.

    The field data returned by the Query is identical to that returned by the Notify.

    Final Transaction notification

    In some cases, the payment method chosen will be more suited to an ‘asynchronous’ process. For instance, when the client is given payment instructions by PayWeb and these instructions will take some time (possibly days) to complete. If/when PayWeb receives a response from the financial service provider stating that the transaction has been completed (or that the transaction status has changed), then PayWeb will post the ‘Response’ data back to the ‘NOTIFY_URL’ provided by the merchant in the Initiate.

    The NOTIFY_URL must return the plain-text value ‘OK’ to indicate that the post was received. If PayWeb cannot contact the merchant’s NOTIFY_URL and/or if an ‘OK’ reply is not received, then PayWeb will try twice more at 30 minute intervals before giving up. (Please note, we only allow PORT 443 (HTTPS) secure and PORT 80 (HTTP) non-secure).

    Security

    Security is enhanced by making use of an MD5 checksum value that is passed in both the request to PayWeb and the response from PayWeb.

    The checksum in all cases is calculated by concatenating all the fields in the relevant ‘step’ even if the field is optional.

    An Encryption Key is appended and the resulting string is passed through an MD5 hash algorithm to produce the checksum. When PayGate receives the PayWeb request, the same checksum calculation is performed. If the PayGate checksum does not match the checksum specified in the request, the transaction is rejected.

    MD5 is a one-way hashing algorithm. Simply stated, input of any length supplied to the function produces a fixed length (in this case 32 characters) output so that the original input is not recognizable. It is impossible to reverse; i.e. giving the function the result will not give you the original source. Most programming languages support the MD5 function; if not native support then by a module or extension.

    The Encryption Key used in the checksum calculation should only be known by the merchants’ website and PayGate. It should not be displayed on any web page i.e. a customer should never be able to see it. PayGate allows for the Encryption Key to be a maximum of 32 alphanumeric characters. The longer and more complex the key is, the harder it is for a malicious user to guess it.

    Checksum

    Initiate Example

    Empty optional fields:

    echo -n 10011072130pgtest_1234567893299ZARhttps://my.return.url/page2018-01-01 12:00:00en-zaZAFcustomer@paygate.co.zasecret | md5sum
    
    <?php
    $encryptionKey = 'secret';
    
    $data = array(
        'PAYGATE_ID'        => 10011072130,
        'REFERENCE'         => 'pgtest_123456789',
        'AMOUNT'            => 3299,
        'CURRENCY'          => 'ZAR',
        'RETURN_URL'        => 'https://my.return.url/page',
        'TRANSACTION_DATE'  => '2018-01-01 12:00:00',
        'LOCALE'            => 'en-za',
        'COUNTRY'           => 'ZAF',
        'EMAIL'             => 'customer@paygate.co.za'
    );
    
    $checksum = md5(implode('', $data) . $encryptionKey);
    /*
    equivalent to
    
    $checksum = md5('10011072130pgtest_1234567893299ZARhttps://my.return.url/page2018-01-01 12:00:00en-zaZAFcustomer@paygate.co.zasecret');
    */
    

    The above command returns a checksum value of

    59229d9c6cb336ae4bd287c87e6f0220 
    

    All fields including the optional fields are concatenated (there is no separator character) to form the source of the MD5 hash:

    PAYGATE_ID + REFERENCE + AMOUNT + CURRENCY + RETURN_URL + TRANSACTION_DATE + LOCALE + COUNTRY + EMAIL + PAY_METHOD + PAY_METHOD_DETAIL + NOTIFY_URL + USER1 + USER2 + USER3 + VAULT + VAULT_ID + KEY

    Assuming the KEY is ‘secret’, the following scenarios are possible:

    10011072130pgtest_1234567893299ZARhttps://my.return.url/page2018-01-01 12:00:00en-zaZAFcustomer@paygate.co.zasecret

    NOTIFY_URL and USER1 fields populated:

    echo -n 10011072130pgtest_1234567893299ZARhttps://my.return.url/page2018-01-01 12:00:00en-zaZAFcustomer@paygate.co.zahttps://my.notify.url/pageUserFieldsecret | md5sum
    
    <?php
    $encryptionKey = 'secret';
    
    $data = array(
        'PAYGATE_ID'        => 10011072130,
        'REFERENCE'         => 'pgtest_123456789',
        'AMOUNT'            => 3299,
        'CURRENCY'          => 'ZAR',
        'RETURN_URL'        => 'https://my.return.url/page',
        'TRANSACTION_DATE'  => '2018-01-01 12:00:00',
        'LOCALE'            => 'en-za',
        'COUNTRY'           => 'ZAF',
        'EMAIL'             => 'customer@paygate.co.za',
        'NOTIFY_URL'        => 'https://my.notify.url/page',
        'USER1'             => 'UserField'
    );
    
    $checksum = md5(implode('', $data) . $encryptionKey);
    
    /*
    equivalent to
    
    $checksum = md5('10011072130pgtest_1234567893299ZARhttps://my.return.url/page2018-01-01 12:00:00en-zaZAFcustomer@paygate.co.zahttps://my.notify.url/pageUserFieldsecret');
    */
    

    The above calculations return a checksum value of

    a7e87c0c9070b79c1b163b8c3262068b 
    

    10011072130pgtest_1234567893299ZARhttps://my.return.url/page2018-01-01 12:00:00en-zaZAFcustomer@paygate.co.zahttps://my.notify.url/pageUserFieldsecret


    Redirect Example

    echo -n 1001107213023B785AE-C96C-32AF-4879-D2C9363DB6E8pgtest_123456789secret | md5sum
    
    <?php
    $encryptionKey = 'secret';
    
    
    $data = array(
        'PAYGATE_ID'     => 10011072130,
        'PAY_REQUEST_ID' => '23B785AE-C96C-32AF-4879-D2C9363DB6E8',
        'REFERENCE'      => 'pgtest_123456789'
    );
    
    $checksum = md5(implode('', $data) . $encryptionKey);
    
    /*
    equivalent to
    
    $checksum = md5('1001107213023B785AE-C96C-32AF-4879-D2C9363DB6E8pgtest_123456789secret');
     */
    

    The above calculations return a checksum value of

    b41a77f83a275a849f23e30b4666e837
    

    All fields are concatenated (there is no separator character) to form the source of the MD5 hash:

    PAYGATE_ID+PAY_REQUEST_ID+REFERENCE+KEY

    Assuming the KEY is ‘secret’, the checksum source would translate to:

    1001107213023B785AE-C96C-32AF-4879-D2C9363DB6E8pgtest_123456789secret

    Testing

    Run in Postman

    Credentials

    Description Value
    PayGate ID 10011072130
    Password secret
    Currencies ZAR, EUR, USD

    PayVault tokenisation of credit card numbers as well as processing of requests using tokens is supported.

    Please refer to the tables below when testing to simulate predictable results:

    Approved Transactions

    RESULT_CODE = 990017; TRANSACTION_STATUS = 1

    Card Brand Card Number Risk Indicator
    Visa 4000000000000002 Authenticated (AX) *
    MasterCard 5200000000000015 Authenticated (AX)
    American Express 378282246310005 Not Authenticated (NX)

    Insufficient Funds Transactions

    RESULT_CODE = 900003; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    MasterCard 5200000000000023 Not Authenticated (NX) *
    Visa 4000000000000028 Not Authenticated (NX)
    American Express 371449635398431 Not Authenticated (NX)

    Declined Transactions

    RESULT_CODE = 900007; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    Visa 4000000000000036 Authenticated (AX) *
    MasterCard 5200000000000049 Authenticated (AX) *
    Diners Club 30569309025904 Not Applicable (XX)

    Unprocessed Transactions

    RESUT_CODE = 990022; TRANSACTION_STATUS = 0

    Card Brand Card Number Risk Indicator
    MasterCard 5200000000000064 Not Applicable (XX)

    Invalid Card Number

    RESULT_CODE = 900004; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    For credit card payment method - all other card numbers Not Applicable (XX)

    Miscellaneous Information

    Error Codes

    Code Description
    CNTRY_INVALID Invalid Country
    DATA_AMT_NUM Amount is not a number
    DATA_AMT_ZERO Amount value is zero
    DATA_CHK Checksum calculated incorrectly
    DATA_CREF No transaction reference
    DATA_DTTM Transaction date invalid
    DATA_INS Error creating record for transaction request
    DATA_PAY_REQ_ID Pay request ID missing or invalid
    DATA_PM Pay Method or Pay Method Detail fields invalid
    DATA_PW Not all required fields have been posted to PayWeb
    DATA_REGION No Country or Locale
    DATA_URL No return url
    INVALID_VAULT Vault value invalid
    INVALID_VAULT_ID Vault ID invalid
    INV_EMAIL Invalid Email address
    LOCALE_INVALID Invalid Locale
    ND_INV_PGID Invalid PayGate ID
    NOT_LIVE_PM No available payment methods
    NO_TRANS_DATA No transaction data found
    PAYVAULT_NOT_EN PayVault not enabled
    PGID_NOT_EN PayGate ID not enabled, there are no available payment methods or there are no available currencies
    TXN_CAN Transaction has already been cancelled
    TXN_CMP Transaction has already been completed
    TXN_PRC Transaction is older than 30 minutes or there has been an error processing it
    VAULT_NOT_ACCEPTED Card types enabled on terminal not available for vaulting

    MasterCard SecureCode & Verified-by-Visa

    What is SecureCode and Verified by Visa?
    SecureCode and Verified by Visa is a MasterCard and Visa initiative to reduce online credit card transaction fraud. (It applies to Master and Visa cards only). The Visa implementation is referred to as Verified by Visa or V-by-V. The MasterCard implementation is referred to as MasterCard Secure Code.

    How does SecureCode and Verified by Visa benefit the merchant?
    It significantly reduces the risk of fraudulent transactions, and moves the risk of certain charge backs from the merchant to the card holder or the Issuing Bank. (Note – there are instances where the charge back risk remains with the merchant – this is detailed in the flowchart below).

    A typical credit card authorisation flow including PayProtector and 3D Credit Card Authorisation Process Flow

    How Does SecureCode and Verified by Visa work?
    When a purchase is made online, the cardholder will be re-directed from the secure PayGate payment page, to the issuing bank’s (cardholder’s bank) SecureCode and Verified by Visa authentication page. Here the cardholder will be required to key in his/her authentication details (e.g. secret PIN code). The Issuing Bank validates this code and returns an 'OK' or 'not OK' response to PayGate. If PayGate receives an 'OK' response then we pass the transaction on to the Acquiring Bank for Authorisation. If the response is 'not OK' then the transaction is ‘Declined’ up front by PayGate.

    It should however be noted that not all Issuing Banks will force their cardholders to register for this service. Where this is the case, a re-direct will still take place to the issuing bank’s website but in this case the transaction will not be authenticated. The message code returned will however indicate that you as a merchant attempted to authenticate the transaction and that the issuing bank is not registered for the service. The transaction will be processed as a SecureCode and Verified by Visa transaction i.e. the risk will be passed to the issuing bank.

    What about the other cards (AMEX, Diners etc.)?
    These cards are not authenticated via the SecureCode and Verified by Visa process. At this time transaction risk for purchases made with cards other than Master and Visa, will remain with the merchant.

    Frequently Asked Questions

    How do I know the transaction is approved?

    You can check up to 3 fields in the response depending on how thorough you want to be. At a minimum, you should check the TRANSACTION_STATUS field: it will contain the value “1”. If you want to check further, the RESULT_CODE field should contain the value “990017” and the AUTH_CODE field should not be blank.

    Can I do the authorisation and the settlement separately?

    Yes, PayGate has an ‘Auto-Settle’ configuration setting that is enabled by default for all merchants. This means that PayGate automatically creates the settlement transaction when a PayWeb request is approved. If you would prefer to only authorise the transaction when the customer enters their card details (i.e. no funds are transferred), please send an email to support@paygate.co.za to request that the ‘Auto-Settle’ feature be disabled. With the ‘Auto-Settle’ feature disabled, the merchant must login to the Merchant Access Portal and effect the settlement manually.

    What response is returned if the customer clicks the ‘Cancel’ button on the PayWeb payment page?

    How will I know that I the transaction was authenticated and I have charge back protection?

    When your website receives the transaction results from PayGate, it should check the first character of the RISK_INDICATOR field. If the first character is ‘A’ then your customer has been authenticated and cannot initiate a charge back. If the first character is ‘N’ then the transaction has been declined or approved but not authenticated; you should take further steps to ensure that you are dealing with the legitimate card holder.

    The transaction was authenticated and declined; how can this be?

    PayGate attempts to authenticate the cardholder before sending the transaction to the bank for authorisation. Therefore, even if the cardholder is authenticated through MasterCard SecureCode or Verified-by-Visa, the bank could still decline the transaction due to insufficient funds etc.

    Is it possible to not use Verified-by-Visa and MasterCard SecureCode?

    3D Secure is mandatory for e-commerce transactions in many countries and acquiring banks may only issue acquiring accounts that have been 3D Secure registered. PayGate can de-activate 3D Secure on a merchant profile level only with express permission to do so from the merchant’s bank.

    PayVault Validation Information

    If a VAULT_ID PayVault Token is sent in the PayWeb Request, then for a transaction to be processed:

    The PayVault Token passed as the VAULT_ID must be an active (not deleted) and cannot be expired for the relevant payment method (e.g. for an expired credit card). Validation will fail the request if an invalid or expired Token is sent.

    If there are multiple payment methods active on a PayGate account and a VAULT_ID is sent in a request without a PAY_METHOD being specified then the payment method associated with the PayVault Token will be displayed as the default method, but the user will be given the option to change payment method on the PayWeb page.

    PayVault tokenisation will only take place when:

    PayHost

    Introduction

    PayHost is a secure PCI compliant payment system hosted by PayGate. A single integration to PayHost gives you access to multiple payment methods and PayGate is continually adding to the list of available payment methods. Please confirm with our Support team at support@paygate.co.za which payment methods and financial institutions are currently supported in your country.

    PayHost allows merchants to integrate into the PayGate system via a ‘host-to-host’ service and make use of a number of different payment methods, risk services and PCI compliant credit card data storage. PayHost also allows payments to be processed via a redirect to a PayGate-hosted secure payments page.

    A payment encryption service such as Visa Checkout is also compatible with PayHost and can be used for customers to authenticate and authorise their payments before a transaction is processed. This encrypted data can then be sent to PayGate for processing in place of card details using the TokenPayment request type. Please contact PayGate to confirm whether Visa Checkout is compatible with your acquiring bank.

    PayHost provides an ideal payment processing solution to applications for online shopping, call-centres, vending machines or any application requiring fast and reliable payment processing using the Internet as a transport layer.

    PayHost Applications

    PayHost is a ‘host-to-host’ integration which makes it ideal for any application where there is internet connectivity. This includes but is not limited to web applications, ticketing systems, applications for mobile phones or vending machines.

    Integration Options

    PayHost can be used in any environment that allows data to be transferred over a HTTPS connection. SOAP is used as the message transport language for PayHost. A merchant can integrate into PayHost using any programming language that supports SOAP calls.

    Some suggested programming languages are:

    Endpoints

    All messages for the PayHost service must be posted to :

    POST https://secure.paygate.co.za/payhost/process.trans

    The WSDL for PayHost is:

    GET https://secure.paygate.co.za/payhost/process.trans?wsdl

    Configuration

    The following parameters are configured for each PayGate account (i.e. per PayGateID). These are agreed and pre-set when your account with PayGate is configured by our Support team.

    Password & Card Types Accepted

    Merchants are given access to the PayHost configuration page (via the Merchant Access Portal) where they set the following options:

    Auto-Settle

    With this option enabled, you do not need to send a Settlement request for an approved Authorisation. As soon as the bank approves the Authorisation, PayGate immediately and automatically creates the Settlement transaction on your behalf. This option is enabled by default

    Process Unauthenticated Transactions

    For merchants with 3D Secure enabled on their PayGate ID, any MasterCard or Visa transaction that is not authenticated through Verified-by-Visa / MasterCard SecureCode is declined and not sent to the bank for authorisation. Enabling this option allows the merchant to send unauthenticated transactions to the bank for authorisation. The option is disabled by default and we discourage merchants from enabling this option, as they will not receive chargeback protection on fraudulent transactions.

    PayProtector

    PayProtector is PayGate’s fraud and risk system, designed to help the merchant minimise the risk of loss from fraudulent transactions. Fraud has become a serious problem and often adds significant costs for internet merchants. PayProtector scrutinises transactions from a number of angles combining internal, local and international information to identify, report on, and / or block fraudulent transactions.

    Please contact support@paygate.co.za if you would like more information on PayProtector.

    Payment Confirmation

    By default PayGate will send a Payment Confirmation email to the customers email address for each approved transaction. If this functionality is not required then it can be switched off per PayGateID. By default nobody is blind copied (Bcc) on payment confirmation emails, but if required a merchant may provide an email address which will be Bcc’d on each payment confirmation email sent.

    Setup options when more than one payment method is activated

    PayGate allows merchants to have multiple terminals, each with their own unique PayGateID. Each terminal has access to the Merchant Access Portal and all transactions processed by PayGate using a particular PayGateID are visible in the Merchant Access Portal. Reports can be viewed in the Merchant Access Portal or downloaded into MS Excel (or similar) applications for offline reporting.

    A merchant with multiple payment methods can choose to either:

    1. Have multiple payment methods all activated on a single PayGateID or,
    2. Have multiple PayGateID’s with a single payment method active per PayGateID or,
    3. Have multiple payment methods activated on a single PayGateID and specify for each transaction which payment methods should be visible to the client (using the PaymentMethod and PaymentMethodDetail fields to control this).

    If option 1 is chosen, then PayHost will display a menu of payment options to the client. The client will choose how (s)he wants to pay and select the relevant menu option.

    If option 2 is chosen, then the client will be taken directly to the relevant payment page.

    If option 3 is chosen, then a menu of payment options will be shown only if more than one payment method meets the criteria specified in the PaymentMethod and PaymentMethodDetail fields for the transaction.

    Payment Methods

    Card Processing

    The payment request transaction reserves the specified amount on the supplied credit card, but does not move the funds from the credit card account to the merchants account. To move the funds you must either process a Settlement transaction or get PayGate to turn on the AutoSettle option when your PayGateID is created. Note that Auto Settle is switched ON by default. (Refer to the PayGate account setup options).

    A payment request transaction becomes more complicated if 3D Secure authentication is required.

    PayHost caters for 3 approaches to 3D secure:

    Request Message Types

    Legend

    Type Description
    Mandatory Field
    Optional field depending on context
    Not required

    PayGateAccountType

    Paygate Account Details

    <Account>
        <PayGateId>10011072130</PayGateId>
        <Password>test</Password>
    </Account>
    
    Field Description Type Required
    PayGateId Your PayGate ID, assigned by PayGate. Number(11)
    Password Your password. The password is set by the merchant in the Merchant Access Portal. The password you send with each transaction must correspond to the value set in the Merchant Access Portal. Varchar(32)

    RiskType

    Risk Details

    <Risk>
        <AccountNumber>12345678</AccountNumber>
        <SessionId>345tg345</SessionId>
        <IpV4Address>192.168.1.1</IpV4Address>
        <IpV6Address>2001:0db8:85a3:0000:0000:8a2e:0370:7334</IpV6Address>
        <UserId>TestId</UserId>
        <MachineId>4d36e968-e325-11ce-bfc1-08002be10318</MachineId>
        <UserProfile>basic</UserProfile>
        <ConsumerWatch>No</ConsumerWatch>
        <Browser>(BrowserType)</Browser>
    </Risk>
    
    Field Description Type Required
    AccountNumber An account number/unique ref number at the Merchant associated with the individual who is transacting with the merchant. Varchar(30)
    If Fraud and Risk screening is activated
    SessionId Web server generated id Varchar(255)
    IpV4Address The customer’s ip v4 address. This attribute is required if the merchant is subscribed to PayProtector. Varchar(15)
    If PayProtector or Fraud and Risk screening is activated
    IpV6Address The customer’s ip v6 address. This attribute is required if the merchant is subscribed to PayProtector. Varchar(15)
    If PayProtector or Fraud and Risk screening is activated
    UserId This is a Merchant configurable data field typically used to identify a customer uniquely within the system, regardless of the amount of accounts that the customer has. Varchar(36)
    MachineId This is an ID used to identify the computer (actual hardware) uniquely within the system, regardless of the amount of customers or accounts that's using the computer. Examples of the User Machine ID are Motherboard ID, Hard drive ID, CPU ID, etc. Varchar(255)
    UserProfile This is a customizable field that may be used by the merchant to supplement fraud screening processes according to a risk classification set by the merchant. (e.g. VIP flag, Indication whether the transaction is part of a promotion, a confidence level around the identity of the customer, etc.). This field may be repeated. Varchar(20)
    ConsumerWatch Register the consumer associated with this transaction for the consumer product. possible values:
    Y = Yes
    N = No
    Char(1)
    Browser Contains a complex type of browser fields BrowserType

    PersonType

    Customer Details

    <Customer>
         <Title>Mr</Title>
         <FirstName>PayGate</FirstName>
         <MiddleName>Soap</MiddleName>
         <LastName>Test</LastName>
         <Telephone>0211234567</Telephone>
         <Telephone>0214567891</Telephone>
         <Mobile>0821234567</Mobile>
         <Email>itsupport@paygate.co.za</Email>
         <DateOfBirth>2013-01-10</DateOfBirth>
         <Nationality>ZAF</Nationality>
         <IdNumber>20130110123456789</IdNumber>
         <IdType>3</IdType>
         <Address>(AddressType)</Address>
     </Customer>
    
    Field Description Type Required
    Title Customer’s title Varchar(5)
    FirstName Customer’s first name. Note: The combined length of the FirstName, MiddleName and LastName fields should not exceed 50 characters Varchar(50)
    MiddleName Customer’s last name. Note: The combined length of the FirstName, MiddleName and LastName fields should not exceed 50 characters Varchar(50)
    LastName Customer’s last name. Note: The combined length of the FirstName, MiddleName and LastName fields should not exceed 50 characters Varchar(50)
    Telephone Customer’s telephone number e.g. +27 21 9991234. Repeatable. Varchar(45)
    If Fraud and Risk screening is activated
    Mobile Customer’s mobile phone number. Repeatable. Varchar(45)
    Fax Customer’s fax number. Repeatable. Varchar(45)
    Email The customer’s email address. Repeatable. Varchar(255)
    DateOfBirth Customer’s date of birth. e.g. 01 Jan 2013 will be 2013-01-10 Date yyyy-mm-dd
    Nationality Customer’s nationality. Refer to Country Codes. e.g. If the customer is living in London, then the country code would be set to GBR. Char(3)
    IdNumber Customer’s ID, Passport or other verification document number. Varchar(40)
    IdType A code that defines the type of verification document supplied. refer to ID Type Values Number(2)
    SocialSecurityNumber Social Security Number (US Residents). Last 4 digits of the SSN Number(4)
    Address Contains a complex type of address fields AddressType

    ID Type Values

    Type Description
    1 Passport
    2 Personal ID
    3 Identity Card
    4 Driver’s License
    5 Other
    8 Travel Document
    12 Residence Permit
    13 Identity Certificate
    16 Registro Federal de Contribuyentes
    17 Credential de Elector
    18 DNI
    19 NIE
    20 CPR Number

    BrowserType

    Browser Details

    <Browser>
        <UserAgent>Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0</UserAgent>
        <Language>en-US</Language>
    </Browser>
    
    Field Description Type Required
    UserAgent USER_AGENT of the browser used Varchar(255)
    Language Language of the browser used Varchar(30)

    AddressType

    Address Details

    <Address>
        <AddressLine>Apartment 2A</AddressLine>
        <AddressLine>1 Main Rd</AddressLine>
        <City>Cape Town</City>
        <Country>ZAF</Country>
        <State>Western Cape</State>
        <Zip>7700</Zip>
    </Address>
    
    Field Description Type Required
    AddressLine Customer’s address line. Repeatable. Varchar(60)
    City Customer’s city Varchar(25)
    If Fraud and Risk screening is activated
    Country Customer’s country. Refer to Country Codes. e.g. If the customer is living in London, then the country code would be set to GBR. Char(3)
    If Fraud and Risk screening is activated
    State Customer's State/Province/District/ County. Note: For USA and Ireland, Canada and the UK, a 2-character code needs to be supplied where the Merchant requests verification services in these countries. Varchar(25)
    Zip Customer’s zip/postal code. Varchar(10)

    ShippingDetailsType

    Shipping Details

    <ShippingDetails>
        <Customer>(PersonType)</Customer>
        <Address>(AddressType)</Address>
        <DeliveryDate>2019-01-02T12:00:00+02:00</DeliveryDate>
        <DeliveryMethod>Over Night</DeliveryMethod>
        <InstallationRequested>N</InstallationRequested>
    </ShippingDetails>
    
    Field Description Type Required
    Customer Contains a complex type of customer fields PersonType
    Address Contains a complex type of address fields AddressType
    DeliveryDate Delivery date must be specified in 'Coordinated Universal Time' (UTC) e.g. 2019-01-02T12:00:00+02:00 Datetime YYYY-MM-DDThh:mm:ss
    DeliveryMethod Method of delivery Varchar(30)
    InstallationRequested Indicates whether goods are supplied together with a physical installation. possible values:
    Y = Yes
    N = No
    Char(1)

    BillingDetailsType

    Billing Details

    <BillingDetails>
        <Customer>(PersonType)</Customer>
        <Address>(AddressType)</Address>
    </BillingDetails>
    
    Field Description Type Required
    Customer Contains a complex type of customer fields PersonType
    Address Contains a complex type of address fields AddressType

    OrderItemType

    Order Item Details

    <OrderItems>
        <ProductCode>ABC-123</ProductCode>
        <ProductDescription>Description</ProductDescription>
        <ProductCategory>Category</ProductCategory>
        <ProductRisk>Low</ProductRisk>
        <OrderQuantity>1</OrderQuantity>
        <UnitPrice>3295</UnitPrice>
        <Currency>ZAR</Currency>
    </OrderItems>
    
    Field Description Type Required
    ProductCode Line item’s product code. Note: If 1 line item tag’s value is populated, all tags must be included Varchar(50)
    ProductDescription Line item’s product description Varchar(50)
    ProductCategory Line item’s product category Varchar(50)
    ProductRisk Line item’s product risk e.g. High, Medium or Low Varchar(50)
    OrderQuantity Line item’s order quantity Number(11)
    UnitPrice Line item’s unit price e.g. R32.95 would be specified as 3295 Number(11)
    Currency Currency code of the currency the customer is paying in. Refer to Currency Codes Char(3)

    OrderType

    Order Details

    <Order>
        <MerchantOrderId>13E22035FC</MerchantOrderId>
        <Currency>ZAR</Currency>
        <Amount>3295</Amount>
        <Discount>295</Discount>
        <TransactionDate>2019-01-01T12:00:00+02:00</TransactionDate>
        <BiilingDetails>(BillingDetailsType)</BiilingDetails>
        <ShippingDetailsType>(ShippingDetailsType)</ShippingDetailsType>
        <OrderItems>(OrderItemsType)</OrderItems>
        <Locale>en</Locale>
    </Order>
    
    Field Description Type Required
    MerchantOrderId This is your reference number for use by your internal systems. e.g. Your Customer, Invoice or Order Number. Varchar(80)
    Currency Currency code of the currency the customer is paying in. Refer to Currency Codes Char(3)
    Amount Transaction amount in cents. e.g. R32.95 would be specified as 3295 Number(11)
    Discount Discount amount in cents. e.g. R32.95 would be specified as 3295 Note: This amount will not be deducted from the amount field. This value is passed to the Fraud and Risk screening service if the merchant is making use of the service. Number(11)
    TransactionDate This is the date that the transaction was initiated on your website or system. The transaction date must be specified in 'Coordinated Universal Time' (UTC) e.g. 2013-01-01T18:30:00+02:00 Datetime YYYY-MM-DDThh:mm:ss
    BillingDetails Contains a complex type of billing fields BillingType
    ShippingDetails Contains a complex type of shipping fields ShippingType
    OrderItems Contains a complex type of order item fields. Repeatable. OrderItemType
    Locale Customer locale of type Language LanguageType

    PassengerType

    Passenger Details

    <Passengers>
        <Passenger>(PersonType)</Passenger>
        <TravellerType>Adult</TravellerType>
        <LoyaltyNumber>123456789123456789</LoyaltyNumber>
        <LoyaltyType>FlyAir</LoyaltyType>
        <LoyaltyTier>Platinum</LoyaltyTier>
    </Passengers>
    
    Field Description Type Required
    Passenger Contains a complex type of customer fields. Repeatable. PersonType
    TravellerType The type of passenger travelling,
    e.g. Adult, Child, Infant.
    possible values:
    A = Adult
    C = Child
    I = Infant
    Char(1)
    LoyaltyNumber Passenger’s loyalty scheme number. Varchar(20)
    LoyaltyType Passenger’s loyalty scheme (e.g. .... Voyager, ) Varchar(20)
    LoyaltyTier Passenger’s loyalty scheme status or level possible values:
    1 = highest tier level e.g. platinum
    2 = second highest tier level e.g. gold
    3 = third highest tier level e.g. silver…,etc.
    Number(3)

    FlightLegType

    Flight Leg Details

    <FlightLegs>
        <DepartureAirport>LHR</DepartureAirport>
        <DepartureCountry>GBR</DepartureCountry>
        <DepartureCity>LON</DepartureCity>
        <DepartDateTime>2019-01-01T21:40:00</DepartDateTime>
        <DepartAirportTimeZone>+02:00</DepartAirportTimeZone>
        <ArrivalAirport>CPT</ArrivalAirport>
        <ArrivalCountry>ZAF</ArrivalCountry>
        <ArrivalCity>CPT</ArrivalCity>
        <ArrivalDateTime>2019-01-02T10:10:00</ArrivalDateTime>
        <ArrivalAirportTimeZone>+02:00</ArrivalAirportTimeZone>
        <Carrier>BA</Carrier>
        <FlightNumber>6428</FlightNumber>
        <FareBasisCode>HL7LNR</FareBasisCode>
        <FareClass>CR</FareClass>
        <BaseFare>52597</BaseFare>
        <BaseFareCurrency>GBP</BaseFareCurrency>
    </FlightLegs>
    
    Field Description Type Required
    DepartureAirport Departure point airport. e.g. If the customer is departing from London Heathrow Airport, then the code would be set to LHR. Char(3)
    DepartureCountry Departure Country. Refer to Country Codes. e.g. If the customer is departing from United Kingdom, then the country code would be set to GBR. Char(3)
    DepartureCity Departure City. e.g. If the customer is departing from London, then the country code would be set to LON. Char(3)
    DepartDateTime Local Date & time of scheduled departure. Datetime YYYY-MM-DDThh:mm:ss
    DepartAirportTimeZone Local time zone, GMT +/- hours. example: +01:00 Varchar(6) (+/-hh:mm)
    ArrivalAirport Arrival Airport. e.g. If the customer is arriving at Cape Town International, then the code would be set to CPT Char(3)
    ArrivalCountry Arrival Country. Refer to Country Codes. e.g. If the customer is arriving in South Africa, then the country code would be set to ZAF. Char(3)
    ArrivalCity Arrival City. e.g. If the customer is arriving in Cape Town, then the country code would be set to CPT. Char(3)
    ArrivalDateTime Local Date & time of scheduled arrival. Datetime YYYY-MM-DDThh:mm:ss
    ArrivalAirportTimeZone Local time zone, GMT +/- hours. example: +01:00 Varchar(6) (+/-hh:mm)
    Carrier Flight carrier for the journey. e.g. if flying with British Airways, the code would be BA Char(2)
    FlightNumber Flight number for the journey. (Data Capture
    not fed into rules engine)
    Char(4)
    FareBasisCode The fare basis code provides information about the specific fare in addition to the class of service required for booking. example: HL7LNR Char(10)
    FareClass Class of flight.
    example:
    F (=Unrestricted First Class)
    FR (=Restricted First Class)
    F (=Unrestricted Business Class)
    CR (=Restricted Business Class)
    Y (=Unrestricted Coach/Economy Class)
    YD (=Restricted Coach/Economy Class)
    (Data Capture - not fed into rules engine)
    Char(3)
    BaseFare The amount of the transaction, excluding taxes and fees, in the smallest unit of the currency i.e. cents or pence. (e.g. US$100.01 = 10001 OR ¥100 = 100). (Data Capture
    not fed into rules engine. For reporting/review purposes. Fraud screening and related velocity calculations will initially be based upon the total value of the purchase transaction)
    Number(11)
    BaseFareCurrency This is the ISO numeric code for the currency in which the transaction should be processed. See Currency Codes. This is mandatory if a base fare is supplied. (Data Capture
    not fed into rules engine. For reporting/review purposes)
    Char(3)

    AirlineBookingType

    Airline Booking Details

    <AirlineBookingDetails>
        <TicketNumber>123459846354968451</TicketNumber>
        <InternalCustomerCode>ABC1235432136475342</InternalCustomerCode>
        <ReservationSystem>FlyMyAirline</ReservationSystem>
        <TravelAgencyCode>FMA123</TravelAgencyCode>
        <PayerTravelling>Y</PayerTravelling>
        <PNR>IB6840F</PNR>
        <Passengers>(PassengersType)</Passengers>
        <FlightLegs>(FlightLegType)</FlightLegs>
    </AirlineBookingDetails>
    
    Field Description Type Required
    TicketNumber The ticket number assigned to the journey. Varchar(30)
    InternalCustomerCode
    ReservationSystem
    TravelAgencyCode
    TravelAgencyName
    PayerTravelling An indication whether the person paying is also travelling on the ticket. possible values:
    Y = Yes
    N = No
    Char(1)
    PNR Passenger Name Record Varchar(10)
    Passengers Contains a complex type of Passenger fields PassengerType
    FlightLegs Contains a complex type of Flight Leg fields FlightLegType

    LanguageType

    Language Details

    <Langauge>en-Us</Langauge>
    
    Field Description Type Required
    Language Format to use - [a-zA-Z]{2}|[iI]-[a-zA-Z]+|[xX]-[a-zA-Z]{1,8})(-[a-zA-Z]{1,8}
    e.g. en-US
    Varchar(30)

    KeyValueType

    Key / Value details

    Field Description Type Required
    key The name of the field Text
    value The value of the field Text

    UserDefinedFieldType

    User Defined Field Details

    Example of a User Defined Field

    <!--Zero or more repetitions:-->
    <UserDefinedFields>
        <key>FieldKey</key>
        <value>FieldValue</value>
    </UserDefinedFields>
    
    Field Description Type Required
    UserDefinedFields This field is a placeholder for merchant specific requirements KeyValueType

    VaultType

    Vault Details

    <Vault>true</Vault>
    
    Field Description Type Required
    Vault If set to true the card details in the transaction will be tokenized for later use boolean

    VaultIdType

    Vault ID Details

    <VaultId>0bf77509-4bd7-4fa4-b954-8f1c7ebb4c24</Vault>
    
    Field Description Type Required
    VaultId The ID of a tokenized card to be used for the transaction string

    RedirectRequestType

    Redirect Details

    <Redirect>
        <NotifyUrl>https://my.application.com/notify</NotifyUrl>
        <ReturnUrl>https://my.application.com/return</ReturnUrl>
    </Redirect>
    
    Field Description Type Required
    NotifyUrl The Notification URL. This is the URL on your site that PayHost will post the final transaction result to. This attribute must only be passed if you intend to use PayHost with 3D Secure using PayGate’s MPI or PayHost redirect solution. Text
    for 3D Secure using PayGate’s MPI or Redirect Solution
    ReturnUrl The Return URL. This is the URL on your site that PayHost will redirect the customer to once the transaction is complete. This attribute must only be passed if you intend to use 3D Secure using PayGate’s MPI or PayHost redirect solution. Text
    for 3D Secure using PayGate’s MPI or Redirect Solution
    Target Where the redirect should be targeted i.e. _parent or _self. default: _self Varchar(30)

    ThreeDSecureType

    3D Secure Details

    <ThreeDSecure>
        <Enrolled>Y</Enrolled>
        <Paresstatus>Y</Paresstatus>
        <Eci>05</Eci>
        <Xid>eY4hCbMdj9FQ0X5CV9iQHt2y82T4=</Xid>
        <Cavv>Td7wOfSL7kueWouRKPhX883w8ReT=</Cavv>
    </ThreeDSecure>
    
    Field Description Type Required
    Enrolled Enrolled status e.g.
    Y - Yes
    N - No
    U - ??Unenrolled
    Char(1)
    Paresstatus Pares status e.g.
    Y - Yes
    N - No
    U - ??Unenrolled
    A - ??Anenrolled
    Char(1)
    Eci The relevant ECI indicator Varchar(3)
    Xid The Base64 encoded transaction identifier Text
    Cavv The Base64 encoded cardholder authentication verification value Text

    PaymentType

    Payment Details

    <PaymentType>
        <Method>BT</Method>
        <Detail>SID</Detail>
    </PaymentType>
    
    Field Description Type Required
    Method This field contains a code describing/confirming the payment method used to process the transaction. It is especially useful where the merchant has more than one payment method activated. Refer to the Payment Method Codes table for a complete list. Varchar(2)
    Detail This field may contain a description of the PaymentMethod code. For instance if the Method is CC to indicate credit card, then the Detail will contain the type of credit card used MasterCard, Visa etc.
    If the Method is something generic such as EW = eWallet, then the Detail field will contain the name of the eWallet.
    Varchar(80)

    Response Message Types

    StatusNameType

    Status Name Details

    Value
    Error
    Pending
    Cancelled
    Completed
    ValidationError
    ThreeDSecureRedirectRequired
    WebRedirectRequired

    StatusType

    Status Details

    Field Description Type Required
    TransactionId The unique reference number assign by PayGate to this transaction. Number(11)
    Reference This is your reference number for use by your internal systems. We return the MerchantOrderId you passed to us in the payment request. e.g. Your Customer, Invoice or Order Number. Varchar(80)
    AcquirerCode This is the transaction status code returned by the acquirer. String
    StatusName Status StatusNameType
    StatusDetail Returns further detail relating to the StatusName returned Varchar(80)
    AuthCode The Authorisation code returned by the acquirer (bank). Varchar(10)
    PayRequestId The unique reference for the payment request Varchar(36)
    VaultId This is the PayVault token associated to the card used to make the payment. This Vault ID can be re-used to process payments on the card. Only the PAN and Expiry Date are linked to this token. This is an optional field and is only returned if PayVault tokenisation is requested. String
    VaultData1 This field contains information on the credit card or e-wallet account linked to the PayVault token for the purpose of managing the use of the token. This is an optional field and is only returned if PayVault tokenisation is requested. Varchar(50)
    VaultData2 This field contains information on the credit card or e-wallet account linked to the PayVault token for the purpose of managing the use of the token. This is an optional field and is only returned if PayVault tokenisation is requested. Varchar(50)
    TransactionStatusCode Transaction status. Refer to the transaction status table. Number(1)
    TransactionStatusDescription Transaction status description. Varchar(80)
    ResultCode Result Code. Refer to the result code table. Number(11)
    ResultDescription Result Code description. Varchar(80)
    Currency Currency code of the currency the customer is paying in. Refer to appendix A for valid currency codes Char(3)
    Amount Transaction amount in cents. e.g. R32.95 would be specified as 3295 Number(11)
    RequestedCurrency The currency code in original request Refer to Appendix A for valid currency codes Char(3)
    Only returned if PayFX currency conversion is used
    RequestedAmount The amount of the original request in cents Number(11)
    Only returned if PayFX currency conversion is used
    ConversionRate Conversion rate used, i.e. 10.40492 Decimal
    Only returned if PayFX currency conversion is used
    RiskIndicator This is a 2-character field containing a risk indicator for this transaction. The first character describes Verified-by-Visa / MasterCard SecureCode authentication. Refer to the Authentication Indicator table for possible values. The second character is for future use and will be set to ‘X’. Char(2)
    Payment The payment method type used in the transaction PaymentType
    BillingDescriptor Value that must be passed to the acquirer to display on the customer’s bank or account statement. Please note that this is not supported for all acquirers. Varchar(45)
    Will be not be returned if not supported by acquirer
    UserDefinedField Contains a complex type of user defined fields UserDefinedFieldType

    RedirectResponseType

    Redirect Response Details

    KeyValuePairs example:

    <UrlParams>
        <key>PAYGATE_ID</key>
        <value>10011013800</value>
    </UrlParams>
    
    Field Description Type Required
    RedirectUrl URL that the merchant needs to redirect the customer to. Refer to section “Redirect To PayGate” for further details. Text
    KeyValuePairs KeyValuePairs is an unbounded list of KeyValue pairs that could be returned. Each Key/Value pair will be enclosed in a UrlParams element. A merchant needs to loop through all Key/Value returned and pass these to the Url returned.
    e.g. Key = PayGateId, Value = 10011013800
    Text

    Single Payment Response (Non-redirect)

    Example of a response where no redirect is required:

    <SinglePaymentResponse xmlns="http://www.paygate.co.za/PayHOST">
        <CardPaymentResponse>
            <Status>
                <TransactionId>28791836</TransactionId>
                <Reference>YourInvoiceNumber1414070789678</Reference>
                <AcquirerCode>00</AcquirerCode>
                <StatusName>Completed</StatusName>
                <AuthCode>FU6FWP</AuthCode>
                <PayRequestId>A23EF01C-D1E7-4F77-B50D-CEE28B3D4ACC</PayRequestId>
                <TransactionStatusCode>1</TransactionStatusCode>
                <TransactionStatusDescription>Approved</TransactionStatusDescription>
                <ResultCode>990017</ResultCode>
                <ResultDescription>Auth Done</ResultDescription>
                <Currency>ZAR</Currency>
                <Amount>113</Amount>
                <RiskIndicator>XX</RiskIndicator>
                <PaymentType>
                    <Method>CC</Method>
                    <Detail>MasterCard</Detail>
                </PaymentType>
            </Status>
        </CardPaymentResponse>
    </SinglePaymentResponse>
    

    Example of a response where no redirect is required and tokenisation was requested:

    <SinglePaymentResponse>
        <CardPaymentResponse>
            <Status>
                <TransactionId>28793400</TransactionId>
                <Reference>YourInvoiceNumber1414583977479</Reference>
                <AcquirerCode>00</AcquirerCode>
                <StatusName>Completed</StatusName>
                <AuthCode>8TDDFD</AuthCode>
                <PayRequestId>B897CD11-D0BE-50E3-68C9-7FB34B5C5C9B</PayRequestId>
                <VaultId>62a083d3-1f7c-474a-bd95-87387323dde0</VaultId>
                <PayVaultData>
                    <cardNumber>xxxxxxxxxx0015</cardNumber>
                    <expDate>012021</expDate>
                </PayVaultData>
                <VaultData2>112030</VaultData2>
                <TransactionStatusCode>1</TransactionStatusCode>
                <TransactionStatusDescription>Approved</TransactionStatusDescription>
                <ResultCode>990017</ResultCode>
                <ResultDescription>Auth Done</ResultDescription>
                <Currency>ZAR</Currency>
                <Amount>113</Amount>
                <RiskIndicator>XX</RiskIndicator>
                <PaymentType>
                    <Method>CC</Method>
                    <Detail>MasterCard</Detail>
                </PaymentType>
            </Status>
        </CardPaymentResponse>
    </SinglePaymentResponse>
    
    Field Description Type Required
    Status A full transaction detail response will be returned StatusType

    Single Payment Response (Redirect)

    Example of a card payment response where a redirect is required:

    <SinglePaymentResponse>
        <CardPaymentResponse>
            <Status>
                <StatusName>ThreeDSecureRedirectRequired</StatusName>
                <StatusDetail>3D Secure Redirect Required To Complete Transaction</StatusDetail>
            </Status>
            <Redirect>
                <RedirectUrl>https://secure.paygate.co.za/PayHost/redirect.trans</RedirectUrl>
                <UrlParams>
                    <key>CHECKSUM</key>
                    <value>7fe36c62991df6de51b09db0c6fd6r29</value>
                </UrlParams>
                <UrlParams>
                    <key>PAY_REQUEST_ID</key>
                    <value>5FC0E808-27EB-7A69-64BF-8163B2837869</value>
                </UrlParams>
                <UrlParams>
                    <key>PAYGATE_ID</key>
                    <value>10011013800</value>
                </UrlParams>
            </Redirect>
        </CardPaymentResponse>
    </SinglePaymentResponse>
    

    Example of a web payment response where a redirect is required:

    <SinglePaymentResponse>
        <WebPaymentResponse>
            <Status>
                <StatusName>WebRedirectRequired</StatusName>
                <StatusDetail>Web Redirect Required To Complete Transaction</StatusDetail>
            </Status>
            <Redirect>
                <RedirectUrl>https://secure.paygate.co.za/PayHost/process.trans</RedirectUrl>
                <UrlParams>
                    <key>PAY_REQUEST_ID</key>
                    <value>18BBC8A5-FCFC-85AC-5733-F3EC906FD7E9</value>
                </UrlParams>
                <UrlParams>
                    <key>PAYGATE_ID</key>
                    <value>10011013800</value>
                </UrlParams>
                <UrlParams>
                    <key>CHECKSUM</key>
                    <value>FBDDDA576EC2A0907FECA5F776C07095</value>
                </UrlParams>
            </Redirect>
        </WebPaymentResponse>
    </SinglePaymentResponse>
    
    Field Description Type Required
    Status A full transaction detail response will be returned StatusType
    Redirect The redirect will contain the URL to where the Merchant needs to redirect the customer as well as Key/Value parameters that need to be included in the post when redirecting the customer. RedirectResponseType

    Redirect To PayGate

    The data returned in the “Redirect” message the URL and additional data that must be POSTed to the URL. This data could include the PayGate ID, PayRequest ID or Transaction ID, but it is not limited to this.

    There are 2 ways in which a merchant can redirect a customer to PayGate. This can either be via a redirect or an HTML IFRAME.

    If the merchant makes use of a standard redirect, then they would use a normal form post containing the Keys and Values returned in the Redirect Response message.
    If the merchant makes use of a HTML IFRAME, then they will need to make sure that the Keys and Values returned in the Redirect Response message are posted to the IFRAME. A GET can’t be used for posting the data to PayGate.

    Example

    The Form and IFRAME that is returned to the customer’s browser would be:

    <form action="https://secure.paygate.co.za/payhost/redirect.trans" name="frmSubmit" id="frmSubmit" method="post" target="iframeID">".
        <input type="hidden" name="PAYGATE_ID" value="10011072130" />
        <input type="hidden" name="PAY_REQUEST_ID" value="7B44FC55-CA90-1922-B32D-00DD010772DB" />
        <input type="hidden" name="CHECKSUM" value="5670e03e6c66ac4f7dac32f553a7f9c2" />
    </form>
    <iframe id="iframeID"></iframe>
    

    Assuming the following values are returned in the "Redirect" message:

    Field Description
    URL (URL attribute) https://secure.paygate.co.za/payhost/redirect.trans
    PayGate ID (PAYGATE_ID attribute) 10011072130
    Pay Request ID (PAY_REQUEST_ID attribute) 7B44FC55-CA90-1922-B32D-00DD010772DB
    Checksum (CHECKSUM attribute) 5670e03e6c66ac4f7dac32f553a7f9c2

    Checksum Calculation

    echo -n 100110721307B44FC55-CA90-1922-B32D-00DD010772DBCustomer1test | md5sum
    
    <?php
    $encryptionKey = 'test';
    
    $data = array(
        'PAYGATE_ID'         => 10011072130,
        'PAY_REQUEST_ID'     => '7B44FC55-CA90-1922-B32D-00DD010772DB',
        'REFERENCE'          => 'Customer1'
    );
    
    $checksum = md5(implode('', $data) . $encryptionKey);
    /*
    equivalent to
    
    $checksum = md5('100110721307B44FC55-CA90-1922-B32D-00DD010772DBCustomer1test');
    */
    
    
    
    

    The above command returns a checksum value of

    5670e03e6c66ac4f7dac32f553a7f9c2 
    

    Redirect the client back to the merchant’s web site

    Once the customer has either completed the authentication process or completed the payment (depending on the method chosen), PayGate will redirect the customer back to the merchants website. The URL specified in the ReturnUrl attribute in the original payment request message is where the customer’s browser will be redirected. The results of the transaction are posted in hidden fields in an HTML form:

    The redirect contains standard HTTP POST data structured like this:

    PAY_REQUEST_ID=7B44FC55-CA90-1922-B32D-00DD010772DB&TRANSACTION_STATUS=1&CHECKSUM=d88fa44173abad44ab68ce6c5457befd
    
    Field Description Type Required
    PAY_REQUEST_ID This field contains the PayGate unique reference number for the transaction. It will be the same as passed in the secure message. Varchar(36)
    TRANSACTION_STATUS The final status of the transaction. Refer to the Transaction Status table for a list of possible values. Number(1)
    CHECKSUM This field contains a calculated MD5 hash based on the values of the PAYGATE_ID, PAY_REQUEST_ID, TRANSACTION_STATUS, REFERENCE fields and a key. Refer to the Checksum Example below for an example of this calculation. Varchar(32)
    echo -n 100110721307B44FC55-CA90-1922-B32D-00DD010772DB1Customer1test | md5sum
    
    <?php
    $encryptionKey = 'test';
    
    $data = array(
        'PAYGATE_ID'         => 10011072130,
        'PAY_REQUEST_ID'     => '7B44FC55-CA90-1922-B32D-00DD010772DB',
        'TRANSACTION_STATUS' => 1,
        'REFERENCE'          => 'Customer1'
    );
    
    $checksum = md5(implode('', $data) . $encryptionKey);
    /*
    equivalent to
    
    $checksum = md5('100110721307B44FC55-CA90-1922-B32D-00DD010772DB1Customer1test');
    */
    
    
    
    

    The above command returns a checksum value of

    802d69d20233e59406cca749e79d7421 
    

    Checksum Calculation

    Concatenate the PAYGATE_ID, PAY_REQUEST_ID, TRANSACTION_STATUS, REFERENCE AND KEY (no separator characters) to form the source of the MD5 hash:
    PAYGATE_ID+PAY_REQUEST_ID+TRANSACTION_STATUS+REFERENCE+KEY

    Assuming the KEY is test, the following scenario is possible:
    100110721307B44FC55-CA90-1922-B32D-00DD010772DB1Customer1test

    The MD5 hash value for this transaction would be: d88fa44173abad44ab68ce6c5457befd

    3D Secure using PayGate’s MPI

    more redirect detail

    If you sent through a payment type of Credit card (containing all card details) and you received a “Redirect” message, it means MasterCard SecureCode / Verified-by-Visa authentication is required. The customer’s browser must be re-directed as described in the “Redirect To PayGate” section.

    Completed 3D Secure or Redirect Solution transaction notification - (If a NotifyUrl has been specified)

    When/if the customer completes either the authentication process or in some cases when the payment method chosen requires a redirect or in some cases when the payment method is suited to an ‘asynchronous’ process, PayGate will call the merchants website in order to advise the merchant what the result was. The URL specified in the NotifyUrl attribute in the original payment request message is where the notification will be posted to. The format is identical to what is decided in the “Redirect the client back to the merchant’s web site” section.

    In the case of a completed 3D Secure or Redirect Solution transaction, PayGate will attempt to post the notification before redirecting the customer back to the Merchant’s website. If this post is not successful, then the customer will be redirected anyway (and PayGate will attempt a further 3 times in the background).

    In the case of an ‘asynchronous’ process transaction, if/when PayGate receives a response from the financial service provider stating that the transaction has been completed (or that the transaction status has changed), then PayHost will notify the merchant via the ‘NotifyUrl’ provided by the merchant.

    A notification will also be sent for all transactions not completed within a reasonable time period (generally 30 minutes), i.e. If the customer closes the browser during the authentication process or at any point while PayGate is processing the transaction. In these circumstances the merchant website (at the address specified by the NotifyUrl) will receive a notification after 30 minutes to indicate an incomplete transaction. The NotifyUrl must return the value ‘OK’ to indicate that the post was received. If PayHost cannot contact the merchant’s NotifyUrl and/or if an ‘OK’ reply is not received, then PayHost will try to repost the response 2 more times at 30 minute intervals and if no response is received no further attempts to re-post the data will take place.

    PayGate Hosted Payment Page

    The PayGate Hosted Payment Page allows a Merchant to make use of PayGate’s secure payment page. Through PayGate’s Secure Payment Page a merchant does not need to integrate to a specific method. The Merchant just redirects the Customer to the PayGate payment page where the Customer will be presented with a list of all Payment Methods that the Merchant has subscribed to.

    Card Payment (Host-to-Host)

    Process Flow

    Steps in the payment request process

    PayHost Card Payment Process Flow

    1. Customer enters card details on the merchant’s web site / system.
    2. Merchant sends a payment request message to PayHost. The following steps are only required if a “Secure” message is received in step 3.
    3. The merchant is required to redirect the customer’s internet browser to PayGate’s MPI. (Refer to “3DSecure using PayGate’s MPI” for more detail).
    4. PayGate re-directs the customer to the appropriate issuing bank 3D Secure authentication page.Customers will be required to enter a PIN code / password known only to themselves and their bank inorder to authenticate them.
    5. The issuing bank 3D Secure authentication page will redirect the customer’s browser back to PayGate.
    6. If the message received from the issuing bank (in step 6) is valid, then PayGate processes the transaction to the acquiring bank and sends a payment notification message to the merchant (if the merchant hasspecified a NotifyUrl)..
    7. The Merchant website responds with the word ‘OK’ to PayGate.
    8. PayGate redirects the customer’s browser back to the merchant’s website so that the merchant can complete the order process. (Refer to “Redirect to website” for more detail). The following step follows on from step 3.
    9. The transaction is processed to the acquiring bank and the result is returned.

    CardPaymentRequestType

    Card Payment Details

    Example of a Card Request:

    <SinglePaymentRequest>
        <CardPaymentRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <Customer>
                <Title>Mr</Title>
                <FirstName>Joe</FirstName>
                <LastName>Soap</LastName>
                <Telephone>0861234567</Telephone>
                <Mobile>0735552233</Mobile>
                <Email>joe@soap.com</Email>
            </Customer>
            <CardNumber>4000000000000002</CardNumber>
            <CardExpiryDate>122015</CardExpiryDate>
            <CVV>999</CVV>
            <BudgetPeriod>0</BudgetPeriod>
            <!-- 3D secure redirect object -->
            <Redirect>
                <NotifyUrl>https://www.mytestsite.com/notify</NotifyUrl>
                <ReturnUrl>https://www.mytestsite.com/return</ReturnUrl>
            </Redirect>
            <Order>
                <MerchantOrderId>INV101</MerchantOrderId>
                <Currency>ZAR</Currency>
                <Amount>100</Amount>
            </Order>
        </CardPaymentRequest>
    </SinglePaymentRequest>
    

    Example of a Card Request with Tokenisation Requested

    <SinglePaymentRequest>
        <CardPaymentRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <Customer>
                <Title>Mr</Title>
                <FirstName>Firstname</FirstName>
                <LastName>Lastname</LastName>
                <Telephone>0211234567</Telephone>
                <Mobile>0873456789</Mobile>
                <Email>first.last@name.com</Email>
            </Customer>
            <CardNumber>5200000000000015</CardNumber>
            <CardExpiryDate>112030</CardExpiryDate>
            <CVV>123</CVV>
            <Vault>true</Vault>
            <BudgetPeriod>0</BudgetPeriod>
            <Order>
                <MerchantOrderId>YourInvoiceNumber1414070780226</MerchantOrderId>
                <Currency>ZAR</Currency>
                <Amount>113</Amount>
            </Order>
        </CardPaymentRequest>
    </SinglePaymentRequest>
    

    Example of a Card Request Using a Token Instead of a Card Number and Expiry Date

    <SinglePaymentRequest>
        <CardPaymentRequest>
            <Account>
                <PayGateId>10011072130</PayGateId>
                <Password> test</Password>
            </Account>
            <Customer>
                <Title>Mr</Title>
                <FirstName>Firstname</FirstName>
                <LastName>Lastname</LastName>
                <Telephone>0211234567</Telephone>
                <Mobile>0873456789</Mobile>
                <Email>first.last@name.com</Email>
            </Customer>
            <VaultId>eb9c11c5-e564-46e2-a087-2207ab8afadd</VaultId>
            <CVV>123</CVV>
            <BudgetPeriod>0</BudgetPeriod>
            <Order>
                <MerchantOrderId>YourInvoiceNumber1414070789678</MerchantOrderId>
                <Currency>ZAR</Currency>
                <Amount>113</Amount>
            </Order>
        </CardPaymentRequest>
    </SinglePaymentRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    Customer Customer Details PersonType
    CardNumber Card Number Number(19)
    CardExpiryDate Expiry date e.g. Jan 2020 will be 012020 Number(6) mmyyyy
    CardIssueDate The issue date of the Customer’s debit card. e.g. Jan 2012 will be 012012 Number(6) mmyyyy
    If payment is being made using a Debit Card
    CardIssueNumber The Issue number of the customer’s Debit Card Number(3)
    If payment is being made using a Debit Card
    VaultId This field is optional and should only be included if PayVault tokenisation is enabled. If a PayVault token GUID is sent the credit card transaction will be processed using the credit card associated with the token. A credit card CVV value will still be required. 3D Secure authentication may also be required. Varchar(40)
    CVV Three or four digit CVV/CVC2 check digit from the back(Visa/MasterCard) or front (Amex/Diners) of the card. Number(4)
    Vault This field is optional but should only be included if PayVault credit card tokenisation is enabled on the merchant profile. This field is used to indicate whether a PayVault token should be issued for the credit card used to make the payment. If True the credit card number will be added to PayVault and the associated Token will be returned in the response to the merchant. If not included the value is assumed to be False. True/False
    BudgetPeriod Set this field to 0 if the purchase is not on budget. Budget Period is applicable to South African cards only. Number(2)
    Redirect Contains a complex type of redirect fields RedirectRequestType
    for 3D Secure using PayGate’s MPI or Redirect Solution
    Order Contains a complex type of order fields OrderType
    ThreeDSecure Only append this element if you are using your own 3D Secure MPI. Make sure you do not pass any values in the “Redirect” attribute. Append this element containing the following fields to the payment processing message. (Refer to the 3D secure using your own MPI.) ThreeDSecureType
    Risk Contains a complex type of risk fields RiskType
    Unless Fraud and Risk screening is activated
    BillingDescriptor Value that must be passed to the acquirer to display on the customer’s bank or account statement. Please note that this is not supported for all acquirers. Varchar(45)
    Will be ignored if not supported by acquirer
    UserDefinedField Contains a complex type of user defined fields UserDefinedFieldType

    Web Payment (Redirect)

    Process Flow

    Steps in the payment request process

    PayHost Web Payment Process Flow

    1. Customer initiates payment on merchant’s website.
    2. Merchant sends a web payment request message to PayGate.
    3. PayGate responds with the PayGate payment page URL that the merchant.
    4. The merchant is required to redirect the customer’s internet browser to the PayGate payments page.
    5. Once the client has completed the payment the customer is redirected back to the merchant’s website.
    6. PayGate sends a notification to the Merchant’s system confirming that the payment has been processed
    7. The merchant sends PayGate a Query request for the transaction.
    8. PayGate responds with the transaction’s current status. The following only applies for asynchronous payment methods where the final transaction status is received from the acquirer after the online payment process is completed.
    9. PayGate receives notification of the transaction’s final status from the relevant acquirer.
    10. PayGate sends a notification to the merchant’s notification URL that the final status has been received.
    11. The merchant’s system responds with ‘OK’ to acknowledge receipt of the notification.
    12. The merchant’s system sends PayGate a Query request for the transaction.
    13. PayGate responds with the transaction’s final status as received from the acquirer.

    WebPaymentRequestType

    Web Payment Details

    Example of a Web Payment Request:

    <WebPaymentRequest>
        <Account>
            <PayGateId>10011072130</PayGateId>
            <Password>test</Password>
        </Account>
        <Customer>
            <Title>Mr</Title>
            <FirstName>Joe</FirstName>
            <LastName>Soap</LastName>
            <Email>joe@soap.com</Email>
        </Customer>
        <Redirect>
            <NotifyUrl>https://www.mytestsite.com/notify</NotifyUrl>
            <ReturnUrl>https://www.mytestsite.com/return</ReturnUrl>
        </Redirect>
        <Order>
            <MerchantOrderId>INV101</MerchantOrderId>
            <Currency>ZAR</Currency>
            <Amount>100</Amount>
            <TransactionDate>2018-01-01T12:00:00</TransactionDate>
            <BillingDetails>
                <Customer>
                    <Title>Mr</Title>
                    <FirstName>Joe</FirstName>
                    <LastName>Soap</LastName>
                    <Email>joe@soap.com</Email>
                </Customer>
                <Address>
                    <Country>ZAF</Country>
                </Address>
            </BillingDetails>
        </Order>
    </WebPaymentRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    Customer Customer details PersonType
    Vault If the card details used in the transaction are to be tokenized for later use VaultType
    VaultId The ID of a vault record for a card to be used in the transaction VaultIdType
    Redirect Contains a complex type of redirect fields RedirectRequestType
    Order Contains a complex type of order fields OrderType
    Risk Contains a complex type of risk fields RiskType
    Unless Fraud and Risk screening is activated
    Payment Only include this element if you have multiple payment methods active on your account and you would like to limit the payment options displayed to your customer. I.e. you have SID & Ukash enabled but for this payment would only like to show the SID option. PaymentType
    BillingDescriptor Value that must be passed to the acquirer to display on the customer’s bank or account statement. Please note that this is not supported for all acquirers. Varchar(45)
    Will be ignored if not supported by acquirer
    UserDefinedField Contains a complex type of user defined fields UserDefinedFieldType

    Token Payment (Host-to-Host)

    Process Flow

    Steps in the payment request process

    1. Customer is redirected to the payment encryption service provider to authorise and authenticate the transaction.
    2. The payment encryption service provider sends the merchant encrypted data for the payment.
    3. The merchant sends the relevant encrypted data to PayGate along with other transaction data.
    4. PayGate decrypts the data received and processes the authorisation to the acquiring bank.
    5. Once the acquiring bank has responded with the authorisation status PayGate sends this response to the merchant.

    TokenPaymentRequestType

    Token Payment Details

    Example of a Token Request:

    <SinglePaymentRequest>
        <TokenPaymentRequest>
            <Account>
                <PayGateId>10011072130</PayGateId>
                <Password>test</Password>
            </Account>
            <Customer>
                <Title>Mr</Title>
                <FirstName>Joe</FirstName>
                <LastName>Soap</LastName>
                <Email>joe@soap.com</Email>
            </Customer>
            <Token>2258098676320541501</Token>
            <TokenDetail>VCO</TokenDetail>
            <Order>
                <MerchantOrderId>Reference</MerchantOrderId>
                <Currency>ZAR</Currency>
                <Amount>1000</Amount>
            </Order>
        </TokenPaymentRequest>
    </SinglePaymentRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    Customer Customer details PersonType *
    Token The data provided by the payment encryption service provider. Text
    TokenDetail The description of the payment encryption service used e.g. Visa Checkout = VCO Varchar
    Vault This field is optional but should only be included if PayVault credit card tokenisation is enabled on the merchant profile. This field is used to indicate whether a PayVault token should be issued for the credit card used to make the payment. If True the credit card number will be added to PayVault and the associated Token will be returned in the response to the merchant. If not included the value is assumed to be False. True/False
    Order Contains a complex type of order fields OrderType
    BillingDescriptor Value that must be passed to the acquirer to display on the customer’s bank or account statement. Please note that this is not supported for all acquirers. Varchar(45)
    Will be ignored if not supported by acquirer
    UserDefinedField Contains a complex type of user defined fields UserDefinedFieldType

    Payout Request

    Single Payout Request

    Payout requests allow a Merchant to process pay-outs to their customers. Please note that pay-outs can only be done if the functionality is supported by the relevant acquirer or payment method.

    PayGate offers the following "Payout Request Types":

    CardPayoutRequest

    Example of Card Payout Request

    <SinglePayoutRequest>
        <CardPayoutRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <Customer>
                <FirstName>Joe</FirstName>
                <LastName>Soap</LastName>
                <Email>joes@example.com</Email>
            </Customer>
            <CardNumber>4000000000000002</CardNumber>
            <CardExpiryDate>052015</CardExpiryDate>
            <Order>
                <MerchantOrderId>order-1234</MerchantOrderId>
                <Currency>ZAR</Currency>
                <Amount>100</Amount>
            </Order>
        </CardPayoutRequest>
    </SinglePayoutRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    Customer Customer details PersonType
    CardNumber Card number Number(19)
    CardExpiryDate Expiry date e.g. Jan 2020 will be 012020 Number(6) mmyyyy
    Order Contains a complex type of order fields OrderType

    CardPayoutResponse

    Example of Card Payout Response

    <SinglePayoutResponse>
        <CardPayoutResponse>
            <Status>
                <TransactionId>28790220</TransactionId>
                <Reference>order-1234</Reference>
                <StatusName>Completed</StatusName>
                <PayRequestId>741B4BE0-5CCE-530C-901A-D9B691528C2D</PayRequestId>
                <TransactionStatusCode>0</TransactionStatusCode>
                <TransactionStatusDescription>Not Done</TransactionStatusDescription>
                <ResultCode>990006</ResultCode>
                <ResultDescription>Request for Payout Received</ResultDescription>
                <Currency>ZAR</Currency>
                <Amount>100</Amount>
                <PaymentType>
                    <Method>CC</Method>
                    <Detail>VISA</Detail>
                </PaymentType>
            </Status>
        </CardPayoutResponse>
    </SinglePayoutResponse>
    
    Field Description Type
    Status A full transaction detail response will be returned StatusType

    Vault Request

    Single Vault Request

    Vault requests allow merchants to manage what is stored by the PayVault tokenisation service. Please note that currently PayVault only supports the tokenisation of credit card data.

    PayGate offers the following Vault Request Types:

    CardVaultRequest

    Example of a Card Vault Request

    <SingleVaultRequest>
        <CardVaultRequest>
            <Account>
                <PayGateId>10011072130</PayGateId>
                <Password>test</Password>
            </Account>
            <CardNumber>5200000000000015</CardNumber>
            <CardExpiryDate>112030</CardExpiryDate>
        </CardVaultRequest>
    </SingleVaultRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    CardNumber Card number Number(19)
    CardExpiryDate Expiry date e.g. Jan 2020 will be 012020 Number(6) mmyyyy

    CardVaultResponse

    Example of a Card Vault Response

    <SingleVaultResponse>
        <CardVaultResponse>
            <Status>
                <StatusName>Completed</StatusName>
                <VaultId>6eb998d9-b4e8-46b8-9772-90ecb644ab54</VaultId>
            </Status>
        </CardVaultResponse>
    </SingleVaultResponse>
    

    A Status Type will be returned containing the following:

    Field Description Type
    StatusName The status of the request StatusNameType
    VaultId The PayVault token GUID corresponding to the credit card number and expiry date that has been added to the database. String

    LookupVaultRequest

    Example of a Lookup Vault Request

    <SingleVaultRequest>
        <LookUpVaultRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <VaultId>c36a13e8-65a0-49fd-a12f-05fe78bf9eaa</VaultId>
        </LookUpVaultRequest>
    </SingleVaultRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    VaultId The PayVault token GUID String

    LookupVaultResponse

    Example of a Lookup Vault Response

    <SingleVaultResponse>
        <LookUpVaultResponse>
            <Status>
                <StatusName>Completed</StatusName>
                <CardNumber>520000xxxxxx0015</CardNumber>
                <CardExpiryDate>112030</CardExpiryDate>
            </Status>
        </LookUpVaultResponse>
    </SingleVaultResponse>
    

    A Status Type will be returned containing the following:

    Field Description Type
    StatusName The status of the request StatusNameType
    CardNumber The masked card number associated to the PayVault Token. The first 6 and last 4 digits of the card number will be returned. Varchar(19)
    CardExpiryDate Expiry date e.g. Jan 2020 will be 012020 Number(6) mmyyyy

    DeleteVaultRequest

    Example of a Delete Vault Request

    <SingleVaultRequest>
        <DeleteVaultRequest>
            <Account>
                <PayGateId>10011072130</PayGateId>
                <Password>test</Password>
            </Account>
            <VaultId>5c633bfa-5359-482e-b144-2949aa332c74</VaultId>
        </DeleteVaultRequest>
    </SingleVaultRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    VaultId The PayVault token GUID String

    DeleteVaultResponse

    Example of a Delete Vault Response

    <SingleVaultResponse>
        <DeleteVaultResponse>
            <Status>
                <StatusName>Completed</StatusName>
            </Status>
        </DeleteVaultResponse>
    </SingleVaultResponse>
    

    A Status Type will be returned containing the following:

    Field Description Type
    StatusName The status of the request StatusNameType

    Follow Up Request

    Follow up requests allow a Merchant multiple options after processing has taken place. These can be either Settling a transaction (if a merchant is not setup for AutoSettle), refunding a transaction, querying a transaction status, etc. PayGate offer the following “Follow Up Request Types”:

    Query

    The Query function allows you to query the final status of previously processed transactions.
    The Query function will accept a PayRequestId, TransId or a Reference as a search key.

    QueryRequestType

    Example of a Query Request

    <SingleFollowUpRequest>
        <QueryRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <PayRequestId>6B739421-C177-903F-B23A-4BC1F09AB791</PayRequestId>
        </QueryRequest>
    </SingleFollowUpRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    PayRequestId The PayRequestId is a GUID allocated by PayHost to the transaction request received in the Redirect step should a transaction require it. Note: Either PayRequestId, MerchantOrderId or TransId must be populated when doing a Query Request Varchar(36) *
    MerchantOrderId This is the reference number generated by your system for the original authorisation e.g. your Customer, Invoice or Order Number. If your MerchantOrderId is not a unique number, then PayHost will return the 5 most recent transactions with a matching MerchantOrderId. Varchar(80) *
    TransId The unique reference number assign by PayGate to the original transaction. Number(11) *
    TransactionType This optional query parameter can be used along with the required query parameter to specify the type of transaction being queried. If not included in the request the default TransactionType is Authorisation. The TransactionType value can be one of the following:
    Authorisation
    Settlement
    Refund
    Payout
    Purchase
    (This will provide results for alternative paymentmethods)
    Varchar(20)

    QueryResponseType

    Example of a Query Response

    <SingleFollowUpResponse>
        <QueryResponse>
            <Status>
                <TransactionId>2920562</TransactionId>
                <Reference>INV101</Reference>
                <AcquirerCode>00</AcquirerCode>
                <StatusName>Completed</StatusName>
                <AuthCode>301948</AuthCode>
                <PayRequestId>6B739421-C177-903F-B23A-4BC1F09AB791</PayRequestId>
                <TransactionStatusCode>1</TransactionStatusCode>
                <TransactionStatusDescription>Approved</TransactionStatusDescription>
                <ResultCode>990017</ResultCode>
                <ResultDescription>Auth Done</ResultDescription>
                <Currency>ZAR</Currency>
                <Amount>100</Amount>
                <RiskIndicator>AX</RiskIndicator>
                <PaymentType>
                    <Method>CC</Method>
                    <Detail>Visa</Detail>
                </PaymentType>
            </Status>
        </QueryResponse>
    </SingleFollowUpResponse>
    
    Field Description Type
    Status A full transaction detail response will be returned StatusType

    Void

    The void function allows merchants to void transactions that are not yet settled or refunded. Settlements and Refunds can only be stopped using the Void request if they have not yet been submitted to the acquiring bank.

    VoidRequestType

    Example of a Void Request

    <SingleFollowUpRequest>
        <VoidRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <TransactionId>28790224</TransactionId>
            <TransactionType>Settlement</TransactionType>
        </VoidRequest>
    </SingleFollowUpRequest>
    

    //TODO TRANSACTION TYPE

    Field Description Type Required
    Account PayGate account details PayGateAccountType
    TransactionId The unique reference number assign by PayGate to the original Authorisation transaction. Number(11)
    TransactionType Transaction type detail of the transaction you want to void TransactionType

    VoidResponseType

    Example of a Void Response

    <SingleFollowUpResponse>
        <VoidResponse>
            <Status>
                <TransactionId>28790224</TransactionId>
                <StatusName>Completed</StatusName>
                <StatusDetail>Settlement Voided</StatusDetail>
                <TransactionStatusCode>7</TransactionStatusCode>
                <TransactionStatusDescription>Settlement Voided</TransactionStatusDescription>
                <Currency>ZAR</Currency>
                <Amount>100</Amount>
                <DateTime>2014-10-02T16:16:14.577+02:00</DateTime>
            </Status>
        </VoidResponse>
    </SingleFollowUpResponse>
    
    Field Description Type
    Status A full transaction detail response will be returned StatusType

    Settlement

    This function allows the merchant to settle an authorisation where AutoSettle is turned off.

    SettlementRequestType

    Example of a Settlement Request

    <SingleFollowUpRequest>
        <SettlementRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <TransactionId>28790224</TransactionId>
        </SettlementRequest>
    </SingleFollowUpRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    TransactionId The unique reference number assign by PayGate to the original Authorisation transaction. TransactionId *
    MerchantOrderId This is the reference number generated by your system for the original authorisation e.g. your Customer, Invoice or Order Number Varchar(80) *

    SettlementResponseType

    Example of a Settlement Response

    <SingleFollowUpResponse>
        <SettlementResponse>
            <Status>
                <TransactionId>28790227</TransactionId>
                <Reference>pgdddtest</Reference>
                <StatusName>Completed</StatusName>
                <TransactionStatusCode>5</TransactionStatusCode>
                <TransactionStatusDescription>Received by Paygate</TransactionStatusDescription>
                <ResultCode>990004</ResultCode>
                <ResultDescription>Request for Settlement Received</ResultDescription>
            </Status>
        </SettlementResponse>
    </SingleFollowUpResponse>
    
    Field Description Type
    Status A full transaction detail response will be returned StatusType

    Refund

    This function allows the merchant to refund a transaction that has already been settled.

    RefundRequestType

    Example of a Refund Request

    <SingleFollowUpRequest>
        <RefundRequest>
            <Account>
                <PayGateId>10011013800</PayGateId>
                <Password>test</Password>
            </Account>
            <TransactionId>28790224</TransactionId>
            <Amount>100</Amount>
        </RefundRequest>
    </SingleFollowUpRequest>
    
    Field Description Type Required
    Account PayGate account details PayGateAccountType
    TransactionId The unique reference number assign by PayGate to the original Authorisation transaction. Number(11) *
    Amount Transaction amount in cents. e.g. R32.95 would be specified as 3295 Number(11)
    MerchantOrderId This is your reference number for use by your internal systems for the original authorisation. e.g. Your Customer, Invoice or Order Number. Varchar(80) *
    Reference This is your reference number for use by your internal systems. We return the MerchantOrderId you passed to us in the payment request. E.g. Your Customer, Invoice or Order Number. Varchar(80)

    RefundResponseType

    Example of a Refund Response

    <SingleFollowUpResponse>
        <RefundResponse>
            <Status>
                <TransactionId>28790228</TransactionId>
                <Reference>pgdddtest</Reference>
                <StatusName>Completed</StatusName>
                <TransactionStatusCode>5</TransactionStatusCode>
                <TransactionStatusDescription>Received by Paygate</TransactionStatusDescription>
                <ResultCode>990005</ResultCode>
                <ResultDescription>Request for Refund Received</ResultDescription>
            </Status>
        </RefundResponse>
    </SingleFollowUpResponse>
    
    Field Description Type
    Status A full transaction detail response will be returned StatusType

    Testing

    Run in Postman

    Credentials

    There are 2 PayGate IDs that can be used for testing:

    Description Value
    PayGate ID 10011072130
    Password test
    Description Value
    PayGate ID 10011064270
    Password test

    PayVault tokenisation of credit card numbers as well as processing of requests using tokens is supported for both of the accounts listed above.

    Please refer to the tables below when testing to simulate predictable results:

    Approved Transactions

    RESULT_CODE = 990017; TRANSACTION_STATUS = 1

    Card Brand Card Number Risk Indicator
    Visa 4000000000000002 Authenticated (AX) *
    MasterCard 5200000000000015 Authenticated (AX)
    American Express 378282246310005 Not Authenticated (NX)

    Insufficient Funds Transactions

    RESULT_CODE = 900003; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    MasterCard 5200000000000023 Not Authenticated (NX) *
    Visa 4000000000000028 Not Authenticated (NX)
    American Express 371449635398431 Not Authenticated (NX)

    Declined Transactions

    RESULT_CODE = 900007; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    Visa 4000000000000036 Authenticated (AX) *
    MasterCard 5200000000000049 Authenticated (AX) *
    Diners Club 30569309025904 Not Applicable (XX)

    Unprocessed Transactions

    RESUT_CODE = 990022; TRANSACTION_STATUS = 0

    Card Brand Card Number Risk Indicator
    MasterCard 5200000000000064 Not Applicable (XX)

    Invalid Card Number

    RESULT_CODE = 900004; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    For credit card payment method - all other card numbers Not Applicable (XX)

    Miscellaneous Information

    Error Codes

    Code Description
    DATA_CHK Checksum calculated incorrectly
    DATA_PAY_REQ_ID Pay request ID missing or invalid
    ND_INV_PGID Invalid PayGate ID
    ND_INV_PRID Invalid Pay Request ID
    PGID_NOT_EN PayGate ID not enabled, there are no available payment methods or there are no available currencies
    TXN_CAN Transaction has already been cancelled
    TXN_CMP Transaction has already been completed
    TXN_PRC Transaction is older than 30 minutes or there has been an error processing it

    MasterCard SecureCode & Verified-by-Visa

    What is SecureCode and Verified by Visa?
    SecureCode and Verified by Visa is a MasterCard and Visa initiative to reduce online credit card transaction fraud. (It applies to Master and Visa cards only). The Visa implementation is referred to as Verified by Visa or V-by-V. The MasterCard implementation is referred to as MasterCard Secure Code.

    How does SecureCode and Verified by Visa benefit the merchant?
    It significantly reduces the risk of fraudulent transactions, and moves the risk of certain charge backs from the merchant to the card holder or the Issuing Bank. (Note – there are instances where the charge back risk remains with the merchant – this is detailed in the flowchart below).

    How Does SecureCode and Verified by Visa work?
    When a purchase is made online, the cardholder will be re-directed from the secure PayGate payment page, to the issuing bank’s (cardholder’s bank) SecureCode and Verified by Visa authentication page. Here the cardholder will be required to key in his/her authentication details (e.g. secret PIN code). The Issuing Bank validates this code and returns an 'OK' or 'not OK' response to PayGate. If PayGate receives an 'OK' response then we pass the transaction on to the Acquiring Bank for Authorisation. If the response is 'not OK' then the transaction is ‘Declined’ up front by PayGate.

    It should however be noted that not all Issuing Banks will force their cardholders to register for this service. Where this is the case, a re-direct will still take place to the issuing bank’s website but in this case the transaction will not be authenticated. The message code returned will however indicate that you as a merchant attempted to authenticate the transaction and that the issuing bank is not registered for the service. The transaction will be processed as a SecureCode and Verified by Visa transaction i.e. the risk will be passed to the issuing bank.

    What about the other cards (AMEX, Diners etc.)?
    These cards are not authenticated via the SecureCode and Verified by Visa process. At this time transaction risk for purchases made with cards other than Master and Visa, will remain with the merchant.

    PayBatch

    Introduction

    Batched transactions can be submitted manually via the Merchant Access Portal or by using the webservice web services.

    This document describes the process for uploading using the Merchant Access Portal file input/output specifications as well as the webservice message formats.

    Merchant Access Portal Processing

    Batch Manager

    This screen will display the last few submitted files. A link on the filename will open a new window to display specific processing results (ie. Number of approved/settled/refunded transactions & number of declines in the case of auths). When the batch is complete, a user will be able to click on a link to download the results file.

    PayBatch Manager

    New File Upload

    Allows a user to upload a new file; the user will also need to specify the type of transactions in the file.

    PayBatch File Upload

    A File containing errors

    The file is validated to detect any simple errors (ie. Invalid expiry date; incorrect format etc.). If errors are found, the batch management system will alert the user to the position in the file where the error is. PayGate will not accept a file that has simple errors. Errors that PayGate cannot scan for initially are invalid card numbers; funds not available etc. These errors are returned by the bank and will be noted once the batch starts processing.

    PayBatch File Invalid

    A Valid File

    This screen displays the total transaction amount and transaction count for the submitted file. The user must now confirm that this file must be submitted for processing. If the user closes the window or clicks on ‘Reset’, the file will not be processed. If the system detects that this file has been processed before, then the user is alerted.

    PayBatch File Valid

    Confirmation

    The confirmation screen displayed to the user.

    PayBatch File Confirmation

    Web Service

    Integration Options

    The PayBatch webservice can be used in any environment that allows data to be transferred over a HTTPS connection. SOAP is used as the message transport language for The PayBatch webservice. A merchant can integrate into The PayBatch webservice using any programming language that supports SOAP calls.

    Some suggested programming languages are:

    Endpoints

    All messages for the PayBatch webservice must be posted to:

    POST https://secure.paygate.co.za/paybatch/1.2/process.trans

    The WSDL for the PayBatch webservice is:

    GET https://secure.paygate.co.za/paybatch/1.2/PayBatch.wsdl

    Authentication

    Example header

    Authorization: Basic MTAwMTEwNzIxMzA6dGVzdA==
    

    Authentication for the service is done via standard HTTP Basic Authentication using the PayGateID as the username, and your encryption key as the password.

    Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

    Transaction Flow

    Auth Confirm Query

    Settle Confirm Query

    Refund Confirm Query

    Batch Line Format

    Example of an authorization batch line

    A, transaction_reference, Joe Soap, 18566ddc-b13b-4c9f-9e88-9a2f9a9dd64a, 00, 1000
    

    The standard format for submitting a transaction

    A comma separated string is used as the batch line, with the following details:

    Position Value Type
    1 Type of transaction (A = Authorisation, S = Settlement, R = Refund) enum
    2 The transaction reference string
    3 Card holder name string
    4 Vault ID of the card to be processed string
    5 The budget period the transaction should be processed with integer (2 digits)
    6 The amount of the transaction (in cents) integer

    Message Types

    Legend

    Type Description
    Mandatory Field
    Optional field depending on context
    Not required

    BatchLine

    Example of a Batch Line

    <!--One or more repetitions:-->
    <BatchLine>A, transaction_reference, Joe Soap, 18566ddc-b13b-4c9f-9e88-9a2f9a9dd64a, 00, 1000</BatchLine>
    
    Field Description Type Required
    BatchLine This field contains the data for a single transaction in the batch, according to the required format. string

    InvalidReason

    Example of InvalidReason

    <!--One or more repetitions:-->
    <InvalidReason>
        <Line>2</Line>
        <Reason>VaultId Not Valid</Reason>
    </InvalidReason>
    
    Field Description Type Required
    Line The line number containing the invalid transaction integer
    Reason The reason for the invalid transaction string

    Auth Request

    A batch request containing authorization transactions

    <Auth>
        <BatchReference>batch_reference</BatchReference>
        <NotificationUrl>http://www.mywebsite.com/notify</NotificationUrl>
        <BatchData>
            (BatchLine)
        </BatchData>
    </Auth>
    
    <?php
    
    $batchReference  = 'AuthBatch201800101';
    $notificationUrl = 'http://yourserver.co.za/notifylocation/';
    
    ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
    
    try {
        //use SimpleXmlElement for better control of children
        $xml = new SimpleXMLElement('<Auth />');
    
        $xml->addChild('BatchReference', $batchReference);
        $xml->addChild('NotificationUrl', $notificationUrl);
    
        $batchData = $xml->addChild('BatchData');
    
        $batchData->addChild('BatchLine', 'A, test1, PayGate Test, 18566ddc-b13b-4c9f-9e88-9a2f9a9dd64a, 00, 100');
    
        //use DomDocument to remove XML headers
        $dom = new DOMDocument();
        $dom->loadXML($xml->asXML());
    
        $soap = $dom->saveXML($dom->documentElement);
    
        //Remove Auth tag because we pass it in the __soapCall
        $childrenOnly = str_replace(['<Auth>', '</Auth>'], '', $soap);
    
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    // array containing login and password for basic http auth, along with trace option for debugging
    $options = array(
        'login'    => '10011072130', //Your PayGate ID
        'password' => 'test',        //Your encryption key (set in the PayXML configuration section of the PayGate Back Office)
        'trace'    => 1
    );
    
    try {
        $soapClient = new SoapClient("https://secure.paygate.co.za/PayBatch/1.2/PayBatch.wsdl", $options); //point to WSDL and set options
        $soapClient->__setLocation("https://secure.paygate.co.za/PayBatch/1.2/process.trans"); //actual location data is processed
    
        $result = $soapClient->__soapCall('Auth', array(
            new SoapVar($childrenOnly, XSD_ANYXML)
        ));
    
        // $result is an object of AuthResponse
        var_dump($result);
    
    } catch(SoapFault $sf){
        var_dump($sf->getMessage());
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    Field Description Type Required
    BatchReference This field contains the reference for the submitted batch string
    NotificationUrl The Notification URL. This is the URL on your site that PayBatch will post the batch results to. string
    BatchData Contains a complex type of Batch Lines BatchLine

    Auth Response

    The response received from the webservice for an Authorization batch

    <AuthResponse>
        <Return>
            <Total>1</Total>
            <Valid>1</Valid>
            <Invalid>0</Invalid>
            <UploadID>292cd489f5afe15cbd362bddfde0b3bc</UploadID>
            <Message/>
        </Return>
    </AuthResponse>
    
    Field Description Type Required
    Total The total number of transactions in the batch integer
    Valid The number of valid transactions in the batch integer
    Invalid The number of invalid transactions in the batch integer
    InvalidReason If Invalid transactions are picked up in the batch, this is returned InvalidReason
    UploadID The ID assigned to the submitted batch request string
    Message optional

    Settle Request

    A batch request containing settlement transactions

    <Settle>
        <BatchReference>batch_reference</BatchReference>
        <NotificationUrl>http://www.mywebsite.com/notify</NotificationUrl>
        <BatchData>
            (BatchLine)
        </BatchData>
    </Settle>
    
    <?php
    
    $batchReference  = 'SettleBatch201800101';
    $notificationUrl = 'http://yourserver.co.za/notifylocation/';
    
    ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
    
    try {
        //use SimpleXmlElement for better control of children
        $xml = new SimpleXMLElement('<Settle />');
    
        $xml->addChild('BatchReference', $batchReference);
        $xml->addChild('NotificationUrl', $notificationUrl);
    
        $batchData = $xml->addChild('BatchData');
    
        $batchData->addChild('BatchLine', 'S, test1, PayGate Test, 18566ddc-b13b-4c9f-9e88-9a2f9a9dd64a, 00, 100');
    
        //use DomDocument to remove XML headers
        $dom = new DOMDocument();
        $dom->loadXML($xml->asXML());
    
        $soap = $dom->saveXML($dom->documentElement);
    
        //Remove Settle tag because we pass it in the __soapCall
        $childrenOnly = str_replace(['<Settle>', '</Settle>'], '', $soap);
    
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    // array containing login and password for basic http auth, along with trace option for debugging
    $options = array(
        'login'    => '10011072130', //Your PayGate ID
        'password' => 'test',        //Your encryption key (set in the PayXML configuration section of the PayGate Back Office)
        'trace'    => 1
    );
    
    try {
        $soapClient = new SoapClient("https://secure.paygate.co.za/PayBatch/1.2/PayBatch.wsdl", $options); //point to WSDL and set options
        $soapClient->__setLocation("https://secure.paygate.co.za/PayBatch/1.2/process.trans"); //actual location data is processed
    
        $result = $soapClient->__soapCall('Settle', array(
            new SoapVar($childrenOnly, XSD_ANYXML)
        ));
    
        // $result is an object of SettleResponse
        var_dump($result);
    
    } catch(SoapFault $sf){
        var_dump($sf->getMessage());
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    Field Description Type Required
    BatchReference This field contains the reference for the submitted batch string
    NotificationUrl The Notification URL. This is the URL on your site that PayBatch will post the batch results to. string
    BatchData Contains a complex type of Batch Lines BatchLine

    Settle Response

    The response received from the webservice for a Settlement batch

    <SettleResponse>
        <Return>
            <Total>1</Total>
            <Valid>1</Valid>
            <Invalid>0</Invalid>
            <UploadID>729600eb419b6c2affffc7bd8a5bd7e6</UploadID>
            <Message/>
        </Return>
    </SettleResponse>
    
    Field Description Type Required
    Total The total number of transactions in the batch integer
    Valid The number of valid transactions in the batch integer
    Invalid The number of invalid transactions in the batch integer
    InvalidReason If Invalid transactions are picked up in the batch, this is returned InvalidReason
    UploadID The ID assigned to the submitted batch request string
    Message optional

    Refund Request

    A batch request containing refund transactions

    <Refund>
        <BatchReference>batch_reference</BatchReference>
        <NotificationUrl>http://www.mywebsite.com/notify</NotificationUrl>
        <BatchData>
            (BatchLine)
        </BatchData>
    </Refund>
    
    <?php
    
    $batchReference  = 'RefundBatch201800101';
    $notificationUrl = 'http://yourserver.co.za/notifylocation/';
    
    ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
    
    try {
        //use SimpleXmlElement for better control of children
        $xml = new SimpleXMLElement('<Refund />');
    
        $xml->addChild('BatchReference', $batchReference);
        $xml->addChild('NotificationUrl', $notificationUrl);
    
        $batchData = $xml->addChild('BatchData');
    
        $batchData->addChild('BatchLine', 'R, test1, PayGate Test, 18566ddc-b13b-4c9f-9e88-9a2f9a9dd64a, 00, 100');
    
        //use DomDocument to remove XML headers
        $dom = new DOMDocument();
        $dom->loadXML($xml->asXML());
    
        $soap = $dom->saveXML($dom->documentElement);
    
        //Remove Refund tag because we pass it in the __soapCall
        $childrenOnly = str_replace(['<Refund>', '</Refund>'], '', $soap);
    
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    // array containing login and password for basic http auth, along with trace option for debugging
    $options = array(
        'login'    => '10011072130', //Your PayGate ID
        'password' => 'test',        //Your encryption key (set in the PayXML configuration section of the PayGate Back Office)
        'trace'    => 1
    );
    
    try {
        $soapClient = new SoapClient("https://secure.paygate.co.za/PayBatch/1.2/PayBatch.wsdl", $options); //point to WSDL and set options
        $soapClient->__setLocation("https://secure.paygate.co.za/PayBatch/1.2/process.trans"); //actual location data is processed
    
        $result = $soapClient->__soapCall('Refund', array(
            new SoapVar($childrenOnly, XSD_ANYXML)
        ));
    
        // $result is an object of RefundResponse
        var_dump($result);
    
    } catch(SoapFault $sf){
        var_dump($sf->getMessage());
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    Field Description Type Required
    BatchReference This field contains the reference for the submitted batch string
    NotificationUrl The Notification URL. This is the URL on your site that PayBatch will post the batch results to. string
    BatchData Contains a complex type of Batch Lines BatchLine

    Refund Response

    The response received from the webservice for a Refund batch

    <RefundResponse>
        <Return>
            <Total>1</Total>
            <Valid>1</Valid>
            <Invalid>0</Invalid>
            <UploadID>729600eb419b6c2affffc7bd8a5bd7e6</UploadID>
            <Message/>
        </Return>
    </RefundResponse>
    
    Field Description Type Required
    Total The total number of transactions in the batch integer
    Valid The number of valid transactions in the batch integer
    Invalid The number of invalid transactions in the batch integer
    InvalidReason If Invalid transactions are picked up in the batch, this is returned InvalidReason
    UploadID The ID assigned to the submitted batch request string
    Message optional

    Confirm Request

    <Confirm>
        <UploadID>292cd489f5afe15cbd362bddfde0b3bc</UploadID>
    </Confirm>
    
    <?php
    
    $uploadId = '292cd489f5afe15cbd362bddfde0b3bc';
    
    ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
    
    try {
        //use SimpleXmlElement for better control of children
        $xml = new SimpleXMLElement('<Confirm />');
    
        $xml->addChild('UploadID', $uploadId);
    
        //use DomDocument to remove XML headers
        $dom = new DOMDocument();
        $dom->loadXML($xml->asXML());
    
        $soap = $dom->saveXML($dom->documentElement);
    
        //Remove Confirm tag because we pass it in the __soapCall
        $childrenOnly = str_replace(['<Confirm>', '</Confirm>'], '', $soap);
    
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    // array containing login and password for basic http auth, along with trace option for debugging
    $options = array(
        'login'    => '10011072130', //Your PayGate ID
        'password' => 'test',        //Your encryption key (set in the PayXML configuration section of the PayGate Back Office)
        'trace'    => 1
    );
    
    try {
        $soapClient = new SoapClient("https://secure.paygate.co.za/PayBatch/1.2/PayBatch.wsdl", $options); //point to WSDL and set options
        $soapClient->__setLocation("https://secure.paygate.co.za/PayBatch/1.2/process.trans"); //actual location data is processed
    
        $result = $soapClient->__soapCall('Confirm', array(
            new SoapVar($childrenOnly, XSD_ANYXML)
        ));
    
        // $result is an object of ConfirmResponse
        var_dump($result);
    
    } catch(SoapFault $sf){
        var_dump($sf->getMessage());
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    Field Description Type Required
    UploadID The ID of the batch submitted via Auth / Settle / Refund string

    Confirm Response

    <ConfirmResponse>
        <Return>
            <Total>1</Total>
            <Valid>1</Valid>
            <Invalid>0</Invalid>
            <UploadID>292cd489f5afe15cbd362bddfde0b3bc</UploadID>
            <Message/>
        </Return>
    </ConfirmResponse>
    
    Field Description Type Required
    Total The total number of transactions in the batch integer
    Valid The number of valid transactions in the batch integer
    Invalid The number of invalid transactions in the batch integer
    InvalidReason If Invalid transactions are picked up in the batch, this is returned InvalidReason
    UploadID The ID assigned to the submitted batch request string
    Message optional

    Query Request

    <Confirm>
        <UploadID>292cd489f5afe15cbd362bddfde0b3bc</UploadID>
    </Confirm>
    
    <?php
    
    $uploadId = '292cd489f5afe15cbd362bddfde0b3bc';
    
    ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
    
    try {
        //use SimpleXmlElement for better control of children
        $xml = new SimpleXMLElement('<Query />');
    
        $xml->addChild('UploadID', $uploadId);
    
        //use DomDocument to remove XML headers
        $dom = new DOMDocument();
        $dom->loadXML($xml->asXML());
    
        $soap = $dom->saveXML($dom->documentElement);
    
        //Remove Confirm tag because we pass it in the __soapCall
        $childrenOnly = str_replace(['<Query>', '</Query>'], '', $soap);
    
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    // array containing login and password for basic http auth, along with trace option for debugging
    $options = array(
        'login'    => '10011072130', //Your PayGate ID
        'password' => 'test',        //Your encryption key (set in the PayXML configuration section of the PayGate Back Office)
        'trace'    => 1
    );
    
    try {
        $soapClient = new SoapClient("https://secure.paygate.co.za/PayBatch/1.2/PayBatch.wsdl", $options); //point to WSDL and set options
        $soapClient->__setLocation("https://secure.paygate.co.za/PayBatch/1.2/process.trans"); //actual location data is processed
    
        $result = $soapClient->__soapCall('Query', array(
            new SoapVar($childrenOnly, XSD_ANYXML)
        ));
    
        // $result is an object of QueryResponse
        var_dump($result);
    
    } catch(SoapFault $sf){
        var_dump($sf->getMessage());
    } catch(Exception $e){
        error_log($e->getMessage());
    }
    
    Field Description Type Required
    UploadID The ID of the batch submitted via Auth / Settle / Refund string

    Query Response

    Example of a query on a batch that is still processing

    <QueryResponse>
        <Return>
            <Reference>batch_reference</Reference>
            <DateUploaded>2018-01-01 12:00:00</DateUploaded>
            <DateCompleted>Still Processing</DateCompleted>
            <Success>0</Success>
            <Fail>0</Fail>
            <Unprocessed>1</Unprocessed>
        </Return>
    </QueryResponse>
    

    Example of a query on a completed batch

    <QueryResponse>
    <Return>
        <Reference>batch_reference</Reference>
        <DateUploaded>2018-01-01 12:00:00</DateUploaded>
        <DateCompleted>2018-01-01 19:08:04</DateCompleted>
        <Success>1</Success>
        <Fail>0</Fail>
        <Unprocessed>0</Unprocessed>
        <TransResult>71737522,A,transaction_reference,123456,1,Approved,990017,Auth Done</TransResult>
    </Return>
    </QueryResponse>
    
    
    Field Description Type Required
    Reference This field contains the reference for the submitted batch string
    DateUploaded The date and time the batch was uploaded string
    DateCompleted The date and time all the transactions in the batch finished processing string
    Success The number of successful transactions in the batch integer
    Fail The number of failed transactions in the batch integer
    Unprocessed The number of unprocessed transactions in the batch integer
    TransResult This field contains the data for a single transaction in the batch, according to the result format. string

    Transaction Result Format

    Example of a transaction result line

    71737522,A,transaction_reference,123456,1,Approved,990017,Auth Done
    

    The standard format for a transaction result line

    A comma separated string is used as the TransResult, with the following details:

    Position Value Type
    1 Transaction ID integer
    2 The transaction type (A = Authorisation, S = Settlement, R = Refund) enum
    3 The transaction reference string
    4 Auth code returned by the bank string
    5 Transaction status code integer
    6 Transaction status description string
    7 Transaction result code integer
    8 Trasnaction result description string

    Testing

    Run in Postman

    PaySubs

    Introduction

    PaySubs is effectively a 'debit order via credit card' system. If you are selling a product or service whereby your customer will be billed a fixed amount over a predetermined period at regular intervals – then PaySubs is ideal. All credit card data is stored on the PayGate system, so it takes the management and security hassle away from the merchant. The merchant is able to manage his subscriptions via the PayGate Back Office interface. The merchant can capture new subscriptions manually via the Back Office. However it is often more practical for the client to key in his details directly – i.e. for the client to create the subscription when (s)he purchases the product or service from the merchants web site. The PaySubs Web Interface enables the merchant to redirect the client to the PaySubs Web Interface page to conclude this transaction.

    What Are The Benefits

    1. The setup process is relatively simple and can be easily integrated into existing web sites.
    2. The merchant doesn’t require a SSL certificate to capture the credit card details as PayGate provides this.
    3. All sensitive credit card information is stored on PayGate's secure servers.
    4. The merchant does not have to submit (and manage) batches of card data to PayGate periodically.
    5. PaySubs can be customised to suit the look & feel of your web site.

    Request and Response data

    This section describes in detail the fields sent to PaySubs and the fields returned by PaySubs.

    Legend

    Type Description
    Mandatory Field
    Optional field depending on context
    Not required

    Endpoints

    Step Url
    Redirect https://www.paygate.co.za/paysubs/process.trans

    How to get it working

    There are 2 steps when connecting a web site to PaySubs. The 1st step is sending the request to PaySubs to show the subscription screen to the customer. The 2nd step involves collecting the results of the transaction from PayGate.

    Redirect

    REDIRECT https://www.paygate.co.za/paysubs/process.trans

    Re-direct client to PaySubs with necessary fields

    All information sent to PaySubs must be in hidden form fields, which are posted to the PaySubs web page.

    An example redirect form

    <form action="https://www.paygate.co.za/paysubs/process.trans" method="POST" >
        <input type="hidden" name="VERSION" value="21">
        <input type="hidden" name="PAYGATE_ID" value="10011072130">
        <input type="hidden" name="REFERENCE" value="Customer1">
        <input type="hidden" name="AMOUNT" value="3299">
        <input type="hidden" name="CURRENCY" value="ZAR">
        <input type="hidden" name="RETURN_URL" value="http://localhost">
        <input type="hidden" name="TRANSACTION_DATE" value="2018-06-30 18:30">
        <input type="hidden" name="SUBS_START_DATE" value="2018-07-01">
        <input type="hidden" name="SUBS_END_DATE" value="2019-06-30">
        <input type="hidden" name="SUBS_FREQUENCY" value="228">
        <input type="hidden" name="PROCESS_NOW" value="NO">
        <input type="hidden" name="PROCESS_NOW_AMOUNT" value="">
        <input type="hidden" name="CHECKSUM" value="f672dfced5732fd4c8dc58e2a4c6ce78">
    </form>
    
    Field Description Type Required
    VERSION This field contains the version number for the PaySubs Web Interface specification. To conform to this document, the version should be 21. number
    PAYGATE_ID Your PayGateID – assigned by PayGate varchar(20)
    REFERENCE This is your reference number for use by your internal systems varchar(110)
    AMOUNT This is the subscription amount that will be applied to the transaction each time the subscription is processed. This amount can be overridden (one time only) by the PROCESS_NOW_AMOUNT if the PROCESS_NOW field is set to “YES”. The amount must be in the lowest denomination (i.e. cents). e.g. 32.99 is specified as 3299 varchar(20)
    CURRENCY This is for future use and for the moment must be set to South African Rands (ZAR). varchar(3)
    RETURN_URL Once the transaction is completed, PaySubs will return the customer to a page on your web site. The page the customer must see is specified in this field. varchar(255)
    TRANSACTION_DATE This is the date that the transaction was initiated on your website or system. The transaction date must be specified in 'Coordinated Universal Time' (UTC) e.g. 2016-05-30 09:30 datetime
    EMAIL The email address of your customer is optional; if it is not supplied, PaySubs will prompt the customer for their email address when entering their credit card details. If the transaction is approved, PaySubs will email a payment confirmation to this email address. If the email address is supplied, it must be included in the CHECKSUM calculation described below. varchar(255)
    SUBS_START_DATE This is the date from which the subscription becomes valid. By specifying a future date you are able to load transactions immediately to be processed at a future date. Specifying today's date or earlier, means that the subscription is immediately within its 'active period' but it will only generate a transaction when the SUBS_FREQUENCY is a match. The data format should be ‘YYYY-MM-DD’ with no time specified. date
    SUBS_END_DATE This is the date when the subscription expires and becomes invalid. This must be a future date. The data format should be 'YYYY-MM-DD' with no time specified. date
    SUBS_FREQUENCY This code specifies the date on which to process the transaction and the frequency with which transactions are processed (daily, weekly, monthly etc). Refer to the Subscription Frequency section number
    PROCESS_NOW This flag indicates if a transaction should be processed immediately. A value of "YES" will process a transaction immediately. A value of "NO" indicates that a transaction must not be processed immediately. This is useful if you want to get your first payment immediately and second and subsequent payments at future intervals. varchar(3)
    PROCESS_NOW_AMOUNT If PROCESS_NOW is “YES” then this field must contain a valid amount. This is the amount that will be deducted from your customer’s card immediately and can be different from the AMOUNT field. If PROCESS_NOW is “NO” then this field should be blank. This amount must be in the lowest denomination (i.e. cents). varchar(20)
    CHECKSUM This field contains a calculated MD5 hash based on the values of ALL the above-mentioned fields and a key. Refer to the section on Security below for more detail regarding the MD5 hash. varchar(40)

    Return to Merchant

    PaySubs redirects the client back to the ‘RETURN_URL’ provided by the merchant in the request.

    Field Description
    PAYGATE_ID This should be the same PayGate ID that was passed in the request; if it is not, then the data has been altered.
    REFERENCE This should be the same reference that was passed in the request; if it is not, then the data has been altered.
    TRANSACTION_STATUS The final status of the transaction. Refer to the Transaction Codes section for possible values.
    RESULT_CODE This field contains a code indicating the result of the transaction. Refer to the Result Code section for a complete list. The description corresponding to this code is in the RESULT_DESC field.
    AUTH_CODE If the PROCESS_NOW field is "YES" and the bank approves the transaction, then the authorisation code will be placed in this field. This is the merchants guarantee that the funds are available on the customers credit card. If the PROCESS_NOW field is "NO" then this field will be empty.
    AMOUNT This field will contain the amount that was used for the transaction. If the PROCESS_NOW field is set to “NO” then this field contains the AMOUNT passed in the request. If the PROCESS_NOW field is set to “YES” then this field contains the PROCESS_NOW_AMOUNT passed in the request.
    RESULT_DESC This field contains a description for the result of the transaction. Refer to the Result Code section for a complete list. The numeric code corresponding to this description is in the RESULT_CODE field.
    TRANSACTION_ID This field contains the PayGate unique reference number for the transaction. It will by empty if the PROCESS_NOW field is "NO".
    SUBSCRIPTION_ID This field contains the PayGate unique reference number for the subscription. In the case of a transaction (if PROCESS_NOW is “YES”) not being successful then the Subscription record will not be written and this field will be empty.
    RISK_INDICATOR This is a 2-character field containing a risk indicator for this transaction. The first character describes the Verified-by-Visa / MasterCard SecureCode authentication; refer to the Authentication Indicator table for the possible values. The second character is for future use and will be set to ‘X’. Please (refer to the MasterCard SecureCode & Verified by Visa section for more info. If the PROCESS_NOW is “NO” then the transaction will not be authenticated and this field will contain “XX”.
    CHECKSUM The MD5 hash calculation of all the response fields including the key known only to the merchant and PayGate. You should do the same calculation when you receive the response to ensure that the data has not been tampered with. Refer to the section on Security below for more detail regarding the MD5 hash.

    Security

    Security is enhanced by making use of an MD5 checksum value that is passed in both the request to PaySubs and the response from PaySubs.

    The checksum in all cases is calculated by concatenating all the fields in the relevant 'step', separated by a pipe character |.

    An Encryption Key is appended and the resulting string is passed through an MD5 hash algorithm to produce the checksum. When PayGate receives the PaySubs request, the same checksum calculation is performed. If the PayGate checksum does not match the checksum specified in the request, the transaction is rejected.

    MD5 is a one-way hashing algorithm. Simply stated, input of any length supplied to the function produces a fixed length (in this case 32 characters) output so that the original input is not recognizable. It is impossible to reverse; i.e. giving the function the result will not give you the original source. Most programming languages support the MD5 function; if not native support then by a module or extension.

    The Encryption Key used in the checksum calculation should only be known by the merchants’ website and PayGate. It should not be displayed on any web page i.e. a customer should never be able to see it. PayGate allows for the Encryption Key to be a maximum of 32 alphanumeric characters. The longer and more complex the key is, the harder it is for a malicious user to guess it.

    Checksum

    Request Example

    Empty optional fields:

    echo -n "21|10011072130|pgtest_123456789|3299|ZAR|https://my.return.url/page|2018-06-30 18:30|2018-07-01|2019-06-30|228|NO||secret" | md5sum
    
    <?php
    $encryptionKey = 'secret';
    
    $data = array(
        'VERSION'            => 21,
        'PAYGATE_ID'         => 10011072130,
        'REFERENCE'          => 'pgtest_123456789',
        'AMOUNT'             => 3299,
        'CURRENCY'           => 'ZAR',
        'RETURN_URL'         => 'https://my.return.url/page',
        'TRANSACTION_DATE'   => '2018-06-30 18:30',
        'SUBS_START_DATE'    => '2018-07-01',
        'SUBS_END_DATE'      => '2019-06-30',
        'SUBS_FREQUENCY'     => 228,
        'PROCESS_NOW'        => 'NO',
        'PROCESS_NOW_AMOUNT' => ''
    );
    
    $checksum = md5(implode('|', $data) . $encryptionKey);
    /*
    equivalent to
    
    $checksum = md5('21|10011072130|pgtest_123456789|3299|ZAR|https://my.return.url/page|2018-06-30 18:30|2018-07-01|2019-06-30|228|NO||secret');
    */
    

    The above command returns a checksum value of

    c659dacf1ce76032b28ac7131fcf613c 
    

    All fields including the optional fields are concatenated (separated with the | character) to form the source of the MD5 hash:

    VERSION + | + PAYGATE_ID + | + REFERENCE + | + AMOUNT + | + CURRENCY + | + RETURN_URL + | + TRANSACTION_DATE + | + EMAIL + | + SUBS_START_DATE + | + SUBS_END_DATE + | + SUBS_FREQUENCY + | + PROCESS_NOW + | + PROCESS_NOW_AMOUNT + | + KEY

    Assuming the KEY is ‘secret’, the following scenarios are possible:

    21|10011072130|pgtest_123456789|3299|ZAR|https://my.return.url/page|2018-06-30 18:30|2018-07-01|2019-06-30|228|NO||secret

    NOTIFY_URL and USER1 fields populated:

    echo -n "21|10011072130|pgtest_123456789|3299|ZAR|https://my.return.url/page|2018-06-30 18:30|customer@paygate.co.za|2018-07-01|2019-06-30|228|YES|3299|secret" | md5sum
    
    <?php
    $encryptionKey = 'secret';
    
    $data = array(
        'VERSION'            => 21,
            'PAYGATE_ID'         => 10011072130,
            'REFERENCE'          => 'pgtest_123456789',
            'AMOUNT'             => 3299,
            'CURRENCY'           => 'ZAR',
            'RETURN_URL'         => 'https://my.return.url/page',
            'TRANSACTION_DATE'   => '2018-06-30 18:30',
            'EMAIL'              => 'customer@paygate.co.za',
            'SUBS_START_DATE'    => '2018-07-01',
            'SUBS_END_DATE'      => '2019-06-30',
            'SUBS_FREQUENCY'     => 228,
            'PROCESS_NOW'        => 'YES',
            'PROCESS_NOW_AMOUNT' => '3299'
    );
    
    $checksum = md5(implode('|', $data) . $encryptionKey);
    
    /*
    equivalent to
    
    $checksum = md5('21|10011072130|pgtest_123456789|3299|ZAR|https://my.return.url/page|2018-06-30 18:30|customer@paygate.co.za|2018-07-01|2019-06-30|228|YES|3299|secret');
    */
    

    The above calculations return a checksum value of

    c0e2feb88e21e5422449b6aba47b80eb 
    

    21|10011072130|pgtest_123456789|3299|ZAR|https://my.return.url/page|2018-06-30 18:30|customer@paygate.co.za|2018-07-01|2019-06-30|228|YES|3299|secret


    Testing

    Credentials

    Description Value
    PayGate ID 10011072130
    Password secret
    Currencies ZAR, EUR, USD

    Please refer to the tables below when testing to simulate predictable results:

    Approved Transactions

    RESULT_CODE = 990017; TRANSACTION_STATUS = 1

    Card Brand Card Number Risk Indicator
    Visa 4000000000000002 Authenticated (AX) *
    MasterCard 5200000000000015 Authenticated (AX)
    American Express 378282246310005 Not Authenticated (NX)

    Insufficient Funds Transactions

    RESULT_CODE = 900003; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    MasterCard 5200000000000023 Not Authenticated (NX) *
    Visa 4000000000000028 Not Authenticated (NX)
    American Express 371449635398431 Not Authenticated (NX)

    Declined Transactions

    RESULT_CODE = 900007; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    Visa 4000000000000036 Authenticated (AX) *
    MasterCard 5200000000000049 Authenticated (AX) *
    Diners Club 30569309025904 Not Applicable (XX)

    Unprocessed Transactions

    RESUT_CODE = 990022; TRANSACTION_STATUS = 0

    Card Brand Card Number Risk Indicator
    MasterCard 5200000000000064 Not Applicable (XX)

    Invalid Card Number

    RESULT_CODE = 900004; TRANSACTION_STATUS = 2

    Card Brand Card Number Risk Indicator
    For credit card payment method - all other card numbers Not Applicable (XX)

    Miscellaneous Information

    Error Codes

    Code Description
    DATA_AMT_NUM Amount is not a number
    DATA_AMT_ZERO Amount value is zero
    DATA_CHK Checksum calculated incorrectly
    DATA_CREF No transaction reference
    DATA_PS_CUR Invalid Currency
    DATA_PS_PNAS Process Now set as "no" but Process Now Amount supplied
    DATA_PS_PYNAS Process Now set as "yes" but Process Now Amount not supplied
    DATA_PS_PNAMT_NUM Process Now Amount not a valid number
    DATA_PS_PNAMT_ZERO Process Now Amount is zero
    DATA_DTTM Transaction date invalid
    DATA_INS Error creating record for transaction request
    DATA_PS Not all required fields have been posted to PaySubs
    DATA_PS_PROC Incorrect Value for Process field
    DATA_PS_VER Incorrect version
    DATA_URL No return url
    ND_INV_PGID Invalid PayGate ID
    NOT_LIVE_PM No available payment methods
    NO_TRANS_DATA No transaction data found
    PAYSUBS_VAL_ERR Date ranges not valid
    PGID_NOT_EN PayGate ID not enabled, there are no available payment methods or there are no available currencies
    TXN_CAN Transaction has already been cancelled
    TXN_CMP Transaction has already been completed
    TXN_PRC Transaction is older than 30 minutes or there has been an error processing it

    MasterCard SecureCode & Verified-by-Visa

    What is SecureCode and Verified by Visa?
    SecureCode and Verified by Visa is a MasterCard and Visa initiative to reduce online credit card transaction fraud. (It applies to Master and Visa cards only). The Visa implementation is referred to as Verified by Visa or V-by-V. The MasterCard implementation is referred to as MasterCard Secure Code.

    How does SecureCode and Verified by Visa benefit the merchant?
    It significantly reduces the risk of fraudulent transactions, and moves the risk of certain charge backs from the merchant to the card holder or the Issuing Bank. (Note – there are instances where the charge back risk remains with the merchant – this is detailed in the flowchart below).

    A typical credit card authorisation flow including PayProtector and 3D Credit Card Authorisation Process Flow

    How Does SecureCode and Verified by Visa work?
    When a purchase is made online, the cardholder will be re-directed from the secure PayGate payment page, to the issuing bank’s (cardholder’s bank) SecureCode and Verified by Visa authentication page. Here the cardholder will be required to key in his/her authentication details (e.g. secret PIN code). The Issuing Bank validates this code and returns an 'OK' or 'not OK' response to PayGate. If PayGate receives an 'OK' response then we pass the transaction on to the Acquiring Bank for Authorisation. If the response is 'not OK' then the transaction is ‘Declined’ up front by PayGate.

    It should however be noted that not all Issuing Banks will force their cardholders to register for this service. Where this is the case, a re-direct will still take place to the issuing bank’s website but in this case the transaction will not be authenticated. The message code returned will however indicate that you as a merchant attempted to authenticate the transaction and that the issuing bank is not registered for the service. The transaction will be processed as a SecureCode and Verified by Visa transaction i.e. the risk will be passed to the issuing bank.

    What about the other cards (AMEX, Diners etc.)?
    These cards are not authenticated via the SecureCode and Verified by Visa process. At this time transaction risk for purchases made with cards other than Master and Visa, will remain with the merchant.

    Frequently Asked Questions

    How do I know the transaction is approved?

    You can check up to 3 fields in the response depending on how thorough you want to be. At a minimum, you should check the TRANSACTION_STATUS field: it will contain the value “1”. If you want to check further, the RESULT_CODE field should contain the value “990017” and the AUTH_CODE field should not be blank.

    If the PROCESS_NOW field is set to "NO" then this value will be 5 to indicate that the transaction has been successfully received (and loaded) by PayGate. If the PROCESS_NOW field is set to "YES" then this value will be 1 to indicate a successful transaction or 2 to indicate that the transaction was Declined by the bank.

    What response is returned if the customer clicks the ‘Cancel’ button on the PaySubs payment page?

    How will I know that I the transaction was authenticated and I have charge back protection?

    When your website receives the transaction results from PayGate, it should check the first character of the RISK_INDICATOR field. If the first character is ‘A’ then your customer has been authenticated and cannot initiate a charge back. If the first character is ‘N’ then the transaction has been declined or approved but not authenticated; you should take further steps to ensure that you are dealing with the legitimate card holder.

    The transaction was authenticated and declined; how can this be?

    PayGate attempts to authenticate the cardholder before sending the transaction to the bank for authorisation. Therefore, even if the cardholder is authenticated through MasterCard SecureCode or Verified-by-Visa, the bank could still decline the transaction due to insufficient funds etc.

    Is it possible to not use Verified-by-Visa and MasterCard SecureCode?

    3D Secure is mandatory for e-commerce transactions in many countries and acquiring banks may only issue acquiring accounts that have been 3D Secure registered. PayGate can de-activate 3D Secure on a merchant profile level only with express permission to do so from the merchant’s bank.

    Subscription Frequency Codes

    Code Description
    111 Weekly on Sunday
    112 Weekly on Monday
    113 Weekly on Tuesday
    114 Weekly on Wednesday
    115 Weekly on Thursday
    116 Weekly on Friday
    117 Weekly on Saturday
       
    121 2nd Weekly on Sunday
    122 2nd Weekly on Monday
    123 2nd Weekly on Tuesday
    124 2nd Weekly on Wednesday
    125 2nd Weekly on Thursday
    126 2nd Weekly on Friday
    127 2nd Weekly on Saturday
       
    131 3rd Weekly on Sunday
    132 3rd Weekly on Monday
    133 3rd Weekly on Tuesday
    134 3rd Weekly on Wednesday
    135 3rd Weekly on Thursday
    136 3rd Weekly on Friday
    137 3rd Weekly on Saturday
       
    201 Monthly on 1st
    202 Monthly on 2nd
    203 Monthly on 3rd
    204 Monthly on 4th
    205 Monthly on 5th
    206 – 227 as above
    228 Monthly on 28th
    229 Last day of the month
       
    301 – 328 Every 2nd month on 1st to 28th respectively
    329 Every 2nd month on last day of the month
       
    401 – 428 Every 3rd month on 1st to 28th respectively
    429 Every 3rd month on last day of the month

    Result Codes

    Credit Card Errors

    These RESULT_CODEs are returned if the transaction cannot be authorised due to a problem with the card. The TRANSACTION_STATUS will be 2.

    Result Code Description Comment
    900001 Call for Approval
    900002 Card Expired
    900003 Insufficient Funds
    900004 Invalid Card Number
    900005 Bank Interface Timeout Indicates a communications failure between the banks systems.
    900006 Invalid Card
    900007 Declined
    900009 Lost Card
    900010 Invalid Card Length
    900011 Suspected Fraud
    900012 Card Reported as Stolen
    900013 Restricted Card
    900014 Excessive Card Usage
    900015 Card Blacklisted
    900207 Declined; authentication failed Indicates the cardholder did not enter their MasterCard SecureCode / Verified by Visa password correctly.
    990020 Auth Declined
    900210 3D Secure Lookup Timeout
    991001 Invalid expiry date
    991002 Invalid Amount

    Transaction Successful

    Result Code Description Comment
    990017 Auth Done

    Communication Errors

    These RESULT_CODEs are returned if the transaction cannot be completed due to an unexpected error. TRANSACTION_STATUS will be 0.

    Result Code Description Comment
    900205 Unexpected authentication result (phase 1)
    900206 Unexpected authentication result (phase 2)
    990001 Could not insert into Database
    990022 Bank not available
    990053 Error processing transaction

    Miscellaneous

    Unless otherwise noted, the TRANSACTION_STATUS will be 0.

    Result Code Description Comment
    900209 Transaction verification failed (phase 2) Indicates the verification data returned from MasterCard SecureCode / Verified-by-Visa has been altered.
    900210 Authentication complete; transaction must be restarted Indicates that the MasterCard SecureCode / Verified-by-Visa transaction has already been completed. Most likely caused by a customer clicking the refresh button.
    900019 Invalid PayVault Scope
    990013 Error processing a batch transaction
    990024 Duplicate Transaction Detected. Please check before submitting
    990028 Transaction cancelled Customer clicks the ‘Cancel’ button on the payment page.

    Transaction Status

    Transaction Code Description
    0 Not Done
    1 Approved
    2 Declined
    3 Cancelled
    4 User Cancelled
    5 Received by PayGate
    7 Settlement Voided

    Authentication Indicators

    MasterCard SecureCode / Verified by Visa Authentication Indicator

    Code Description Comment
    N Not Authenticated Authentication was attempted but NOT successful. Merchant does NOT receive charge back protection for this transaction.
    A Authenticated Authentication was attempted and was successful. Merchant does receive charge back protection for this transaction.
    X Not Applicable Authentication processing NOT enabled on PayGate account or unexpected error in authentication process. Merchant does NOT receive charge back protection for this transaction.

    Payment Method Codes

    Payment Method Description
    CC Credit Card
    DC Debit Card
    EW E-Wallet
    BT Bank Transfer
    CV Cash Voucher
    PC Pre-Paid Card

    Locale Codes

    Code Description
    af Afrikaans
    sq Albanian
    ar-dz Arabic (Algeria)
    ar-bh Arabic (Bahrain)
    ar-eg Arabic (Egypt)
    ar-iq Arabic (Iraq)
    ar-jo Arabic (Jordan)
    ar-kw Arabic (Kuwait)
    ar-lb Arabic (Lebanon)
    ar-ly Arabic (Libya)
    ar-ma Arabic (Morocco)
    ar-om Arabic (Oman)
    ar-qa Arabic (Qatar)
    ar-sa Arabic (Saudi Arabia)
    ar-sy Arabic (Syria)
    ar-tn Arabic (Tunisia)
    ar-ae Arabic (U.A.E.)
    ar-ye Arabic (Yemen)
    eu Basque
    br Belarusian
    bg Bulgarian
    ca Catalan
    zh-hk Chinese (Hong Kong SAR)
    zh-cn Chinese (PRC)
    zh-sg Chinese (Singapore)
    zh-tw Chinese (Taiwan)
    hr Croatian
    cs Czech
    da Danish
    nl Dutch (Standard)
    nl-be Dutch (Belgium)
    en English
    en-au English (Australia)
    en-bz English (Belize)
    en-ca English (Canada)
    en-cb English (Caribbean)
    en-ie English (Ireland)
    en-jm English (Jamaica)
    en-nz English (New Zealand)
    en-za English (South Africa)
    en-tt English (Trinidad)
    en-gb English (United Kingdom)
    en-us English (United States)
    et Estonian
    fo Faeroese
    fa Farsi
    fi Finnish
    fr French (Standard)
    fr-be French (Belgium)
    fr-ca French (Canada)
    fr-lu French (Luxembourg)
    fr-ch French (Switzerland)
    gd Gaelic (Scotland)
    de German (Standard)
    de-at German (Austria)
    de-li German (Liechtenstein)
    de-lu German (Luxembourg)
    de-ch German (Switzerland)
    el Greek
    he Hebrew
    hi Hindi
    hu Hungarian
    is Icelandic
    id Indonesian
    ga Irish
    it Italian (Standard)
    it-ch Italian (Switzerland)
    ko Korean
    lv Latvian
    lt Lithuanian
    mk Macedonian (FYROM)
    ms Malaysian
    mt Maltese
    no Norwegian
    pl Polish
    pt-br Portuguese (Brazil)
    pt Portuguese (Portugal)
    rm Rhaeto-Romanic
    ro Romanian
    ro-mo Romanian (Republic of Moldova)
    ru Russian
    ru-mo Russian (Republic of Moldova)
    sz Sami (Lappish)
    sr Serbian
    sk Slovak
    sl Slovenian
    sb Sorbian
    es Spanish (Spain)
    es-mx Spanish (Mexico)
    es-gt Spanish (Guatemala)
    es-cr Spanish (Costa Rica)
    es-pa Spanish (Panama)
    es-do Spanish (Dominican Republic)
    es-ve Spanish (Venezuela)
    es-co Spanish (Colombia)
    es-pe Spanish (Peru)
    es-ar Spanish (Argentina)
    es-ec Spanish (Ecuador)
    es-cl Spanish (Chile)
    es-uy Spanish (Uruguay)
    es-py Spanish (Paraguay)
    es-bo Spanish (Bolivia)
    es-sv Spanish (El Salvador)
    es-hn Spanish (Honduras)
    es-ni Spanish (Nicaragua)
    es-pr Spanish (Puerto Rico)
    sx Sutu
    sv Swedish
    sv-fi Swedish (Finland)
    th Thai
    ts Tsonga
    tn Tswana
    tr Turkish
    uk Ukrainian
    ur Urdu
    ve Venda
    vi Vietnamese xh Xhosa
    ji Yiddish
    zu Zulu

    Country Codes

    Country Country Code Currency Currency Code
    Afghanistan AFG Afghani AFA
    Albania ALB Lek ALL
    Algeria DZA Algerian Dinar DZD
    American Samoa ASM U.S. Dollar USD
    Andorra AND Euro EUR
    Angola AGO Kwanza AOA
    Anguilla AIA E.Caribbean Dollar XCD
    Antarctica ATA Norwegian Krone NOK
    Antigua and Barbuda ATG E.Caribbean Dollar XCD
    Argentina ARG Argentine Peso ARS
    Armenia ARM Armenian Dram AMD
    Aruba ABW Aruban Guilder AWG
    Australia AUS Australian Dollar AUD
    Austria AUT Euro EUR
    Azerbaijan AZE Azerbaijan Manat AZM
    Bahamas BHS Bahamian Dollar BSD
    Bahrain BHR Bahraini Dinar BHD
    Bangladesh BGD Taka BDT
    Barbados BRB Barbados Dollar BBD
    Belarus BLR Belarussian Ruble BYR
    Belgium BEL Euro EUR
    Belize BLZ Belize Dollar BZD
    Benin BEN CFA Franc BCEAO XOF
    Bermuda BMU Bermudian Dollar BMD
    Bhutan BTN Indian Rupee INR
    Bolivia BOL Boliviano BOB
    Bosnia and Herzegovina BIH Bosnian Convertible Mark BAM
    Botswana BWA Pula BWP
    Bouvet Is. BVT Norwegian Krone NOK
    Brazil BRA Brazilian Real BRL
    British Indian Ocean Territory IOT U.S. Dollar USD
    British Virgin Is. VGB U.S. Dollar USD
    Brunei Darussalam BRN Brunei Dollar BND
    Bulgaria BGR Bulgarian Lev BGN
    Burkina Faso BFA CFA Franc BCEAO XOF
    Burundi BDI Burundi Franc BIF
    Cambodia KHM Riel KHR
    Cameroon United Republic of CMR CFA Franc BEAC XAF
    Canada CAN Canadian Dollar CAD
    Cape Verde Is. CPV Cape Verde Escudo CVE
    Cayman Is. CYM Cayman Is. Dollar KYD
    Central African Republic CAF CFA Franc BEAC XAF
    Chad TCD CFA Franc BEAC XAF
    Chile CHL Chilean Peso CLP
    China CHN Yuan Renminbi CNY
    Christmas Is. CXR Australian Dollar AUD
    Cocos (Keeling) Is. CCK Australian Dollar AUD
    Colombia COL Colombian Peso COP
    Comoros COM Comoro Franc KMF
    Congo COG CFA Franc BEAC XAF
    Cook Is. COK New Zealand Dollar NZD
    Costa Rica CRI Costa Rican Colon CRC
    Côte d’Ivoire (Ivory Coast) CIV CFA Franc BCEAO XOF
    Croatia HRV Croatian Kuna HRK
    Cuba CUB Cuban Peso CUP
    Cyprus CYP Cyprus Pound CYP
    Czech Republic CZE Czech Koruna CZK
    Democratic Republic of the Congo (formerly Zaire) COD Franc Congolais (formerly New Zaire) CDF
    Denmark DNK Danish Krone DKK
    Djibouti DJI Djibouti Franc DJF
    Dominica DMA E.Caribbean Dollar XCD
    Dominican Rep. DOM Dominican Peso DOP
    East Timor TMP Timor Escudo TPE
    Ecuador ECU Sucre ECS
    Egypt EGY Egyptian Pound EGP
    El Salvador SLV U.S. Dollar USD
    Equatorial Guinea GNQ CFA Franc BEAC XAF
    Eritrea ERI Eritean Nakfa ERN
    Estonia EST Kroon EEK
    Ethiopia ETH Ethiopian Birr ETB
    European Monetary Cooperation Fund -- European Currency Unit XEU
    European Union -- Euro EUR
    Faeroe Is. FRO Danish Krone DKK
    Falkland Is. (Malvinas) FLK Falkland Is. Pound FKP
    Fiji FJI Fiji Dollar FJD
    Finland FIN Euro EUR
    France FRA Euro EUR
    France Metropolitan FXX Euro EUR
    French Guiana GUF Euro EUR
    French Polynesia PYF CFP Franc XPF
    French Southern Territory ATF Euro EUR
    Gabon GAB CFA Franc BEAC XAF
    Gambia GMB Dalasi GMD
    Georgia GEO Georgian Lari GEL
    Germany DEU Deutsche Mark DEM
    Ghana GHA Cedi GHC
    Gibraltar GIB Gibraltar Pound GIP
    Greece GRC Euro EUR
    Greenland GRL Danish Krone DKK
    Grenada GRD E.Caribbean Dollar XCD
    Guadeloupe GLP Euro EUR
    Guam GUM U.S. Dollar USD
    Guatemala GTM Quetzal GTQ
    Guinea GIN Guinea Franc GNF
    Guinea—Bissau GNB Guinea-Bissau Peso GWP
    Guyana GUY Guyana Dollar GYD
    Haiti HTI Gourde HTG
    Heard and McDonald Is. HMD Australian Dollar AUD
    Holy See (Vatican City State) VAT Euro EUR
    Honduras HND Lempira HNL
    Hong Kong China HKG Hong Kong Dollar HKD
    Hungary HUN Forint HUF
    Iceland ISL Iceland Krona ISK
    India IND Indian Rupee INR
    Indonesia IDN Rupiah IDR
    Iran Airlines -- Iranian Airline Rate IRA
    Iran Islamic Republic of IRN Iranian Rial IRR
    Iraq IRQ Iraqi Dinar IQD
    Ireland Republic of IRL Euro EUR
    Israel ISR New Israeli Shekel ILS
    Italy ITA Euro EUR
    Jamaica JAM Jamaican Dollar JMD
    Japan JPN Yen JPY
    Jordan JOR Jordanian Dinar JOD
    Kazakhstan KAZ Tenge KZT
    Kenya KEN Kenyan Shilling KES
    Kiribati KIR Australian Dollar AUD
    Korea Democratic People’s Republic of (North Korea) PRK North Korean Won KPW
    Korea Republic of KOR Won KRW
    Kuwait KWT Kuwaiti Dinar KWD
    Kyrgyzstan KGZ Som KGS
    Lao People’s Democratic Republic LAO Kip LAK
    Latvia LVA Latvian Lats LVL
    Lebanon LBN Lebanese Pound LBP
    Lesotho LSO Rand ZAR
    Liberia LBR Liberian Dollar LRD
    Libyan Arab Jamahiriya LBY Libyan Dinar LYD
    Liechtenstein LIE Swiss Franc CHF
    Lithuania LTU Lithuanian Litas LTL
    Luxembourg LUX Euro EUR
    Macau China MAC Pataca MOP
    Macedonia the Former Yugoslav Republic of MKD Denar MKD
    Madagascar MDG Malagasy Franc MGF
    Malawi MWI Malawi Kwacha MWK
    Malaysia MYS Malaysian Ringgit MYR
    Maldives MDV Rufiyaa MVR
    Mali MLI CFA Franc BCEAO XOF
    Malta MLT Maltese Lira MTL
    Marshall Islands MHL U.S. Dollar USD
    Martinique MTQ Euro EUR
    Mauritania MRT Ouguiya MRO
    Mauritius MUS Mauritius Rupee MUR
    Mayotte MYT Euro EUR
    Mexico MEX Mexican Peso MXN
    Micronesia FSM U.S. Dollar USD
    Moldova Republic of MDA Moldovan Leu MDL
    Monaco MCO Euro EUR
    Mongolia MNG Tugrik MNT
    Montenegro -- Yugoslavian New Dinar YUM
    Montserrat MSR E.Caribbean Dollar XCD
    Morocco MAR Moroccan Dirham MAD
    Mozambique MOZ Metical MZM
    Myanmar MMR Kyat MMK
    Namibia NAM Namibia Dollar NAD
    Nauru NRU Australian Dollar AUD
    Nepal NPL Nepalese Rupee NPR
    Netherlands NLD Euro EUR
    Netherlands Antilles ANT Nether. Antillian Guilder ANG
    New Caledonia NCL CFP Franc XPF
    New Zealand NZL New Zealand Dollar NZD
    Nicaragua NIC Cordoba Oro NIO
    Niger NER CFA Franc BCEAO XOF
    Nigeria NGA Naira NGN
    Niue NIU New Zealand Dollar NZD
    Norfolk Is. NFK Australian Dollar AUD
    Northern Mariana Islands MNP U.S. Dollar USD
    Norway NOR Norwegian Krone NOK
    Oman OMN Rial Omani OMR
    Pakistan PAK Pakistan Rupee PKR
    Palau PLW U.S. Dollar USD
    Panama PAN Balboa PAB
    Papua New Guinea PNG Kina PGK
    Paraguay PRY Guarani PYG
    Peru PER Nuevo Sol PEN
    Philippines PHL Philippine Peso PHP
    Pitcairn PCN New Zealand Dollar NZD
    Poland POL Polish New Zloty PLN
    Portugal PRT Euro EUR
    Puerto Rico PRI U.S. Dollar USD
    Qatar QAT Qatari Rial QAR
    Reunion REU Euro EUR
    Romania ROM Leu ROL
    Russian Federation RUS Russian Ruble (International) RUB
    Russian Ruble (Domestic) RUS Russian Ruble (Domestic) RUR
    Rwanda RWA Rwanda Franc RWF
    Samoa WSM Tala WST
    San Marino SMR Euro EUR
    Sao Tome and Principe STP Dobra STD
    Saudi Arabia SAU Saudi Riyal SAR
    Senegal SEN CFA Franc BCEAO XOF
    Seychelles SYC Seychelles Rupee SCR
    Sierra Leone SLE Leone SLL
    Singapore SGP Singapore Dollar SGD
    Slovakia SVK Slovak Koruna SKK
    Slovenia SVN Tolar SIT
    So. Georgia and So. Sandwich Is. SGS Pound Sterling GBP
    Solomon Is. SLB Solomon Is. Dollar SBD
    Somalia SOM Somali Shilling SOS
    South Africa ZAF Rand ZAR
    Spain ESP Euro EUR
    Sri Lanka LKA Sri Lanka Rupee LKR
    St. Helena SHN St. Helena Pound SHP
    St. Kitts-Nevis KNA E.Caribbean Dollar XCD
    St. Lucia LCA E.Caribbean Dollar XCD
    St. Pierre and Miquelon SPM Euro EUR
    St. Vincent and The Grenadines VCT E.Caribbean Dollar XCD
    Sudan SDN Sudanese Pound SDD
    Sudan Airlines -- Sudan Airline Rate SDA
    Suriname SUR Surinam Guilder SRG
    Svalbard and Jan Mayen Is. SJM Norwegian Krone NOK
    Swaziland SWZ Lilangeni SZL
    Sweden SWE Swedish Krona SEK
    Switzerland CHE Swiss Franc CHF
    Syrian Arab Rep. SYR Syrian Pound SYP
    Taiwan TWN New Taiwan Dollar TWD
    Tajikistan TJK Somoni TJS
    Tanzania United Republic of TZA Tanzanian Shilling TZS
    Thailand THA Thailand Baht THB
    Togo TGO CFA Franc BCEAO XOF
    Tokelau TKL New Zealand Dollar NZD
    Tonga TON Pa’anga TOP
    Trinidad and Tobago TTO Trinidad and Tobago Dollar TTD
    Tunisia TUN Tunisian Dinar TND
    Turkey TUR Turkish Lira TRL
    Turkmenistan TKM Manat TMM
    Turks and Caicos Is. TCA U.S. Dollar USD
    Tuvalu TUV Australian Dollar AUD
    U.S. Minor Outlying Islands UMI U.S. Dollar USD
    U.S. Virgin Is. VIR U.S. Dollar USD
    Uganda UGA Uganda Shilling UGX
    Ukraine UKR Ukrainian Hryvnia UAH
    United Arab Emirates ARE U.A.E. Dirham AED
    United Kingdom GBR Pound Sterling GBP
    United States USA U.S. Dollar USD
    Uruguay URY Peso Uruguayo UYU
    Uzbekistan UZB Uzbekistan Sum UZS
    Vanuatu VUT Vatu VUV
    Venezuela VEN Bolivar VEB
    Vietnam VNM Dong VND
    Wallis and Futuna Is. WLF CFP Franc XPF
    Western Sahara ESH Moroccan Dirham MAD
    Yemen YEM Yemeni Rial YER
    Yugoslavia YUG Yugoslavian New Dinar YUM
    Zambia ZMB Zambian Kwacha ZMK
    Zimbabwe ZWE Zimbabwe Dollar ZWD