Initialize Transaction

Endpoint

POST /api/v1/transactions/initialize

Important behavior

This endpoint creates a Clive transaction record only (legacy two-step flow).

• It does not create a Stripe PaymentIntent.
• It does not set Stripe statement_descriptor_suffix.
• You must call /transactions/attach-intent after creating/obtaining a PaymentIntent ID.
• For the recommended one-call flow, use /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	init-EZ12345-v1

Request body

{
  "partner_id": "ECHEZONA001",
  "client_id": "AIRPEACE001",
  "amount": 750,
  "currency": "USD",
  "echezona_reference": "EZ12345",
  "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
echezona_reference	string	Yes	Partner-generated immutable transaction reference
meta	object	No	Optional JSON object stored with the transaction and echoed back in outbound partner webhooks

Success response

201 Created

{
  "clive_tx_id": "CLVTX_1739378102312_420",
  "status": "initialized"
}

Error responses

400 Validation error

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "fieldErrors": {
      "amount": ["Number must be greater than 0"]
    },
    "formErrors": []
  }
}

401 / 403 / 404 domain security errors

Possible code values:

• API_KEY_INVALID
• HMAC_INVALID
• PARTNER_NOT_FOUND
• PARTNER_NOT_ACTIVE
• KYC_NOT_APPROVED
• CLIENT_NOT_FOUND
• CLIENT_NOT_ACTIVE

cURL example

BODY='{"partner_id":"ECHEZONA001","client_id":"AIRPEACE001","amount":750,"currency":"USD","echezona_reference":"EZ12345","meta":{"order_id":"ORD-1001","cart_id":"CART-2002"}}'
SIG='replace-with-sha256-hmac'

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