API DOCUMENTATION

TOKENIZATION API
MobiToken by MobiCard

Use this multi-platform API to reduce your PCI compliance footprint by tokenizing payment card information. Store only tokens instead of actual card data, and detokenize when needed for payment processing.

With two API endpoints: Tokenization (convert card data to token) and Detokenization (convert token back to card data). Implement secure card storage while maintaining PCI DSS compliance.

PCI Compliance Benefit: By storing only tokens and masked card numbers instead of actual card data, you significantly reduce your PCI DSS compliance scope and liability.
Token Security: Tokens are cryptographically secure and can be configured as single-use (regenerated after each detokenization) or multi-use based on your security requirements.

Select an API below:

Tokenization API Overview

Convert sensitive card data into a secure token that can be safely stored in your systems. The original card data is stored in our PCI-compliant vault.

Use Case: During card registration, tokenize the card details and store only the token and masked card number. Use the token for subsequent transactions without storing actual card data.
Single-Use Tokens: Set mobicard_single_use_token_flag = "1" to regenerate a new token after each detokenization, enhancing security for one-time use cases.

Tokenization Implementation

Generate a signed JWT token with embedded request.

Send card details to receive a secure card token. Store the token and masked card number instead of actual card data.

PHP Implementation
<?php

// Mandatory claims
$mobicard_version = "2.0";
$mobicard_mode = "LIVE"; // production
$mobicard_merchant_id = "4";
$mobicard_api_key = "YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9";
$mobicard_secret_key = "NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9";

$mobicard_token_id = abs(rand(1000000,1000000000));
$mobicard_token_id = "$mobicard_token_id";

$mobicard_txn_reference = abs(rand(1000000,1000000000));
$mobicard_txn_reference = "$mobicard_txn_reference";

$mobicard_service_id = "20000";
$mobicard_service_type = "TOKENIZATION";

$mobicard_single_use_token_flag = "0"; // Change to "1" for single-use tokens

// Card details to tokenize
$mobicard_card_number = "4242424242424242"; // Test card number
$mobicard_card_expiry_month = "02"; // MM
$mobicard_card_expiry_year = "28"; // YY

// Custom data fields (optional)
$mobicard_custom_one = "mobicard_custom_one";
$mobicard_custom_two = "mobicard_custom_two";
$mobicard_custom_three = "mobicard_custom_three";
$mobicard_extra_data = "your_custom_data_here_will_be_returned_as_is";

// Create JWT Header
$mobicard_jwt_header = [
    "typ" => "JWT",
    "alg" => "HS256"
];
$mobicard_jwt_header = rtrim(strtr(base64_encode(json_encode($mobicard_jwt_header)), '+/', '-_'), '=');

// Create JWT Payload
$mobicard_jwt_payload = array(
    "mobicard_version" => "$mobicard_version",
    "mobicard_mode" => "$mobicard_mode",
    "mobicard_merchant_id" => "$mobicard_merchant_id",
    "mobicard_api_key" => "$mobicard_api_key",
    "mobicard_service_id" => "$mobicard_service_id",
    "mobicard_service_type" => "$mobicard_service_type",
    "mobicard_token_id" => "$mobicard_token_id",
    "mobicard_txn_reference" => "$mobicard_txn_reference",
    "mobicard_single_use_token_flag" => "$mobicard_single_use_token_flag",
    "mobicard_card_number" => "$mobicard_card_number",
    "mobicard_card_expiry_month" => "$mobicard_card_expiry_month",
    "mobicard_card_expiry_year" => "$mobicard_card_expiry_year",
    "mobicard_custom_one" => "$mobicard_custom_one",
    "mobicard_custom_two" => "$mobicard_custom_two",
    "mobicard_custom_three" => "$mobicard_custom_three",
    "mobicard_extra_data" => "$mobicard_extra_data"
);

$mobicard_jwt_payload = rtrim(strtr(base64_encode(json_encode($mobicard_jwt_payload)), '+/', '-_'), '=');

// Generate Signature
$header_payload = $mobicard_jwt_header . '.' . $mobicard_jwt_payload;
$mobicard_jwt_signature = rtrim(strtr(base64_encode(hash_hmac('sha256', $header_payload, $mobicard_secret_key, true)), '+/', '-_'), '=');

// Create Final JWT
$mobicard_auth_jwt = "$mobicard_jwt_header.$mobicard_jwt_payload.$mobicard_jwt_signature";

// Make API Call
$mobicard_request_access_token_url = "https://mobicardsystems.com/api/v1/card_tokenization";

$mobicard_curl_post_data = array('mobicard_auth_jwt' => $mobicard_auth_jwt);

$curl_mobicard = curl_init();
curl_setopt($curl_mobicard, CURLOPT_URL, $mobicard_request_access_token_url);
curl_setopt($curl_mobicard, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl_mobicard, CURLOPT_POST, true);
curl_setopt($curl_mobicard, CURLOPT_POSTFIELDS, json_encode($mobicard_curl_post_data));
curl_setopt($curl_mobicard, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl_mobicard, CURLOPT_SSL_VERIFYPEER, false);
$mobicard_curl_response = curl_exec($curl_mobicard);
curl_close($curl_mobicard);

// Parse Response
$response_data = json_decode($mobicard_curl_response, true);

if(isset($response_data) && is_array($response_data)) {
    if($response_data['status'] === 'SUCCESS') {
        // Store these in your database
        $card_token = $response_data['card_information']['card_token'];
        $card_number_masked = $response_data['card_information']['card_number_masked'];
        
        echo "Tokenization Successful!
"; echo "Card Token: " . $card_token . "
"; echo "Masked Card: " . $card_number_masked . "
"; echo "Store these values instead of actual card data."; } else { echo "Error: " . $response_data['status_message'] . " (Code: " . $response_data['status_code'] . ")"; } } else { echo "Error: Invalid API response"; }
cURL Implementation
#!/bin/bash

# Configuration
MOBICARD_VERSION="2.0"
MOBICARD_MODE="LIVE"
MOBICARD_MERCHANT_ID="4"
MOBICARD_API_KEY="YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9"
MOBICARD_SECRET_KEY="NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9"
MOBICARD_TOKEN_ID=$(shuf -i 1000000-1000000000 -n 1)
MOBICARD_TXN_REFERENCE=$(shuf -i 1000000-1000000000 -n 1)
MOBICARD_SERVICE_ID="20000"
MOBICARD_SERVICE_TYPE="TOKENIZATION"
MOBICARD_SINGLE_USE_TOKEN_FLAG="0"
MOBICARD_CARD_NUMBER="4242424242424242"
MOBICARD_CARD_EXPIRY_MONTH="02"
MOBICARD_CARD_EXPIRY_YEAR="28"
MOBICARD_CUSTOM_ONE="mobicard_custom_one"
MOBICARD_CUSTOM_TWO="mobicard_custom_two"
MOBICARD_CUSTOM_THREE="mobicard_custom_three"
MOBICARD_EXTRA_DATA="your_custom_data_here_will_be_returned_as_is"

# Create JWT Header
JWT_HEADER=$(echo -n '{"typ":"JWT","alg":"HS256"}' | base64 | tr '+/' '-_' | tr -d '=')

# Create JWT Payload
PAYLOAD_JSON=$(cat << EOF
{
  "mobicard_version": "$MOBICARD_VERSION",
  "mobicard_mode": "$MOBICARD_MODE",
  "mobicard_merchant_id": "$MOBICARD_MERCHANT_ID",
  "mobicard_api_key": "$MOBICARD_API_KEY",
  "mobicard_service_id": "$MOBICARD_SERVICE_ID",
  "mobicard_service_type": "$MOBICARD_SERVICE_TYPE",
  "mobicard_token_id": "$MOBICARD_TOKEN_ID",
  "mobicard_txn_reference": "$MOBICARD_TXN_REFERENCE",
  "mobicard_single_use_token_flag": "$MOBICARD_SINGLE_USE_TOKEN_FLAG",
  "mobicard_card_number": "$MOBICARD_CARD_NUMBER",
  "mobicard_card_expiry_month": "$MOBICARD_CARD_EXPIRY_MONTH",
  "mobicard_card_expiry_year": "$MOBICARD_CARD_EXPIRY_YEAR",
  "mobicard_custom_one": "$MOBICARD_CUSTOM_ONE",
  "mobicard_custom_two": "$MOBICARD_CUSTOM_TWO",
  "mobicard_custom_three": "$MOBICARD_CUSTOM_THREE",
  "mobicard_extra_data": "$MOBICARD_EXTRA_DATA"
}
EOF
)

JWT_PAYLOAD=$(echo -n "$PAYLOAD_JSON" | base64 | tr '+/' '-_' | tr -d '=')

# Generate Signature
HEADER_PAYLOAD="$JWT_HEADER.$JWT_PAYLOAD"
JWT_SIGNATURE=$(echo -n "$HEADER_PAYLOAD" | openssl dgst -sha256 -hmac "$MOBICARD_SECRET_KEY" -binary | base64 | tr '+/' '-_' | tr -d '=')

# Create Final JWT
MOBICARD_AUTH_JWT="$JWT_HEADER.$JWT_PAYLOAD.$JWT_SIGNATURE"

# Make API Call
API_URL="https://mobicardsystems.com/api/v1/card_tokenization"

RESPONSE=$(curl -X POST "$API_URL" \
  -H "Content-Type: application/json" \
  -d "{\"mobicard_auth_jwt\":\"$MOBICARD_AUTH_JWT\"}" \
  --silent)

echo "$RESPONSE" | python -m json.tool
Python Implementation
import json
import base64
import hmac
import hashlib
import random
import requests

class MobicardTokenization:
    def __init__(self, merchant_id, api_key, secret_key):
        self.mobicard_version = "2.0"
        self.mobicard_mode = "LIVE"
        self.mobicard_merchant_id = merchant_id
        self.mobicard_api_key = api_key
        self.mobicard_secret_key = secret_key
        self.mobicard_service_id = "20000"
        self.mobicard_service_type = "TOKENIZATION"
        
        self.mobicard_token_id = str(random.randint(1000000, 1000000000))
        self.mobicard_txn_reference = str(random.randint(1000000, 1000000000))
    
    def tokenize_card(self, card_number, expiry_month, expiry_year, 
                     single_use_token=False, custom_data=None):
        """Tokenize card details"""
        
        mobicard_single_use_token_flag = "1" if single_use_token else "0"
        
        # Default custom data
        if custom_data is None:
            custom_data = {
                "mobicard_custom_one": "mobicard_custom_one",
                "mobicard_custom_two": "mobicard_custom_two",
                "mobicard_custom_three": "mobicard_custom_three",
                "mobicard_extra_data": "your_custom_data_here_will_be_returned_as_is"
            }
        
        # Create JWT Header
        jwt_header = {"typ": "JWT", "alg": "HS256"}
        encoded_header = base64.urlsafe_b64encode(
            json.dumps(jwt_header).encode()
        ).decode().rstrip('=')
        
        # Create JWT Payload
        jwt_payload = {
            "mobicard_version": self.mobicard_version,
            "mobicard_mode": self.mobicard_mode,
            "mobicard_merchant_id": self.mobicard_merchant_id,
            "mobicard_api_key": self.mobicard_api_key,
            "mobicard_service_id": self.mobicard_service_id,
            "mobicard_service_type": self.mobicard_service_type,
            "mobicard_token_id": self.mobicard_token_id,
            "mobicard_txn_reference": self.mobicard_txn_reference,
            "mobicard_single_use_token_flag": mobicard_single_use_token_flag,
            "mobicard_card_number": card_number,
            "mobicard_card_expiry_month": expiry_month,
            "mobicard_card_expiry_year": expiry_year,
            "mobicard_custom_one": custom_data.get("mobicard_custom_one", ""),
            "mobicard_custom_two": custom_data.get("mobicard_custom_two", ""),
            "mobicard_custom_three": custom_data.get("mobicard_custom_three", ""),
            "mobicard_extra_data": custom_data.get("mobicard_extra_data", "")
        }
        
        encoded_payload = base64.urlsafe_b64encode(
            json.dumps(jwt_payload).encode()
        ).decode().rstrip('=')
        
        # Generate Signature
        header_payload = f"{encoded_header}.{encoded_payload}"
        signature = hmac.new(
            self.mobicard_secret_key.encode(),
            header_payload.encode(),
            hashlib.sha256
        ).digest()
        encoded_signature = base64.urlsafe_b64encode(signature).decode().rstrip('=')
        
        jwt_token = f"{encoded_header}.{encoded_payload}.{encoded_signature}"
        
        # Make API Call
        url = "https://mobicardsystems.com/api/v1/card_tokenization"
        payload = {"mobicard_auth_jwt": jwt_token}
        
        try:
            response = requests.post(url, json=payload, verify=False, timeout=30)
            response_data = response.json()
            
            if response_data.get('status') == 'SUCCESS':
                return {
                    'status': 'SUCCESS',
                    'card_token': response_data['card_information']['card_token'],
                    'card_number_masked': response_data['card_information']['card_number_masked'],
                    'raw_response': response_data
                }
            else:
                return {
                    'status': 'ERROR',
                    'status_code': response_data.get('status_code'),
                    'status_message': response_data.get('status_message')
                }
                
        except Exception as e:
            return {'status': 'ERROR', 'error_message': str(e)}

# Usage
tokenizer = MobicardTokenization(
    merchant_id="4",
    api_key="YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9",
    secret_key="NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9"
)

result = tokenizer.tokenize_card(
    card_number="4242424242424242",
    expiry_month="02",
    expiry_year="28",
    single_use_token=False
)

if result['status'] == 'SUCCESS':
    print(f"Token: {result['card_token']}")
    print(f"Masked Card: {result['card_number_masked']}")
    print("Store token and masked card in your database.")
else:
    print(f"Error: {result.get('status_message')}")
Node JS Implementation
const crypto = require('crypto');
const axios = require('axios');

class MobicardTokenization {
    constructor(merchantId, apiKey, secretKey) {
        this.mobicardVersion = "2.0";
        this.mobicardMode = "LIVE";
        this.mobicardMerchantId = merchantId;
        this.mobicardApiKey = apiKey;
        this.mobicardSecretKey = secretKey;
        this.mobicardServiceId = "20000";
        this.mobicardServiceType = "TOKENIZATION";
        
        this.mobicardTokenId = Math.floor(Math.random() * (1000000000 - 1000000 + 1)) + 1000000;
        this.mobicardTxnReference = Math.floor(Math.random() * (1000000000 - 1000000 + 1)) + 1000000;
    }

    generateJWT(cardData) {
        const jwtHeader = { typ: "JWT", alg: "HS256" };
        const encodedHeader = Buffer.from(JSON.stringify(jwtHeader)).toString('base64url');

        const jwtPayload = {
            mobicard_version: this.mobicardVersion,
            mobicard_mode: this.mobicardMode,
            mobicard_merchant_id: this.mobicardMerchantId,
            mobicard_api_key: this.mobicardApiKey,
            mobicard_service_id: this.mobicardServiceId,
            mobicard_service_type: this.mobicardServiceType,
            mobicard_token_id: this.mobicardTokenId.toString(),
            mobicard_txn_reference: this.mobicardTxnReference.toString(),
            mobicard_single_use_token_flag: cardData.singleUseToken ? "1" : "0",
            mobicard_card_number: cardData.cardNumber,
            mobicard_card_expiry_month: cardData.expiryMonth,
            mobicard_card_expiry_year: cardData.expiryYear,
            mobicard_custom_one: cardData.customOne || "mobicard_custom_one",
            mobicard_custom_two: cardData.customTwo || "mobicard_custom_two",
            mobicard_custom_three: cardData.customThree || "mobicard_custom_three",
            mobicard_extra_data: cardData.extraData || "your_custom_data_here_will_be_returned_as_is"
        };

        const encodedPayload = Buffer.from(JSON.stringify(jwtPayload)).toString('base64url');

        const headerPayload = `${encodedHeader}.${encodedPayload}`;
        const signature = crypto.createHmac('sha256', this.mobicardSecretKey)
            .update(headerPayload)
            .digest('base64url');

        return `${encodedHeader}.${encodedPayload}.${signature}`;
    }

    async tokenizeCard(cardData) {
        try {
            const jwtToken = this.generateJWT(cardData);
            
            const url = "https://mobicardsystems.com/api/v1/card_tokenization";
            const payload = { mobicard_auth_jwt: jwtToken };

            const response = await axios.post(url, payload, {
                httpsAgent: new (require('https').Agent)({ rejectUnauthorized: false })
            });

            const responseData = response.data;

            if (responseData.status === 'SUCCESS') {
                return {
                    status: 'SUCCESS',
                    cardToken: responseData.card_information.card_token,
                    cardNumberMasked: responseData.card_information.card_number_masked,
                    rawResponse: responseData
                };
            } else {
                return {
                    status: 'ERROR',
                    statusCode: responseData.status_code,
                    statusMessage: responseData.status_message
                };
            }
        } catch (error) {
            return {
                status: 'ERROR',
                errorMessage: error.message
            };
        }
    }
}

// Usage
async function main() {
    const tokenizer = new MobicardTokenization(
        "4",
        "YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9",
        "NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9"
    );

    const result = await tokenizer.tokenizeCard({
        cardNumber: "4242424242424242",
        expiryMonth: "02",
        expiryYear: "28",
        singleUseToken: false
    });

    if (result.status === 'SUCCESS') {
        console.log("Tokenization Successful!");
        console.log(`Card Token: ${result.cardToken}`);
        console.log(`Masked Card: ${result.cardNumberMasked}`);
    } else {
        console.log(`Error: ${result.statusMessage}`);
    }
}

main();
Java Implementation
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
import java.util.Random;
import java.util.HashMap;
import java.util.Map;

import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class MobicardTokenization {
    
    private final String mobicardVersion = "2.0";
    private final String mobicardMode = "LIVE";
    private final String mobicardMerchantId;
    private final String mobicardApiKey;
    private final String mobicardSecretKey;
    private final String mobicardServiceId = "20000";
    private final String mobicardServiceType = "TOKENIZATION";
    
    private final String mobicardTokenId;
    private final String mobicardTxnReference;
    
    private final Gson gson = new Gson();
    
    public MobicardTokenization(String merchantId, String apiKey, String secretKey) {
        this.mobicardMerchantId = merchantId;
        this.mobicardApiKey = apiKey;
        this.mobicardSecretKey = secretKey;
        
        Random random = new Random();
        this.mobicardTokenId = String.valueOf(random.nextInt(900000000) + 1000000);
        this.mobicardTxnReference = String.valueOf(random.nextInt(900000000) + 1000000);
    }
    
    public String generateJWT(String cardNumber, String expiryMonth, String expiryYear, 
                             boolean singleUseToken, Map customData) throws Exception {
        
        Map jwtHeader = new HashMap<>();
        jwtHeader.put("typ", "JWT");
        jwtHeader.put("alg", "HS256");
        String encodedHeader = base64UrlEncode(gson.toJson(jwtHeader));
        
        Map jwtPayload = new HashMap<>();
        jwtPayload.put("mobicard_version", mobicardVersion);
        jwtPayload.put("mobicard_mode", mobicardMode);
        jwtPayload.put("mobicard_merchant_id", mobicardMerchantId);
        jwtPayload.put("mobicard_api_key", mobicardApiKey);
        jwtPayload.put("mobicard_service_id", mobicardServiceId);
        jwtPayload.put("mobicard_service_type", mobicardServiceType);
        jwtPayload.put("mobicard_token_id", mobicardTokenId);
        jwtPayload.put("mobicard_txn_reference", mobicardTxnReference);
        jwtPayload.put("mobicard_single_use_token_flag", singleUseToken ? "1" : "0");
        jwtPayload.put("mobicard_card_number", cardNumber);
        jwtPayload.put("mobicard_card_expiry_month", expiryMonth);
        jwtPayload.put("mobicard_card_expiry_year", expiryYear);
        jwtPayload.put("mobicard_custom_one", customData.getOrDefault("customOne", "mobicard_custom_one"));
        jwtPayload.put("mobicard_custom_two", customData.getOrDefault("customTwo", "mobicard_custom_two"));
        jwtPayload.put("mobicard_custom_three", customData.getOrDefault("customThree", "mobicard_custom_three"));
        jwtPayload.put("mobicard_extra_data", customData.getOrDefault("extraData", "your_custom_data_here_will_be_returned_as_is"));
        
        String encodedPayload = base64UrlEncode(gson.toJson(jwtPayload));
        
        String headerPayload = encodedHeader + "." + encodedPayload;
        String signature = generateHMAC(headerPayload, mobicardSecretKey);
        
        return encodedHeader + "." + encodedPayload + "." + signature;
    }
    
    public JsonObject tokenizeCard(String cardNumber, String expiryMonth, String expiryYear, 
                                  boolean singleUseToken) throws Exception {
        
        Map customData = new HashMap<>();
        customData.put("customOne", "mobicard_custom_one");
        customData.put("customTwo", "mobicard_custom_two");
        customData.put("customThree", "mobicard_custom_three");
        customData.put("extraData", "your_custom_data_here_will_be_returned_as_is");
        
        String jwtToken = generateJWT(cardNumber, expiryMonth, expiryYear, singleUseToken, customData);
        
        HttpClient client = HttpClient.newHttpClient();
        
        Map requestBody = new HashMap<>();
        requestBody.put("mobicard_auth_jwt", jwtToken);
        
        String jsonBody = gson.toJson(requestBody);
        
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://mobicardsystems.com/api/v1/card_tokenization"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();
        
        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        return gson.fromJson(response.body(), JsonObject.class);
    }
    
    private String base64UrlEncode(String data) {
        return Base64.getUrlEncoder().withoutPadding().encodeToString(data.getBytes());
    }
    
    private String generateHMAC(String data, String key) throws Exception {
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(), "HmacSHA256");
        sha256Hmac.init(secretKey);
        byte[] hmacBytes = sha256Hmac.doFinal(data.getBytes());
        return base64UrlEncode(new String(hmacBytes));
    }
    
    public static void main(String[] args) {
        try {
            MobicardTokenization tokenizer = new MobicardTokenization(
                "4",
                "YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9",
                "NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9"
            );
            
            JsonObject result = tokenizer.tokenizeCard(
                "4242424242424242",
                "02",
                "28",
                false
            );
            
            if (result.has("status")) {
                String status = result.get("status").getAsString();
                
                if ("SUCCESS".equals(status)) {
                    System.out.println("Tokenization Successful!");
                    
                    if (result.has("card_information")) {
                        JsonObject cardInfo = result.getAsJsonObject("card_information");
                        
                        System.out.println("Card Token: " + 
                            cardInfo.get("card_token").getAsString());
                        System.out.println("Masked Card: " + 
                            cardInfo.get("card_number_masked").getAsString());
                        System.out.println("\nStore these values in your database.");
                    }
                } else {
                    System.out.println("Tokenization Failed!");
                    if (result.has("status_message")) {
                        System.out.println("Error: " + result.get("status_message").getAsString());
                    }
                }
            }
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Detokenization API Overview

Convert a secure token back to the original card data for payment processing. The token must have been previously generated through the Tokenization API.

Use Case: When you need to process a payment, detokenize the stored token to retrieve the original card details for transaction processing.
Single-Use Tokens: If the token was created with mobicard_single_use_token_flag = "1", a new token will be generated and returned after detokenization.

Detokenization Implementation

Generate a signed JWT token with embedded request.

Send the card token to retrieve the original card details. For single-use tokens, a new token will be returned.

PHP Implementation
<?php

// Mandatory claims
$mobicard_version = "2.0";
$mobicard_mode = "LIVE"; // production
$mobicard_merchant_id = "4";
$mobicard_api_key = "YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9";
$mobicard_secret_key = "NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9";

$mobicard_token_id = abs(rand(1000000,1000000000));
$mobicard_token_id = "$mobicard_token_id";

$mobicard_txn_reference = abs(rand(1000000,1000000000));
$mobicard_txn_reference = "$mobicard_txn_reference";

$mobicard_service_id = "20000";
$mobicard_service_type = "DETOKENIZATION";

// Token to detokenize (retrieved from your database)
$mobicard_card_token = "tok_mc_3b0da132b39673f01eafb3865ec1a9a56b0712c59a82d3d0807ade74b68cb38b4c559e50817452270c88afa3e0de2c8cd32d8a69ee9f72de8a04c2c4955cdcce";

// Create JWT Header
$mobicard_jwt_header = [
    "typ" => "JWT",
    "alg" => "HS256"
];
$mobicard_jwt_header = rtrim(strtr(base64_encode(json_encode($mobicard_jwt_header)), '+/', '-_'), '=');

// Create JWT Payload
$mobicard_jwt_payload = array(
    "mobicard_version" => "$mobicard_version",
    "mobicard_mode" => "$mobicard_mode",
    "mobicard_merchant_id" => "$mobicard_merchant_id",
    "mobicard_api_key" => "$mobicard_api_key",
    "mobicard_service_id" => "$mobicard_service_id",
    "mobicard_service_type" => "$mobicard_service_type",
    "mobicard_token_id" => "$mobicard_token_id",
    "mobicard_txn_reference" => "$mobicard_txn_reference",
    "mobicard_card_token" => "$mobicard_card_token"
);

$mobicard_jwt_payload = rtrim(strtr(base64_encode(json_encode($mobicard_jwt_payload)), '+/', '-_'), '=');

// Generate Signature
$header_payload = $mobicard_jwt_header . '.' . $mobicard_jwt_payload;
$mobicard_jwt_signature = rtrim(strtr(base64_encode(hash_hmac('sha256', $header_payload, $mobicard_secret_key, true)), '+/', '-_'), '=');

// Create Final JWT
$mobicard_auth_jwt = "$mobicard_jwt_header.$mobicard_jwt_payload.$mobicard_jwt_signature";

// Make API Call
$mobicard_request_access_token_url = "https://mobicardsystems.com/api/v1/card_tokenization";

$mobicard_curl_post_data = array('mobicard_auth_jwt' => $mobicard_auth_jwt);

$curl_mobicard = curl_init();
curl_setopt($curl_mobicard, CURLOPT_URL, $mobicard_request_access_token_url);
curl_setopt($curl_mobicard, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl_mobicard, CURLOPT_POST, true);
curl_setopt($curl_mobicard, CURLOPT_POSTFIELDS, json_encode($mobicard_curl_post_data));
curl_setopt($curl_mobicard, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl_mobicard, CURLOPT_SSL_VERIFYPEER, false);
$mobicard_curl_response = curl_exec($curl_mobicard);
curl_close($curl_mobicard);

// Parse Response
$response_data = json_decode($mobicard_curl_response, true);

if(isset($response_data) && is_array($response_data)) {
    if($response_data['status'] === 'SUCCESS') {
        // Extract card details for processing
        $card_number = $response_data['card_information']['card_number'];
        $card_expiry_date = $response_data['card_information']['card_expiry_date'];
        $card_token = $response_data['card_information']['card_token'];
        
        echo "Detokenization Successful!
"; echo "Card Number: " . $response_data['card_information']['card_number_masked'] . "
"; echo "Expiry Date: " . $card_expiry_date . "
"; // If single-use token flag was set, new token is returned if($response_data['mobicard_single_use_token_flag'] === '1') { echo "New Token Generated: " . $card_token . "
"; echo "Update your database with the new token."; } // Use $card_number for payment processing // Process payment here... } else { echo "Error: " . $response_data['status_message'] . " (Code: " . $response_data['status_code'] . ")"; } } else { echo "Error: Invalid API response"; }
cURL Implementation
#!/bin/bash

# Configuration
MOBICARD_VERSION="2.0"
MOBICARD_MODE="LIVE"
MOBICARD_MERCHANT_ID="4"
MOBICARD_API_KEY="YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9"
MOBICARD_SECRET_KEY="NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9"
MOBICARD_TOKEN_ID=$(shuf -i 1000000-1000000000 -n 1)
MOBICARD_TXN_REFERENCE=$(shuf -i 1000000-1000000000 -n 1)
MOBICARD_SERVICE_ID="20000"
MOBICARD_SERVICE_TYPE="DETOKENIZATION"

# Token to detokenize (from your database)
MOBICARD_CARD_TOKEN="tok_mc_3b0da132b39673f01eafb3865ec1a9a56b0712c59a82d3d0807ade74b68cb38b4c559e50817452270c88afa3e0de2c8cd32d8a69ee9f72de8a04c2c4955cdcce"

# Create JWT Header
JWT_HEADER=$(echo -n '{"typ":"JWT","alg":"HS256"}' | base64 | tr '+/' '-_' | tr -d '=')

# Create JWT Payload
PAYLOAD_JSON=$(cat << EOF
{
  "mobicard_version": "$MOBICARD_VERSION",
  "mobicard_mode": "$MOBICARD_MODE",
  "mobicard_merchant_id": "$MOBICARD_MERCHANT_ID",
  "mobicard_api_key": "$MOBICARD_API_KEY",
  "mobicard_service_id": "$MOBICARD_SERVICE_ID",
  "mobicard_service_type": "$MOBICARD_SERVICE_TYPE",
  "mobicard_token_id": "$MOBICARD_TOKEN_ID",
  "mobicard_txn_reference": "$MOBICARD_TXN_REFERENCE",
  "mobicard_card_token": "$MOBICARD_CARD_TOKEN"
}
EOF
)

JWT_PAYLOAD=$(echo -n "$PAYLOAD_JSON" | base64 | tr '+/' '-_' | tr -d '=')

# Generate Signature
HEADER_PAYLOAD="$JWT_HEADER.$JWT_PAYLOAD"
JWT_SIGNATURE=$(echo -n "$HEADER_PAYLOAD" | openssl dgst -sha256 -hmac "$MOBICARD_SECRET_KEY" -binary | base64 | tr '+/' '-_' | tr -d '=')

# Create Final JWT
MOBICARD_AUTH_JWT="$JWT_HEADER.$JWT_PAYLOAD.$JWT_SIGNATURE"

# Make API Call
API_URL="https://mobicardsystems.com/api/v1/card_tokenization"

RESPONSE=$(curl -X POST "$API_URL" \
  -H "Content-Type: application/json" \
  -d "{\"mobicard_auth_jwt\":\"$MOBICARD_AUTH_JWT\"}" \
  --silent)

echo "$RESPONSE" | python -m json.tool
Python Implementation
import json
import base64
import hmac
import hashlib
import random
import requests

class MobicardDetokenization:
    def __init__(self, merchant_id, api_key, secret_key):
        self.mobicard_version = "2.0"
        self.mobicard_mode = "LIVE"
        self.mobicard_merchant_id = merchant_id
        self.mobicard_api_key = api_key
        self.mobicard_secret_key = secret_key
        self.mobicard_service_id = "20000"
        self.mobicard_service_type = "DETOKENIZATION"
        
        self.mobicard_token_id = str(random.randint(1000000, 1000000000))
        self.mobicard_txn_reference = str(random.randint(1000000, 1000000000))
    
    def detokenize(self, card_token):
        """Detokenize a card token to retrieve original card details"""
        
        # Create JWT Header
        jwt_header = {"typ": "JWT", "alg": "HS256"}
        encoded_header = base64.urlsafe_b64encode(
            json.dumps(jwt_header).encode()
        ).decode().rstrip('=')
        
        # Create JWT Payload
        jwt_payload = {
            "mobicard_version": self.mobicard_version,
            "mobicard_mode": self.mobicard_mode,
            "mobicard_merchant_id": self.mobicard_merchant_id,
            "mobicard_api_key": self.mobicard_api_key,
            "mobicard_service_id": self.mobicard_service_id,
            "mobicard_service_type": self.mobicard_service_type,
            "mobicard_token_id": self.mobicard_token_id,
            "mobicard_txn_reference": self.mobicard_txn_reference,
            "mobicard_card_token": card_token
        }
        
        encoded_payload = base64.urlsafe_b64encode(
            json.dumps(jwt_payload).encode()
        ).decode().rstrip('=')
        
        # Generate Signature
        header_payload = f"{encoded_header}.{encoded_payload}"
        signature = hmac.new(
            self.mobicard_secret_key.encode(),
            header_payload.encode(),
            hashlib.sha256
        ).digest()
        encoded_signature = base64.urlsafe_b64encode(signature).decode().rstrip('=')
        
        jwt_token = f"{encoded_header}.{encoded_payload}.{encoded_signature}"
        
        # Make API Call
        url = "https://mobicardsystems.com/api/v1/card_tokenization"
        payload = {"mobicard_auth_jwt": jwt_token}
        
        try:
            response = requests.post(url, json=payload, verify=False, timeout=30)
            response_data = response.json()
            
            if response_data.get('status') == 'SUCCESS':
                result = {
                    'status': 'SUCCESS',
                    'card_number': response_data['card_information']['card_number'],
                    'card_number_masked': response_data['card_information']['card_number_masked'],
                    'card_expiry_date': response_data['card_information']['card_expiry_date'],
                    'card_token': response_data['card_information']['card_token'],
                    'single_use_token_flag': response_data.get('mobicard_single_use_token_flag', '0'),
                    'raw_response': response_data
                }
                
                # Check if new token was generated (single-use token)
                if result['single_use_token_flag'] == '1':
                    result['new_token_generated'] = True
                    result['message'] = "New token generated. Update your database."
                
                return result
            else:
                return {
                    'status': 'ERROR',
                    'status_code': response_data.get('status_code'),
                    'status_message': response_data.get('status_message')
                }
                
        except Exception as e:
            return {'status': 'ERROR', 'error_message': str(e)}

# Usage
detokenizer = MobicardDetokenization(
    merchant_id="4",
    api_key="YmJkOGY0OTZhMTU2ZjVjYTIyYzFhZGQyOWRiMmZjMmE2ZWU3NGIxZWM3ZTBiZSJ9",
    secret_key="NjIwYzEyMDRjNjNjMTdkZTZkMjZhOWNiYjIxNzI2NDQwYzVmNWNiMzRhMzBjYSJ9"
)

# Token from your database
card_token = "tok_mc_3b0da132b39673f01eafb3865ec1a9a56b0712c59a82d3d0807ade74b68cb38b4c559e50817452270c88afa3e0de2c8cd32d8a69ee9f72de8a04c2c4955cdcce"

result = detokenizer.detokenize(card_token)

if result['status'] == 'SUCCESS':
    print(f"Card Number: {result['card_number_masked']}")
    print(f"Expiry Date: {result['card_expiry_date']}")
    
    if result.get('new_token_generated'):
        print(f"New Token: {result['card_token']}")
        print("Update your database with the new token.")
    
    # Use result['card_number'] for payment processing
else:
    print(f"Error: {result.get('status_message')}")
Node JS Implementation
const crypto = require('crypto');
const axios = require('axios');

class MobicardDetokenization {
    constructor(merchantId, apiKey, secretKey) {
        this.mobicardVersion = "2.0";
        this.mobicardMode = "LIVE";
        this.mobicardMerchantId = merchantId;
        this.mobicardApiKey = apiKey;
        this.mobicardSecretKey = secretKey;
        this.mobicardServiceId = "20000";
        this.mobicardServiceType = "DETOKENIZATION";
        
        this.mobicardTokenId = Math.floor(Math.random() * (1000000000 - 1000000 + 1)) + 1000000;
        this.mobicardTxnReference = Math.floor(Math.random() * (1000000000 - 1000000 + 1)) + 1000000;
    }

    generateJWT(cardToken) {
        const jwtHeader = { typ: "JWT", alg: "HS256" };
        const encodedHeader = Buffer.from(JSON.stringify(jwtHeader)).toString('base64url');

        const jwtPayload = {
            mobicard_version: this.mobicardVersion,
            mobicard_mode: this.mobicardMode,
            mobicard_merchant_id: this.mobicardMerchantId,
            mobicard_api_key: this.mobicardApiKey,
            mobicard_service_id: this.mobicardServiceId,
            mobicard_service_type: this.mobicardServiceType,
            mobicard_token_id: this.mobicardTokenId.toString(),
            mobicard_txn_reference: this.mobicardTxnReference.toString(),
            mobicard_card_token: cardToken
        };

        const encodedPayload = Buffer.from(JSON.stringify(jwtPayload)).toString('base64url');

        const headerPayload = `${encodedHeader}.${encodedPayload}`;
        const signature = crypto.createHmac('sha256', this.mobicardSecretKey)
            .update(headerPayload)
            .digest('base64url');

        return `${encodedHeader}.${encodedPayload}.${signature}`;
    }

    async detokenize(cardToken) {
        try {
            const jwtToken = this.generateJWT(cardToken);
            
            const url = "https://mobicardsystems.com/api/v1/card_tokenization";
            const payload = { mobicard_auth_jwt: jwtToken };

            const response = await axios.post(url, payload, {
                httpsAgent: new (require('https').Agent)({ rejectUnauthorized: false })
            });

            const responseData = response.data;

            if (responseData.status === 'SUCCESS') {
                const result = {
                    status: 'SUCCESS',
                    cardNumber: responseData.card_information.card_number,
                    cardNumberMasked: responseData.card_information.card_number_masked,
                    cardExpiryDate: responseData.card_information.card_expiry_date,
                    cardToken: responseData.card_information.card_token,
                    singleUseTokenFlag: responseData.mobicard_single_use_token_flag || '0',
                    rawResponse: responseData
                };

                // Check if new token was generated
                if (result.singleUseTokenFlag === '1') {
                    result.newTokenGenerated = true;
                    result.message = "New token generated. Update your database.";
                }

                return result;
            } else {
                return {
                    status: 'ERROR',
                    statusCode: responseData.status_code,
                    statusMessage: responseData.status_message
                };
            }
        } catch (error) {
            return {
                status: 'ERROR',
                errorMessage: error.message
            };
        }
    }
}

// Usage
async function main() {
    const detokenizer = new MobicardDetokenization(
        "",
        "",
        ""
    );

    // Token from your database
    const cardToken = "tok_mc_3b0da132b39673f01eafb3865ec1a9a56b0712c59a82d3d0807ade74b68cb38b4c559e50817452270c88afa3e0de2c8cd32d8a69ee9f72de8a04c2c4955cdcce";

    const result = await detokenizer.detokenize(cardToken);

    if (result.status === 'SUCCESS') {
        console.log("Detokenization Successful!");
        console.log(`Card Number: ${result.cardNumberMasked}`);
        console.log(`Expiry Date: ${result.cardExpiryDate}`);
        
        if (result.newTokenGenerated) {
            console.log(`New Token: ${result.cardToken}`);
            console.log(result.message);
        }
        
        // Use result.cardNumber for payment processing
    } else {
        console.log(`Error: ${result.statusMessage}`);
    }
}

main();
Java Implementation
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
import java.util.Random;
import java.util.HashMap;
import java.util.Map;

import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class MobicardDetokenization {
    
    private final String mobicardVersion = "2.0";
    private final String mobicardMode = "LIVE";
    private final String mobicardMerchantId;
    private final String mobicardApiKey;
    private final String mobicardSecretKey;
    private final String mobicardServiceId = "20000";
    private final String mobicardServiceType = "DETOKENIZATION";
    
    private final String mobicardTokenId;
    private final String mobicardTxnReference;
    
    private final Gson gson = new Gson();
    
    public MobicardDetokenization(String merchantId, String apiKey, String secretKey) {
        this.mobicardMerchantId = merchantId;
        this.mobicardApiKey = apiKey;
        this.mobicardSecretKey = secretKey;
        
        Random random = new Random();
        this.mobicardTokenId = String.valueOf(random.nextInt(900000000) + 1000000);
        this.mobicardTxnReference = String.valueOf(random.nextInt(900000000) + 1000000);
    }
    
    public String generateJWT(String cardToken) throws Exception {
        
        Map jwtHeader = new HashMap<>();
        jwtHeader.put("typ", "JWT");
        jwtHeader.put("alg", "HS256");
        String encodedHeader = base64UrlEncode(gson.toJson(jwtHeader));
        
        Map jwtPayload = new HashMap<>();
        jwtPayload.put("mobicard_version", mobicardVersion);
        jwtPayload.put("mobicard_mode", mobicardMode);
        jwtPayload.put("mobicard_merchant_id", mobicardMerchantId);
        jwtPayload.put("mobicard_api_key", mobicardApiKey);
        jwtPayload.put("mobicard_service_id", mobicardServiceId);
        jwtPayload.put("mobicard_service_type", mobicardServiceType);
        jwtPayload.put("mobicard_token_id", mobicardTokenId);
        jwtPayload.put("mobicard_txn_reference", mobicardTxnReference);
        jwtPayload.put("mobicard_card_token", cardToken);
        
        String encodedPayload = base64UrlEncode(gson.toJson(jwtPayload));
        
        String headerPayload = encodedHeader + "." + encodedPayload;
        String signature = generateHMAC(headerPayload, mobicardSecretKey);
        
        return encodedHeader + "." + encodedPayload + "." + signature;
    }
    
    public JsonObject detokenize(String cardToken) throws Exception {
        
        String jwtToken = generateJWT(cardToken);
        
        HttpClient client = HttpClient.newHttpClient();
        
        Map requestBody = new HashMap<>();
        requestBody.put("mobicard_auth_jwt", jwtToken);
        
        String jsonBody = gson.toJson(requestBody);
        
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://mobicardsystems.com/api/v1/card_tokenization"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();
        
        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        return gson.fromJson(response.body(), JsonObject.class);
    }
    
    private String base64UrlEncode(String data) {
        return Base64.getUrlEncoder().withoutPadding().encodeToString(data.getBytes());
    }
    
    private String generateHMAC(String data, String key) throws Exception {
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(), "HmacSHA256");
        sha256Hmac.init(secretKey);
        byte[] hmacBytes = sha256Hmac.doFinal(data.getBytes());
        return base64UrlEncode(new String(hmacBytes));
    }
    
    public static void main(String[] args) {
        try {
            MobicardDetokenization detokenizer = new MobicardDetokenization(
                "",
                "",
                ""
            );
            
            // Token from your database
            String cardToken = "tok_mc_3b0da132b39673f01eafb3865ec1a9a56b0712c59a82d3d0807ade74b68cb38b4c559e50817452270c88afa3e0de2c8cd32d8a69ee9f72de8a04c2c4955cdcce";
            
            JsonObject result = detokenizer.detokenize(cardToken);
            
            if (result.has("status")) {
                String status = result.get("status").getAsString();
                
                if ("SUCCESS".equals(status)) {
                    System.out.println("Detokenization Successful!");
                    
                    if (result.has("card_information")) {
                        JsonObject cardInfo = result.getAsJsonObject("card_information");
                        
                        System.out.println("Card Number: " + 
                            cardInfo.get("card_number_masked").getAsString());
                        System.out.println("Expiry Date: " + 
                            cardInfo.get("card_expiry_date").getAsString());
                        
                        // Check if single-use token flag is set
                        if (result.has("mobicard_single_use_token_flag")) {
                            String singleUseFlag = result.get("mobicard_single_use_token_flag").getAsString();
                            if ("1".equals(singleUseFlag)) {
                                System.out.println("New Token Generated: " + 
                                    cardInfo.get("card_token").getAsString());
                                System.out.println("Update your database with the new token.");
                            }
                        }
                        
                        // Use cardInfo.get("card_number").getAsString() for payment processing
                    }
                } else {
                    System.out.println("Detokenization Failed!");
                    if (result.has("status_message")) {
                        System.out.println("Error: " + result.get("status_message").getAsString());
                    }
                }
            }
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Success Response Format

Both Tokenization and Detokenization APIs return the same success response format.

JSON Success Response
{
  "status": "SUCCESS",
  "status_code": "200",
  "status_message": "SUCCESS",
  "mobicard_txn_reference": "998470530",
  "mobicard_token_id": "325026456",
  "mobicard_single_use_token_flag": "0",
  "mobicard_custom_one": "mobicard_custom_one",
  "mobicard_custom_two": "mobicard_custom_two",
  "mobicard_custom_three": "mobicard_custom_three",
  "timestamp": "2026-01-26 13:25:29",
  "card_information": {
    "card_number": "4242424242424242",
    "card_number_masked": "4242********4242",
    "card_expiry_date": "02/28",
    "card_expiry_month": "02",
    "card_expiry_year": "28",
    "card_token": "tok_mc_3b0da132b39673f01eafb3865ec1a9a56b0712c59a82d3d0807ade74b68cb38b4c559e50817452270c88afa3e0de2c8cd32d8a69ee9f72de8a04c2c4955cdcce"
  },
  "addendum_data": "your_custom_data_here_will_be_returned_as_is"
}
Response Fields Explanation:
  • status: Always "SUCCESS" or "FAILED" - use this to determine subsequent actions
  • status_code: HTTP status code (200 for success)
  • card_number_masked: Masked card number for display purposes
  • card_token: Secure token to store instead of actual card data
  • mobicard_single_use_token_flag: "1" if token is single-use, "0" if multi-use
  • addendum_data: Custom data echoed back from request
  • mobicard_custom_one: Custom fields : One, Two & Three may be used to store extra info such as card-holder name etc

Error Response Format

Error responses have a simplified format with only 3 fields of essential information.

Use the "status" field to determine if any API request is successful or not. The value is always either "SUCCESS" or "FAILED".

JSON Error Response
{
  "status": "FAILED",
  "status_code": "400",
  "status_message": "BAD REQUEST"
}

Status Codes Reference

Complete list of status codes returned by the API.

Status Code Status Status Message Interpretation Action Required
200 SUCCESS SUCCESS Process the response data
400 FAILED BAD REQUEST - Invalid parameters or malformed request Check request parameters
429 FAILED TOO MANY REQUESTS - Rate limit exceeded Wait before making more requests
250 FAILED INSUFFICIENT TOKENS - Token account balance insufficient Top up your account
500 FAILED UNAVAILABLE - Server error Try again later or contact support
430 FAILED TIMEOUT - Request timed out Issue new token and retry

API Request Parameters Reference

Complete reference of all request parameters used in the Tokenization API.

Parameter Required Tokenization Detokenization Description Example Value
mobicard_version Yes API version "2.0"
mobicard_mode Yes Environment mode "TEST" or "LIVE"
mobicard_merchant_id Yes Your merchant ID ""
mobicard_api_key Yes Your API key ""
mobicard_secret_key Yes Your secret key ""
mobicard_service_id Yes Service ID "20000"
mobicard_service_type Yes Service type "TOKENIZATION" or "DETOKENIZATION"
mobicard_token_id Yes Unique token identifier String/number
mobicard_txn_reference Yes Your transaction reference String/number
mobicard_single_use_token_flag Tokenization only Single-use token flag "0" or "1"
mobicard_card_number Tokenization only Card number to tokenize "4242424242424242"
mobicard_card_expiry_month Tokenization only Card expiry month (MM) "02"
mobicard_card_expiry_year Tokenization only Card expiry year (YY) "28"
mobicard_card_token Detokenization only Token to detokenize "bbaefff665082af8f3a41fa51853062b..."
mobicard_custom_one No Custom data field 1 Any string
mobicard_custom_two No Custom data field 2 Any string
mobicard_custom_three No Custom data field 3 Any string
mobicard_extra_data No Custom data returned in response Any string

API Response Parameters Reference

Complete reference of all response parameters returned by the API.

The value for the "status" response parameter is always either "SUCCESS" or "FAILED". Use this to determine subsequent actions.

Parameter Always Returned Description Example Value
status Yes Transaction status "SUCCESS" or "FAILED"
status_code Yes HTTP status code "200"
status_message Yes Status description "SUCCESS"
mobicard_txn_reference Yes Your original transaction reference "998470530"
mobicard_token_id Yes Your unique API request id "325026456"
mobicard_single_use_token_flag Yes Single-use token flag from request "0" or "1"
timestamp Yes Response timestamp "2026-01-26 13:25:29"
card_information.card_number Yes Full card number (for Detokenization only in Tokenization response) "4242424242424242"
card_information.card_number_masked Yes Masked card number (for display) "4242********4242"
card_information.card_expiry_date Yes Card expiry in MM/YY format "02/28"
card_information.card_expiry_month Yes Expiry month (2 digits) "02"
card_information.card_expiry_year Yes Expiry year (2 digits) "28"
card_information.card_token Yes Secure card token "bbaefff665082af8f3a41fa51853062b..."
mobicard_custom_one Only when sent in request Custom data field 1 echoed back "mobicard_custom_one"
mobicard_custom_two Only when sent in request Custom data field 2 echoed back "mobicard_custom_two"
mobicard_custom_three Only when sent in request Custom data field 3 echoed back "mobicard_custom_three"
addendum_data Only when sent in request Custom data echoed back from request "your_custom_data_here_will_be_returned_as_is"

Best Practices & PCI Compliance

Tokenization Workflow:
  • Step 1: Collect card details from customer (on secure, PCI-compliant form)
  • Step 2: Call Tokenization API with card details
  • Step 3: Store only the returned token and masked card number in your database
  • Step 4: When processing payment, call Detokenization API with stored token
  • Step 5: Use the returned card details for payment processing
  • Step 6: Never store actual card details in your systems
Security Considerations:
  • Store your 'api_key' and 'secret_key' in your .env file and never expose publicly
  • Implement proper PCI DSS compliance for card data collection forms
  • Use HTTPS for all API calls
  • Validate all responses on server-side
  • Implement rate limiting on your end
  • Log all tokenization/detokenization attempts for audit
  • Use single-use tokens for higher security requirements
PCI Compliance Benefits:
  • Reduced Scope: By storing tokens instead of card data, you significantly reduce your PCI DSS compliance scope
  • Reduced Risk: Tokens have no value if stolen, unlike actual card data
  • Simplified Audits: Fewer systems in scope means simpler and cheaper PCI audits
  • Flexible Storage: Tokens can be stored in databases, logs, and analytics without PCI restrictions
  • Portability: Tokens can be used across multiple systems without exposing card data
Implementation Tips:
  • Implement retry logic with exponential backoff for failed API calls
  • Cache successful token responses where appropriate
  • Monitor API usage and set up alerts for unusual patterns
  • Implement token expiration and renewal policies

Frequently Asked Questions

Q: What is the difference between single-use and multi-use tokens?

A: Single-use tokens (mobicard_single_use_token_flag = "1") are regenerated after each detokenization. Multi-use tokens can be detokenized multiple times without changing.

Q: How do I handle token expiration?

A: Tokens don't expire, but you should implement your own token lifecycle management. Consider re-tokenizing cards periodically or when card details are updated.

Q: Can I tokenize cards from different payment networks?

A: Yes, the API supports all major card networks (Visa, Mastercard, Amex, Discover, etc.) as long as the card number passes Luhn validation.

Q: What happens if I lose a token?

A: Without the token, you cannot retrieve the original card data. Always ensure token storage is redundant and backed up. Consider storing tokens in multiple secure locations.

Q: Is there a limit to how many tokens I can create?

A: No. Token limits are based on your Token account balance. Check your account dashboard or contact support for any specific limits.

Q: Can I search for a token by card number?

A: No, for security reasons, you cannot search or retrieve tokens by card number. You must store the association between tokens and cards in your own system.