Skip to main content

Get Started

Integration prerequisites​

Before integrating, make sure you have:

  • partner_id (for example: ECHEZONA001)
  • one or more valid client_id values for merchants under the partner (provisioned by Clive admin, or registered by you via POST /clients with a partner-scoped API key)
  • shared API security values:
    • x-api-key
    • HMAC shared secret (for x-clive-hmac)
  • Stripe publishable key consumption on your frontend (Clive creates intents server-side)
  • public HTTPS webhook URL to receive signed Clive status callbacks

Integration options​

You can integrate in either mode:

  • Raw API mode: call Clive endpoints directly and compute x-clive-hmac yourself.
  • SDK mode: install @clive-alliance/partner-sdk so request signing, auth headers, and idempotency defaults are handled for you.
  • SDK advanced widget mode: use createClivePaymentsWidget for a hosted-like, multi-processor checkout UI with external success/error callbacks.

See: NPM SDK Integration

Widget v2 trust boundary (must follow)​

When using the advanced widget:

  • Allowed direct browser -> Clive call: branding packet (GET /branding/packet)
  • Required browser -> backend -> Clive call: checkout initialization (POST /transactions/checkout-intent-v2)

Your backend must sign Clive ingestion requests with:

  • x-api-key
  • x-clive-hmac
  • idempotency-key

Keep these server-only:

  • CLIVE_API_KEY
  • CLIVE_HMAC_SECRET
  • processor secret keys

Fastest path (same pattern as sandbox-web)​

If you want the easiest production-safe flow, copy this pattern:

  1. Your backend calls Clive POST /transactions/checkout-intent
  2. Clive creates Stripe PaymentIntent and returns client_secret
  3. Your frontend renders Stripe Payment Element and confirms payment
  4. Clive finalizes status and notifies your webhook

Frontend engineer implementation note​

For processor checkout pages, treat these as required:

  • Use the returned stripe_publishable_key to initialize Stripe.
  • Use the returned client_secret in <Elements options={{ clientSecret }}>.
  • Include <PaymentElement /> on the checkout form.
  • On submit, call elements.submit() before stripe.confirmPayment(...).
  • Reconcile using clive_tx_id after confirmation; do not finalize solely from frontend success callback.

Stripe ownership boundary (important)​

In the recommended production flow, Clive creates and owns the Stripe PaymentIntent through /transactions/checkout-intent.

That means your backend is responsible for:

  • calling Clive with signed request headers
  • passing a deterministic statement_descriptor_suffix for statement clarity
  • persisting Clive/Stripe identifiers returned by checkout-intent

Required records to persist on your side​

For every checkout attempt, store:

  • clive_tx_id
  • stripe_payment_intent_id
  • statement_descriptor_suffix
  • your immutable business reference (echezona_reference)
  • idempotency key used for checkout-intent

Backend endpoint example​

// POST /checkout-intent
const checkout = await clive.createCheckoutIntent({
  partner_id: "ECHEZONA001",
  client_id: "AIRPEACE001",
  amount: 750,
  currency: "USD",
  email: "buyer@example.com",
  statement_descriptor_suffix: "AIRPEACE",
  echezona_reference: `EZ-${Date.now()}`
});

return {
  clive_tx_id: checkout.clive_tx_id,
  client_secret: checkout.client_secret,
  stripe_payment_intent_id: checkout.stripe_payment_intent_id,
  stripe_publishable_key: checkout.stripe_publishable_key
};

Frontend example (Stripe Elements)​

const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: window.location.href },
  redirect: "if_required"
});

if (!error) {
  // refresh tx status from your backend/Clive read endpoint
}

Environment variables (partner side)​

CLIVE_API_BASE_URL=https://<your-host>/api/v1
CLIVE_API_KEY=<your-partner-api-key>
CLIVE_HMAC_SECRET=<shared-hmac-secret>

Required headers by endpoint type​

Endpoint typeRequired headers
Partner transaction ingestionx-api-key, x-clive-hmac, idempotency-key
Partner client registration (POST /clients)x-api-key, x-clive-hmac, idempotency-key
Partner read endpoints (GET /transactions, GET /clients, …)x-api-key
Admin endpointsAuthorization: Bearer <jwt>

Generate HMAC signature​

x-clive-hmac is the SHA-256 HMAC of the exact raw request body.

node -e "const c=require('crypto');const body='{\"partner_id\":\"ECHEZONA001\",\"client_id\":\"AIRPEACE001\",\"amount\":750,\"currency\":\"USD\",\"echezona_reference\":\"EZ12345\"}';console.log(c.createHmac('sha256', process.env.CLIVE_HMAC_SECRET).update(body).digest('hex'))"

Idempotency expectations​

  • Use a unique idempotency-key per logical checkout-intent action.
  • If you retry with the same key, Clive returns the original payload with idempotentReplay: true.
  • Keep keys stable across network retries from your app or gateway.

First successful flow checklist​

  1. Call POST /transactions/checkout-intent (include statement_descriptor_suffix)
  2. Render Stripe Payment Element with returned client_secret
  3. Complete payment in frontend
  4. Consume Clive webhook updates on your webhook URL

Next: USD Integration Flow