Skip to main content
Execution-Rail Partners

Become a Vektrum
Execution-Rail Partner

Vektrum is the conditional authorization layer for construction draws. When all conditions pass, we fire a signed authorization signal to your endpoint. You execute the payment on your licensed rail. You retain full control of fund movement — Vektrum provides the governance, audit trail, and release signal.

How it works

Three steps from authorization to execution.

1

Funder authorizes a draw in Vektrum

The funder triggers a release for a specific milestone. Vektrum's 10-condition gate evaluates all conditions atomically — including AI draw review, lien waiver status, contract validity, and funded balance. If any condition fails, the release is blocked. If all 10 conditions pass, the release is authorized.

2

Vektrum fires a signed webhook to your endpoint

Vektrum immediately fires a signed release.authorized webhook to the endpoint you registered during partner setup. The payload includes the release ID, deal details, milestone details, amounts, and an idempotency key. The signature is an HMAC-SHA256 of the timestamp and raw body, using your partner-specific signing secret.

3

You execute and confirm via API

Your licensed system executes the payment on your rail — wire, ACH, check, or your treasury infrastructure. Once executed, you call POST /api/partner/releases/:id/confirm with the payment reference and method. Vektrum records the confirmation and settles the deal ledger. If execution fails, call POST /api/partner/releases/:id/fail.

Webhook payload

The release.authorized event

When all 10 conditions pass, Vektrum fires this payload to your registered webhook endpoint. All monetary amounts are in USD as a decimal number. The idempotency_key is a UUID stable for the lifetime of the release — safe to use as a deduplication key on retries.

{
  "event": "release.authorized",
  "api_version": "2026-04-25",
  "release_id": "uuid",
  "deal_id": "uuid",
  "deal_title": "123 Main St Construction",
  "milestone_id": "uuid",
  "milestone_title": "Foundation Complete",
  "amount": 50000,
  "fee_amount": 750,
  "retainage_amount": 5000,
  "net_to_contractor": 44250,
  "contractor_id": "uuid",
  "funder_id": "uuid",
  "authorized_at": "2026-04-25T14:00:00Z",
  "authorized_by": "uuid",
  "idempotency_key": "uuid"
}

Important: Always verify the webhook signature before processing. A request without a valid X-Vektrum-Signature header must be rejected. See the signature verification section below.

Signature verification

Verify every webhook before processing.

Every outbound webhook is signed: X-Vektrum-Signature: t=<unix_ts>,sha256=HMAC-SHA256(<ts>.<body>, secret). Enforce a 5-minute tolerance window on the timestamp to prevent replay attacks.

TypeScript

import crypto from 'crypto'

function verifyVektrumSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
  toleranceSeconds = 300
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  )
  const ts = parts['t']
  const received = parts['sha256']
  if (!ts || !received) return false

  const age = Math.floor(Date.now() / 1000) - parseInt(ts, 10)
  if (Math.abs(age) > toleranceSeconds) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(received),
    Buffer.from(expected)
  )
}

Python

import hmac, hashlib, time

def verify_vektrum_signature(
    raw_body: str,
    signature_header: str,
    secret: str,
    tolerance: int = 300
) -> bool:
    parts = dict(
        p.split("=", 1)
        for p in signature_header.split(",")
    )
    ts = parts.get("t")
    received = parts.get("sha256")
    if not ts or not received:
        return False
    if abs(time.time() - int(ts)) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{ts}.{raw_body}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(received, expected)

Partner API endpoints

Three endpoints. All authenticated with your API key.

Authenticate all requests with Authorization: Bearer <your_api_key>. API keys are prefixed vkp_ and 68 characters total.

GET/api/partner/releases/:id

Fetch the current state of a release. Use this to poll for pending releases if you did not receive the webhook, or to confirm the release is still in pending state before executing payment.

Response 200:

{
  "release": {
    "id": "uuid",
    "deal_id": "uuid",
    "deal_title": "string",
    "milestone_id": "uuid",
    "milestone_title": "string",
    "amount": 50000,
    "fee_amount": 750,
    "retainage_amount": 5000,
    "net_to_contractor": 44250,
    "execution_status": "pending | confirmed | failed",
    "execution_rail": "external_manual",
    "execution_notes": "string | null",
    "authorized_at": "ISO 8601"
  }
}
403Deal not associated with your partner account
404Release not found
POST/api/partner/releases/:id/confirm

Record that you have executed the authorized payment. Vektrum settles the deal ledger, inserts the billing record, and marks the release confirmed. Safe to retry — already-confirmed releases return 200 with alreadyConfirmed: true.

Request body:

{
  "payment_method": "wire | ach | check | other",
  "payment_reference": "string",
  "executed_at": "ISO 8601 (optional)",
  "notes": "string (optional)",
  "proof_document_id": "uuid (optional)"
}

Response 200:

{
  "success": true,
  "releaseId": "uuid",
  "execution_status": "confirmed",
  "alreadyConfirmed": true
}
409State changed by a concurrent request
POST/api/partner/releases/:id/fail

Record that execution failed on your rail. Vektrum frees the reservation and records the reason. The authorization signal has been voided. Admin review is required to re-authorize.

Request body:

{
  "reason": "string (min 10 chars)"
}

Response 200:

{
  "success": true,
  "releaseId": "uuid",
  "execution_status": "failed",
  "reservation_cancelled": true
}

Get started

Ready to integrate?

Contact us to receive your partner API key and webhook signing secret. Credentials are issued once and shown only to the issuing admin. Once you have your credentials, you can begin testing against sandbox releases immediately.

API key + secret

Issued by Vektrum admin. Shown once, stored as SHA-256 hash. Rotatable on demand.

Sandbox testing

Test confirm and fail endpoints with sandbox releases before going live.

Audit trail

Every confirm and fail call is logged in the hash-chained audit log.

Contact partners@vektrum.io