TradeSafe API User Guide

The TradeSafe API User Guide outlines the steps needed to start using our API in your business.

The source code for the Documentation is available on GitHub and we welcome contributions.

Getting Started

Useful Links:

  • API spec - The API specification.
  • sandbox - Our sandbox environment for testing.

To start using our API you first need to crate an account on our sandbox environment. Ensure that both your email and mobile number have been validated.

From here you can manually create test trades through the sandbox site to get an idea of how the process works.

To get your API key send a request to support once approved you can then generate your API key.

Creating your API Key

Once you have received notice that the API has been enabled, login and goto My Account.

_images/user_links.png

On your account settings page you will now see a new section called API Access.

_images/api_access.png

Fill in both the website url and callback url. You can use a service like mockbin for your callback url if your don’t have one yet.

Once you have saved the page a JSON Web Token (JWT) will be generated for you.

Note

If you change the Website URL and new token will be generated for your account. You can change the callback url at any time.

Receiving a Callback

All callbacks include the following data. When receiving a callback you must return a 200 response code, TradeSafe will continue retry the callback until a 200 response code is received or the timeout condition it met.

Example of the callback data

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
 "id":"5899715f-bda4-4c91-b78c-033aac102991",
 "transaction_id":"123456",
 "buyer_id":"1",
 "seller_id":"2",
 "owner_id":"2",
 "litigation_initiator_id":"0",
 "negotiation_id":null,
 "step":"FUNDS_RECEIVED",
 "sent_started":null,
 "industry":"GENERAL_GOODS_SERVICES",
 "meta":{
    "reference":"my_reference"
 },
 "name":"Trade Name",
 "description":"Trade Description",
 "fee_allocation":"1",
 "value":"10000.00",
 "value_total":"0.00",
 "renegotiated_value":null,
 "buyer_cost":"0.00",
 "seller_cost":"0.00",
 "admin_cost":null,
 "completion_total_days":"0",
 "completion_days":"5",
 "completion_months":"0",
 "completion_years":"0",
 "inspection_days":"5",
 "counterparty_email":"",
 "tracking_number":null,
 "courier":null,
 "delivery_required":false,
 "delivery_type":"not_required",
 "delivery_address":null,
 "delivery_start_date":null,
 "delivery_street":null,
 "delivery_extra":null,
 "delivery_suburb":null,
 "delivery_city":null,
 "delivery_country":null,
 "delivery_zip":null,
 "delivery_comment":null,
 "review":false,
 "amendment":false,
 "updated":"2016-06-04 14:52:00",
 "created":"2016-06-04 07:03:59"
}

Validate a User

The technical specifications can be viewed on our API docs.

Warning

You are responsible for providing the correct information.

Before creating a user you can check the data using the verify endpoint. On a successful validation the API will return a 200 status code along with the data you posted.

PHP Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
<?php

// get cURL resource
$ch = curl_init();

// set url
curl_setopt($ch, CURLOPT_URL, 'https://local.platform.tradesafe.dev/api/verify/user');

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...',
  'Content-Type: application/json; charset=utf-8',
]);

// json body
$json_array = [
  'id_number' => '8208014477088',
  'mobile_country' => 'ZA',
  'mobile' => '084 116 7762',
  'first_name' => 'Joe'
  'last_name' => 'Somebody',
  'email' => 'joe.sombody@example.com',
  'bank_account' => [
    'number' => '1234567890',
    'bank' => '123456',
    'type' => 'CHEQUE',
    'branch_code' => '123456'
  ],
  'company' => [
    'name' => 'Company Name',
    'reg_number' => '123/456/789',
    'type' => 'Company Type'
  ],
];
$body = json_encode($json_array);

// set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);

Creating a User

The technical specifications can be viewed on our API docs.

Warning

You are responsible for providing the correct information.

When creating a contract you need a user_id to identify the user. This can be done by either creating an account for the user or allowing then you link their existing TradeSafe Account.

The example below will create a user in response you will receive a user_id that you can associate with the user account on your system. This action only needs to be done once and the user_id can be user for all subsequent transactions. A user can then manage their details from their TradeSafe account.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
<?php

// get cURL resource
$ch = curl_init();

// set url
curl_setopt($ch, CURLOPT_URL, 'https://local.platform.tradesafe.dev/api/user');

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...',
  'Content-Type: application/json; charset=utf-8',
]);

// json body
$json_array = [
  'id_number' => '8208014477088',
  'mobile_country' => 'ZA',
  'mobile' => '084 116 7762',
  'first_name' => 'Joe'
  'last_name' => 'Somebody',
  'email' => 'joe.sombody@example.com',
  'bank_account' => [
    'number' => '1234567890',
    'bank' => '123456',
    'type' => 'CHEQUE',
    'branch_code' => '123456'
  ],
  'company' => [
    'name' => 'Company Name',
    'reg_number' => '123/456/789',
    'type' => 'Company Type'
  ],
];
$body = json_encode($json_array);

// set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);

Linking a User Account

In some cases a user might already have a user account. I this case you can request that they link their TradeSafe account. This is a two step process.

Request Auth Token

You first need to generate an auth token. This is used to identify your platform an validate the request is valid.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<?php

// get cURL resource
$ch = curl_init();

// set url
curl_setopt($ch, CURLOPT_URL, 'https://sandbox.tradesafe.co.za/api/authorize/token');

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...',
]);

// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);

You will get a response with the token, created time and expiry time. If the token expires before the user links their account a new token will be required.

1
2
3
4
5
{
  "token": "6855476e6f64b280b5f8be63f58f422cdd22072faa89710ddd3f623721944223",
  "created": 1559296474,
  "expire": 1559300074
}

Create Authorization Request

Once you have the token it can be used to create a form request to /api/authorize

1
2
3
4
5
6
7
8
9
<form action="https://sandbox.tradesafe.co.za/api/authorize" method="post" target="_blank">
    <input type="hidden" name="auth_key" value="39abf0e5-8468-4989-ae98-470a76e0b4a3">
    <input type="hidden" name="auth_token" value="6855476e6f64b280b5f8be63f58f422cdd22072faa89710ddd3f623721944223">
    <input type="hidden" name="success_url" value="https://example.com/success">
    <input type="hidden" name="failure_url" value="https://example.com/failure">
    <input type="hidden" name="parameters[name1]" value="value1">
    <input type="hidden" name="parameters[name2]" value="value2">
    <input type="submit" value="Link Your TradeSafe Account">
</form>
auth_key
This is your user_id
auth_token
This is the token generated using /api/authorize/token
success_url
Where should the user be redirected if successful
failure_url
Where should the user be redirected if they cancel
parameters[name]
You can define several parameters that will be sent to you along with the user_id in a callback. For example the username or ID od the current user account.

If the user successfully authorizes the request a callback will be sent to the URL defined in your account along with any parameters you defined.

Validate a Trade

The technical specifications can be viewed on our API docs.

Warning

You are responsible for providing the correct information.

Before creating a contract you can use the validate endpoint to ensure that the data is correct. On a successful validation the API will return a 200 status code along with the data you posted.

PHP Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
<?php

// get cURL resource
$ch = curl_init();

// set url
curl_setopt($ch, CURLOPT_URL, 'https://sandbox.tradesafe.co.za/api/validate/contract');

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIU...',
  'Content-Type: application/json; charset=utf-8',
]);

// json body
$json_array = [
  'name' => 'Contract Name',
  'description' => 'Description of the new Contract'
  'reference' => 'your_reference',
  'industry' => 'GENERAL_GOODS_SERVICES',
  'buyer' => '184c16a9-6013-4aaa-896d-2fab38adb603',
  'seller' => '9f816402-3f15-4a3d-be1a-8a16a67872e1',
  'agent' => 'a68f4d96-f94e-4a4c-8335-54f41d87b9a5',
  'beneficiary' => [
    [
      'value' => 50,
      'user_id' => '5cdbfa9d-2e40-4ca7-ae0f-1ba80ad33704',
      'type' => 'OTHER',
      'fee_type' => 0,
      'fee_allocation' => 3
    ]
  ],
  'value' => 10000,
  'agent_fee_type' => 0,
  'agent_fee' => '50',
  'agent_fee_allocation' => 0,
  'delivery_fee' => 123.45,
  'completion_days' => 30,
  'completion_months' => 12,
  'completion_years' => 5,
  'inspection_days' => 7,
  'fee_allocation' => 0,
  'delivery_required' => false,
];
$body = json_encode($json_array);

// set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);

Creating a Trade

The technical specifications can be viewed on our API docs.

Warning

You are responsible for providing the correct information.

PHP Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
<?php

// get cURL resource
$ch = curl_init();

// set url
curl_setopt($ch, CURLOPT_URL, 'https://sandbox.tradesafe.co.za/api/contract');

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIU...',
  'Content-Type: application/json; charset=utf-8',
]);

// json body
$json_array = [
  'name' => 'Contract Name',
  'description' => 'Description of the new Contract'
  'reference' => 'your_reference',
  'industry' => 'GENERAL_GOODS_SERVICES',
  'buyer' => '184c16a9-6013-4aaa-896d-2fab38adb603',
  'seller' => '9f816402-3f15-4a3d-be1a-8a16a67872e1',
  'agent' => 'a68f4d96-f94e-4a4c-8335-54f41d87b9a5',
  'beneficiary' => [
    [
      'value' => 50,
      'user_id' => '5cdbfa9d-2e40-4ca7-ae0f-1ba80ad33704',
      'type' => 'OTHER',
      'fee_type' => 0,
      'fee_allocation' => 3
    ]
  ],
  'value' => 10000,
  'agent_fee_type' => 0,
  'agent_fee' => '50',
  'agent_fee_allocation' => 0,
  'delivery_fee' => 123.45,
  'completion_days' => 30,
  'completion_months' => 12,
  'completion_years' => 5,
  'inspection_days' => 7,
  'fee_allocation' => 0,
  'delivery_required' => false,
];
$body = json_encode($json_array);

// set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);

The Payment URL

When you create a trade a summary of the information you posted will be sent back to you along with a payment_url [/api/payment/eftsecure/YOUR-TRADE-ID]. This link can be embedded into your website through an iframe and will allow users to access to our banking details for EFT payment.

You wil also get a payfast_payment_url. This URL provides an html button formatted in JSON that you can embed on your website.

Also included is a withdraw_url [/api/contracts/deposit/YOUR-TRADE-ID]. This allows sellers to add their own banking details to a trade.

Warning

The withdraw_url been deprecated in favor of receiving the banking details during the create trade process.

Retrieve Trade Information

The technical specifications can be viewed on our API docs.

PHP Example

<?php
# The JWT for your account
$json_token = 'your_jwt_token';

# The url of the API
$service_url = 'https://sandbox.tradesafe.co.za/api/contract/{ID_OF_THE_TRADE}';

$curl = curl_init($service_url);

curl_setopt_array($curl, array(
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer ' . $json_token,
    'Content-Type: application/json'
  )
));

$curl_response = curl_exec($curl);
curl_close($curl);

$response = json_decode($curl_response);

print_r($response);
?>

This allows you to query any trade you have created at any time, the data is similar to what you receive when creating a trade.

This can be useful for recovering from an outage for example. We recommend that you cache this data and only make requests when necessary. As the callback will send through data every time the trade is transitioned to a new step.

Updating a Trade

The technical specifications can be viewed on our API docs.

To update a trade certain conditions have to be met. In this example we must have already verified the funds before this request can be processed.

Not all steps are available and currently we do not allow any modification of the trade data after it has been accepted.

The example below would be typically run once you have received notification that your user has received the goods or service.

PHP Example 1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<?php
# The JWT for your account
$json_token = 'your_jwt_token';

# The url of the API
$service_url = 'https://sandbox.tradesafe.co.za/api/contract/{ID_OF_THE_TRADE}';

$curl = curl_init($service_url);

$postfields = array(
  "id" => "5899715f-bda4-4c91-b78c-033aac102991",
  "step" => "GOODS_ACCEPTED"
);

curl_setopt_array($curl, array(
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_RETURNTRANSFER => TRUE,
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer ' . $json_token,
    'Content-Type: application/json'
  ),
  CURLOPT_POSTFIELDS => json_encode($postfields)
));

$curl_response = curl_exec($curl);
curl_close($curl);

$response = json_decode($curl_response);

print_r($response);
?>

When declining a trade after the funds deposited step but before the goods sent step, the contract can be declined. The standard behaviour is to issue a refund to the buyer however a refund split can be defined, for example when implementing a late cancellation penalties.

PHP Example 2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<?php
# The JWT for your account
$json_token = 'your_jwt_token';

# The url of the API
$service_url = 'https://sandbox.tradesafe.co.za/api/contract/{ID_OF_THE_TRADE}';

$curl = curl_init($service_url);

$postfields = array(
  "id" => "5899715f-bda4-4c91-b78c-033aac102991",
  "step" => "DECLINED",
  "refund" => array(
    "buyer_refund" => 100,
    "agent_fee" => 0,
    "seller_fee" => 10,
  )
);

curl_setopt_array($curl, array(
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_RETURNTRANSFER => TRUE,
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer ' . $json_token,
    'Content-Type: application/json'
  ),
  CURLOPT_POSTFIELDS => json_encode($postfields)
));

$curl_response = curl_exec($curl);
curl_close($curl);

$response = json_decode($curl_response);

print_r($response);
?>

Amending a trade

When a client has accepts the goods there may be an amendment required. For example a 1000 items were ordered but only 950 were delivered, the client wants to accept the goods on the condition of a refund for the items not delivered.

This can be done by adding an amendment when setting the GOODS_ACCEPTED step. The ‘renegotiated_value’ replaces the original trade value before fees are deducted.

PHP Example 3

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<?php
# The JWT for your account
$json_token = 'your_jwt_token';

# The url of the API
$service_url = 'https://sandbox.tradesafe.co.za/api/contract/{ID_OF_THE_TRADE}';

$curl = curl_init($service_url);

$postfields = array(
  "id" => "5899715f-bda4-4c91-b78c-033aac102991",
  "step" => "GOODS_ACCEPTED",
  "amend" => array(
    "renegotiated_value" => 100.01,
    "stock_volume" => 0, // optional
    "refund_to_wallet" => 0, // optional
  )
);

curl_setopt_array($curl, array(
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_RETURNTRANSFER => TRUE,
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer ' . $json_token,
    'Content-Type: application/json'
  ),
  CURLOPT_POSTFIELDS => json_encode($postfields)
));

$curl_response = curl_exec($curl);
curl_close($curl);

$response = json_decode($curl_response);

print_r($response);
?>

Updating a Milestone

The technical specifications can be viewed on our API docs.

To update a milestone certain conditions have to be met. In this example we must have already verified the funds before this request can be processed.

Not all steps are available and currently we do not allow any modification of the milestone data after it has been accepted.

The example below would be typically run once you have received notification that your user has received the goods or service for a specific milestone.

Warning

Once the last milestone marked as completed the whole trade will be updated as completed.

PHP Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<?php
# The JWT for your account
$json_token = 'your_jwt_token';

# The url of the API
$service_url = 'https://sandbox.tradesafe.co.za/api/milestone/{ID_OF_THE_TRADE}/{ID_OF_THE_MILESTONE}';

$curl = curl_init($service_url);

$postfields = array(
  "id" => "5899715f-bda4-4c91-b78c-033aac102991",
  "milestone_id" => 10,
  "step" => "GOODS_ACCEPTED"
);

curl_setopt_array($curl, array(
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_RETURNTRANSFER => TRUE,
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer ' . $json_token,
    'Content-Type: application/json'
  ),
  CURLOPT_POSTFIELDS => json_encode($postfields)
));

$curl_response = curl_exec($curl);
curl_close($curl);

$response = json_decode($curl_response);

print_r($response);
?>

Get Constants from the API

There are a number of constants that are used to create a contract ranging from industry to a list of steps and many more. You can always get the most recent values using the constant endpoint.

Below is an example to retrieve a list of industries.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<?php

// get cURL resource
$ch = curl_init();

// set url
curl_setopt($ch, CURLOPT_URL, 'https://sandbox.tradesafe.co.za/api/constant/industry-types');

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...',
  'Content-Type: application/json; charset=utf-8',
]);

// json body
$json_array = [

];
$body = json_encode($json_array);

// set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);

Example Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "GENERAL_GOODS_SERVICES": "General Goods & Services",
  "AGRICULTURE_LIVESTOCK_GAME": "Agriculture, Livestock & Game",
  "ART_ANTIQUES_COLLECTIBLES": "Art, Antiques & Collectibles",
  "BUSINESS_SALE_BROKING": "Business Sale & Broking",
  "VEHICLES_WATERCRAFT": "Cars, Bikes & Watercraft",
  "CONSTRUCTION": "Construction",
  "CONTRACT_WORK_FREELANCING": "Contract Work & Freelancing",
  "FUEL": "Diesel, Petroleum & Biofuel (Local)",
  "FUEL_INTERNATIONAL": "Diesel, Petroleum & Biofuel (Cross-Border)",
  "DONATIONS_TRUSTS": "Donations & Trusts",
  "FILMS_PRODUCTION": "Films & Production",
  "HOLIDAY_LETS_DEPOSITS": "Holiday Lets & Deposits",
  "INVESTMENTS_EXITS": "Investments & Exits",
  "MINING": "Mining, Metals & Minerals",
  "LEASES_RENTAL_DEPOSITS": "Rental Deposits",
  "USED_PARTS": "Used Parts",
  "SOFTWARE_DEV_WEB_DOMAINS": "Web Domain Purchases & Transfers",
  "WEDDINGS_FUNCTIONS": "Weddings & Functions"
}

There are several other constants available:

Note

Replace {constant-type} in /api/constant/{constant-type} with any of the values below.

industry-types
A list of available industries
step-types
A list of all the steps
beneficiary-types
A list of different types of beneficiaries
fee-allocation-types
A list of types of fee allocations
company-types
A list of company types
company-suffix-types
A list of company suffixes
bank-account-types
A list of bank account types
bank-codes
A list of bank branch (CBC) codes

Constants & Variables

Industries

The following constants are used for industry.

  • ART_ANTIQUES_COLLECTABLES - Art, Antiques & Collectables
  • BUSINESS_SALE_BROKING - Business Sale & Broking
  • CONSTRUCTION - Construction
  • CONTRACT_WORK_FREELANCING - Contract Work & Freelancing
  • DONATIONS_TRUSTS - Donations & Trusts
  • FILMS_PRODUCTION - Films & Production
  • GENERAL_GOODS_SERVICES - General Goods & Services
  • HOLIDAY_LETS_DEPOSITS - Holiday Lets & Deposits
  • INVESTMENTS_EXITS - Investments & Exits
  • LEASES_RENTAL_DEPOSITS - Rental Deposits
  • PETS_LIVESTOCK_GAME - Pets, Livestock & Game
  • SOFTWARE_DEV_WEB_DOMAINS - Web Domain purchases and transfers
  • USED_PARTS - Used Parts
  • VEHICLES_WATERCRAFT - Cars, Bikes & Watercraft
  • WEDDINGS_FUNCTIONS - Weddings & Functions

Steps

The following constants are used for step.

  • CREATED - Invitation to be sent
  • INVITATION_SENT - Invitation Sent
  • NEGOTIATION - Trade Negotiation
  • ACCEPTED - Trade Accepted
  • FUNDS_DEPOSITED - Funds Deposited
  • FUNDS_RECEIVED - Funds Received & Cleared
  • SENT - Goods Sent / Service Initiated
  • GOODS_RECEIVED - Goods Received / Service Received
  • GOODS_ACCEPTED - Goods Accepted / Service Accepted
  • FUNDS_RELEASED - Funds Released
  • COMPLETED - Trade Completed
  • DECLINED - Trade Declined
  • DISPUTED - Trade Disputed
  • LEGAL - Legal
  • SUSPENDED - Suspended by admin

Fee Allocation

The following constants are used for TradeSafe’s escrow fee fee_allocation.

  • 0 - Buyer Pays
  • 1 - Seller Pays
  • 2 - 50/50 Split [Buyer / Seller]
  • 3 - Agent Pays
  • 4 - 50/50 Split [Agent / Buyer]
  • 5 - 50/50 Split [Agent / Seller]
  • 6 - 3-Way Split [Agent / Buyer / Seller]

The following constants are used for agent_fee_allocation

  • 0 - Buyer Pays
  • 1 - Seller Pays
  • 2 - 50/50 Split [Buyer / Seller]

Beneficiaries

The following is used to for beneficiary_types

  • ADVISER - Adviser
  • CONSULTANT - Consultant
  • DELIVERY_COMPANY - Delivery Company
  • FINANCIAL_INSTITUTION - Financial Institution
  • INTERMEDIARY - Intermediary
  • LEGAL_COUNSEL - Legal counsel
  • SUB_AGENT - Sub-Agent
  • {custom_bank_name} - Other

Bank Accounts

The following is used to for account_types

  • CHEQUE - Cheque/Current Account
  • SAVINGS - Savings Account
  • TRANSMISSION - Transmission Account
  • BOND - Bond Account

Company Types

  • private - Private company (Pty) Ltd
  • public - Public company (Ltd)
  • state - State-owned company (SOC)
  • inc - Personal liability company (Inc)
  • cc - Close Corporation (CC)
  • npc - Non-profit company (NPC)
  • trust - Trust
  • other - Other