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
boardingstage until they are reviewed. Processing of transactions is not possible until stagepending.
Add
Create a new Site using this entry point. Multiple sites can be created by providing an array with data for each site.
WarningDue 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 name | Type | Description |
|---|---|---|
[request] | container | General container for this resource. (XML only) |
[sites] | container | Optional container to submit multiple sites at once. |
The [request] (or each site in [sites]) contains the following site items:
| Field name | Required | Description | |
|---|---|---|---|
url | required | URL of the website. Also shown to the consumer on the default payment pages. | |
name | required | Name of the website. This will be visible on the default payment pages (when shown; depends on payment method). | |
trading_name | Trading name used on the website. | ||
hash_key | Optional Hash-Key to be used for callbacks for this site. Please see Hash in Callback for more information. | ||
url_callback | Default URL to Callback script. | ||
url_success | Default URL to success landing page. | ||
url_failure | Default URL to landing page when the transaction has failed. | ||
url_cancel | Default URL to landing page when the transaction was cancelled. The url_failure will be used if not specified. | ||
url_pending | Default URL to landing page when the transaction is still pending. The url_success will be used if not specified. | ||
callback_email | This 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_status | Filter 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). | ||
platform | Name of webshop platform. | ||
sbi | Website 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_url | URL of test site. | ||
test_auth | Authorisation information to access the test site. | ||
target | Description of target audience and services/goods available on the webshop. | ||
background_color | Hexadecimal color code (RRGGBB) for the background of the default payment pages. | ||
font_color | Hexadecimal color code (RRGGBB) for text on the default payment pages. | ||
use_custom_email | Flag to indicate custom e-mail settings must be used for emails. | ||
email_font_color | Hexadecimal color code (RRGGBB) for text in the emails. | ||
notify_email_consumer_success | Flag to enable mail to consumers when transactions are successful. | ||
notify_email_consumer_refund | Flag to enable mail to consumers when transactions are refunded. | ||
notify_paylink_consumer_failure | Flag to enable mail to consumers to re-issue a payment when a transaction failed. | ||
notify_email_admin_success | Flag to enable mail to administrators when transactions are successful. | ||
notify_email_admin_refund | Flag to enable mail to administrators when transactions are refunded. | ||
notify_sms_admin_success | Flag to enable SMS to administrators for successful transactions (beware of extra costs!). | ||
require_consumer | Flag 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_email | Administrator email address to receive administrative mail on. Multiple addresses are allowed using ,. | ||
admin_mobile | Administrator mobile number to receive SMS on. |
REST response elements
| Field name | Description | |
|---|---|---|
[response] | container | General response container (XML Only) |
success | true or false indicating the result of the call | |
code optional | Error Code | |
message optional | Textual message indicating what went wrong in case the call was unsuccessful |
[sites] container — Site information:
| Field name | Description | |
|---|---|---|
id | Unique site id. | |
name | Name of the website. | |
url | URL of the website. | |
hash_key | secret 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 name | Required | Description | |
|---|---|---|---|
[request] | container | General container for this resource. (XML only) | |
site-id | required | numeric id of the site |
REST response elements
| Field name | Description | |
|---|---|---|
[response] | container | General response container (XML Only) |
success | true or false indicating the result of the call. | |
message optional | Optional textual message indicating what went wrong in case the call was unsuccessful. | |
code optional | Extra internal error code (ie. Site.API.Error) |
[site] container — Site information:
| Field name | Description | |
|---|---|---|
id | Unique site id. | |
merchant_id | Merchant id for this site. | |
name | Name of the website. | |
idname | Id and name of the website (for dropdown lists). | |
trading_name | Trading name for the website. | |
url | URL of the website. | |
active | 1 when the site is enabled. | |
url_callback | URL which will receive transaction updates automatically. | |
url_success | Optional return URL for pending payments. The url_success will be used if not specified. | |
url_failure | Optional Return URL for failed payments. | |
hash_key | secret Hash-Key. Please see Hash in Callback for more information. | |
status | Site status indicator1 boarding2 pending3 approved4 rejected 5suspended 6 cancelled (by merchant)7 cancelled (by CURO)8 terminate (by merchant)9 terminate (by CURO)10 deleted11 test | |
created | Date when the site was created (YYYY-MM-DD format). | |
changed | Date and time when the site was last changed (YYYY-MM-DD H:i:s format). | |
last_transaction | Date and time of the last transaction for this site (YYYY-MM-DD H:i:s format). | |
last_transaction_days | Number of days since the last transaction for this site. | |
payment_type_ids | array | List of payment type id's for this site. |
| allow_payments |
JSON example request
GET /rest/v1/curo/site/20437/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Host: secure.curopayments.net
Accept: application/jsonResponse 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 name | Description | |
|---|---|---|
[response] | container | General response container (XML Only) |
success | true or false indicating the result of the call. | |
message optional | Optional 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 name | Description | |
|---|---|---|
[request] | container | General container for this resource. (XML only) |
enabled | Boolean (Yes/No/TRUE/FALSE) to filter on enabled or disabled sites. | |
fields | Comma separated list of fields to return in the result. | |
sort | Field to sort results on. | |
dir | Sort direction: ASC or DESC. | |
search | Value 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;
}Updated 2 months ago