Create Checkout Intent

Endpoint

POST /api/v1/transactions/checkout-intent

Authentication and required headers

Header	Required	Example
Content-Type	Yes	application/json
x-api-key	Yes	cp_live_partner_xxx
x-clive-hmac	Yes	40f3...
idempotency-key	Yes	checkout-EZ12345-v1

Request body

{
  "partner_id": "ECHEZONA001",
  "client_id": "AIRPEACE001",
  "amount": 750,
  "currency": "USD",
  "email": "buyer@example.com",
  "echezona_reference": "EZ12345",
  "statement_descriptor_suffix": "AIRPEACE",
  "meta": {
    "order_id": "ORD-1001",
    "cart_id": "CART-2002"
  }
}

Field details

Field	Type	Required	Description
partner_id	string	Yes	Partner identifier provisioned by Clive
client_id	string	Yes	Merchant/client identifier under the partner
amount	number	Yes	Positive transaction amount in major currency units
currency	string(3)	Yes	ISO-4217 currency code (for USD use USD)
email	string	Yes	Buyer email used for Stripe receipt/payment context
echezona_reference	string	Yes	Partner-generated immutable transaction reference
statement_descriptor_suffix	string	No	Optional card statement suffix (1-22 chars, letters/numbers/space/-/_/.)
meta	object	No	Optional JSON object stored on the transaction and replayed in Clive partner webhooks

Success response

201 Created

{
  "clive_tx_id": "CLVTX_1739378102312_420",
  "status": "pending",
  "stripe_payment_intent_id": "pi_3QxYFh2eZvKYlo2CxA8Nt42p",
  "client_secret": "pi_3Qx..._secret_...",
  "stripe_publishable_key": "pk_test_..."
}

Common errors

HTTP	Code	Meaning
400	VALIDATION_ERROR	Invalid body shape/fields
400	IDEMPOTENCY_KEY_MISSING	Missing idempotency key
401	API_KEY_INVALID	Invalid API key
401	HMAC_INVALID	Signature mismatch
403	PARTNER_NOT_ACTIVE	Partner not active
404	CLIENT_NOT_FOUND	Unknown client
500	STRIPE_KEY_MISSING	Clive Stripe secret key missing
500	STRIPE_PUBLISHABLE_MISSING	Clive Stripe publishable key missing

cURL example

BODY='{"partner_id":"ECHEZONA001","client_id":"AIRPEACE001","amount":750,"currency":"USD","email":"buyer@example.com","echezona_reference":"EZ12345","statement_descriptor_suffix":"AIRPEACE","meta":{"order_id":"ORD-1001","cart_id":"CART-2002"}}'
SIG='replace-with-sha256-hmac'

curl -X POST "$CLIVE_API_BASE_URL/transactions/checkout-intent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLIVE_API_KEY" \
  -H "x-clive-hmac: $SIG" \
  -H "idempotency-key: checkout-EZ12345-v1" \
  -d "$BODY"

Notes

• This is the recommended endpoint for new partner integrations.
• Clive internally initializes the transaction and links the created PaymentIntent.
• Use returned client_secret to render/confirm Stripe Payment Element on frontend.

Frontend checkout page usage (Stripe Elements)

After your backend calls this endpoint, return these fields to the page:

• client_secret
• stripe_publishable_key
• clive_tx_id

Then implement checkout page flow:

1. loadStripe(stripe_publishable_key)
2. Render <Elements options={{ clientSecret }}>
3. Render <PaymentElement />
4. On submit: call elements.submit()
5. Confirm: stripe.confirmPayment({ elements, confirmParams: { return_url }, redirect: "if_required" })
6. Reconcile transaction state using clive_tx_id

Minimal example:

const stripePromise = loadStripe(stripePublishableKey);

<Elements stripe={stripePromise} options={{ clientSecret }}>
  <form
    onSubmit={async (e) => {
      e.preventDefault();
      const submitResult = await elements.submit();
      if (submitResult.error) return;

      await stripe.confirmPayment({
        elements,
        confirmParams: { return_url: window.location.href },
        redirect: "if_required"
      });
    }}
  >
    <PaymentElement />
    <button type="submit">Pay now</button>
  </form>
</Elements>