Tokenization Guide

Tokenization allows you to securely save a customer's card details for future payments. This improves the checkout experience for returning customers by eliminating the need to re-enter card information.

How it Works

When you request to save a card, Little Pay interacts with the payment gateway to create a secure token (Customer ID). This token represents the cardholder's information and can be used for subsequent transactions.

1. Creating a Token (Saving a Card)

To save a card during a payment, you must set the createCustomer flag in the metadata of your payment intent.

Request Example (Create Intent)

JavaScript
PHP
Python
Java

const https = require("https");

const data = JSON.stringify({
  amount: 100,
  currency: "KES",
  description: "Saving card for future use",
  callbackUrl: "https://your-domain.com/callback",
  key: "SAVE_CARD_123",
  payload: {
    billingAddress: {
      firstName: "John",
      lastName: "Doe",
      email: "john@example.com",
    },
  },
  metadata: {
    createCustomer: true, // This triggers tokenization
  },
});

const options = {
  hostname: "pay.little.africa",
  path: "/api/payments/{tokenId}/pay",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization:
      "Basic " + Buffer.from("CLIENT_ID:CLIENT_SECRET").toString("base64"),
    "Content-Length": data.length,
  },
};

const req = https.request(options, (res) => {
  let body = "";
  res.on("data", (chunk) => (body += chunk));
  res.on("end", () => console.log(JSON.parse(body)));
});

req.write(data);
req.end();

<?php
$url = "https://pay.little.africa/api/payments/{tokenId}/pay";
$data = [
    "amount" => 100,
    "currency" => "KES",
    "description" => "Saving card for future use",
    "callbackUrl" => "https://your-domain.com/callback",
    "key" => "SAVE_CARD_123",
    "metadata" => [
        "createCustomer" => true
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Basic ' . base64_encode("CLIENT_ID:CLIENT_SECRET")
]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

import requests
from requests.auth import HTTPBasicAuth

url = "https://pay.little.africa/api/payments/{tokenId}/pay"
payload = {
    "amount": 100,
    "currency": "KES",
    "description": "Saving card for future use",
    "callbackUrl": "https://your-domain.com/callback",
    "key": "SAVE_CARD_123",
    "metadata": {
        "createCustomer": True
    }
}

response = requests.post(url, auth=HTTPBasicAuth('CLIENT_ID', 'CLIENT_SECRET'), json=payload)
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://pay.little.africa/api/payments/{tokenId}/pay"; // Replace {tokenId}
        String clientId = "YOUR_CLIENT_ID";
        String clientSecret = "YOUR_CLIENT_SECRET";
        String auth = Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes());

        String jsonPayload = """
            {
              "amount": 100,
              "currency": "KES",
              "description": "Saving card for future use",
              "callbackUrl": "https://your-domain.com/callback",
              "key": "SAVE_CARD_123",
              "payload": {
                "billingAddress": {
                  "firstName": "John",
                  "lastName": "Doe",
                  "email": "john@example.com"
                }
              },
              "metadata": {
                "createCustomer": true
              }
            }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .header("Authorization", "Basic " + auth)
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

When the payment is successfully processed, the response from the payment gateway will include a token identifier. Little Pay automatically creates a Customer record in its database linked to this token.

2. Retrieving the Token

After a successful payment where createCustomer was set to true, the payment callback or the status check response will contain the tokenInformation.

{
  "status": "COMPLETED",
  "data": {
    "tokenInformation": {
      "customer": {
        "id": "1FCA46377B709D13E0631E588D0AC763" // This is the Saved Customer ID
      }
    }
  }
}

You should store this customer.id in your system, associated with your user's profile.

3. Paying with a Saved Card (Using a Token)

To process a payment using a saved card, you only need the customer.id (the token). You do not need to provide the full card details.

Request Example (Process Payment)

When calling the /process endpoint for an intent, pass the customer.id in the payment object:

JavaScript
PHP
Python
Java

const https = require("https");

const data = JSON.stringify({
  type: "CARDS",
  payment: {
    customer: {
      id: "1FCA46377B709D13E0631E588D0AC763", // Saved Customer ID
    },
  },
});

const options = {
  hostname: "pay.little.africa",
  path: "/pay/{reference}/process",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Content-Length": data.length,
  },
};

const req = https.request(options, (res) => {
  let body = "";
  res.on("data", (chunk) => (body += chunk));
  res.on("end", () => console.log(JSON.parse(body)));
});

req.write(data);
req.end();

<?php
$url = "https://pay.little.africa/pay/{reference}/process";
$data = [
    "type" => "CARDS",
    "payment" => [
        "customer" => [
            "id" => "1FCA46377B709D13E0631E588D0AC763"
        ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

import requests

url = "https://pay.little.africa/pay/{reference}/process" # Replace {reference}
payload = {
    "type": "CARDS",
    "payment": {
        "customer": {
            "id": "1FCA46377B709D13E0631E588D0AC763"
        }
    }
}

response = requests.post(url, json=payload)
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://pay.little.africa/pay/{reference}/process"; // Replace {reference}

        String jsonPayload = """
            {
              "type": "CARDS",
              "payment": {
                "customer": {
                  "id": "1FCA46377B709D13E0631E588D0AC763"
                }
              }
            }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Security & Compliance

PCI Compliance: Little Pay handles the secure communication with the payment gateway. Your system never needs to store raw card data (PAN, CVV).
Merchant Specific: Tokens are linked to a specific merchant account. Tokens created for one merchant account cannot be used with another merchant account.
Sandbox vs Production: Tokens created in the sandbox environment are not valid in production and vice-versa.

Relevant Endpoints

Create Intent: POST /payments/{tokenId}/pay (Set metadata.createCustomer: true)
Process Payment: POST /pay/{reference}/process (Provide payment.customer.id)

Tokenization Guide

How it Works​

1. Creating a Token (Saving a Card)​

Request Example (Create Intent)​

2. Retrieving the Token​

3. Paying with a Saved Card (Using a Token)​

Request Example (Process Payment)​

Security & Compliance​

Relevant Endpoints​