Beginner10 min read

Quickstart

From zero to your first successful charge, end to end.

Your first hands-on steps. Clicking through a dashboard, not writing code.

This is the shortest path from a fresh account to a completed charge. It assumes you have already created an account and provisioned an app with the CaaS API enabled.

Not there yet?

Start with Create a developer account and Provision your app. Both are click-through guides with no code.

  1. Collect your API Key and Secret

    Open your approved application in the Digimart portal. The API Key identifies your app publicly; the API Secret must never leave your server.
    # Never commit this file.
DIGIMART_API_KEY=your_api_key_here
DIGIMART_API_SECRET=your_api_secret_here
DIGIMART_REDIRECT_URL=https://yourapp.com/payment/return

  2. Build the signature

    Join your API Key, the current timestamp and your API Secret with pipe characters, then hash the result with SHA-512. For a one-time charge, append the amount as a fourth field.
    # Subscription
apiKey | requestTime | apiSecret

# One-time charge (CaaS), amount is included
apiKey | requestTime | apiSecret | amount

# Concrete example (no spaces around the pipes):
myApiKey123|2024-08-08T12:00:00Z|mySecretKey456|50

  3. Redirect the customer

    Assemble the authorize URL and send the customer's browser to it. Do this from your server so the secret never reaches the browser.
    import { createHash, randomInt } from "node:crypto";
import express from "express";

const app = express();

app.get("/buy", (req, res) => {
  const apiKey      = process.env.DIGIMART_API_KEY;
  const apiSecret   = process.env.DIGIMART_API_SECRET;
  const amount      = "50";

  // Unique 15 digits, every single time.
  const requestId   = String(randomInt(1e14, 1e15));
  const requestTime = new Date().toISOString();

  const signature = createHash("sha512")
    .update(`${apiKey}|${requestTime}|${apiSecret}|${amount}`)
    .digest("hex");

  const url = new URL(
    "https://user.digimart.store/sdk/subscription/caas-authorize"
  );
  url.search = new URLSearchParams({
    apiKey,
    requestId,
    requestTime,
    signature,
    amount,
    redirectUrl: process.env.DIGIMART_REDIRECT_URL,
  }).toString();

  // Store requestId against this order before you leave.
  res.redirect(url.toString());
});

  4. Digimart handles the customer

    Your work pauses here. Digimart captures the mobile number (automatically, if header enrichment is on), sends the OTP, shows the confirmation screen, handles wrong codes and cancellations, and performs the charge.

  5. Read the redirect response

    The customer lands back on your redirect URL carrying the outcome: a subscription status, a masked subscriber ID, and the request ID you sent.
    {
  "subscriptionStatus": "CHARGED",
  "subscriberId": "tel:NTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5nbGFsaW5r",
  "requestId": "202407081033549",
  "statusCode": "S1000"
}

  6. Wait for the notification before delivering

    Digimart also calls your notification URL server-to-server with the transaction detail. Treat that callback, not the browser redirect, as the fact that money moved.

What usually breaks first

  • E1002, invalid signature. Almost always a mismatch between the requestTime you hashed and the one you sent. Build the timestamp once, into a variable, and reuse it.
  • E1005, duplicate requestId. You reused an ID, often by retrying a failed request with the same one. Generate a fresh one per attempt.
  • E3009, insufficient balance. Not a bug. Your customer simply has no credit. This will be your most frequent failure in production, so design a kind screen for it.
Signature deep diveAll error codes