Gateway Request API - CardGate

The Request API expects that you send your customer to the gateway URL together with some variables. The variables can to be send by a POST or GET request.

Entry point of the gateway is https://secure.curopayments.net/gateway/cardgate/.
The CardGate protocol is designed to be backward compatible with earlier CardGate implementations.
Naming of arguments and which parameters you will receive on url_callback and url_success/failure/pending will be CardGate compatible.

Quick-start

A little code says more than words, so let's start with a full POST example page in PHP: A live demo can be viewed here, including the PHP source file (which is the same as above).
There is also a simple PHP Class demo available here

Overview of POST variables

In the table below you can find the optional- and required variables that you can send to the gateway.

Name	Type*	Required	Description
test	i	optional	With this variable you can do a test transaction. Possible values are 1 for a test transaction and 0 for a normal transaction.
option	s	optional	If there is more then one payment method activated, the gateway will show a payment method selection page to the user. You can skip this page by telling which payment method should be used. An overview of the possible values can be found under Available payment methods. The preferred way is to always have the customer select the payment method on the website checkout page and pass that to the Payment Gateway!
siteid	i	required	The ID of your site. This ID is listed in the Merchant Back-office under Sites.
currency	s	required	The currency for the transaction. If you send a currency that is different from your default account currency, the gateway will try to make a conversion to the required currency. Exactly 3 characters, for example EUR or USD. If you would like to use multiple currencies, please contact us. Multi-currency support also depends on the selected payment method! Please check with us if you need other currencies.
amount	i	required	The amount in cents. If the customer needs to pay 10 euros, you need to send 1000
ref	s	required	Your unique reference for this transaction, 128 characters maximum. This value needs to be globally unique, including even test-transactions! Beware if you reset your web-shop after you go from testing to production, or do a (major) upgrade your web-shop software.
description	s	optional	Description for the transaction (32 characters maximum). This will be shown on the payment pages is supported by the payment method. If not specified the system will use the website name.
extra	s	optional	Extra information for this transactions which will also be passed back in the Callback URL. Maximum 255 characters.
return_url	s	optional	By sending the return_url variable, you will temporarily overwrite the setting of the return url value which is set in the site configuration.
return_url_failed	s	optional	By sending the return_url_failed variable, you will temporarily overwrite the setting of the return url failed value which is set in the site configuration.
language	s	optional	Preferred language for messages and input form (2 char max) Possible options at this time: Czech (cz) German (de) Danish (dk) Spanish (es) French (fr) Greek (gr) Hunguarian (hr) Italian (it) Dutch (nl) default Russian (ru) Swedish (se) Turkish (tr)
hash	s	required	A checksum code which is generated by using the hash key. Exactly 32 characters
ip_address	s	advisable	Consumer IP address. The IP in the HTTP headers will be used if no value is given (REMOTE_ADDR)
recurring	i	optional	Use 1 to indicate the transaction as authoritive/mandate for recurring payments. Not supported for all payment methods. Consumers must be informed about recurring payments when making the initial/authorizing payment in compliance with the rules of a SEPA Direct Debit transfer as agreed by all European banks!
Consumer information below will be used for anti-fraud checks, and will also be posted back to the Callback URL. In case additional information is required for the chosen payment method, a form will be presented to the consumer to provide that information. Any POSTed fields will already be filled in, so please include any fields that are already present in your system.
first_name	s	optional	First name of your customer (48 characters maximum)
last_name	s	optional	Last name of your customer (48 chars max)
company_name	s	optional	Customer company name (64 chars max)
email	s	advisable	E-mail address of the customer (48 chars max)
address	s	optional	The address of your customer (48 char max)
postal_code	s	optional	The postal code of your customer (16 chars max)
city	s	optional	The city of your customer (48 char max)
state	s	optional	The state of your customer (48 char max)
country_code	s	optional	The two letter country code of your customer, according to ISO 3166. Exactly 2 characters, for example NL for the Netherlands or DE for Germany.
phone_number	s	optional	The customers phone number (24 char max)
The fields below are required for Klarna transactions only.
dob	s	required	Date of birth (YYYYMMDD or DD-MM-YYYY)
gender	s	required	Consumers gender (F or M)
cartitems	s	required	Cart items of the webshop order; Array in PHP serialized or JSON format. The following fields must be present for each order line: qty Quantity id Article number name Article name/title/description price Article price (999.99) ex optional 1 to indicate price is Excluding VAT vat VAT amount discount optional discount amount

To verify that the transaction request which is send to our gateway comes from a trusted source, all transaction requests should contain the hash variable.

Normal hash key calculation

$sHashKey = "abcdefgh";
$hash = md5( $siteID . $amount . $ref . $sHashKey );

Hash in test-mode

For a transaction in 'test' mode, the hash calculation is slightly different. To avoid abuse of the ‘test’ mode to retrieve the correct ‘hash’ value for a live transaction, you should precede the variables with TEST in ‘test’ mode.

$sHashKey = "abcdefgh";
$hash = md5( "TEST" . $siteID . $amount . $ref . $sHashKey );

When the transaction has been processed, the consumer will be redirected to the return_url or return_url_failed depending on the status of the transaction.
For both URL's you can dynamically add any required arguments to continue the consumer session on you webshop when you submit the transaction data to the gateway.

Return URL failed arguments

The return_url_failed will automatically receive additional parameters indicating the reason of the failure.

In the checkout page of the webshop, you should present the possible payment methods to the consumer, and pass the selected method value to the gateway in parameter option.

Payment method		Value	Availability
	Credit card	creditcard	Worldwide
	iDEAL	ideal
	SOFORTbanking	directebanking
	Bancontact / Mister Cash	mistercash
	PayPal	paypal	Worldwide
	Giropay	giropay
	Bank transfer	banktransfer	Worldwide
	SEPA Direct Debit	directdebit	Europe (SEPA countries)
	Klarna postpay	klarna	(alleen invoice)

To perform a test transaction, you must send the variable test with the value 1 to the gateway. Please remember about the additional prefix in the hash calculation for test transactions.

Test Simulator

After the transaction request has been verified at the gateway, your customer can finalize the transaction. After every transaction, successful or unsuccessful, the gateway will send a request to the Callback URL you have set.

To be certain the callback is coming from CURO, all requests to the Callback URL will contain a hash variable.

This hash variable is an MD5 encoding of the following values: transaction_id, currency, amount, ref, status and the hash key which is set by you in the Merchant Back-office. The hash key should only be known to you and us. You can change this key at any given time, as long as you change it in your code as well.

Test mode Hash

PHP example verification

<?php
$sHashKey  =  'abcdefgh';
// Set correct prefix for test/live transactions
if( '1' == $_POST['is_test'] ) {
    $sPrefix = 'TEST';
} else {
    $sPrefix = '';
}
$sHashVerify = md5( $sPrefix . $_POST['transactionid'] . $_POST['currency'] . $_POST['amount'] . $_POST['ref'] . $_POST['status'] . $sHashKey);

if ( $sHashVerify == $_POST['hash'] ) {
    // Transaction OK
    // We should check currency, amount and status in our own system using $_POST['ref'] here
    exit( $_POST['transactionid'] . '.' . $_POST['status'] );

}  else  {
    // Transaction not OK!
    mail( 'security@mydomain.tld', 'Hash verification error!', print_r($_POST,1) );
    // Indicate a problem by sending an unexpected response
    exit( 'ERROR' );
}
?>

The gateway expects a response containing the CURO transaction ID, a dot (.) and the status code. For example:

3562456.200

3562456.300

When processing the callback, please be aware of the following:

Multiple Callbacks

Depending on the payment method, it is possible that a callback is send by our gateway more than once. Although this happens rarely, it would be unwelcome to process this callback as another transaction.
Because every callback includes your unique ref, you can check on your side if the transaction has already been processed. If you receive another callback with the same ref and same status code, you can ignore this callback.

Callback order

It is possible that our system sends a status 200 (‘Transaction successful’) first and a status 300 (‘Transaction unsuccessful’) after that. In this case, the status 200 is always final. You can be assured that the transaction has been processed successfully when you receive a status 200.

Unique reference

The unique reference must be unique in both test- and live mode. Please beware if you switch from testing to live or when upgrading your webshop software.

Originating IP address

With iDEAL payments it is possible and advisable to redirect the user directly to the site of the bank from your payment page. To achieve this you must send the variable suboption to our gateway.

The variable suboption is a string that contains the issuer-code for each supported bank.

List of banks

PHP Serialized

https://secure.curopayments.net/cache/idealDirectoryCUROPayments.dat

PHP Sample

$sBankOptions = file_get_contents('https://secure.curopayments.net/cache/idealDirectoryCUROPayments.dat');
if( empty($sBankOptions) || $sBankOptions[0]!='a' ) {
    # Fallback in case of an error
   $sBankOptions = 'a:11:{i:0;s:0:"";s:8:"ABNANL2A";s:13:"ABN Amro Bank";s:8:"ASNBNL21";s:8:"ASN Bank";s:8:"BUNQNL2A";s:4:"bunq";s:8:"INGBNL2A";s:3:"ING";s:8:"KNABNL2H";s:4:"Knab";s:8:"RABONL2U";s:8:"Rabobank";s:8:"RBRBNL21";s:9:"RegioBank";s:8:"SNSBNL2A";s:8:"SNS Bank";s:8:"TRIONL2U";s:12:"Triodos Bank";s:8:"FVLBNL22";s:21:"Van Lanschot Bankiers";}';
}
$aBankOptions = unserialize($sBankOptions);
unset($aBankOptions[0]); # Remove blank option
# Convert to HTML
$sBankOptions = '<optgroup label="Kies uw bank">';
foreach( $aBankOptions as $k => $v ) {
if( $v[0]=='-' ) {
       $sBankOptions .= '<optgroup label="'.str_replace('-','',$v).'">';
   } else {
       $sBankOptions .= '<option value="'.$k.'">'.$v.'</option>';
   }
}
$sBankOptions.= '</optgroup>';
    

JSON Encoded

https://secure.curopayments.net/cache/idealDirectoryCUROPayments.json

This Javascript Array contains an id and name element for each bank containing the issuer-code and issuer-name respectively.

XML

https://secure.curopayments.net/cache/idealDirectoryCUROPayments.xml

XML list of issuers in the iDEAL V3.3 (SEPA) format.

After a consumer has chosen to pay with Klarna, CURO will create a Klarna transaction which is "Not Shipped".
After you ship the products to the consumer, the order needs to be Activated in the backoffice so Klarna will start collecting from the consumer.

If there's something wrong with the order, it is also possible to Cancel the order in the backoffice

Below is a list of the status codes that are currently being used by the CURO system:

Date       Name Ver.  Notes
10-11-2009  BZ  2.00  Initial version
26-04-2010  BZ  2.10  Changes in test mode
                      Added new payment methods
08-06-2010  BZ  2.11  Changes to 'Payment page description'
04-05-2011  BZ  2.22  Added ‘hash’ check in callback
                      Added direct connection to iDEAL banks
                      Updated iDEAL banks
19-08-2011  BZ  2.23  Added Triodos Bank to iDEAL
11-07-2013  LH  2.24  Separate iDEAL suboption page
20-02-2014  LH  3.01  Online HTML version
16-03-2014  LH  3.02  Updated accepted POST variables. Style fixes
15-12-2014  LH  3.03  Fixes; Originating IP's and extra argument added
13-05-2015  LH  3.04  Consequent naming of hash key
15-03-2016  RB  3.05  Better menu