API reference

Start ticket checkout

Validates organization ticketing access, selected ticket and buyer information, then creates or reuses central checkout with a receipt bound to this domain.

POSThttps://api.sparkglim.net/api/white-label/v1/payments/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

Name	Type	Validation
`x-white-label-domain`Required Verified website hostname used to resolve the approved organization account and bind this request.	`string`	Validation: verified HTTPS hostname.
`x-white-label-key-id`Required Identifier extracted from the single issued Private Key value; never send its secret in this header.	`string`	Validation: issued private key internal identifier.
`x-white-label-signature-version`Required Selects the domain-bound signing format; API routes remain Version 1.	`string`	Validation: 2.
`x-white-label-timestamp`Required Request signing time in milliseconds, checked against the server clock to reject stale requests.	`string`	Validation: 13 digit milliseconds; within five minutes.
`x-white-label-nonce`Required Fresh random signing value recorded by the server to reject replay of a signed request.	`string`	Validation: fresh 16–128 [A-Za-z0-9_-].
`x-white-label-signature`Required HMAC-SHA256 of the canonical domain, idempotency key, campaign credential, timestamp, nonce, method, path, sorted query and exact body hash.	`string`	Validation: lowercase hexadecimal HMAC-SHA256.
`x-white-label-campaign-key`Optional Optional complete Campaign Key that narrows a private request to the same authorized campaign.	`string`	Validation: complete optional scoped keyId:secret.
`X-Idempotency-Key`Required Stable business-operation identity reused on retries with unchanged request details; different details under the same key are rejected.	`string`	Validation: 16–128 [A-Za-z0-9_-].

Request

Name	Type	Validation
`campaign_id`Required Existing campaign record within the caller’s account and any narrower campaign credential.	`string`	Validation: UUID.
`ticket_id`Required The selected ticket type belonging to the specified campaign; server checks status, capacity and price.	`string`	Validation: UUID.
`quantity`Required Number of tickets requested; inventory and per-person purchase limits remain server-enforced.	`integer`	Validation: 1–100.
`phone_number`Required Participant contact phone; required payment channels and campaign rules may require a valid international number.	`string`	Validation: nonempty valid phone.
`email`Optional Contact email used by the configured campaign or account workflow; never a credential granting access by itself.	`string`	Validation: email.
`discount_code`Optional Existing campaign-specific discount or invitation credential, revalidated by the server before purchasing.	`string`	Validation: trimmed nonempty.
`invite_code`Optional Existing campaign-specific discount or invitation credential, revalidated by the server before purchasing.	`string`	Validation: trimmed nonempty.
`luggage_quantity`Optional Quantity of luggage in an event that actually supports the configured luggage option.	`integer`	Validation: >=0.
`attendee_information`Optional Answers matching the actual campaign-specific fields, required values and supported options.	`object`	Validation: string values matching configured fields.
`payment_channel`Optional Optional channel preference; only methods enabled for the real selling country, currency and merchant may be used.	`enum`	Validation: card \| mobile_money \| apple_pay \| bank_transfer \| crypto; availability is server-controlled.
`network_code`Optional Configured mobile network selection where the chosen payment channel requires it.	`string`	Validation: configured network.
`is_app`Optional Existing caller context used to select Web or User App configuration; it grants no extra permissions.	`boolean`	Validation: client context.
`return_path`Optional Relative return destination on the verified current website after centralized checkout.	`string`	Validation: same verified domain relative path.
`clientIp`Optional Original client IP supplied by an authorized backend; used by existing abuse controls.	`string`	Validation: valid IP.

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/payments/initialize

http

POST /api/white-label/v1/payments/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

{
  "campaign_id": "11111111-1111-4111-8111-111111111111",
  "ticket_id": "22222222-2222-4222-8222-222222222222",
  "quantity": 1,
  "phone_number": "+233200000000",
  "return_path": "/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

Access model

Headers

Request

Request

Response

Limits & retries

Source compatibility

Continue building