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
- The setup process is relatively simple and can be easily integrated into existing web sites.
- PayWeb can be customized to suit the look and feel of your website.
- Multiple payment methods are accessible via a single PayWeb integration.
- Multiple payment options can be offered to the client via a menu system or PayGate can provide the merchant with many PayGateID’s so that the merchant can display the choice of payment methods to the client.
- MasterCard SecureCode and Verified-by-Visa cardholder authentication built in to minimize the risk of charge backs for credit card transactions.
- PayGate’s PayProtector fraud and risk system is supported for real-time fraud screening and reporting.
- Using PayWeb will reduce a merchant’s PCI compliance scope as all sensitive data is captured in the PayGate environment. PayGate is certified PCI DSS Level 1 compliant.
- PayVault credit card tokenisation can be activated on PayWeb, and PayWeb allows for PayVault tokens to be submitted in the PayWeb request to allow for payments without the card holder having to enter their card number or expiry date (a CVV will be required).
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:
- The Encryption Key used in the checksum calculation.
- Choose which credit card brands to accept. MasterCard and Visa are enabled by default if the credit card payment method is activated.
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:
- Have multiple payment methods all activated on a single PayGate ID or
- Have multiple PayGate ID’s with a single payment method active per PayGate ID or
- 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
Process flow description
- The merchant begins the process by posting a detailed ‘Request’ to PayWeb.
- PayWeb responds immediately with a unique PAY_REQUEST_ID field.
- 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.
- 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.
- 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.
- PayWeb redirects the client back to the ‘RETURN_URL’ provided by the merchant in step 1.
- The merchant can ‘Query’ PayWeb and post the PAY_REQUEST_ID field to PayWeb.
- PayWeb replies immediately to step 6 by posting back detailed ‘Response’ data.
- 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
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
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) | |
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:
- If all the optional fields are empty, the checksum source would translate to:
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
- With the NOTIFY_URL and USER1 fields populated, the checksum source would translate to:
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
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
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?
- The TRANSACTION_STATUS field will contain “3”.
- The RESULT_CODE field will contain “990028”.
- The TRANSACTION_ID field will be blank.
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:
- PayVault must be enabled on the PayGate account.
- The VAULT_ID must be valid for the PAY_METHOD passed in the request or, if no PAY_METHOD is passed, the VAULT_ID must be valid for one of the payment methods available on the PayGate account.
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:
- PayVault is enabled on the merchant’s PayGate profile.
- A VAULT value of ‘1’ is sent in the Request. If no VAULT value is sent it is assumed to be ‘0’ and no tokenisation will take place.
- PayVault tokenisation is supported for the payment method selected by the user if multiple payment methods are available. Currently only credit card (PAY_METHOD of ‘CC’) is supported by PayVault for tokenisation.
- The payment is approved by the acquirer. This is set as default in the PayGate account configuration but can be set to tokenise all transactions whether approved or not.
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:
- Java
- .Net
- PHP
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:
- The PayHost password that is passed in the SOAP message.
- Choose which credit card brands to accept. MasterCard and Visa are enabled by default if the credit card payment method is activated.
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:
- Have multiple payment methods all activated on a single PayGateID or,
- Have multiple PayGateID’s with a single payment method active per PayGateID or,
- 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:
- No 3D Secure
- 3D Secure using PayGate’s ‘Merchant Plug In’ (MPI)
- 3D Secure using the merchant’s MPI
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) | |
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
- Customer enters card details on the merchant’s web site / system.
- Merchant sends a payment request message to PayHost. The following steps are only required if a “Secure” message is received in step 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).
- 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.
- The issuing bank 3D Secure authentication page will redirect the customer’s browser back to PayGate.
- 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)..
- The Merchant website responds with the word ‘OK’ to PayGate.
- 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.
- 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
- Customer initiates payment on merchant’s website.
- Merchant sends a web payment request message to PayGate.
- PayGate responds with the PayGate payment page URL that the merchant.
- The merchant is required to redirect the customer’s internet browser to the PayGate payments page.
- Once the client has completed the payment the customer is redirected back to the merchant’s website.
- PayGate sends a notification to the Merchant’s system confirming that the payment has been processed
- The merchant sends PayGate a Query request for the transaction.
- 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.
- PayGate receives notification of the transaction’s final status from the relevant acquirer.
- PayGate sends a notification to the merchant’s notification URL that the final status has been received.
- The merchant’s system responds with ‘OK’ to acknowledge receipt of the notification.
- The merchant’s system sends PayGate a Query request for the transaction.
- 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
- Customer is redirected to the payment encryption service provider to authorise and authenticate the transaction.
- The payment encryption service provider sends the merchant encrypted data for the payment.
- The merchant sends the relevant encrypted data to PayGate along with other transaction data.
- PayGate decrypts the data received and processes the authorisation to the acquiring bank.
- 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
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.
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.
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.
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.
Confirmation
The confirmation screen displayed to the user.
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:
- Java
- .Net
- PHP
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
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
- The setup process is relatively simple and can be easily integrated into existing web sites.
- The merchant doesn’t require a SSL certificate to capture the credit card details as PayGate provides this.
- All sensitive credit card information is stored on PayGate's secure servers.
- The merchant does not have to submit (and manage) batches of card data to PayGate periodically.
- 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 | |
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:
- If all the optional fields are empty, the checksum source would translate to:
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
- With the NOTIFY_URL and USER1 fields populated, the checksum source would translate to:
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
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?
- The TRANSACTION_STATUS field will contain “3”.
- The RESULT_CODE field will contain “990028”.
- The TRANSACTION_ID field will be blank.
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 |