Skip to documentation
SparkGlimDeveloper
AI integration hub
SparkGlimSparkGlim Developer
Search all documentation

Try a topic in your language or an exact API path.

    Documentation navigation

    API reference

    Start vote checkout

    Validates campaign and nominee, initializes the existing vote payment and reuses the durable operation on retries; the server records completed votes.

    POSThttps://api.sparkglim.net/api/white-label/v1/votes/initialize

    Access model

    Access model
    Server-side Organization HMAC
    Required scope
    payments:write
    Documented availability
    Implemented in source

    Availability is verified from source, not a live production guarantee.

    Private signing stays on your server. API Version 1 uses signature format v2; it is not API v2.

    Headers

    NameTypeValidation
    x-white-label-domainRequired

    Verified website hostname used to resolve the approved organization account and bind this request.

    		stringValidation: verified HTTPS hostname.
    x-white-label-key-idRequired

    Identifier extracted from the single issued Private Key value; never send its secret in this header.

    		stringValidation: issued private key internal identifier.
    x-white-label-signature-versionRequired

    Selects the domain-bound signing format; API routes remain Version 1.

    		stringValidation: 2.
    x-white-label-timestampRequired

    Request signing time in milliseconds, checked against the server clock to reject stale requests.

    		stringValidation: 13 digit milliseconds; within five minutes.
    x-white-label-nonceRequired

    Fresh random signing value recorded by the server to reject replay of a signed request.

    		stringValidation: fresh 16–128 [A-Za-z0-9_-].
    x-white-label-signatureRequired

    HMAC-SHA256 of the canonical domain, idempotency key, campaign credential, timestamp, nonce, method, path, sorted query and exact body hash.

    		stringValidation: lowercase hexadecimal HMAC-SHA256.
    x-white-label-campaign-keyOptional

    Optional complete Campaign Key that narrows a private request to the same authorized campaign.

    		stringValidation: complete optional scoped keyId:secret.
    X-Idempotency-KeyRequired

    Stable business-operation identity reused on retries with unchanged request details; different details under the same key are rejected.

    		stringValidation: 16–128 [A-Za-z0-9_-].

    Request

    NameTypeValidation
    campaignIdRequired

    Existing campaign record within the caller’s account and any narrower campaign credential.

    		stringValidation: UUID.
    participantIdRequired

    The nominee selected within this campaign; approval and campaign rules are checked by the server.

    		stringValidation: UUID.
    voteCountRequired

    Number of votes requested for the selected nominee; SparkGlim Server determines the valid price and records completed votes.

    		integerValidation: 1–100.
    phoneNumberRequired

    Participant contact phone; required payment channels and campaign rules may require a valid international number.

    		stringValidation: 8–32.
    callbackUrlRequired

    Return destination accepted by the existing integration contract; never proof that a payment succeeded.

    		stringValidation: URL.
    emailOptional

    Contact email used by the configured campaign or account workflow; never a credential granting access by itself.

    		string|nullValidation: email.
    channelOptional

    Delivery or integration channel supported by this operation and the account’s enabled configuration.

    		enumValidation: web | ussd | telegram | whatsapp.
    payment_channelOptional

    Optional channel preference; only methods enabled for the real selling country, currency and merchant may be used.

    		enumValidation: enabled checkout method.
    metadataOptional

    Additional JSON metadata accepted by the documented schema; it never overrides authorization, prices or account ownership.

    		objectValidation: JSON object.

    Request

    Examples describe the contract and are not executed. Use authorized test records; never paste a real secret into these pages.

    POST /api/white-label/v1/votes/initialize
    http
    POST /api/white-label/v1/votes/initialize HTTP/1.1
Host: api.sparkglim.net
x-white-label-domain: events.example.com
x-white-label-key-id: <ISSUED_KEY_ID>
x-white-label-signature-version: 2
x-white-label-timestamp: <FRESH_MILLISECONDS>
x-white-label-nonce: <FRESH_SIGNING_NONCE>
x-white-label-signature: <SERVER_GENERATED_SIGNATURE>
X-Idempotency-Key: example_stable_operation_0001
Content-Type: application/json

{
  "campaignId": "11111111-1111-4111-8111-111111111111",
  "participantId": "33333333-3333-4333-8333-333333333333",
  "voteCount": 1,
  "phoneNumber": "+233200000000",
  "callbackUrl": "https://events.example.com/payment-return"
}

    Response

    Success response · HTTP 200
    json
    {
  "success": true,
  "data": {
    "authorization_url": "https://checkout.sparkglim.net/gh/<SERVER_REFERENCE>",
    "reference": "<SERVER_REFERENCE>"
  },
  "requestId": "wlapi_example"
}
    Error response · HTTP 400
    json
    {
  "success": false,
  "error": "<ERROR_MESSAGE>",
  "requestId": "wlapi_example"
}

    Validation, permissions, unavailable records and temporary service failures use the handler’s HTTP status and error payload.

    Limits & retries

    Organization limiter: 120 requests per key and 300 per IP per window; honor Retry-After and X-RateLimit headers.

    Source compatibility

    Authorized operations require account-specific testing.

    • server/src/api/router.ts
    • server/src/api/routes/white-label.ts
    • server/src/white-label/auth.ts
    • server/src/white-label/schemas.ts
    • server/src/white-label/organization-service.ts
    • server/src/white-label/service.ts

    Continue building