Provider: Ingesting Vouchers via API

Overview

The Provider API allows you to submit batches of voucher codes to FinWallet. Vouchers are ingested asynchronously — your batch is queued and processed in the background. You can monitor ingest status from the Provider Portal.

Authentication

Every API request requires two security headers:

• Authorization: Bearer <your-api-token>
• X-Provider-Signature: HMAC-SHA256 signature of the request body, using your signing secret

Requests missing or failing signature verification are rejected with a 401 Unauthorized response and logged to the audit trail.

Generating the HMAC Signature

Compute the signature as:

HMAC-SHA256( rawRequestBody, signingSecret )

Encode the result as a lowercase hexadecimal string and pass it in the X-Provider-Signature header.

Example (PHP)

$signature = hash_hmac('sha256', $rawBody, $signingSecret);

Example (Python)

import hmac, hashlib
signature = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()

Ingest Endpoint

POST /api/v1/vouchers/ingest

Request Body

{
  "provider_reference": "EXT-VODCO-20260601-001",
  "vouchers": [
    {
      "code": "VCHR-ABCD-1234",
      "denomination": 50.00,
      "currency": "ZAR",
      "expires_at": "2026-12-31T23:59:59Z",
      "metadata": { "campaign": "Winter2026" }
    }
  ]
}

Fields

• provider_reference — your unique batch identifier. Must match your assigned prefix (e.g. EXT-VODCO-).
• code — the voucher code string. Must be unique across all providers.
• denomination — the face value of the voucher.
• currency — ISO 4217 currency code matching the target programme.
• expires_at — ISO 8601 UTC datetime. Required.
• metadata — optional key-value pairs for your own tracking purposes.

Partial Failures

The ingest API processes batches in a fault-tolerant way. If individual vouchers in a batch are invalid (e.g. duplicate code, missing field), those records are skipped and logged to the audit trail as ingest_failed. The rest of the batch continues processing.

The response body includes a summary of accepted and rejected codes so you can identify and resubmit failed records.

Idempotency

The ingest endpoint is idempotent on the provider_reference. Submitting the same provider_reference within 24 hours returns the original response without re-processing. Use a unique reference per batch.

Cashout Callback

If your programme supports cashout, FinWallet can notify your system when a cashout completes or fails via a signed callback:

POST /api/v1/cashout/callback

The callback payload is signed with the same HMAC-SHA256 mechanism. Verify the X-Provider-Signature header on every incoming callback before processing.