GPN DATA - Documentation

CURL
PHP

Overview
API Commands
Notifications
Transaction/Gateway Status Codes
Appendix - 3D Secure Integration
FAQs for using 3DS
Rebill Explanation
IFrame Integration
HTTP Form Post
Error Codes

GPN DATA MERCHANT API
INTEGRATION GUIDE

API INTEGRATION GUIDE (v 1.12.0)

API Commands are send from merchant’s system to the Gateway with HTTP protocol. Request need to be sent to URL provided by GPN Data. Data is transmitted as POST parameter strrequest, which contain XML string with the API Command required details.

Overview

The GPN DATA Payment Page is the method by which GPN DATA conducts secure CNP (Card Not Present) transactions when the Merchant either chooses not to provide the Payment Page or the Merchant site does not meet PCI requirements. The target audience of this document is the Programmer or IT Professional who will be integrating the GPN DATA Payment Page into the Merchant’s web site.

GPN DATA strictly adheres to the standards set forth by PCI-DSS (Payment Card Industry – Data Security Standard). The intent of the Payment Page is to remove the possibility of the Merchant acquiring CHD (Card Holder Data). Any attempts to circumvent this protection and attempt to acquire CHD (Card Holder Data) are a violation of PCI-DSS standards. To obtain the latest information regarding PCI-DSS please consult:

https://www.pcisecuritystandards.org/security_standards/documents.curl

All information contained in this document is the intellectual property of GPN DATA Europe Ltd. and is protected by International Copyrights.

All references in this document to “gateway” or Gateway” directly refer to GPN DATA Europe unless otherwise specified.

All information in this document is subject to Non Disclosure Agreements signed by the principal officer of the Merchant.

Terminology Used

Gateway - The web server, database server and programs associated with Credit Card processing

Transaction - Any exchange of date between the Gateway and the Merchant.

CHD - Card Holder Data as described by PCI (the Payment Card Industry and CHD are addressed in more detail in the Security section of this document).

Charge - A Charge transaction performs an Authorize transaction and immediately follows with an automatic Capture transaction

Chargeback - Chargebacks are created when the Cardholder informs the Issuing Bank that there is a problem with the goods or services received or not received from the merchant.

3DS - 3DS is a generic name for programs from several of the card companies. The formal names are: Verified by Visa, Secure Code by Mastercard and JSecure from JCB. Transactions processed under 3DS involve the Cardholder being redirected to the Issuing Bank for transaction Authorization. Transactions processed as 3DS provide some levels of protection for the Merchant against Chargebacks resulting from fraudulent charges.

Testing

For each Merchant account, the Merchant will be issued login credentials and URL for the Merchant Back Office on a TEST server. All necessary API documentation and connection information will be located there. The TEST server has the following features to assist in integration:

Initially, the Acquiring Bank will be an internal “test bank“ and no actual charges will be placed on any card used for testing.
CVV values of 000 to 799 will result in the transaction returning as following:
- 001 to 249 – emulate non-enrolled card, transaction approved;
- 250 to 499 – emulate enrolled card (with 3D Secure redirection), Transaction approved after successful ACS authentication;
- 500 – emulate transaction error
- 501 to 749 – emulate non-enrolled card, transaction declined;
- 750 to 799 – emulate enrolled card (with 3D Secure redirection), Transaction declined even after successful ACS authentication.

Security

There are several overriding concerns with regard to security: CHD (Card Holder Data), Transaction Verification and Intrusion Prevention to mention just a few.

GPN DATA does not record or save sensitive CHD. Even the transaction logs are “sanitized” before being written to disk to mask the PAN (Primary Account Number) and the CVV. All GPN DATA procedures with regard to CHD are in adherence to PCI-DSS specifications as mentioned in the Overview section.

All Transactions between merchants and GPN DATA include a checksum. The checksum is created using a Secure Hash Algorithm. The Payment Page uses SHA-1 algorithm and an API key assigned to every merchant by GPN DATA. This API key is never included in the actual transaction, but is used in calculating the checksum. You will find the API key on the “Technical Integration” menu in the Merchant Back Office.

All transactions will contain a checksum; the checksum is calculated by concatenating data from specific fields in the transaction (the appropriate fields are indicated in the API Transaction Tables listed below), the secret API key is then appended to the end of the string and the checksum is calculated using SHA-1 algorithm. Before accepting the transaction request, each side must perform this procedure and compare checksums in order to validate the transaction.

Test Server: https://txtest.txpmnts.com/api/transaction/ 

PROD. Server: https://txpmnts.com/api/transaction/

 PHP SDK on Github 
The GPN DATA SDK for PHP is an open source project hosted on Github. You can get the latest version of the SDK or contribute to it via Github: https://github.com/gpndata/omnipay-gpn

PHP SDK Installation

GPN SDK is installed via Composer. To install, simply add it to your composer.json file:


{
    "require": {
        "gpndata/omnipay-gpn": "dev-master"
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}

And run composer to update your dependencies:

	
$ curl -s http://getcomposer.org/installer | php
$ php composer.phar update

cURL Request Sample

   
$ch = curl_init();
         
         
//Set up curl parameters
curl_setopt($ch, CURLOPT_URL, 'https://txtest.txpmnts.com/api/transaction/');   // set remote address
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestMessage);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);    // Make CURL pass the response as a curl_exec return value instead of outputting to STDOUT
curl_setopt($ch, CURLOPT_POST, 1);                // Activate the POST method
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
// curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-type: text/xml',
    'Accept: text/xml'
        ]);
         
//execute the connection
 $result = curl_exec($ch);
         
 echo "
Result Code:".$result.']]>';
         
$debugoutput = curl_getinfo($ch);
         
$curl_error_message = curl_error($ch); // must retrieve an error message (if any) before closing the curl object
         
 echo "
Curl Error message:".$curl_error_message;
         
curl_close($ch);
 
         
//Trim headers
$pos = strstr($result, "\n");
  echo '
Result'.$pos;

GPN DATA MERCHANT API

API Commands are send from merchant’s system to the Gateway with HTTP protocol. Request need to be sent to URL provided by GPN Data. Data is transmitted as POST parameter strrequest , which contain XML string with the API Command required details.

700 – Start Credit Card charge (3DS Enabled)

Description: Allows the merchant to submit a charge to the cardholder’s Credit Card and includes 3DS capability when 3DS is specified in the Merchant Agreement. (See Appendix for “3DS Explanation”).

700 Request Data description:

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	700	3 digit numeric transaction code must be 700
transaction		YES	Xml Node	Section containing Transaction Information
transaction->merchanttransid	YES (4)	YES	Character max 50.	Merchant transaction id must be included in the request. Merchant transaction id must be unique for each transaction.
transaction->amount	YES (5)	YES	Number with point decimal	Full amount to charge in currency specified. The amount must be specified as a number with decimal point and 2 digits to the right of the decimal point. Decimal separator must be point (.). example: 3500.25 = Three thousand five hundred units of currency and twenty five hundredths of a single unit of currency.
transaction->curcode	YES (6)	YES	Character 3.	May only use currencies specified in the Merchant Agreement.
transaction->description		YES	Character max 100.	Description of the charge. When available, that description may be used in the billing statement of the card holder.
transaction->merchantspecific1		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific2		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific3		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific4		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific5		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
rebill		No	Xml Node	Section containing Rebill Information. Note: Availability is subject to terms of Merchant Agreement. This tag must be present to indicate that this is the initiation of a Rebill sequence. If no other rebill tag is used, you must use or Note: Merchants not authorized for should not use these tags.
rebill->freq		No	Character max 5.	Rebilling frequency. Valid values are: d (days), w (weeks), m (months), y (years). Examples: 7d = rebill every 7 days 1m = rebill every month If not provided, default frequency from Merchant account profile will be used.
rebill->start		No	Date format yyyy-mm-dd	Optional start date for rebill period. Additional rebills will be calculated from this date at rebill->freq for number of occurrences in rebill->count (this date counts as the first of rebill->count). If not provided, default start date from Merchant account profile will be used.
rebill->amount		No	Number with point decimal	Rebilling amount to charge in currency specified. If not provided, default amount from Merchant account profile will be used.
rebill->desc		No	Character max 100.	Rebilling description. If not provided, default description from Merchant account profile will be used.
rebill->count		No	Number 1-2 digits	Maximum number of Rebilling transactions. If not provided, default count from Merchant account profile will be used.
rebill->followup_time		No	Date format yyyy-mm-dd	Date at which transaction followup (conversion) will be scheduled. If not present, default date from Merchant account profile may be used. See detailed description of followup in Appendix
rebill->followup_amount		No	Number with point decimal	Transaction followup (conversion) amount to charge in currency specified. If not provided, default followup amount from Merchant account profile may be used. See detailed description of followup in Appendix
customer		YES	Xml Node	Section containing Customer Information
customer->firstname		YES	Character max 50.	First name of the Customer.
customer->lastname		YES	Character max 50.	Last name of the Customer.
customer->birthday		YES*	Number 1-2 digits	Day of birth of the Customer (1-31) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. Tag will be set as “Optional” only with GPN’s Sales Account Manager approval.
customer->birthmonth		YES*	Number 1-2 digits	Month of birth of the customer (1-12) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. Tag will be set as “Optional” only with GPN’s Sales Account Manager approval.
customer->birthyear		YES*	Number 4 digits	Year of birth of the customer (1900-2100) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. Tag will be set as “Optional” only with GPN’s Sales Account Manager approval.
customer->email		YES	Character max 100.	Email of the Customer.
customer->countryiso		YES	Character exactly 3.	3 letter ISO country code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
customer->stateregioniso		YES	Character max 3.	1-3 character ISO 3166 state/region/province code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
customer->zippostal		YES	Character max 15.	Customer’s Zipcode or postal code.
customer->city		YES	Character max 50.	Customer’s City
customer->address1		YES	Character max 75.	Customer’s address line 1
customer->address2		OPT	Character max 75.	Customer’s address line 2
customer->phone1phone		YES	Character max 20.	Customer’s phone number, including country code and area code. Digits only, without (+) character
customer->phone2phone		OPT	Character max 20.	Customer’s phone number, including country code and area code. Digits only, without (+) character
customer->accountid		YES	Character max 50.	Customer unique account id used inside the merchant organization.
customer->ipaddress		YES	Character max 15.	Full IP address of the customer used for this transaction
creditcard		COND	Xml Node	Section containing sepa bank account Information. Required for sepa transactions, forbidden for credit card transactions.
creditcard->ccnumber	YES (7)	YES	Character max 16.	Full credit card number without dashes or separators. Only numbers.
creditcard->cccvv	YES (8)	YES	Character max 4.	Verification Code of the Credit Card
creditcard->expmonth		YES	Numeric 1-2	Expiration month of the credit card.
creditcard->expyear		YES	Numeric 4	Expiration year of the credit card.
creditcard->nameoncard	YES (9)	YES	Character max 50.	Full name as it appears on card.
creditcard->billingcountryiso		YES	Character exactly 3.	3-digits ISO country code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
creditcard->billingstateregioniso		YES	Character max 5.	ISO 3166 state/region/province code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
creditcard->billingzippostal		YES	Character max 15.	Customer’s Zip code or postal code.
creditcard->billingcity		YES	Character max 50.	Customer’s City
creditcard->billingaddress1		YES	Character max 75.	Customer’s address line 1
creditcard->billingaddress2		OPT	Character max 75.	Customer’s address line 2
creditcard->billingphone1phone		YES	Character max 20.	Customer’s phone number, including country code and area code. Digits only, without (+) character
creditcard->issuemonth		OPT	Numeric 1-2	Issuing month of the credit card.
creditcard->issueyear		OPT	Numeric 4	Issuing year of the credit card.
sepa		COND	Xml Node	Section containing sepa bank account Information. Required for sepa transactions, forbidden for credit card transactions.
sepa->iban	YES (7)	YES	Characters min 16, max 40.	Full international bank account number without dashes or separators. Only alphanumeric characters.
sepa->bic	YES (8)	YES	Character min 8, max 11.	Bank identitfication code (a.k.a. SWIFT code) without dashes or separators. Only alphanumeric characters.
checksum		YES	Character 36	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.
auth		YES	Xml Node	Section containing authorization type
auth->type		YES	Character max. 6	This tag Must be present. Valid values are Direct = non- 3DS Charge (Auth/Capture) Auth = non-3DS Auth Only 3DS = 3DS Charge (Auth/Capture) Auth3DS = 3DS Auth Only Note: only those choices available as indicated in the Merchant Profile are accepted.
auth->sid		COND	Character no limit*	This tag is used only during 3D Secure transactions. It is intended to use as a session identification string and it is forwarded to you as a part of your Return URL. (See Appendix for “3D Secure Integration”) Note: Keep in mind that URL length (your Return URL + SID) must be under 2 000 characters
auth-> mdstatus		COND	Character 1	This tag Must be present. Valid values are Y (or lower case) = Authentication process was successful A (or lower case) = Authentication process was attempted U (or lower case) = Unable to authenticate N (or lower case) = Authentication process failed To be taken from ACS Response.
auth->xid		COND	28 byte-long	base-64 encoded XID : Unique Internet transaction ID To be taken from ACS Response.
auth->eci		COND	Numeric 2	Valid values are 01,02,05,06,07 MasterCard: 01 / 02 Visa: 05 / 06 / 07 empty for non-3D transactions To be taken from ACS Response.
auth->cavv		COND	Character 28	contains a 20-byte value that has been Base64 encoded, giving a 28 byte result. To be taken from ACS Response.
auth->cavvAlgorithm		COND	Numeric 1	Digit from [0-9] depending on ACS response. To be taken from ACS Response.

700 – Response

The response to a 700-Start Credit card Charge Transaction is:
• The completion of the transaction if the Merchant Agreement does NOT require 3DS.
• The completion of the transaction if the Merchant Agreement DOES require 3DS and the Issuing Bank is NOT a 3DS participant.
• The end of the first step for a 3DS transaction if the Issuing Bank IS a 3DS participant. The merchant must continue with the 705 command to complete the transaction IF the merchant receives a response from the redirect screen (see Appendix “3DS Explanation” for more information).

Response Data description:

Node	Optional	Data Type	Description
result	YES	Character	Indicates the result of the transaction. SUCCESS: Customer’s Credit Card account has been charged (or AUTHORIZED) with the amount of the transaction. DECLINED: transaction was declined. ERROR: An error has been detected in the request. PENDING: If the Issuing bank has been determined to participate in the 3DS program, this is the normal response and it will include the PaReq and ACS data. The merchant must present a redirect screen to the cardholder, using the URL supplied in the ACS tag and supply the PaReq as a POST parameter. For further instructions see the Appendix “3DS Explanation”
merchanttransid	YES	Character max 50.	Unique merchant transaction id received in the request.
transref	COND	Integer	Gateway’s transaction reference number. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for support and troubleshooting.
gatetransid	COND	Character 36	Gateway transaction ID. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for refunds and other transaction activity performed through API.
errorcode	YES	Character 3	Error Code of the transaction or 000 if no error condition found.
errormessage	OPT	Character max 100	Full description of the error.
description	OPT	Character no limit	Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.
ACS	NO	Character string No limit	Not present if not a 3DS transaction or if it is a 3DS transaction and the Issuing Bank is not a participant in the 3DS program. If present, this is the URL for the redirect screen (see Appendix “3DS Explanation”)
parameters	COND	XML node	Not present if not a 3DS transaction or if it is a 3DS transaction and the Issuing Bank is not a participant in the 3DS program. If present, ALL child elements must be transmitted in the redirect screen (see Appendix “3DS Explanation”)
parameters ->PaReq	COND	Encoded character string no limit	This string must be transmitted in the redirect screen (see Appendix “3DS Explanation”)
parameters ->MD	COND	Character string max 50	This is the authorization process ID for the redirect screen (see Appendix “3DS Explanation”). It must be stored and forwarded in API Call 705
parameters ->TermUrl	COND	Character string max 2000	This is the URL where Access Control Server sends response, which need to be forwarded to the Gateway. Depending on Acquiring bank this value may be different than 3DS Return URL provided by merchant
parameters->…	NO	Character string	Optional other parameters that must be transmitted in the redirect screen
rebillwindows	NO	XML Node	Not present unless this is a Rebill Transaction and the Manual Rebill Request has been authorized in the Merchant Agreement and is selected in the Merchant Profile. Section containing valid Manual Rebill Periods (windows of opportunity)
rebillwindows->window	NO	XML attribute	Not present unless this is a Rebill Transaction and the Manual Rebill Request has been authorized in the Merchant Agreement and is selected in the Merchant Profile. No data is contained in this tag, rather the XML tag has two date attributes, each formatted as YYYY-MM-DD HH:MM:SS in UTC. The number of window tags equals transaction->rebill_count and represents the exclusive time periods when a 756 Manual Rebill Request will be accepted and not return an Error

The 700 request is plain XML that contains the following data:

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
	<apiUser> </apiUser>
	<apiPassword> </apiPassword>
	<apiCmd> </apiCmd>
		<transaction> 
			<merchanttransid> </merchanttransid>
			<amount> </amount>
			<curcode> </curcode>
			<description> </description>
			<merchantspecific1> </merchantspecific1>
			<merchantspecific2> </merchantspecific2>
			<merchantspecific3> </merchantspecific3>
			<merchantspecific4> </merchantspecific4>
			<merchantspecific5> </merchantspecific5>
		</transaction>
		<rebill> 
			<freq> </freq>
			<start> </start>
			<amount> </amount>
			<desc> </desc>
			<count> </count>
			<followup_time> </followup_time>
			<followup_amount> </followup_amount>
		</rebill>
		<customer> 
			<firstname> </firstname>
			<lastname> </lastname>
			<birthday> </birthday>
			<birthmonth> </birthmonth>
			<birthyear> </birthyear>
			<email> </email>
			<countryiso> </countryiso>
			<stateregioniso> </stateregioniso>
			<zippostal> </zippostal>
			<city> </city>
			<address1> </address1>
			<address2> </address2>
			<phone1phone> </phone1phone>
			<phone2phone> </phone2phone>
			<accountid> </accountid>
			<ipaddress> </ipaddress>					
		</customer>
		<creditcard> 
			<ccnumber> </ccnumber>
			<cccvv> </cccvv>
			<expmonth> </expmonth>
			<expyear> </expyear>
			<nameoncard> </nameoncard>
			<billingcountryiso> </billingcountryiso>
			<billingstateregioniso> </billingstateregioniso>
			<billingzippostal> </billingzippostal>
			<billingcity> </billingcity>
			<billingaddress1> </billingaddress1>
			<billingaddress2> </billingaddress2>
			<billingphone1phone> </billingphone1phone>
		</creditcard> 	
		<sepa> 	
			<iban> </iban>
			<bic> </bic>
		</sepa> 
		<checksum> </checksum>
		<auth> 
			<type> </type>
			<sid> </sid>
		</auth> 
	</transaction>

The 700 response is plain XML that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
	<result> </result>
	<merchanttransid> </merchanttransid>
	<transref> </transref>
	<gatetransid> </gatetransid>
	<errorcode> </errorcode>
	<errormessage> </errormessage>
	<description> </description>
	<ACS> </ACS>
	<parameters> 
		<PaReq> </PaReq>
		<MD> </MD>
		<TermUrl> </TermUrl>
	</parameters> 
	<rebillwindows> 
<window from="2012-08-15 18:00:00" to="2012-08-19 18:00:00"></window> 
<window from="2012-09-15 18:00:00" to="2012-08-19 18:00:00"></window> 
<window from="2012-10-15 18:00:00" to="2012-08-19 18:00:00"></window> 
	</rebillwindows> 
	</transaction>

The 700 request is plain XML that contains the following data:


require_once 'autoload.php';

use Omnipay\Common\CreditCard;
use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');

$card = new CreditCard([
	'firstname'        => '',
	'lastname'         => '',
	'billingAddress1'  => '',
	'billingAddress2'  => '',
	'billingCity'      => '',
	'billingPostcode'  => '',
	'billingState'     => '',
	'billingCountry'   => '',
	'shippingAddress1' => '',
	'shippingAddress2' => '',
	'shippingCity'     => '',
	'shippingPostcode' => '',
	'shippingState'    => '',
	'shippingCountry'  => '',
	'phone'            => '',
	'number'           => '4127209999999581',
	'expiryMonth'      => 04,
	'expiryYear'       => 2018,
	'cvv'              => 345,
]);

$params = [
	'amount'        => '',
	'firstName'     => '',
	'lastName'      => '',
	'card'          => $card,
	'currency'      => '',
	'transactionId' => '',
	'statement'     => '',
	'description'   => '',
	'birthDay'      => 16,
	'birthMonth'    => 7,
	'birthYear'     => 1985,
	'email'         => '',
	'clientIp'      => '',
	'accountId'     => 12345,
	'rebillAmount'  => 10,
	'rebillCount'   => 3,
	'rebillDescription' => '',
	'rebillFollowupAmount' => '',
	'rebillFollowupTime' => '',
	'rebillFrequency' => '1d',
	'rebillStart' => '',
	'rebill' => true,
	'authType' => 'Auth3DS',
];

try {
	// Auth3DS
	$response = $gpnGateway->purchase($params)->send();
	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());
if($response->getData()->getSecure()->getAcs()){
echo 'ACS : '; print_r($response->getData()->getSecure()->getAcs());
echo 'MD : '; print_r($response->getData()->getSecure()->getMD());
echo 'PaReq : '; print_r($response->getData()->getSecure()->getPaReq());
echo 'Term URL : '; print_r($response->getData()->getSecure()->getTermUrl());
}
if($response->getData()->getRebill()->getWindow()){
echo 'Rebill Windows : '; print_r($response->getData()->getRebill()->getWindow());
}

} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

701 – Request Capture Authorization

Description: Allows the merchant to submit a request to capture an authorized only transaction previously submitted and approved using the 700 command.

701 Request Data description:

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	701	3 digit numeric transaction code must be 701
gatetransid	YES (4)	YES	Character max 50.	Unique gateway internal transaction id, received by the merchant in the 850 Notification of the originating transaction.
amount		Opt	Number with point decimal	Optionally may be Required, depending on setting in Merchant Profile. Will be in currency of the original authorization transaction. The amount for capture may not exceed the amount in the authorized transaction. Decimal separator must be point (.). example: 125.45 = One hundred and twenty-five Major Currency Units with forty-five Minor Currency Units.
carrier		Opt	Character max 50.	Optionally may be Required, depending on setting in Merchant Profile. Must be one of the following: USPS, FedEx, UPS, DHL, Canada, TNT
trackingnumber		Opt	Character max 100.	Optionally may be Required, depending on setting in Merchant Profile. This is the tracking number provided by the carrier
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

701 Response Data description

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. SUCCESS: Transaction has been Captured PENDING: Request for Capture has been accepted but yet processed. (Can happen in case of transactions which need to be confirmed by staff or when tracking number provided). After the Capture has been processed, the results will be sent in the 850 Transaction State Notification that will be sent from the system server to the merchant server. Do NOT ASSUME the pending request as APPROVED or DECLINED. ERROR: means error detected in the request, no processing takes place, and transaction was not accepted by the system.
gatetransid	YES	Character max 50.	Unique gateway internal transaction id refers to Authorized transaction for which the Capture has been requested.
errorcode	YES	Character 3	Error Code of the transaction or 000 if no error condition found.
errormessage	YES	Character max 100	Full description of the error.
description	OPT	Character no limit	Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.

The 701 request is plain XML that contains the following data:

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd> </apiCmd>
		<gatetransid> </gatetransid>
		<amount> </amount>
		<carrier> </carrier>
		<trackingnumber> </trackingnumber>
		<checksum> </checksum>		
	</transaction>

The response to a 701 - Request Capture Authorization is plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
		<merchanttransid> </merchanttransid>
		<gatetransid> </gatetransid>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
		<description> </description>
	</transaction>

The 701 request is PHP that contains the following data:

  require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');


$params = [
	'gateTransId' => 'F1CD74B9-E94B-1877-DB9F-4A44B82D04EC',
	'amount' => '10.00',
	'carrier' => '',
    'trackingNumber' => '',	
];

try {
	// Capture 701
	$response = $gpnGateway->capture($params)->send();
	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());


} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

702 – Request Cancel Authorization

Description: Allows the merchant to submit a request to cancel an authorized only transaction previously submitted and approved using the 700 command.

702 Request Data description:

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	701	3 digit numeric transaction code must be 701
gatetransid	YES (4)	YES	Character max 50.	Unique gateway internal transaction id, received by the merchant in the 850 Notification of the originating transaction.
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

702 Response Data description

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. CANCELED: Cancel has been completed PENDING: Request for Cancel has been accepted but not yet processed. After the Cancel has been processed, the results will be sent in the 850 Notification that will be sent from the system server to the merchant server. ERROR: means error detected in the request, no processing takes place, and transaction was not accepted by the system. No record for the transaction has been created. Note: Do NOT ASSUME the pending request will result in CANCELED as it could also result in ERROR.
gatetransid	YES	Character max 50.	Unique gateway internal transaction id refers to Authorized transaction for which the Capture has been requested.
errorcode	YES	Character 3	Error Code of the transaction or 000 if no error condition found.
errormessage	YES	Character max 100	Full description of the error.
description	OPT	Character no limit	Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.

702 Request Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd> </apiCmd>
		<gatetransid> </gatetransid>
		<checksum> </checksum>		
	</transaction>

The response to a 702 - Request Cancel Authorization is a plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
		<gatetransid> </gatetransid>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
		<description> </description>
	</transaction>

702 Request Sample

  require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');


$params = [

	'gatewayTransactionId' => '2FB757FB-C83D-2852-E8FB-DDB2CE1046DF',
];

try {
	// Cancel Authorization 702
	$response = $gpnGateway->cancel($params)->send();
	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());

} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

705 – 3DS Transaction Continuation

Description: This applies only when Merchant Agreement is for 3DS and is a “followup” transaction to the 700 command when the results of the cardholder authentication have been returned by the Issuing Bank’s ACS.

705 Request Data description:

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	701	3 digit numeric transaction code must be 701
auth		YES	Xml Node	Section containing authorization type
auth->type	Yes (4)	YES	Character	This tag Must be present and the value for type must be: 3DS or Auth3DS
auth->ACSRes		YES	Character no limit	This is the complete, raw POST data returned by the Issuing Bank ACS to the URL provided by the merchant in the redirect screen POST variable (TermUrl). It must be packed base64 (example: if POST input data is “test=value123”, ACSRes will contain “dGVzdD12YWx1ZTEyMw==”). Raw POST data can be obtained in curl with function file_get_contents('curl://input')
auth->MD	Yes (5)	YES	Character max 50.	Authorization process ID as received from ACS server in POST "MD" field. Must be included in the request. It is equivalent to MD received in response to the 700 request which started the transaction.
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

705 Response Data description

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. SUCCESS: Customer’s Credit Card account has been charged (or authorized) with the amount of the transaction. DECLINED: transaction was declined. ERROR: An error has been detected in the request. The transaction has NOT been accepted by the Gateway and thus No processing has taken place.
merchanttransid	YES	Character max 50.	Unique merchant transaction id received in the request.
transref	YES	Integer	System transaction reference number. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for support and troubleshooting. The transaction ID used for Refunds and other transaction activity will be sent in the Merchant Notification to the URL furnished by the Merchant and specified in the Merchant Profile.
errorcode	NO	Character 3	Error Code of the transaction or 000 if no error condition found.
errormessage	NO	Character max 100	Full description of the error.
description	OPT	Character no limit	Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.

705 Request

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd> </apiCmd>
	<auth> 
		<type> </type>
		<ACSRes> </ACSRes>
		<MD> </MD>
	</auth>
		<checksum> </checksum>		
	</transaction>

705 Response

The response to a 705 – 3DS Transaction continuation is a plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
		<merchanttransid> </merchanttransid>
		<transref> </transref>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
		<description> </description>
	</transaction>

702 Request Sample

 
require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');



$params = [
	'authorizeACSRes' : '',
	'authorizeMD' => '',
    'authorizeType' => '',	
];

try {
	// Complete 3DS 705
	$response = $gpnGateway->completePurchase($params)->send();
	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());

} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

709 – Check transaction status

Description: Returns current transaction state. Optionally sends Notification 850.

709 Request Data description:

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	701	3 digit numeric transaction code must be 701
merchanttransid	YES (4)	COND	Character max 50.	Unique merchant transaction id received in the request 700. Required if gatetransid not provided. Otherwise ignored.
gatetransid	Yes (5)	COND	Character max 50.	Unique gateway internal transaction id refers to charge transaction for which the status check has been requested. Required if merchanttransid not provided.
notify		NO	Character max 3	YES: command will also trigger Notification 850 Other value: ignored.
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

709 Response Data description

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. SUCCESS: Transaction was found and current state is returned. NOTFOUND: Transaction was not found. ERROR: Transaction state change failed.
transaction	YES	Xml Node	Section containing authorization type
transaction->gatetransid	Cond	Character	Gateway transaction ID
transaction->merchanttransid	Cond	Character	Merchant transaction ID provided during execution of 700 command
transaction->amount	Cond	Number with decimal point	Full amount to charge in currency specified.
transaction->curcode	Cond	Character 3	Transaction currency
transaction->state	Cond	Character	Current status of the transaction. AUTHORIZED: Funds from Customers Credit Card account have been “reserved” but not charged to the account. CAPTURED: Customer’s Credit Card account has been charged with the amount of the transaction. DECLINED: transaction was declined. PENDING: Transaction is in pending state CANCELED: authorization of the transaction was canceled ERROR: An error occurred during transaction processing REVERSED: Transaction was reversed REFUNDED: Transaction was refunded REFUND PENDING: Refund is waiting for staff confirmation CHARGEBACK: means that a charge back for the transaction was received by the gateway.
transaction->merchantspecific1	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific2	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific3	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific4	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific5	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
errorcode	NO	Character 3	Error Code of the transaction or 000 if no error condition found.
errormessage	NO	Character max 100	Full description of the error.

709 Request Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd> </apiCmd>
		<merchanttransid> </merchanttransid>
		<notify> </notify>
		<checksum> </checksum>		
	</transaction>

709 Response

The response to a 709 – Check transaction status is a plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
	<transaction>
		<gatetransid> </gatetransid>
		<merchanttransid> </merchanttransid>
		<amount> </amount>
		<curcode> </curcode>
		<state> </state>
		<merchantspecific1> </merchantspecific1>
		<merchantspecific2> </merchantspecific2>
		<merchantspecific3> </merchantspecific3>
		<merchantspecific4> </merchantspecific4>
		<merchantspecific5> </merchantspecific5>
	</description> </description>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
	</transaction>

708 – Check transaction details

Description: Returns current transaction details including rebill child transactions.

708 Request Data description:

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	701	3 digit numeric transaction code must be 701
merchanttransid	YES (4)	COND	Character max 50.	Unique merchant transaction id received in the request 700. Required if gatetransid not provided. Otherwise ignored.
gatetransid	Yes (5)	COND	Character max 50.	Unique gateway internal transaction id refers to charge transaction for which the status check has been requested. Required if merchanttransid not provided.
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

708 Response Data description

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. SUCCESS: Transaction was found and current state is returned. NOTFOUND: Transaction was not found. ERROR: Transaction state change failed.
transaction	YES	Xml Node	Section containing authorization type
transaction->gatetransid	Cond	Character	Gateway transaction ID
transaction->merchanttransid	Cond	Character	Merchant transaction ID provided during execution of 700 command
transaction->created	Cond	digits	Transaction date in format : YYYY-MM-DD HH:MM:SS
transaction->amount	Cond	Number with decimal point	Full amount to charge in currency specified.
transaction->curcode	Cond	Character 3	Transaction currency
transaction->state	Cond	Character	Current status of the transaction. AUTHORIZED: Funds from Customers Credit Card account have been “reserved” but not charged to the account. CAPTURED: Customer’s Credit Card account has been charged with the amount of the transaction. DECLINED: transaction was declined. PENDING: Transaction is in pending state CANCELED: authorization of the transaction was canceled ERROR: An error occurred during transaction processing REVERSED: Transaction was reversed REFUNDED: Transaction was refunded REFUND PENDING: Refund is waiting for staff confirmation CHARGEBACK: means that a charge back for the transaction was received by the gateway.
transaction->merchantspecific1	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific2	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific3	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific4	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
transaction->merchantspecific5	Cond	Character max 200	Merchant specific data for merchant use only, provided during 700 command.
errorcode	NO	Character 3	Error Code of the transaction or 000 if no error condition found.
errormessage	NO	Character max 100	Full description of the error.
transaction	YES	Xml Node	Section containing authorization type
customer->firstname		Character max 50.	First name of the Customer.
customer->lastname		Character max 50.	Section containing authorization type
customer->birthday		Number 1-2 digits	Day of birth of the Customer (1-31) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. Tag will be set as “Optional” only with GPN’s Sales Account Manager approval.
customer->birthmonth		Number 1-2 digits	Month of birth of the customer (1-12) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. Tag will be set as “Optional” only with GPN’s Sales Account Manager approval.
customer->birthyear		Number 4 digits	Year of birth of the customer (1900-2100) Important Note: If Merchant cannot provide such data, he/she should contact GPN’s Sales Account Manager. Tag will be set as “Optional” only with GPN’s Sales Account Manager approval.
customer->email		Character max 100.	Email of the Customer.
customer->countryiso		Character exactly 3.	3 letter ISO country code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
customer->stateregioniso		Character max 3.	1-3 character ISO 3166 state/region/province code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
customer->zippostal		Character max 15.	Customer’s Zipcode or postal code.
customer->city		Character max 50.	Customer’s City
customer->address1		Character max 75.	Customer’s address line 1
customer->address2		Character max 75.	Customer’s address line 2
customer->phone1phone		Character max 20.	Customer’s phone number, including country code and area code. Digits only, without (+) character
customer->phone2phone		Character max 20.	Customer’s phone number, including country code and area code. Digits only, without (+) character
customer->accountid		Character max 50.	Customer unique account id used inside the merchant organization.
customer->ipaddress		Character max 15.	Full IP address of the customer used for this transaction
creditcard	YES	Xml Node	Section containing authorization type
creditcard->brand		Character max 50.	Card Brand: Visa MasterCard Maestro Amex JCB DinnersClub UnionPay
creditcard->last4		Number digit 4	Last 4 number of the card
creditcard->nameoncard		Character max 50.	Full name as it appears on card.
creditcard->billingcountryiso		Character exactly 3.	3-digits ISO country code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
creditcard->billingstateregioniso		Character max 5.	ISO 3166 state/region/province code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
creditcard->billingzippostal		Character max 15.	Customer’s Zip code or postal code.
creditcard->billingcity		Character max 50.	Customer’s City
Rebills	COND	Xml Node	Section containing details of Rebill subscription
rebills->transaction->rebillid	Cond	Character	Gateway transaction ID of the child Rebill transaction
rebills->transaction->created	Cond	digits	Transaction date in format : YYYY-MM-DD HH:MM:SS
rebills->transaction->state	Cond	Characters	Current status of the transaction. AUTHORIZED: Funds from Customers Credit Card account have been “reserved” but not charged to the account. CAPTURED: Customer’s Credit Card account has been charged with the amount of the transaction. DECLINED: transaction was declined. PENDING: Transaction is in pending state CANCELED: authorization of the transaction was canceled ERROR: An error occurred during transaction processing REVERSED: Transaction was reversed REFUNDED: Transaction was refunded REFUND PENDING: Refund is waiting for staff confirmation CHARGEBACK: means that a charge back for the transaction was received by the gateway.
rebills->transaction->description		Character max 100	Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.

708 Request Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd> </apiCmd>
		<merchanttransid> </merchanttransid>
		<notify> </notify>
		<checksum> </checksum>		
	</transaction>

708 Response

The response to a 708 – Check transaction status is a plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
	<transaction>
		<gatetransid> </gatetransid>
		<merchanttransid> </merchanttransid>
		<amount> </amount>
		<created> </created>
		<curcode> </curcode>
		<state> </state>
		<merchantspecific1> </merchantspecific1>
		<merchantspecific2> </merchantspecific2>
		<merchantspecific3> </merchantspecific3>
		<merchantspecific4> </merchantspecific4>
		<merchantspecific5> </merchantspecific5>
		<description> </description>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
	</transaction> 
	<customer> 
			<firstname> </firstname>
			<lastname> </lastname>
			<birthday/> 
			<birthmonth/> 
			<birthyear/> 
			<email> </email>
			<zippostal/> 
			<address1/> 
			<address2/> 
			<phone1phone/> 
			<phone2phone/> 
			<city> </city>
			<countryiso> </countryiso>
			<stateregioniso/> 
		</customer>
		<creditcard> 
			<brand> </brand>
			<last4> </last4>
			<name> </name>
			<billingaddress1/> 
			<billingaddress2/> 
			<billingcity/> 
			<billingzippostal/> 
			<billingcountryiso/> 
		</creditcard> 
		<rebills> 
			<transaction> 
				<rebillid> </rebillid>
				<created> </created>
				<status> </status>
				<reason> </reason>
			</transaction> <transaction> 
				<rebillid> </rebillid>
				<created> </created>
				<status> </status>
				<reason> </reason>
			</transaction> 
		</rebills> 
	</transaction>

708 Request Sample

 
require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');


	
$params = [
	'merchantTransactionId' => '',	
	'gatewayTransactionId' => '',	
		 
		];

try {
	// Check Transaction
	$response = $gpnGateway->Transaction($params)->send();
	
	printf("%s-%s\n", $response->getCode(), $response->getMessage());
} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

720 – Credit Request

Description: Allows the merchant to submit a request for credit to the cardholder’s Credit Card.

720 Credit Request Data description

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	700	3 digit numeric transaction code must be 720
transaction		YES	Xml Node	Section containing Transaction Information
transaction->merchanttransid	YES (4)	YES	Character max 50.	Merchant transaction id must be included in the request. Merchant transaction id must be unique for each transaction.
transaction->amount	YES (5)	YES	Number with point decimal	Full amount to charge in currency specified. The amount must be specified as a number with decimal point and 2 digits to the right of the decimal point. Decimal separator must be point (.). example: 3500.25 = Three thousand five hundred units of currency and twenty five hundredths of a single unit of currency.
transaction->curcode	YES (6)	YES	Character 3.	May only use currencies specified in the Merchant Agreement.
transaction->statement		YES	Character max 100.	Purpose of the credit. When available, that descriptor may be used in the billing statement of the card holder.
transaction->description		YES	Character max 100.	Description of the charge. When available, that description may be used in the billing statement of the card holder.
transaction->merchantspecific1		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific2		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific3		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific4		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific5		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
customer		YES	Xml Node	Section containing Customer Information
customer->firstname		YES	Character max 50.	First name of the Customer.
customer->lastname		YES	Character max 50.	Last name of the Customer.
customer->accountid		YES	Character max 50.	Customer unique account id used inside the merchant organization.
customer->ipaddress		YES	Character max 15.	Full IP address of the customer used for this transaction
customer->email		YES	Character max 100.	Email of the Customer.
customer->countryiso		YES	Character exactly 3.	3 letter ISO country code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
customer->stateregioniso		COND	Character max 3.	1-3 character ISO 3166 state/region/province code of the Customer. Full list of codes can be obtained from the website inside your merchant account.
customer->zippostal		YES	Character max 15.	Customer’s Zipcode or postal code.
customer->city		YES	Character max 50.	Customer’s City
creditcard		COND	Xml Node	Section containing sepa bank account Information. Required for sepa transactions, forbidden for credit card transactions.
creditcard->ccnumber	YES (7)	YES	Character max 16.	Full credit card number without dashes or separators. Only numbers.
sepa		COND	Xml Node	Section containing sepa bank account Information. Required for sepa transactions, forbidden for credit card transactions.
sepa->iban	YES (7)	YES	Characters min 16, max 40.	Full international bank account number without dashes or separators. Only alphanumeric characters.
sepa->bic	YES (8)	YES	Character min 8, max 11.	Bank identitfication code (a.k.a. SWIFT code) without dashes or separators. Only alphanumeric characters.
checksum		YES	Character 36	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

720 – Response

Response Data description:

Node	Optional	Data Type	Description
result	YES	Character	Indicates the result of the transaction. SUCCESS: Customer’s Credit Card account has been credited with the amount of the transaction. DECLINED: transaction was declined. ERROR: An error has been detected in the request. The transaction has NOT been accepted by the Gateway and thus No processing has taken place and No record for the transaction has been created. PENDING: Depending on the Acquiring Bank and/or the Merchant Account Agreement, the requested credit has been successfully submitted, but has not been released to the Issuing Bank. Once the credit request has been successfully processed by the Acquiring Bank, an 820 Notification will be sent to Merchant.
merchanttransid	YES	Character max 50.	Unique merchant transaction id received in the request.
transref	OPT	Integer	System transaction reference number. Will be sent in the response only if the result is not ERROR. In the case of ERROR, a guid based identification number will be sent instead of an integer. Merchant should save this reference number for support and troubleshooting. The transaction ID used for Refunds and other transaction activity will be sent in the Merchant Notification to the URL furnished by the Merchant and specified in the Merchant Profile.
errorcode	YES	Character 3	Error Code of the transaction or 000 if no error condition found.
errormessage	OPT	Character max 100	Full description of the error.
description	OPT	Character no limit	Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.

720 Credit Request Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
	<apiUser> </apiUser>
	<apiPassword> </apiPassword>
	<apiCmd> </apiCmd>
		<transaction> 
			<merchanttransid> </merchanttransid>
			<amount> </amount>
			<curcode> </curcode>
			<statement> </statement>
			<description> </description>
			<merchantspecific1> </merchantspecific1>
			<merchantspecific2> </merchantspecific2>
			<merchantspecific3> </merchantspecific3>
			<merchantspecific4> </merchantspecific4>
			<merchantspecific5> </merchantspecific5>
		</transaction>
		<customer> 
			<firstname> </firstname>
			<lastname> </lastname>
			<accountid> </accountid>
			<ipaddress> </ipaddress>
			<email> </email>
			<city> </city>
			<countryiso> </countryiso>
		</customer>
		<creditcard> 
			<ccnumber> </ccnumber>
			<expmonth> </expmonth>
			<expyear> </expyear>
		</creditcard> 	
		<sepa> 	
			<iban> </iban>
			<bic> </bic>
		</sepa> 
		<checksum> </checksum>
	</transaction>

The 720 response is plain xml un-encoded that contains the following data:


<?xmlversion="1.0" encoding="utf-8" ?>
<transaction>
	<result> </result>
	<merchanttransid> </merchanttransid>
	<transref> </transref>
	<errorcode> </errorcode>
	<errormessage> </errormessage>
	<description> </description>
</transaction>

720 Request Sample

 
require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');


	
$params = [
	'ptid' => '651C6D7D-D360-D29A-AFEE-13CA0F15A0FA', // previous transaction ID
	'currency'      => 'USD',
	'amount'        => '10.00',
	'description'   => 'Description of item',
	'firstName'     => '',
	'lastName'      => '',
	'email'         => '',
	'clientIp'      => '',
	'country'		 => '', // Country ISO Code 
	'city'			 => '',
	'TransactionId' => '', // new Merchant Transaction ID


];

try {
	// Credit 720
	$response = $gpnGateway->credit($params)->send();
	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());

} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

755 – Update Rebill Instructions

Description: Allows the merchant to stop, restart, or change the amount for an existing rebilling transaction (submitted using the 700 transaction).

755 Request Data description:

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	701	3 digit numeric transaction code must be 701
merchanttransid	YES (4)	COND	Character max 50.	Unique merchant transaction id must be included in the request. Merchant transaction id can be up to 100 characters id.
gatetransid	Yes (5)	COND	Character max 50.	UGateway transaction id received in the original charge request.
action		YES	Character max 15	The change desired to the rebill transaction. Accepted values are: stop, start, cancel, changeamount or changecount (count may only be decreased, amount can only be changed within agreed limits)
amount		COND	Number with point decimal	New rebill amount (only required if the action is changeamount).
count	)	COND	Number with point decimal	New rebill count (only required if the action is changecount).
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

755 Response Data description

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. SUCCESS: The Rebill changes were accepted ERROR: An error has been detected and no change has been made to the Rebill transaction
merchanttransid	YES	Character max 50.	Unique merchant transaction id received in the request.
transref		Integer	System transaction reference number. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for support and troubleshooting.
errorcode	YES	Character exactly 3	Error Code of the transaction or 000 if no error condition found.
errormessage	YES	Character max 100	Full description of the error.

755 Request Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd>755</apiCmd>
		<merchanttransid> </merchanttransid>
		<gatetransid> </gatetransid>
		<action> </action>
		<amount> </amount>
		<checksum> </checksum>		
	</transaction>

755 Response

The response to a 755-Update Rebill Transaction is a plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
		<merchanttransid> </merchanttransid>
		<transref> </transref>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
	</transaction>

755 Manual Rebill Request Sample

 
require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');



$params = [
	'gatewayTransactionId' => 'CDD40F5F-6B58-3B29-174E-EACE780CF9C0', // Gateway Transaction ID from 1st trx
	'TransactionId' => '12931', // New Merchant transaction ID
];

try {
	// Manual Rebill 755
	$response = $gpnGateway->manualRebill($params)->send();


	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());
} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

756 – Manual Rebill Request

Description: Allows the merchant to manually request the execution of the Rebill and follow-up transaction when authorized by Merchant Agreement and indicated in the Merchant Profile. (Submitted using the 700 transaction)
Note: All Manual Rebill Requests must occur within the timeframe(s) indicated in the rebillwindows->window tags returned in the 700 Response or an error will be returned.

756 Manual Rebill Request data description

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	756	3 digit numeric transaction code must be 756
gatetransid	Yes (5)	COND	Character max 50.	UGateway transaction id received in the original charge request.
transaction		YES	Xml Node	Section containing Transaction Information
transaction->amount		OPT	Number with point decimal	Full amount to charge in currency specified. If not provided, rebill->amount from initiating 700 transaction will be used
transaction-> merchanttransid	YES (5)	YES	Number with point decimal	Unique merchant transaction id for this rebill transaction must be included in the request. Merchant transaction id can be up to 100 characters id.
transaction->merchantspecific1		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific2		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific3		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific4		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
transaction->merchantspecific5		OPT	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

756 Manual Rebill Request Response

756 Manual Rebill Request Response data description

Node	Optional	Data Type	Description
result	YES	Character	Indicates the result of the transaction. SUCCESS: Customer’s Credit Card account has been charged (or AUTHORIZED) with the amount of the transaction. DECLINED: transaction was declined. ERROR: An error has been detected in the request.
merchanttransid	YES	Character max 50.	Unique merchant transaction id received in the request.
transref	COND	Integer	Gateway’s transaction reference number. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for support and troubleshooting.
gatetransid	COND	Character 36	Gateway transaction ID. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for other transaction activity performed through API.
errorcode	YES	Character exactly 3	Error Code of the transaction or 000 if no error condition found.
errormessage	OPT	Character max 100	Full description of the error.
description	OPT	Character no limit	Optional details of the transaction except in the case of DECLINED and then the reason for the decline. May be null.

756 Manual Rebill Request Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd>756</apiCmd>
		<gatetransid> </gatetransid>
	<transaction>
		<amount> </amount>
		<merchanttransid> </merchanttransid>
		<merchantspecific1> </merchantspecific1>
		<merchantspecific2> </merchantspecific1>
		<merchantspecific3> </merchantspecific1>
		<merchantspecific4> </merchantspecific1>
		<merchantspecific5> </merchantspecific1>
	</transaction>
	<checksum> </checksum>		
</transaction>

756 Manual Rebill Request Response

The response to a 756-Manual Rebill Request transaction is a plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
		<merchanttransid> </merchanttransid>
		<transref> </transref>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
	</transaction>

756 Manual Rebill Request Sample

 
require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');


$params = [
	'gatewayTransactionId' => '',	
];

try {
	// Manual Rebill
	$response = $gpnGateway->manualRebill($params)->send();
	
	printf("%s-%s\n", $response->getCode(), $response->getMessage());

echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());
} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

760 – Request Refund

Description: Allows the merchant to submit a refund request.

760 Request Data description

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	760	3 digit numeric transaction code must be 760
gatetransid	Yes (3)	YES	Character max 50.	Unique gateway internal transaction id, received by the merchant in the originating 700 transaction, refers to charge transaction for which the refund has been requested.
amount	YES (5)	YES	Number with point decimal	Refunds will be in currency of the original charge transaction. The amount requested for refund may not exceed the original amount less any previous refunds approved for this transaction. Decimal separator must be point (.). example: 125.45 = One hundred and twenty-five Major Currency Units with forty-five Minor Currency Units.
reason		YES	Character max 256.	Merchant reason for requesting refund
checksum		YES	Character no limit	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by gateway to the merchant. This field must be calculated using the fields marked as “Include in checksum” (in the order indicated) plus the API key at the end.

760 Response Data description

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. NOTE: Refunds are “requested” by the Merchant. Depending on the Merchant Agreement, the refund may be automatically processed or may be delayed for review by gateway personnel. SUCCESS: Refund has been Approved PENDING: Request for refund has been accepted but yet processed. After the Refund has been processed, the results will be sent in the 860 Refund Notification that will be sent from the system server to the merchant server. Do NOT ASSUME the pending request as SUCCESS or DECLINED. ERROR: means error detected in the request, no processing takes place, and transaction was not accepted by the system. No record for the transaction has been created.
gatetransid	COND	Character 36	Gateway transaction ID. Will be sent in the response only if the result is not ERROR. Merchant should save this reference number for other transaction activity performed through API.
errorcode	YES	Character exactly 3	Error Code of the transaction or 000 if no error condition found.
errormessage	OPT	Character max 100	Full description of the error.

760 Request Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd>760</apiCmd>
		<gatetransid> </gatetransid>
		<amount> </amount>
		<reason> </reason>
		<checksum> </checksum>		
</transaction>

760 Request Response

The response to a 760 - Request Refund is a plain xml un-encoded that contains the following data:


	<?xmlversion="1.0" encoding="utf-8" ?>
	<transaction>
		<result> </result>
		<gatetransid> </gatetransid>
		<errorcode> </errorcode>
		<errormessage> </errormessage>
	</transaction>

760 Request Sample

 
require_once 'autoload.php';

use Omnipay\GPNDataEurope\GPNGateway;
set_time_limit(0);

$gpnGateway = new GPNGateway();
$gpnGateway->setApiKey('APIKEY');
$gpnGateway->setApiPassword('APIPASS');
$gpnGateway->setApiUser('APIUSER');
$gpnGateway->setMode(GPNGateway::PROD_MODE);
$gpnGateway->setPROD('https://txtest.txpmnts.com/api/transaction/');


$params = [
	'gatewayTransactionId' => '45CCC608-9BA3-9DE1-C6BB-00466386DEDD',
	'amount' => '10.00',
	'reason' => 'test'	
];

try {
	// Request Refund 760
	$response = $gpnGateway->refund($params)->send();


	printf("%s-%s\n", $response->getCode(), $response->getMessage());
	
echo 'GPN Ref. No : '; print_r($response->getData()->getrefer());
echo 'Description : '; print_r($response->getData()->getmessage());
echo 'Merchant Transaction ID : '; print_r($response->getData()->getmerchantTransId());
echo 'Status : '; print_r($response->getData()->getstatus());
echo 'Status Code : '; print_r($response->getData()->getstatusCode());
echo 'Gateway Transaction ID : '; print_r($response->getData()->gettransId());

} catch (Exception $exc) {
	print_r($exc->getCode(), $exc->getMessage());
}

Notifications

As an additional way of informing your system about command results or changes of the transaction state, our system sends notifications to the merchant’s system. After each transaction is completed, an Asynchronous Notification message will be sent from the Gateway Transaction Server to the Merchant Transaction Server at the URL provided by the Merchant. While charge transactions can be processed without the Notification, it is highly recommended to add the necessary program logic for handling the Notifications as additional information about the transaction is contained therein. Some API commands, such as Refunds, cannot be transmitted without the additional data contained in the Notifications.

Additionally notification will inform about changes to transaction, for example when Chargeback, TC-40 Fraud, Alert was issued or when transaction was refunded from MBO or by GPN Data staff.

Notifications are sent with HTTP protocol to URL provided by merchant. Data is transmitted as POST parameter strdata, which contain XML structure.

Node	Optional	Data Type	Description
result	YES	Character	Result indicates the result of the transaction. OK: means transaction notification was received and accepted. ERROR: means error detected in the notification from the gateway.
gatetransid	NO	Character 36	Unique gateway transaction id.
merchanttransid	No	Character max 50.	Unique merchant transaction id received in the request.
errorcode	NO	Character	Optional Error Code from the Merchant
errormessage	NO	Character	Optional description of the error.

Notifications Responses

Response from the merchant must be a non-encoded plain XML. Responses to each notification have the same structure. If no response, an invalid response or an error is received from the merchant, the system will attempt to deliver notification for the following 7 days. No further notifications will be sent and the merchant account may be suspended pending resolution of the problem. The Response will take the form of the following example:

  <?xmlversion="1.0" encoding="utf-8" ?>
<response>
		<result> </result>
		<gatetransid> </gatetransid>
		<merchanttransid>760</merchanttransid>
		<errorcode> </errorcode>
		<errormessage> </errormessage>		
</response>

850 – Transaction state Notification

Description: Notifies the merchant about the result of a submitted charge as well as most other commands except for Credits (720), Refunds (760), Rebills (756) and received chargebacks, frauds, alerts and other disputes.

850 Notification Data description

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	850	3 digit numeric transaction code must be 850
merchanttransid	YES (4)	YES	Character max 50.	Unique merchant transaction id received in the charge request.
gatetransid				Unique gateway internal transaction id.
amount	Yes (5)	YES	Number with point decimal	Full amount to charge in specified currency. Decimal separator must be point (.). example: 125.45 = One hundred and twenty-five Major Currency Units with forty-five Minor Currency Units.
curcode	YES (6)	YES	Character exactly 3	3-letters Currency Code. Must be one of approved in the Merchant Profile.
state		YES	Character	Current state of the transaction. AUTHORIZED: Funds from Customers Credit Card account have been “reserved” but not charged to the account. CAPTURED: Customer’s Credit Card account has been charged with the amount of the transaction. DECLINED: transaction was declined. PENDING: Transaction is in pending state CANCELED: authorization of the transaction was canceled CREDITED: Customer’s Credit Card was credited with the amount of the transaction ERROR: An error occurred during transaction processing REVERSED: Transaction was reversed REFUNDED: Transaction was refunded REFUND PENDING: Refund is waiting for staff confirmation CHARGEBACK: means that a chargeback for the transaction was received by the gateway.
merchantspecific1		YES	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
merchantspecific2		YES	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
merchantspecific3		YES	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
merchantspecific4		YES	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
merchantspecific5		YES	Character max 200.	Merchant specific data for merchant use only. Data sent in this field will be stored and sent in any communication or response to the merchant.
description		NO	Character max 100.	Additional descriptive information about this transaction status.
time		YES	Character 25.	Date and time of notification generation in ISO 8601 format, example: 2015-11-07T15:04:42+00:00
checksum		YES	Character 36	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by GPN DATA to the merchant. This field must be calculated using the fields marked as “Include in checksum” plus the API key at the end.

850 Notification Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd>850</apiCmd>
		<merchanttransid> </merchanttransid>
		<gatetransid> </gatetransid>
		<amount> </amount>
		<curcode> </curcode>
		<state> </state>
		<merchantspecific1> </merchantspecific1>
		<merchantspecific2> </merchantspecific2>
		<merchantspecific3> </merchantspecific3>
		<merchantspecific4> </merchantspecific4>
		<merchantspecific5> </merchantspecific5>
		<description> </description>
		<time> </time>
		<checksum> </checksum>		
</transaction>

860 – Refund Notification.

Description: Notifies the merchant about the result of a submitted refund.

860 Notification Data description

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	860	3 digit numeric transaction code must be 860
gatetransid	YES (4)	YES	Character max 50.	Unique gateway transaction id refers to charge transaction for which the refund has been requested.
amount	Yes (5)	YES	Number with point decimal	Full amount to charge in specified currency. Decimal separator must be point (.). example: 125.45 = One hundred and twenty-five Major Currency Units with forty-five Minor Currency Units.
status	YES (7)	YES	Character	Last change in the status of the transaction. DECLINED: The Refund Request was declined. SUCCESS: The Refund has been successfully Processed
reason		OPT	Character max 256.	The gateway may optionally include an explanation for Approving or Declining a Request for Refund. This field will contain the reason for a REFUND processed by GPN DATA where no request for refund has been made.
merchantspecific1		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific2		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific3		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific4		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific5		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
time		YES	Character 25.	Date and time of notification generation in ISO 8601 format, example: 2015-11-07T15:04:42+00:00
checksum		YES	Character 36	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by GPN DATA to the merchant. This field must be calculated using the fields marked as “Include in checksum” plus the API key at the end.

860 Notification Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd>860</apiCmd>
		<gatetransid> </gatetransid>
		<amount> </amount>
		<status> </status>
		<reason> </reason>
		<merchantspecific1> </merchantspecific1>
		<merchantspecific2> </merchantspecific2>
		<merchantspecific3> </merchantspecific3>
		<merchantspecific4> </merchantspecific4>
		<merchantspecific5> </merchantspecific5>
		<time> </time>
		<checksum> </checksum>		
</transaction>

870 – Rebill Notification.

Description: Notifies the merchant about the result of a submitted Rebill transaction.

870 Notification Data description

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	860	3 digit numeric transaction code must be 860
gaterebillid	YES (4)	YES	Character 36.	Unique gateway transaction id of the originating transaction (Rebill ID).
gatetransid	YES (5)	COND	Character 36	Unique gateway transaction id for this Rebill occurrence that has just been triggered by a 756-Manual Rebill Request if applicable.
status	Yes (6)	YES	Character	SUCCESS: means transaction was processed and approved. DECLINED: means transaction was declined. ERROR: means there was some type of error transpired with this transaction CANCELED: rebill was canceled (e.g. because of too many declined attempts)
reason		NO	Character max 256.	In case of a DECLINED transaction, a description of an ERROR
merchantspecific1		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific2		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific3		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific4		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific5		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
time		YES	Character 25.	Date and time of notification generation in ISO 8601 format, example: 2015-11-07T15:04:42+00:00
checksum		YES	Character 36	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by GPN DATA to the merchant. This field must be calculated using the fields marked as “Include in checksum” plus the API key at the end.

870 Notification Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd>870</apiCmd>
		<gatetransid> </gatetransid>
		<gaterebillid> </gaterebillid>
		<status> </status>
		<reason> </reason>
		<merchantspecific1> </merchantspecific1>
		<merchantspecific2> </merchantspecific2>
		<merchantspecific3> </merchantspecific3>
		<merchantspecific4> </merchantspecific4>
		<merchantspecific5> </merchantspecific5>
		<time> </time>
		<checksum> </checksum>		
</transaction>

880 – Dispute Notification.

Description: Notifies the merchant about disputes to transaction.

880 Notification Data description

Node	Include in Checksum (in this order)	Optional	Data Type	Description
apiUser	YES (1)	YES	Character max 50.	The API user assigned by the Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiPassword	YES (2)	YES	Character max 50.	The API password assigned by Gateway to the merchant. Can be obtained from the website inside your merchant account.
apiCmd	YES (3)	YES	880	3 digit numeric transaction code must be 880
gatetransid	YES (4)	YES	Character max 50.	Unique gateway internal transaction id.
transref		YES	Character max 50.	Unique gateway internal transaction reference.
merchanttransid		YES	Character max 50.	Unique merchant transaction id received in the request.
status	Yes (5)	YES	Character	CHARGEBACK: transaction was reported as chargeback. FRAUD: transaction was reported as TC-40 Fraud ALERT: transaction was reported as a fraud by issuer through independent system COPYREQUEST: Issuing Bank requested some details about the transaction and proof of product delivery or service provide.
amount		YES	Character exactly 3	3-letter code of currency, example: USD, EUR
disputeDate		YES	YYYY-MM-DD HH:MM:SS	Date of the dispute
ARN		NO	Character max 256.	Acquirer reference number. Required for dispute procedure
reasonCode		COND	Character no limit	Code of chargeback’s reason
reasonText		COND	Character max 256.	Description of chargeback’s reason
merchantspecific1		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific2		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific3		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific4		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
merchantspecific5		YES	Character max 200.	Merchant specific data for merchant use only. Data sent is the same as was sent in the 700 transaction.
time		YES	Character 25.	Date and time of notification generation in ISO 8601 format, example: 2015-11-07T15:04:42+00:00
checksum		YES	Character 36	SHA-1 calculated using the fields specified by the transaction plus the API key assigned by GPN DATA to the merchant. This field must be calculated using the fields marked as “Include in checksum” plus the API key at the end.

880 Notification Sample

  <?xmlversion="1.0" encoding="utf-8" ?>
<transaction>
		<apiUser> </apiUser>
		<apiPassword> </apiPassword>
		<apiCmd>880</apiCmd>
		<gatetransid> </gatetransid>
		<transref> </transref>
		<merchanttransid> </merchanttransid>
		<status> </status>
		<amount> </amount>
		<currency> </currency>
		<disputeDate> </disputeDate>
		<arn> </arn>
		<reasonCode> </reasonCode>
		<reasonText> </reasonText>
		<merchantspecific1> </merchantspecific1>
		<merchantspecific2> </merchantspecific2>
		<merchantspecific3> </merchantspecific3>
		<merchantspecific4> </merchantspecific4>
		<merchantspecific5> </merchantspecific5>
		<time> </time>
		<checksum> </checksum>		
</transaction>

Transaction Status Codes

Status Code	Status Description
`101`	Approved / Capture
`102`	Authorized
`103`	Capture Pending
`107`	Pending
`108`	Pending 3DS Authentication
`190`	Partial success
`201`	DECLINED by Bank
`202`	System Decline
`203`	Maintenance decline
`204`	Transaction limits decline
`251`	Preauthorization Cancelled
`252`	Cancel pending
`253`	Auto cancel pending
`254`	Preauthorization Cancelled automatically
`211`	3DS Timeout
`301`	Refunded
`302`	Refund requested
`304`	Partial Refunded
`306`	Refund pending
`501`	Declined Fraud Pick-up
`502`	Declined Fraud Lost
`503`	Declined Fraud Stolen
`504`	Declined Fraud
`505`	Declined Possible Fraud
`350`	Chargeback
`351`	Representment
`400`	Credit granted
`450`	Credit declined
`451`	Credit declined by bank

ERROR

Status Code	Status Description
`901`	Bank Error
`902`	Gateway Error
`903`	Timeout Error
`904`	Response Error
`905`	Error (No Response)
`907`	Error (Configuration)
`909`	Error (Generic)
`910`	Error (MPI)
`911`	Error (limits)

3D Secure Explanation

3DS is a fraud prevention system that has different names depending on the Card Issuer (Verified by Visa, Mastercard SecureCode, etc.) but it functions the same way. During a CNP (Card Not Present) e-Commerce transaction, the CH (Card Holder) will be redirected to a page hosted by the Issuing Bank for his Card and there he will input identification information as required by his bank to verify that he is indeed the CH. The information may be as simple as a PIN or may ask other questions known only to the CH and the Issuing Bank. No one else is involved, not the Merchant, the Gateway or the Acquiring Bank. The process works as follows:

Once the CH has completed the payment form and has entered the card data (PAN, CVV, etc.) the CH selects 'Submit' (or pay now or whatever is used on the Merchant site to submit the payment)
The merchant transmits the payment transaction to the Gateway
The Gateway submits the PAN to an MPI (an authorized participant in the 3DS system) who then checks to see if the Issuing Bank is a participant in the associated 3DS program and if so, obtains the ACS (Access Control Server) Url.
- If the Issuing Bank is NOT a participant in 3DS, the transactin will be dealt with in the manner proscribed by the Gateway for non-3DS transactions
- If the Issuing Bank IS a participant in 3DS, the following steps will continue.
The Gateway sends to the Merchant the PaReq, MD and the ACS URL which will be used by the Merchant to provide a redirect for the CH to the Secure web page provided by the Issuing Bank for 3DS validation.
The Merchant constructs a redirection form which sends the PaReq, MD and TermUrl via POST fields to the ACS URL (the ACS URL is the form's "action" attribute), and presents it to the user's browser.
The Cardholder follows the redirection form to the ACS website and performs the authentication procedure.
There are four possible outcomes to this part of the process:
- The CH is properly validated and the ACS returns to the TermUrl provided in the redirect the proper 3DS authorization for this transaction only (any subsequent transactions must repeat this process). The authorization consists of several POST variables which are meant to be forwarded to the Gateway in an API call (ACSRes node in 705).
- The CH takes too long to decide and the page times out – Transaction ends in Error
- The CH fails validation – Transaction ends in Decline (with possible fraud notation)
- The CH's card is not enrolled in his banks program and declines to enroll at this time – Transaction ends in Decline
Assuming a successful validation, the process continues and the transaction is submitted to the Acquiring Bank along with the data (ACSRes) returned by the ACS for normal processing. The outcome of the transaction is still based upon normal criteria such as sufficient funds available, etc.

With 3DS, the Issuing Bank is hard pressed to accept a declaration of fraud from the CH if a chargeback is attempted. Non-fraud reasons are still acceptable (did not receive promised goods or services, etc.)

Note:

Display the 3D authentication inline - do not use popups or separate windows for the authentication because popups/separate windows may be blocked by the shopper’s browser settings. Also it is forbidden by Visa and MasterCard rules. Even when the window is not blocked (e.g. by using target="_blank") it is still confusing for the shopper to face multiple windows. 3D Secure Best Practices strongly encourage you to use the inline approach - for U.S. merchants this is even a „must have“-requirement. After this redirect, the merchant has no longer any control over the client browser and therefore awaits the asynchronous response message from the payment server about the final result of the payment transaction.

3D Transaction step 1

When you will get 3DS response, first you must save incoming MD parameter. It will be required in step 2. After that you must redirect customer to received ACS URL and transmit all parameters (under parameters element) with POST method. Simplest way is to generate autosubmitting HTML form. Below you can find example HTML code of that form:

 
<!DOCTYPE html> 
<html> 
 <head> 
   <meta http-equiv="Content-Type" content="text/html; Charset=UTF-8"> 
   <title>3D-Secure Payment Transaction</title>
 </head> 
 <body OnLoad="OnLoadEvent();"> 
   <form id="secureForm" action="_ACS_URL_HERE_" method="POST"> 
    <div> 
	 <h1 style="text-align: center;">Processing your 3D-Secure Payment Transaction</h1> 
	 <input type="hidden" name="PaReq" value="_PAREQ_HERE_" /> 
	 <input type="hidden" name="MD" value="_MD_HERE_" /> 
	 <input type="hidden" name="TermUrl" value="_TERM_URL_HERE_" /> 
	 <noscript> 
	   <p>JavaScript is currently disabled or is not supported by your browser.</p> 
	   <p>Please click Submit to continue the processing of your 3D-Secure Payment transaction.</p>
	   <input type="submit" value="Submit" /> 
	 </noscript> 
	 </div> 
    </form> 
    <script type="text/javascript">
	/* <![CDATA[ */ 
	function OnLoadEvent() { document.getElementById('secureForm').submit(); } 
	/* ]]> */ 
    </script> 
 </body> 
</html>

3D Transaction step 2

TERM URL PAGE THAT YOU WILL RECIEVE " MD AND PARES " AND SEND 705 TO Gateway

When you will receive 3DS response to URL you provided, you must forward it to us using API call 705. ACSRes value is full, unmodified HTTP request body sent to your 3DS Return URL, and then Base64 encoded. For example, in curl you can obtain ACSRes value by using base64_encode(file_get_contents('curl://input')). More details about API call 705 you can find in chapter 705 - 3DS Transaction continuation.



$md = $_POST['MD'];
$encoded = base64_encode(file_get_contents('curl://input'));

// Checksum calculation - see the Data Table for the API Command being used to verify the fields used and the field order
$checksum = sha1('ApiUser'.'ApiPassword'.'705'.'Auth3DS'.$md);

//create XML of data to be posted
$requestMessage = '<?xml version="1.0" encoding="utf-8" ?>
    <transaction> 
		<apiUser>ApiUser</apiUser>
		<apiPassword>ApiPassword</apiPassword>
		<apiCmd>705</apiCmd>
		<auth>
			<type>Auth3DS</type>
			<ACSRes>'.str_replace('%','/',$encoded).'</ACSRes>
			<MD>'.$md.'</MD>
		</auth>
		<checksum>'.$checksum.'</checksum>
    </transaction>';
        echo '<br />Request Message :'.$requestMessage;

$ch= curl_init();

 //Set up curl parameters
 curl_setopt($ch, CURLOPT_URL, 'https://txtest.txpmnts.com/api/transaction/');       // set remote address
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('strrequest' =>$requestMessage)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);    // Make CURL pass the response as a curl_exec return value instead of outputting to STDOUT
curl_setopt($ch, CURLOPT_POST, 1);              // Activate the POST method
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_HEADER, 0);

//execute the connection
$result = curl_exec($ch);

echo "<br />Result Code:<pre>".$result.']]></pre>';

$debugoutput = curl_getinfo($ch);

$curl_error_message = curl_error($ch); // must retrieve an error message (if any) before closing the curl object
echo "<br />Curl Error message:".$curl_error_message;
curl_close($ch);
//Trim headers
$pos = strstr($result, "\n");
$result = substr($result, $pos);
echo '<br />Result'.$result;

What is 3DS?

Verified by Visa, SecureCode by MasterCard and similar programs from JCB (J/Secure, American Express and other card companies are programs introduced to fight fraudulent use of cards (collectively referred to as “3DS”). These programs also alleviate some of the pain to the merchant caused by fraudulent activity.

Why should I use 3DS?

In the e-Commerce community, fraudulent use of credit cards can be a painful and expensive experience. The protection of Chargeback is designed to protect the cardholder from fraudulent activity, but the burden is simply shifted to the e-Commerce merchant. The situation is further compounded by fraudulent use of the Chargeback protection afforded to the cardholder by unscrupulous cardholders. Since the burden of proof on a Chargeback is placed upon the merchant, many cardholders (especially in the USA) have learned that they can use the Chargeback to get relief for “buyer’s remorse” when the normal refund policy of the merchant does not allow them to escape the responsibilities of their purchasing decisions. Simply by claiming that they were not the person who authorized the charge, the cardholder requests a Chargeback by claiming “fraud” further compounding the problems for the merchant.

While Chargebacks, in general, are problems for the e-Commerce merchant, the frequent use of certain categories of Chargebacks described as “fraudulent” (the chargeback codes are different for different card companies) can result in cancellation of the MID. Enrollment and use of the 3DS programs offered by the card companies can offer some protection for the merchant from possible loss of their MID due to excessive Chargeback claims of this nature. (Visa Reason codes 75, 83)

How does 3DS work?

During a financial transaction, after the cardholder has input his card details for the charge and hit the Submit or Pay button, the cardholder is redirected to a verification web page provided by the Bank that issued his card. The process of verification is unique for each bank and is known only to the cardholder and the bank. The process of charging the card is then resumed as normal, but the transaction is noted to be a 3DS transaction. Standard reasons for Chargebacks (“Did not receive product or service”, “Terms of sale were not met”, etc.) are unaffected. However, claims that are fraud based (“I did not authorize that transaction”) are rejected. The actual list of 3DS protected Chargeback codes is unique to each card company and provided upon enrollment.

Not all Issuing Banks participate in 3DS so what happens then?

If the merchant is enrolled in a 3DS program all transactions submitted as 3DS receive the same protection, even if the Issuing Bank is not a 3DS participant or the cardholder has not enrolled his card. The process works like this: at the beginning of the transaction, it is submitted to a server to see if the Issuing Bank is a 3DS participant. If yes, then the normal 3DS process is continued. If no, then the card is processed normally, however, the transaction is “marked” as a 3DS transaction, thus incurring the protections proscribed by the card companies.

What is the downside of 3DS?

All good things have a price. During a 3DS transaction with a card from a participating bank, the cardholder may perceive being redirected to another website as a “scam” and simply close the browser. There are two causes for this problem:

The most frequently occurring is that the screen given to the cardholder by the merchant before he is redirected does not contain an explanation or the 3DS logos from the card companies (“Verified by Visa”, “Secure Card by MasterCard”) . This is easily corrected by the merchant presenting an “assuring” redirect screen to the cardholder.
Some banks contract out their 3DS authorization process and the Verification screen where they have been redirected does not contain the URL for their bank. This is infrequent, but does happen.

Rebill Explanation

As noted before, a Rebill transaction (also known as Recurring Charge) occurs when the cardholder and merchant agree to purchase goods or services on an ongoing basis over a period of time. Recurring transactions are multiple transactions processed at predetermined intervals, not to exceed one year between transactions. Examples of recurring transactions include insurance premiums, subscriptions, Internet service provider fees, membership fees, tuition, or utility charges.

At the time of the original 700 Start Credit Card charge transaction, all Rebill information must be included in order for our Gateway to issue the Rebill charges for the amount and frequency specified. It is not possible to ask for Rebill charges if the original transaction did not include this information. It is possible to request an increase in the amount originally specified for the Rebill, up to 15% of the original transaction. It is NOT possible to change the frequency of the Rebill charges, however, the Rebill may be cancelled and a new Transaction issued with the new frequency. This will require the complete Cardholder data (PAN, CVV, Exp Date, Name on Card)

A Rebill transaction is a “contract” between the Merchant and the Cardholder according to the Terms and Conditions provided to the Cardholder by the Merchant at the time of purchase. The Cardholder is in effect agreeing to the Rebill charges that are stipulated at that time, by providing their Cardholder Data. This is why changes to Amount (greater than previously specified), Frequency and Number of Occurrences are not possible. Only when the Cardholder enters his Cardholder Data, can we show that the Cardholder is aware of the terms of the Rebill charges.

The Command 700 Start Credit Card Charge used to initiate a series of Rebill transactions contains all of the necessary tags for establishing a Rebill series. The Merchant Account Profile will be populated with default data for these tags (derived from the Merchant’s published pricing and Terms and conditions) and any of the tags omitted will be filled with the default data. One exception to this is the “followup” charge and it will be explained in the next paragraph. If “followup is not used, by the merchant, no data will be inserted.

The “followup” feature allows a third amount and billing date to be inserted into the Rebill series and is not counted when calculating the rebill->count. The intent of this feature is best outlined in an example:

Product sell price is $100.00, but is offered with a “Trial Price” of 15.00 and if the customer keeps the product, the balance of the first order is billed at 85.00 on the date specified. Future Rebills begin either on a date specified or if not specified, one period (rebill->frequency) from the original transaction date.

IFrame Integration

Node	Required	Description
data-merchant-id	Required	Merchant ID will be provided by TechSupport, during initial communication.
data-amount	Required	Amount must be expressed in cents, Example 2000 cents in order to pay $20.00
data-currency	Required	Currency must be expressed by 3 letters ISO 4217. Example : USD If wished multiple currencies can be shown in a drop down menu by listing separate by command as following "USD,EUR,GBP". Note : Only currencies specified in the Merchant Agreement can be used
data-description	Required	Description of the product or service
data-company	Optional	If not provided GPN Data will be visible at the iFrame checkout data-logo
data-billing-address	Optional	Default is set to “false” as the same Customer address will be used for Billing. set to “true” to be included in the form
data-order-id	Optional	To be used for auto population of the iFrame checkout form. Order ID on merchant web site. (if not included, this will be generated by the PaymentPage)
data-customer-id	Optional	To be used for auto population of the iFrame checkout form. Customer ID on merchant web site. (if not included, it will be empty)
data-customer-email	Optional	To be used for auto population of the iFrame checkout form. Customer Email address.
data-customer-phone	Optional	To be used for auto population of the iFrame checkout form. Customer phone number.
data-customer-firstname	Optional	To be used for auto population of the iFrame checkout form. Customer first name.
data-customer-lastname	Optional	To be used for auto population of the iFrame checkout form. Customer last name.
data-customer-birthdate	Optional	To be used for auto population of the iFrame checkout form. Customer last BirthDate. or set to “true” in order to be shown in the form.
data-customer-addressline	Optional	To be used for auto population of the iFrame checkout form. Customer street address.
data-customer-zipcode	Optional	To be used for auto population of the iFrame checkout form. Customer zipcode.
data-customer-city	Optional	To be used for auto population of the iFrame checkout form. Customer city
data-customer-state	Optional	To be used for auto population of the iFrame checkout form. Customer State two letter ISO
data-customer-country	Optional	To be used for auto population of the iFrame checkout form. Customer State three letter ISO
data-merchant-spec1	Optional	To be used for additional merchant data, which will be received in the Notification API call 850
data-merchant-spec2	Optional	To be used for additional merchant data, which will be received in the Notification API call 850
data-merchant-spec3	Optional	To be used for additional merchant data, which will be received in the Notification API call 850
data-merchant-spec4	Optional	To be used for additional merchant data, which will be received in the Notification API call 850
data-merchant-spec5	Optional	To be used for additional merchant data, which will be received in the Notification API call 850
Rebill Feature	Optional	In order to enable rebill feature a "data-rebill" node with a TRUE value must be added on the button data. 850
data-rebill	Optional	Note Rebill execution will have to be done via GPN Data Merchant Back Office

Rebill Feature

In order to enable rebill feature a "data-rebill" node with a TRUE value must be added on the button data.

Node	Required	Description
data-rebill	Required	Value must be TRUE to enable rebill feature.
data-allow-rebill	Optional	If TRUE a checkbox will appear on the iFrame and the customer must check it accepting the rebill payment
data-rebill-amount	Optional	Amount to be charged periodically. Must be expressed in a decimal with 2 decimal digits Example $20.00, $99.99
data-rebill-freq	Optional	Period of time between charges. Must be expressed {digit}(d\|w\|m\|y) expression d = days, m = month, y = year. Example 30d, 1m.
data-company	Optional	If not provided GPN Data will be visible at the iFrame checkout data-logo
data-rebill-count	Optional	Number of periodic charges.
data-rebill-start-date	Optional	Date on which rebill should start. Must be expressed in the following format YYYY-mm-dd
Customization Features	Optional	Following option can be added to the iFrame form:
data-auto-open	Optional	If set to "true" iframe page will auto open when usuing pop-up mode
data-page-container	Optional	If data-page-container = ".payment-form" and it's specified in a component selector, for example class="g pn-payform" Payment page will open in flat mode and not in pop-up mode
data-skip-customerinfo	Optional	If set to "true" iframe page will open in Step2 - Card Data In order to use this option, customer data needs to be sent in the form

IFrame Request Sample:

 
<html>
<head>
<title>Merchant Site</title>
</head>
<body>
<h2>Merchant Site</h2>
<button
type="button" class="gpn-button-sample"
data-merchant-id="merchant-pretty-name"
data-amount="2000"
data-currency="EUR"
data-company="Merchant CompanyName"
data-description="Description of Product or Service"
data-logo="/assets/img/logo.png"
data-billing-address="true"
data-order-id="order-reference"
data-customer-id="customer-account-id"
data-customer-email="[email protected]"
data-customer-phone="48000000000"
data-customer-firstname="John"
data-customer-lastname="Doe"
data-customer-birthdate="1989-08-30"
data-customer-addressline="Street 24"
data-customer-zipcode="12345"
data-customer-city="Wonderland"
data-customer-state="MA"
data-customer-country="POL"
Store Card
>
</button>
<script src="https://[payment page domain]/checkout.js"></script>
</body>
</html>

IFrame Rebill Request Sample:

In order to enable rebill feature a "data-rebill" node with a TRUE value must be added on the button data.



<html>
<head>
<title>Merchant Site</title>
</head>
<body>
<h2>Merchant Site</h2>
<button
type="button" class="gpn-button-sample"
data-merchant-id="merchant-pretty-name"
data-amount="2000"
data-currency="EUR"
data-company="Merchant CompanyName"
data-description="Description of Product or Service"
data-logo="/assets/img/logo.png"
data-billing-address="true"
data-order-id="order-reference"
data-customer-id="customer-account-id"
data-customer-email="[email protected]"
data-customer-phone="48000000000"
data-customer-firstname="John"
data-customer-lastname="Doe"
data-customer-birthdate="1989-08-30"
data-customer-addressline="Street 24"
data-customer-zipcode="12345"
data-customer-city="Wonderland"
data-customer-state="MA"
data-customer-country="POL"
data-rebill="true"
data-allow-rebill="false"
data-rebill-amount="2.33"
data-rebill-freq="1m"
data-rebill-count="5"
data-rebill-start-date="2016-12-29">
Button Pay with GPN DATA
>Pay with Rebill
</button>
<script src="https://[payment page domain]/checkout.js"></script>
</body>
</html>

Payment Page Instructions using HTTP Form Post

Revised 2015-10-29

Integration from an eCommerce web page can be accomplished using HTTP Form Post. These instructions are designed to allow you to cut and paste the HTML code into your webpage and simply replace various parameters as indicated.These instructions are intended for the person who is capable of making HTML changes to your website. If you cannot do this, forward these instructions to someone who can and have THEM contact our Technical Support team on your behalf.

DO NOT ask the Technical team to do the integration for you or to teach you about HTML.
DO NOT play middleman and relay instructions between the GPN Tech Team and your programmer
DO NOT ask the GPN Tech Team any questions until you have read this document in its entirety.

Step 1

login to your MBO (Merchant Back Office) using the credentials emailed to you. Navigate to the Merchant::Technical Integration page and obtain your:

MerchantID
Transaction Currencies
Transaction URL
apiKey

Step 2

For each product or service you offer on your web page, you must add an HTML form using method=”post” with a submit button (or image used as a button). Use hidden HTML tags to send the data.

MerchantID
Transaction Currencies
Transaction URL
apiKey

Note #1

Replace https://your Transaction URL with the Transaction URL obtained in Step 1

Note #2

Replace your MerchantID the MerchantID obtained in Step 1

Note #3

Replace the amount of this item the exact amount listed on your website for this plan. The amount must be expressed as 129.00 using a period for the decimal and including the 00.

`129.00`	Correct
`129`	Incorrect
`105.90`	Correct
`105.9`	Incorrect

Note #4

Replace the currency used with one of the Transaction Currencies obtained in Step 1

Note #5

Replace the name of the your plan with the name of your Plan, exactly as it appears on your website.

Note #6

Replace the calculated checksum with the checksum calculated in Step 3

Step 3 - Checksum

To assure the integrity of the information being sent, we use a checksum calculated using various parameters in a concatenated string and a sha1() function. The parameters used are the following and MUST be used in the order given:

merchantid amount currency description (maintain any spaces used in the description) apikey

The apiKey can be obtained from the MBO (see Step #1)

Using the following example:

Merchantid = 9101 amount = 29.99 currency = USD description = My Product apikey = 66D91A29-0E7A-4D72-AE75-D2C4C5DBE223

$str = 910129.99USDMy Product66D91A29-0E7A-4D72-AE75-D2C4C5DBE223

Checksum = sha1($str) = 2ae38e4d472f077c40e22d675beee5db2de117dc

The checksum will be unique for each HTML Form (see Step#2) used. If you make any changes to any of the 5 elements used to calculate the checksum, you must recalculate.

Step 4 - Testing

Once you have completed your HTML Form(s), you must make a test transaction.

During Testing, no transactions will be submitted to a real bank and no cards will be charged
You may use any valid card number (except 4111111111111111). If you need test card numbers, please search the web for “get credit card numbers”.
Select an expiration date greater than this month and year
Use 300 for the CVV for Approved results or 800 for Declined results
Use a realistic values for the customer details (first and last name, email, etc). DO NOT USE NAMES LIKE TEST OR TESTTEST!
If you choose to make multiple tests using the same card number you MUST use the same customer details! (we do not support different people using the same card number)
It is best that you test each of your Plans
Notify our Technical Support team when you believe you have finished testing. You may do so via the online chat in your MBO or via email: [email protected]

Note:

Your transactions will be processed as 3D Secure (Verified by Visa, SecureCard by MasterCard). During testing, your account is connected to a TEST bank to simulate live processing and no cards are actually sent to a live bank. The GPN Test bank includes a 3D Secure Authentication Page. This is for Testing only and no customer will see this page. If their card is enrolled in a 3D Secure program, they will see an Authentication Page from the Bank that issued their card. If the card is not enrolled, the card will be processed normally.

Step 5 – Migrating to PRODUCTION account and live processing

Once our Technical Team checks your test transactions and are satisfied they meet our requirements, the Tech will notify you via online chat in your MBO and email. At that time, the GPN DATA Sales team will be notified that you have completed integration. When the Tech Support Team receives permission from the Sales Team that all agreements are in order, you will be contacted by the Technical Team regarding your next steps.

Do not ask the Technical Support Team when you will be able to begin live processing. If you have questions such as this, refer them (as well as any other commercial questions) to your Account Manager.

Step 6 – Migrating to PRODUCTION account and live processing

Once we receive permission from your Account Manager, you will receive an email with login credentials to your MBO on the PRODUCTION server.

You must repeat
Step 1 to obtain your PRODUCTION account details.
Change the MerchantID and Transaction URL for each Plan (see Step 2)
Recalculate the checksums using the new API key
Notify Technical Support via online chat in your MBO that you are ready to try at least one of your Plans on the PRODUCTION server to be certain your changes are correct. This MUST be accomplished during live communications between you and the Tech.
Wait for the Tech to tell you that you may begin to test one of your plans with the new account information. You may use a test card number (Step 4 Item 2) or a real credit card as the test will not result in any charges to the card.
If the test is unsuccessful, work with the Tech to see what is wrong and correct it.
If the test is successful, the Tech will inform you to wait a few minutes while your account is connected to the live Acquiring Bank.
Once the Tech confirms that you are connected to a live Acquiring Bank, you are ready to begin accepting real credit card transactions.

Optional Additional Transaction Data

The HTML Form must contain these fields at a minimum:

merchantid
amount
currency
description
checksum

You may also select to “pre-populate” the Payment Page with Customer data. Simply add additional lines with hidden tags:

<input type="hidden" name="" value="”>

The names for the additional Tags are:

orderid (if not included, this will be generated by the PaymentPage)
firstname
lastname
birthday
birthmonth
birthyear
email
country (3 character iso code)
stateregion (2 character iso code)
zippostal
city
address1
address2 (optional second address line if needed)
phone (full with country code and area code, without +)
accountid (Your own method of customer id used in your system. If not provided email is used).

HTML Form Request Example

 
<form action="https://TransactionURL" method="post"> {see note #1} 
  <input type="hidden" name="merchantid" value="your MerchantID"> {see note #2} 
  <input type="hidden" name="amount" value="the amount of this item"> {see note #3} 
  <input type="hidden" name="currency" value="the currency used"> {see note #4} 
  <input type="hidden" name="description" value="the name of the your plan"> {see note #5} 
  <input type="hidden" name="checksum" value="the calculated checksum"> {see note #6} 
  <input type="submit" value="Purchase Now"> 
</form>

ERROR CODES

Error codes may include but not be limited to the ones listed below. At any time new error codes may be introduced.

`007`	Invalid transaction ID
`008`	Authorization failed (Invalid API credentials)
`009`	Command do not exist
`010`	Incomplete data provided in API Request
`121`	Invalid amount
`130`	Invalid currency
`146`	Invalid checksum
`147`	Merchant account inactive
`148`	Duplicated transaction
`153`	Customer/Account ID mismatch
`159`	Customer data mismatch
`161`	Rebill general error
`165`	Rebill window missed
`201`	Unsupported feature
`202`	Invalid value
`211`	Database error
`220`	Integrity error
`250`	System maintenance
`299`	Generic system error
`301`	Card unsupported
`302`	Luhn test failed
`304`	Card expired
`305`	Name on card mismatch
`351`	Card blocked
`352`	Card and Customer blocked
`801`	No input
`802`	Input is not XML
`810`	Input field invalid
`811`	Required input field missing
`812`	Input data format invalid

Remember that the above codes are not the only error codes, simply some of the more common and basic ones. The full description of the error will be returned in the errormessage node in case of error and in description node otherwise.

Transaction limits Error Codes

`450`	Velocity limit reached (too many transactions in too short time period)
`451`	Does not meet minimum single transaction amount for the customer
`452`	Exceeds single transaction amount for the customer
`453`	Exceeds transaction number limit per customer per day
`454`	Exceeds transaction total amount limit per customer per day
`455`	Exceeds transaction number limit per customer per week
`456`	Exceeds transaction total amount limit per customer per week
`457`	Exceeds transaction number limit per customer per month
`458`	Exceeds transaction total amount limit per customer per month
`459`	Exceeds transaction number limit per customer per 2 months
`460`	Exceeds transaction total amount limit per customer per 2 months
`461`	Exceeds transaction number limit per customer per quarter
`462`	Exceeds transaction total amount limit per customer per quarter
`463`	Exceeds transaction number limit per customer per half-year
`464`	Exceeds transaction total amount limit per customer half-year
`465`	Exceeds transaction number limit per customer per year
`466`	Exceeds transaction total amount limit per customer per year
`467`	Too many declined transactions with this customer within a day
`468`	Too many declined transactions with this customer within a month
`471`	Does not meet minimum single transaction amount for the card
`472`	Exceeds single transaction amount for the card
`473`	Exceeds transaction number limit per card per day
`474`	Exceeds transaction total amount limit per card per day
`475`	Exceeds transaction number limit per card per week
`476`	Exceeds transaction total amount limit per card per week
`477`	Exceeds transaction number limit per card per month
`478`	Exceeds transaction total amount limit per card per month
`479`	Exceeds transaction number limit per card per 2 months
`480`	Exceeds transaction total amount limit per card per 2 months
`481`	Exceeds transaction number limit per card per quarter
`482`	Exceeds transaction total amount limit per card per quarter
`483`	Exceeds transaction number limit per card per half-year
`484`	Exceeds transaction total amount limit per card half-year
`485`	Exceeds transaction number limit per card per year
`486`	Exceeds transaction total amount limit per card per year
`487`	Too many declined transactions with this card within a day
`488`	Too many declined transactions with this card within a month
`490`	Exceeds available whitelisted customer per merchant limit
`491`	Exceeds available whitelisted customer per merchant limit
`493`	Exceeds available whitelisted customer global (gateway) limit

GPN DATA MERCHANT API INTEGRATION GUIDE API INTEGRATION GUIDE (v 1.12.0)

Overview

Terminology Used

Testing

Security

PHP SDK on Github

PHP SDK Installation

cURL Request Sample

GPN DATA MERCHANT API

700 – Start Credit Card charge (3DS Enabled)

700 Request Data description:

700 – Response

Response Data description:

701 – Request Capture Authorization

701 Request Data description:

701 Response Data description

702 – Request Cancel Authorization

702 Request Data description:

702 Response Data description

705 – 3DS Transaction Continuation

705 Request Data description:

705 Response Data description

705 Request

705 Response

709 – Check transaction status

709 Request Data description:

709 Response Data description

709 Request Sample

709 Response

708 – Check transaction details

708 Request Data description:

708 Response Data description

708 Request Sample

708 Response

720 – Credit Request

720 Credit Request Data description

720 – Response

Response Data description:

755 – Update Rebill Instructions

755 Request Data description:

755 Response Data description

755 Request Sample

755 Response

756 – Manual Rebill Request

756 Manual Rebill Request data description

756 Manual Rebill Request Response

756 Manual Rebill Request Response data description

756 Manual Rebill Request Sample

756 Manual Rebill Request Response

760 – Request Refund

760 Request Data description

760 Response Data description

760 Request Sample

760 Request Response

Notifications

Notifications Responses

850 – Transaction state Notification

850 Notification Data description

850 Notification Sample

860 – Refund Notification.

860 Notification Data description

860 Notification Sample

870 – Rebill Notification.

870 Notification Data description

870 Notification Sample

880 – Dispute Notification.

880 Notification Data description

880 Notification Sample

Transaction Status Codes

ERROR

3D Secure Explanation

Note:

3D Transaction step 1

3D Transaction step 2

What is 3DS?

Why should I use 3DS?

How does 3DS work?

Not all Issuing Banks participate in 3DS so what happens then?

What is the downside of 3DS?

Rebill Explanation

GPN DATA MERCHANT API
INTEGRATION GUIDE

API INTEGRATION GUIDE (v 1.12.0)