API DOCUMENTATION

Merchant Shopping Cart Interface

The Shopping Cart APP Interface Documentation

This document describes how to connect an online or Web-based shopping cart to Zo! via the Exposed API. The Zo! Shopping Cart Interface (SCI)interface is implemented mainly at the server and the USer shown the address to make payments to. The merchant will pre-initiate the payment at his server, by making a call to Zo! which replies with the initaited order data. The merchant then shows the user the order->address to send coins to. The Zo! shopping cart interface, allows an online buyer to pay using crypto , directly to the merchant’s Zo!® account. This document includes an example PHP implementation interfacing with the Zo!® payment system.

initatiating an order

The Merchant will will post the order details (serverside) to the api. https://cointogo.ecurrency-hub.com/api/neworder
The return is json with parameters reference and redirect. The customer will be redirected to redirect to complete payment The reference is used to query the APi for for the tx status.
Download your Api Key required to use this service.
	/* we shall use guzzle for this example
	* see here http://docs.guzzlephp.org/en/stable/overview.html#installation
	* install guzzle in your project root
	* composer require guzzlehttp/guzzle;
	* download your long api key here 
	*/
	
	 require_once 'vendor/autoload.php';
	 $accessToken = 'YOUR API KEY'; // 1071 chars, copy the APi key downloaded.
	 // example order items
	 $items = [
			[
				'name'=>'Face Cap',
				'description'=>'Blue Zizi facecap',
				'price'=>'2000',
				'id'=>'30',
			],
			[
				'name'=>'Gucci Belt',
				'description'=>'Pure Fashion 2018 Belly Belt',
				'price'=>'12000',
				'id'=>'38',
			],
			[
				'name'=>'Gucci Watch',
				'description'=>'Pure Fashion 2018 wrist Watch',
				'price'=>'12000',
				'id'=>'32',
			],
			[
				'name'=>'Gucci Bag',
				'description'=>'Pure Fashion 2018 Hand Bag',
				'price'=>'17000',
				'id'=>'36',
			],
			[
				'name'=>'Gucci sunglasses',
				'description'=>'Pure Fashion 2018 Eye Beaty',
				'price'=>'67000',
				'id'=>'647',
			],
			
			[
				'name'=>'Tax',
				'description'=>'VAT 18%',
				'price'=>'2780',
				'id'=>'2764',
			],
			
			
		];
		
		$data['items'] = $items ;
		$data['amount'] = '120000.9867';
		$data['symbol'] = 'ANT'; //REQUIRED
		/* return url REQUIRED
		* return url is the URL users are returned to after making payment.								
		* There are no post variables. 
		* You are free to add request  variables
		*/
		$data['return_url'] = 'http://www.your-website.com/'; //REQUIRED
		
		/* ipn_url
		* return url is the URL users are returned to after making payment.								
		* There are no post variables. 
		* You are free to add request  variables
		
		*/
		$data['ipn_url'] = 'https://www.your-website.com/8.php'; //REQUIRED
		$data['cancel_url'] = 'http://www.your-website.com/cancel/'; //REQUIRED
		
		// Note how the access token is used in the Authorisation Header
		
		$client = new \GuzzleHttp\Client();
		try {
			$response = $client->request('POST', 'https://cointogo.ecurrency-hub.com/api/neworder', [
				'headers' => [
					'Accept' => 'application/json',
					'Authorization' => 'Bearer '.$accessToken,
				 ],
				 'form_params'=> $data,
				 'debug' => false
			 ]);
		 } catch (\GuzzleHttp\Exception\TransferException $e) {
			throw new \Exception ($e->getMessage());
		}
		if ($response->getStatusCode() < 200 || $response->getStatusCode() >= 300) {
			throw new \Exception ('HTTP error');
		}
		$json = json_decode($response->getBody());
		if (isset($json->error)) {
			throw new \Exception($json->error);
		}
		$reference = $json->reference; // use this eference to track tx progress
		$redirect = $json->redirect; // redirect user to this to complete paymeny
		redirect($redirect);
	
	
Return Data
Structure of the returned json is shown Below. Take Note of three things, The address, the address_qr_image link and the reference
	
	[
		"address" => "0xb21d8545c56b62c875402e5e52e4a4618e0e5fde",
		"address_qr_image" => "https://cointogo.ecurrency-hub.com/qr-code/0xb21d8545c56b62c875402e5e52e4a4618e0e5fde",
		"symbol" => "ANT",
		"amount" => "120000.9867",
		"reference" => "e1917fdbfa43f87b8cc55168eb081e0b",
		"status" => "UNPAID",
		"confirmations" => NULL,
		"transactions" => [], 
		"item_data"=> [
			"items"=> [], // list of your items above.
		]
	
When payment is first recieved on the order address, The updated order json (above ) will be re posted to the ipn_url Now showing the confirmation count and status "PENDING" or "COMPLETE"

Instant Pay Notification: IPN

When a payment is confirmed 3 times in the block chain, the order data is posted one last time to the ipn_url the order data is showed below
	
	{
		  "address": "0xb21d8545c56b62c875402e5e52e4a4618e0e5fde",
		  "symbol": "ANT",
		  "amount": "120000.9867",
		  "confirmations" => 4,
		  "status": "COMPLETE",
		  "transactions": []
		  "reference": "e1917fdbfa43f87b8cc55168eb081e0b",
		  "item_url": "http://www.your-website.com/",
		  "item_data": {
			"items": [
			  {
				"name": "Face Cap",
				"description": "Blue Zizi facecap",
				"price": "2000",
				"id": "30"
			  },
			  {
				"name": "Gucci Belt",
				"description": "Pure Fashion 2018 Belly Belt",
				"price": "12000",
				"id": "38"
			  },
			  {
				"name": "Gucci Watch",
				"description": "Pure Fashion 2018 wrist Watch",
				"price": "12000",
				"id": "32"
			  },
			  {
				"name": "Gucci Bag",
				"description": "Pure Fashion 2018 Hand Bag",
				"price": "17000",
				"id": "36"
			  },
			  {
				"name": "Gucci sunglasses",
				"description": "Pure Fashion 2018 Eye Beaty",
				"price": "67000",
				"id": "647"
			  },
			  {
				"name": "Tax",
				"description": "VAT 18%",
				"price": "2780",
				"id": "2764"
			  }
			],
			"amount": "120000.9867",
			"symbol": "ANT",
			"return_url": "http://www.your-website.com/",
			"ipn_url": "https://www.your-website.com/8.php",
			"cancel_url": "http://www.your-website.com/cancel/",
			"expiry": 10
		  },
		}
	
You can use the post post variables easily.
	 $reference = $_POST['reference'];
	

Checking / verifying Payment status

Merchants Must ensure they fetch the order json from the status url https://cointogo.ecurrency-hub.com/api/order/{$reference} (where {$reference} is your order reference ) to avoid user tampering.

Order Json structure

		{
		  "address": "0xb21d8545c56b62c875402e5e52e4a4618e0e5fde",
		  "symbol": "ANT",
		  "amount": "120000.9867",
		  "confirmations" => 4,
		  "status": "COMPLETE",
		  "transactions": []
		  "reference": "e1917fdbfa43f87b8cc55168eb081e0b",
		  "item_url": "http://www.your-website.com/",
		  "item_data": {
			"items": [
			  {
				"name": "Face Cap",
				"description": "Blue Zizi facecap",
				"price": "2000",
				"id": "30"
			  },
			  {
				"name": "Gucci Belt",
				"description": "Pure Fashion 2018 Belly Belt",
				"price": "12000",
				"id": "38"
			  },
			  {
				"name": "Gucci Watch",
				"description": "Pure Fashion 2018 wrist Watch",
				"price": "12000",
				"id": "32"
			  },
			  {
				"name": "Gucci Bag",
				"description": "Pure Fashion 2018 Hand Bag",
				"price": "17000",
				"id": "36"
			  },
			  {
				"name": "Gucci sunglasses",
				"description": "Pure Fashion 2018 Eye Beaty",
				"price": "67000",
				"id": "647"
			  },
			  {
				"name": "Tax",
				"description": "VAT 18%",
				"price": "2780",
				"id": "2764"
			  }
			],
			"amount": "120000.9867",
			"symbol": "ANT",
			"return_url": "http://www.your-website.com/",
			"ipn_url": "https://www.your-website.com/8.php",
			"cancel_url": "http://www.your-website.com/cancel/",
			"expiry": 10
		  },
		}
		

Example php IPN code

	 require_once 'vendor/autoload.php'; // to load guzzle.
	 $accessToken = 'YOUR API KEY'; // 1071 chars
	 $order_reference = $_POST['reference'];
	 $client = new \GuzzleHttp\Client();
		try {
			$response = $client->request('POST', 'https://cointogo.ecurrency-hub.com/api/order/e1917fdbfa43f87b8cc55168eb081e0b', [
				'headers' => [
					'Accept' => 'application/json',
					'Authorization' => 'Bearer '.$accessToken,
				 ],
				 'form_params'=> ['reference'=>$order_reference ],
				 'debug' => false
			 ]);
		 } catch (\GuzzleHttp\Exception\TransferException $e) {
			die(var_dump((string)$e->getResponse()->getBody()));
			//throw new \Exception ($err);
		}
		if ($response->getStatusCode() < 200 || $response->getStatusCode() >= 300) {
			throw new \Exception ('HTTP error');
		}
		$order = json_decode($response->getBody(),true);

		//verify that the status is paid and sum of all paid transactions is enough to clear your order
		
		if($order['status'] ==='PAID' && array_sum(array_column($order['transactions'],'amount')) >= $myorder->amount ){
		
			//completeOrder($myorder->id); complete your order here
			
		}else{
		
		// order is not paid in full
		}