Accept Payment

Charge your customer direct from your web or app.

With Shoket, you can collect payments from customers using any of these payment methods: Mobile money, Card.

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

You can generate an API key from your Dashboard at any time. Shoket private key can be obtained here.

Collect customer information

To make a transaction you will need to pass customer information such as (number used, amount, channel, email, customer name). The request must be made with Shoket private key which can be obtained here. Here are full list of parameters and their meaning.

Parameter	Required	Description
Amount	Yes	This is an amount in Tanzania shilling.
Customer Number	Yes	This is a customer phone number which will be used to charge a customer.
Email	Yes	This is a customer Email
Channel	Yes	Mobile-provider name which is used by the customer phone number.
Customer names	Yes	This is a customer full name

Make a payment request

Here is an example of a POST request to charge a customer.

NodeJs

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'api.shoket.co',
  'path': '/v1/charge/',
  'headers': {
    'Authorization': 'Bearer sk_mpBicAlPYEWbYR',
    'Content-Type': 'application/json'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "amount": "5000",
  "customer_name": "John Doe",
  "email": "[e-mail]",
  "number_used": "255612345678",
  "channel": "Tigo"
});

req.write(postData);

req.end();

Python

# Install via pip
pip install requests

import requests
import json

url = "https://api.shoket.co/v1/charge/"

payload = json.dumps({
  "amount": "5000",
  "customer_name": "John Doe",
  "email": "[e-mail]",
  "number_used": "255612345678",
  "channel": "Tigo"
})
headers = {
  'Authorization': 'Bearer sk_mpBicAlPYEWbYR',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.shoket.co/v1/charge/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "amount": "5000",
    "customer_name": "John Doe",
    "email": "[e-mail]",
    "number_used": "255612345678",
    "channel": "Tigo"
   }',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer sk_mpBicAlPYEWbYR',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

JavaScript

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer sk_mpBicAlPYEWbYR");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "amount": "5000",
  "customer_name": "John Doe",
  "email": "[e-mail]",
  "number_used": "255612345678",
  "channel": "Tigo"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.shoket.co/v1/charge/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Dart

var headers = {
  'Authorization': 'Bearer sk_mpBicAlPYEWbYR',
  'Content-Type': 'application/json'
};
var request = http.Request('POST', Uri.parse('https://api.shoket.co/v1/charge/'));
request.body = json.encode({
  "amount": "5000",
  "customer_name": "John Doe",
  "email": "[e-mail]",
  "number_used": "255612345678",
  "channel": "Tigo"
});
request.headers.addAll(headers);

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
  print(await response.stream.bytesToString());
}
else {
  print(response.reasonPhrase);
}

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"amount\": \"5000\",\r\n    \"customer_name\": \"John Doe\",\r\n    \"email\": \"[e-mail]\",\r\n    \"number_used\": \"255612345678\",\r\n    \"channel\": \"Tigo\"\r\n   }");
Request request = new Request.Builder()
  .url("https://api.shoket.co/v1/charge/")
  .method("POST", body)
  .addHeader("Authorization", "Bearer sk_mpBicAlPYEWbYR")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Swift

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{\r\n    \"amount\": \"5000\",\r\n    \"customer_name\": \"John Doe\",\r\n    \"email\": \"[e-mail]\",\r\n    \"number_used\": \"255612345678\",\r\n    \"channel\": \"Tigo\"\r\n   }"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "https://api.shoket.co/v1/charge/")!,timeoutInterval: Double.infinity)
request.addValue("Bearer sk_mpBicAlPYE", forHTTPHeaderField: "Authorization")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    semaphore.signal()
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

After making a POST request Shoket will return a JSON data with transaction data. Also this request will pop up a USSD push to the customer's phone number which you provided

NOTICE: The returned transaction data does not mean that the transaction was made successfully, you have to verify that the status of transaction is Success(this identifies that the transaction was completed). Please read down the table of Status and their meaning.

Here is the sample of returned JSON data.

{
    "Status": "success" ,
    "customer" {
        "customer_name": "376FcD3gbidW",
        "email": "[e-mail]",
        "id": 64043
    },
    "data": {
        "amount": 64000,
        "channel": "Halotel",
        "currency": "TSH",
        "number_used": "0663803078",
        "status": "Success",
        "transaction_date": "2021-06-27 15:08:59.917691"
    },
    "message": "Transaction is completed",
    "reference": "adz49dS428b7kbDTdG4MN"
}

Charge a customer

POST https://api.shoket.co/v1/charge/

Headers

Name	Type	Description
Authorization*	String	Bearer sk_mpBicAlPYEWbYR
Content-Type*	String	application/json

Request Body

Name	Type	Description
amount*	String	5000
customer_name*	String	John Doe
email*	String	[e-mail]
number_used*	String	255612345678
channel	String	Tigo

200: OK Request was successful and intended action was carried out. Note that we will always send a 200 if a charge or verify request was made. Do check the data object to know how the charge went (i.e. successful or failed).

{
    "Status": "success" ,
    "customer" {
        "customer_name": "376FcD3gbidW",
        "email": "[e-mail]",
        "id": 64043
    },
    "data": {
        "amount": 64000,
        "channel": "Halotel",
        "currency": "TSH",
        "number_used": "255663803078",
        "status": "Success",
        "transaction_date": "2021-06-27 15:08:59.917691"
    },
    "message": "Transaction is completed",
    "reference": "adz49dS428b7kbDTdG4MN"
}

401: Unauthorized The request sent was not authorized due not invalid Secret Key or more.

{
    Unauthorized Access
}

422: Unprocessable Entity This may be caused by passing empty some fieldes which are required or by incorrect paramenter.

{
    // Response
}

404: Not Found The resource your requesting is not available.

{
    // Response
}

400: Bad Request An error happened in the client side

{
    // Response
}

500: Internal Server Error Request denied due to error in Shoket Server.

{
    // Response
}

405: Method Not Allowed The method used in the request is not allowed for the requested URL.

{
    // Response
}

403: Forbidden You don't have permission to access the requested resource

{
    // Response
}

429: Too Many Requests You have made too many requests. Please look at our late limiting description

{
    // Response
}