Sites Module

Each merchant can have multiple websites for transaction processing.
Using the Sites Module you can add, modify and delete sites and options directly in the CURO system.
Sites in the CURO system have several stages:

boarding → pending → approved / cancelled / rejected

📘

Note

  • All sites must be (pre-)approved before payment methods are enabled.
  • New sites will be in boarding stage until they are reviewed. Processing of transactions is not possible until stage pending.

Add

Create a new Site using this entry point. Multiple sites can be created by providing an array with data for each site.

❗️

Warning

Due to strict regulations website data will never be actually deleted from the CURO system.

Always make sure your API implementation works correctly by using the Staging Platform on https://api-staging.curopayments.net/.

Please prevent testing or creating unused sites on the production system!

Entry point: /rest/v1/site/add/ (or POST to /rest/v1/site/)

REST request elements

Field nameTypeDescription
[request]containerGeneral container for this resource. (XML only)
[sites]containerOptional container to submit multiple sites at once.

The [request] (or each site in [sites]) contains the following site items:

Field nameType LengthRequiredDescription
urlstring ≤ 255requiredURL of the website. Also shown to the consumer on the default payment pages.
namestring ≤ 128requiredName of the website. This will be visible on the default payment pages (when shown; depends on payment method).
trading_namestring ≤ 32Trading name used on the website.
hash_keystring ≤ 32Optional Hash-Key to be used for callbacks for this site. Please see Hash in Callback for more information.
url_callbackstring ≤ 255Default URL to Callback script.
url_successstring ≤ 255Default URL to success landing page.
url_failurestring ≤ 255Default URL to landing page when the transaction has failed.
url_cancelstring ≤ 255Default URL to landing page when the transaction was cancelled. The url_failure will be used if not specified.
url_pendingstring ≤ 255Default URL to landing page when the transaction is still pending. The url_success will be used if not specified.
callback_emailstring ≤ 64This e-mail address will receive mail for any transaction status change. You can filter on the status-codes you want to receive mail for in the callback_email_status field.
callback_email_statusstring ≤ 64Filter option for sending Callback E-mails. This can be a list of status-codes or error to receive e-mail in case of any error (e.g. 200, 200,400, error).
platformstring ≤ 64Name of webshop platform.
sbistring ≤ 10Website category code (e.g.
C101 General retail,
C201 Consumer electronics,
C600 Ticketing,
C700 Crowdfunding,
C710 Sponsoring and charity,
C1000 Crypto Currency,
C1200 Gaming/Adult,
C1400 Foodsupplements/Medical).
test_urlstring ≤ 255URL of test site.
test_authstring ≤ 255Authorisation information to access the test site.
targetstring ≤ 255Description of target audience and services/goods available on the webshop.
background_colorstring ≤ 8Hexadecimal color code (RRGGBB) for the background of the default payment pages.
font_colorstring ≤ 8Hexadecimal color code (RRGGBB) for text on the default payment pages.
use_custom_emailboolean 1Flag to indicate custom e-mail settings must be used for emails.
email_font_colorstring ≤ 8Hexadecimal color code (RRGGBB) for text in the emails.
notify_email_consumer_successboolean 1Flag to enable mail to consumers when transactions are successful.
notify_email_consumer_refundboolean 1Flag to enable mail to consumers when transactions are refunded.
notify_paylink_consumer_failureboolean 1Flag to enable mail to consumers to re-issue a payment when a transaction failed.
notify_email_admin_successboolean 1Flag to enable mail to administrators when transactions are successful.
notify_email_admin_refundboolean 1Flag to enable mail to administrators when transactions are refunded.
notify_sms_admin_successboolean 1Flag to enable SMS to administrators for successful transactions (beware of extra costs!).
require_consumerboolean 1Flag to require full consumer details for each transaction. If information is missing, the payment gateway will present the default payment page where the consumer can enter this.
admin_emailstring ≤ 64Administrator email address to receive administrative mail on. Multiple addresses are allowed using ,.
admin_mobilestring ≤ 20Administrator mobile number to receive SMS on.

REST response elements

Field nameType LengthDescription
[response]containerGeneral response container (XML Only)
successboolean 1true or false indicating the result of the call
code optionalstring ≤ 48Error Code
message optionalstring ≤ 255Textual message indicating what went wrong in case the call was unsuccessful

[sites] container — Site information:

Field nameType LengthDescription
idinteger ≤ 11Unique site id.
namestring ≤ 255Name of the website.
urlstring ≤ 255URL of the website.
hash_keystring ≤ 32secret Hash-Key of the website as it was given when the site was created.

JSON example request

POST /rest/v1/curo/site/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Host: secure.curopayments.net
Content-type: application/json
{
"name": "My Brand New Site",
"url": "https://my.brandnew.site/",
"trading_name": "My Brand is a band of My Company",
"description": "My Brand New Site is the place to go for all your new things. We trade them big and small to private individuals and companies world wide."
}

Response for success:

HTTP/1.0 200 OK
Content-Type: application/json
{
"success": true,
"site": {
	"id": "20453",
	"merchant_id": "1066",
	"name": "My Brand New Site",
	"idname": "#20453 My Brand New Site",
	"trading_name": "My Brand is a band of My Company",
	"url": "https://my.brandnew.site/",
	"active": "1",
	"url_callback": null,
	"url_success": null,
	"url_failure": null,
	"hash_key": null,
	"status": "1",
	"created": "2017-07-26",
	"changed": "2017-07-26 09:36:09",
	"last_transaction": null,
	"last_transaction_days": null,
	"payment_type_ids": "4,10,13,18,19,26,30,39,40,48,60,61,62,64,65,66,70",
	"allow_payments": "0"
}
}

Details

Retrieve current status and information of a site.

Entry point: /rest/v1/curo/site/<site-id>/

REST request elements

Field nameType LengthRequiredDescription
[request]containerGeneral container for this resource. (XML only)
site-idinteger ≤ 11requirednumeric id of the site

REST response elements

Field nameType LengthDescription
[response]containerGeneral response container (XML Only)
successboolean 1true or false indicating the result of the call.
message optionalstring ≤ 255Optional textual message indicating what went wrong in case the call was unsuccessful.
code optionalstring ≤ 64Extra internal error code (ie. Site.API.Error)

[site] container — Site information:

Field nameType LengthDescription
idinteger ≤ 11Unique site id.
merchant_idinteger ≤ 11Merchant id for this site.
namestring ≤ 255Name of the website.
idnamestring ≤ 255Id and name of the website (for dropdown lists).
trading_namestring ≤ 32Trading name for the website.
urlstring ≤ 255URL of the website.
activeinteger 11 when the site is enabled.
url_callbackstring ≤ 255URL which will receive transaction updates automatically.
url_successstring 255Optional return URL for pending payments. The url_success will be used if not specified.
url_failurestring 255Optional Return URL for failed payments.
hash_keystring ≤ 32secret Hash-Key. Please see Hash in Callback for more information.
statusinteger 2Site status indicator
Value Status
1 boarding
2 pending
3 approved
4 rejected
5suspended
6 cancelled (by merchant)
7 cancelled (by CURO)
8 terminate (by merchant)
9 terminate (by CURO)
10 deleted
11 test
createddate 10Date when the site was created (YYYY-MM-DD format).
changeddatetime 19Date and time when the site was last changed (YYYY-MM-DD H:i:s format).
last_transactiondtatetime 19Date and time of the last transaction for this site (YYYY-MM-DD H:i:s format).
last_transaction_daysinteger ≤ 19Number of days since the last transaction for this site.
payment_type_idsarrayList of payment type id's for this site.
allow_paymentsboolean 1

JSON example request

GET /rest/v1/curo/site/20437/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Host: secure.curopayments.net
Accept: application/json

Response for success:

HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"site": {
	"id": "20437",
	"merchant_id": "1066",
	"name": "Leeg",
	"idname": "#20437 Leeg",
	"trading_name": "",
	"url": "http://Leeg",
	"active": "1",
	"url_callback": "",
	"url_success": "",
	"url_failure": "",
	"hash_key": "WPK4X-2z",
	"status": "2",
	"created": "2017-07-24",
	"changed": "2017-07-25 15:01:23",
	"last_transaction": null,
	"last_transaction_days": null,
	"payment_type_ids": "4,10,13,18,19,26,30,39,40,48,60,61,62,64,65,66,70",
	"allow_payments": "0"
}
}

Edit

Site fields can be updated via this API. Some fields will be read-only when the site has been approved!

Entry point: /rest/v1/curo/site/edit/<site-id>

REST request elements

The [request] container (XML only) holds the site information. It accepts the same site items as described in the Add section.

REST response elements

Field nameType LengthDescription
[response]containerGeneral response container (XML Only)
successboolean 1true or false indicating the result of the call.
message optionalstring 255Optional textual message indicating what went wrong in case the call was unsuccessful.

JSON example request

POST /rest/v1/curo/site/20438/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Host: secure.curopayments.net
Content-type: application/json
Accept: application/json

{
"name": "New Site Changed",
"url": "https://my.brandnew.site/",
"description": "My Brand New Site now has a new description."
}

Response for success:

HTTP/1.1 200 OK
Content-Type: application/json

{
"success": true,
"code": "Success",
"message": "Site details updated"
}

List

Retrieve a list of sites. By default (using GET) the complete list of sites will be returned.

Optional filters can be send using a POST request.

Entry point: /rest/v1/curo/sites/

REST request elements

Field nameType LengthDescription
[request]containerGeneral container for this resource. (XML only)
enabledbooleanBoolean (Yes/No/TRUE/FALSE) to filter on enabled or disabled sites.
fieldstextComma separated list of fields to return in the result.
sortstringField to sort results on.
dirstringSort direction: ASC or DESC.
searchstringValue to search for in any of the fields.

REST response

See Details for the returned site information.

PHP example

The PHP example below uses cURL to communicate with the API. PHP supports libcurl, which allows you to connect and communicate with many different types of servers and different types of protocols. You are free to use any other library for communication over HTTPS protocol or you can connect directly via socket.

<?php
/**
 * CURO Backoffice Sample - Site module
 *
 * @author CURO Payments
 * @package curopayments_www_api
 * @version 1.0a
 */

// For debugging we want all errors and reporting; REMOVE THIS for production!
define('DEBUG', true); // Uncomment this line to show all I/O
error_reporting(E_ALL);
ini_set('display_errors', 1);
if (php_sapi_name() != 'cli') {
    echo "<pre>";
}

// Set the right API URL for testing or live
// define('API_URL', 'https://api.curopayments.net/rest/v1/'); // Real
define('API_URL', 'https://api-staging.curopayments.net/rest/v1/'); // Test

// Your API authentication info
define('API_MERCHANT', 1001);
define('API_KEY', 'api-keys-can-be-created-per-user-in-the-backoffice');

// Create a new site
echo "1) ADD ";
$data = [
    /**** REQUIRED ARGUMENTS ****/
    // Name of the website as it will be shown in the backoffice
    'name' => 'New With Logo And CC Info',
    'url' => 'https://my.brand.new/',

    /**** OPTIONAL ARGUMENTS ****/
    // Trading name will be shown on the generic payment pages (if applicable)
    'trading_name' => 'My Brand is a band of My Company',

    // Generic description of the kind of business that is traded on the site
    'description' => 'My Brand New Site is the place to go for all your new things. We trade them big and small to private individuals and companies world wide.',
];
$result = APICall('site/', $data);
if (empty($result['sites'][0]['id'])) {
    die("*ERROR?*");
} else {
    $siteId = $result['sites'][0]['id'];
}

echo "\n2) EDIT ";
$data = [
    'name' => 'New Site Changed',
    'url' => 'https://my.brandnew.site/',
    'description' => 'My Brand New Site now has a new description.',

    // We can sent our own logo
    'header_logo' => new CURLFile('logo.png'),
];
$result = APICall('site/', $data, false /* Don't encode data argument or upload won't work! */);

echo "\n3) GET SITE #{$siteId}";
//$result = APICall('site/' . $siteId);

echo "\n4) GET SITE LIST";
$result = APICall('sites/');

/**
 * Call CURL API helper function.
 * @param string $entryPoint The entry point we want
 * @param array $data Optional data to send to the API
 * @return array API Result
 */
function APICall($entryPoint, $data = null, $autoEncode = true)
{
    global $curlInfo;

    // Set basic cURL options
    $options = [
        CURLOPT_URL => API_URL . $entryPoint,
        CURLOPT_PORT => 443,
        CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
        CURLOPT_USERPWD => API_MERCHANT . ':' . API_KEY,
        CURLOPT_TIMEOUT => 120,
        CURLOPT_HEADER => false,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_VERBOSE => defined('DEBUG'),
    ];

    // Use POST for request variables if the're given
    if (!is_null($data)) {
        $options[CURLOPT_POST] = true;
        // We can't use encodeing when we need to upload files!
        if (is_scalar($data) || !$autoEncode) {
            $options[CURLOPT_POSTFIELDS] = $data;
        } else {
            $options[CURLOPT_POSTFIELDS] = json_encode($data);
            $options[CURLOPT_HTTPHEADER] = ['Accept: application/json', 'Content-Type: application/json'];
        }
    }

    // Create a new cURL resource and set options
    $curl = curl_init();
    curl_setopt_array($curl, $options);

    // Send the request and get server response
    $response = curl_exec($curl);
    $curlInfo = curl_getinfo($curl);
    $curlInfo['error_no'] = curl_errno($curl);
    $curlInfo['error_msg'] = curl_error($curl);
    $curlInfo['body'] = &$response;

    // Close cURL resource, and free up system resources
    curl_close($curl);

    $responseData = @json_decode($response, true);

    if ('200' != $curlInfo['http_code'] || empty($responseData['success'])) {
        echo "*ERROR* ";
        if ($curlInfo['error_no'] > 0) {
            echo @$curlInfo['error_no'] . ' ' . @$curlInfo['error_msg'] . PHP_EOL;
        }
        if (!empty($responseData['error'])) {
            echo @$responseData['error']['code'] . ' ' . @$responseData['error']['message'] . PHP_EOL;
        } elseif (!empty($curlInfo['body'])) {
            echo $curlInfo['body'] . PHP_EOL;
        }
    }

    if (defined('DEBUG')) {
        echo "=== {$entryPoint} === " . PHP_EOL;
        if (!empty($options[CURLOPT_POSTFIELDS])) {
            echo "Request: " . print_r($options[CURLOPT_POSTFIELDS], 1) . PHP_EOL;
        }
        echo "Info: " . print_r($curlInfo) . PHP_EOL;
        echo "Response: " . print_r($responseData, 1) . PHP_EOL . PHP_EOL;
    }
    return $responseData;
}

Did this page help you?