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

    Server payment reconciliation

    Server-side reconciliation checks the opaque receipt against this account/domain/reference before using the existing authoritative payment service. Never call from a public browser.

    POSThttps://api.sparkglim.net/api/white-label/v1/payments/verify

    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.

    Request

    NameTypeValidation
    referenceRequired

    Opaque transaction reference returned by the original server initialization; retain it unchanged.

    		stringValidation: 1–200.
    receiptTokenRequired

    Opaque receipt from ticket initialization, required with the matching reference for server-side reconciliation.

    		stringValidation: UUID bound to this domain/account/payment.

    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/verify
    http
    POST /api/white-label/v1/payments/verify 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>
Content-Type: application/json

{
  "reference": "<SERVER_REFERENCE>",
  "receiptToken": "44444444-4444-4444-8444-444444444444"
}

    Response

    Success response · HTTP 200
    json
    {
  "success": true,
  "data": {
    "reference": "<SERVER_REFERENCE>",
    "status": "pending"
  },
  "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