Skip to main content

NPM SDK Integration

Choose your integration mode​

Clive supports both options:

  1. Direct API calls (you control signing/headers)
  2. @clive-alliance/partner-sdk (Clive SDK handles signing, idempotency defaults, and request wiring)

If your team prefers speed and fewer auth mistakes, use the SDK.

Install​

npm install @clive-alliance/partner-sdk

Initialize the SDK client​

import { CliveClient } from "@clive-alliance/partner-sdk";

const clive = new CliveClient({
  baseUrl: process.env.CLIVE_API_BASE_URL,
  apiKey: process.env.CLIVE_API_KEY!,
  hmacSecret: process.env.CLIVE_HMAC_SECRET!
});

Transaction flow with SDK​

const initialized = await clive.initializeTransaction({
  partner_id: "ECHEZONA001",
  client_id: "AIRPEACE001",
  amount: 750,
  currency: "USD",
  echezona_reference: "EZ12345"
});

// Create PaymentIntent using your Stripe secret key/server
const paymentIntentId = "pi_3Qxx...";

const attached = await clive.attachPaymentIntent({
  clive_tx_id: initialized.clive_tx_id,
  stripe_payment_intent_id: paymentIntentId
});

The SDK signs and sends Clive API requests.
In the production flow, your backend still creates Stripe PaymentIntents and must set statement_descriptor_suffix.

Sandbox-web style server route​

Use one backend route to return both client_secret and clive_tx_id to your frontend:

app.post("/checkout-intent", async (req, res) => {
  const { amount, email } = req.body;

  const initialized = await clive.initializeTransaction({
    partner_id: "ECHEZONA001",
    client_id: "AIRPEACE001",
    amount,
    currency: "USD",
    echezona_reference: `EZ-${Date.now()}`
  });

  const pi = await stripe.paymentIntents.create({
    amount: Math.round(amount * 100),
    currency: "usd",
    receipt_email: email,
    statement_descriptor_suffix: "AIRPEACE",
    automatic_payment_methods: { enabled: true },
    metadata: {
      clive_tx_id: initialized.clive_tx_id,
      partner_id: "ECHEZONA001",
      client_id: "AIRPEACE001"
    }
  });

  await clive.attachPaymentIntent({
    clive_tx_id: initialized.clive_tx_id,
    stripe_payment_intent_id: pi.id
  });

  res.json({
    clive_tx_id: initialized.clive_tx_id,
    client_secret: pi.client_secret
  });
});

Helpful SDK utilities​

  • CliveClient.createIdempotencyKey(prefix, reference)
  • CliveClient.createRandomIdempotencyKey(prefix)
  • CliveClient.signPayload(rawBody, hmacSecret)
  • createSignedRequestHeaders(...) for teams that still send raw fetch requests

Suffix compliance checklist​

  • Keep suffix deterministic by merchant/client identity.
  • Keep suffix short and human-readable (Stripe statement constraints apply).
  • Store the suffix with clive_tx_id and stripe_payment_intent_id in your DB.

Direct API alternative (no SDK)​

If you prefer direct calls, continue with: