GIFTBANK (1 GB) API integration & FreeByte rewards data export

1. Auth — OTP login & token refresh

POST /api/v1/giftbank/auth/otp_request
Content-Type: application/json
{ "msisdn": "+9053XXXXXXXX", "device_id": "a1b2c3..." }

POST /api/v1/giftbank/auth/otp_verify
{ "msisdn": "+9053XXXXXXXX", "otp": "493210" }
-> 200 { "access_token": "eyJ...", "refresh_token": "rt_...",
         "expires_in": 3600, "user_id": "u_8f21" }

POST /api/v1/giftbank/auth/refresh
Authorization: Bearer <REFRESH>
-> 200 { "access_token": "...", "expires_in": 3600 }

2. FreeByte balance & ledger

GET /api/v1/giftbank/balance
Authorization: Bearer <ACCESS_TOKEN>
-> 200 {
  "user_id": "u_8f21",
  "balance": 12480,
  "pending": 320,
  "lifetime_earned": 58210,
  "lifetime_burned": 45730,
  "currency_unit": "FreeByte"
}

GET /api/v1/giftbank/ledger?from=2026-04-01&to=2026-04-30
                          &source=kazandirio,tosla,games
-> 200 { "items":[
   {"ts":"2026-04-12T18:04:11Z","source":"games",
    "game_id":"g_solitaire","amount":40,"campaign":"PLY_v2"},
   {"ts":"2026-04-15T10:22:03Z","source":"kazandirio",
    "amount":150,"campaign":"pepsi_qr_2026"} ],
  "next_cursor":"c_84a9" }

3. Redemption webhook (HMAC signed)

POST https://your-app.example.com/hooks/giftbank
X-Giftbank-Signature: t=1714560000,v1=ab9c...e1
Content-Type: application/json
{
  "event": "redemption.completed",
  "order_id": "ord_4f81b2",
  "user_id": "u_8f21",
  "sku": "turkcell_5gb_30d",
  "partner": "turkcell",
  "freebyte_cost": 4500,
  "fiat_value_try": 89.90,
  "status": "fulfilled",
  "ts": "2026-05-01T09:14:22Z"
}

# Verify in Python
import hmac, hashlib
expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, sig_v1)

Compliance & privacy

Because GIFTBANK's primary user base is in Turkey, the integration is designed against the Turkish Personal Data Protection Law (KVKK, Law No. 6698 of 2016) and against the GDPR for any EU-resident accruing FreeByte through partner promotions. Consent is captured before any export channel is opened, the minimum field set is pulled, and erasure requests propagate to the downstream warehouse within the statutory window.

• VERBIS-aware data controller mapping for Turkish deployments
• Explicit opt-in record for marketing channels (email, SMS, push)
• Data-minimisation profile: never pull raw OTPs, never persist refresh tokens server-side beyond TTL
• Reference: KVKK overview on Wikipedia and the official KVKK authority guidance

Data flow / architecture

A typical pipeline has four nodes and stays under one second of end-to-end latency for balance reads:

1. Client — your back office or mobile SDK.
2. Integration gateway — our Python / Node.js layer that brokers auth tokens, throttles, and signs webhooks.
3. Storage — Postgres for the ledger, S3 / object storage for redemption export files.
4. Downstream — BI (Metabase, Looker), CRM (Braze, Iterable), or your data warehouse via Airbyte / Fivetran connectors.

Deliverables checklist

• OpenAPI 3.1 specification for every endpoint above
• Protocol & auth flow report (OTP, token rotation, anti-replay)
• Runnable source in Python (FastAPI) and Node.js (Express)
• Webhook signer and reference verification snippets
• Postman collection plus pytest / vitest suites
• KVKK + GDPR data-handling notes and DPIA template

Engagement workflow

1. Scope confirmation: which surfaces (balance, ledger, redemption, catalog).
2. Protocol analysis & API design — 2 to 5 business days.
3. Build & internal validation — 3 to 8 business days.
4. Docs, samples and test cases — 1 to 2 business days.
5. Typical first delivery: 5 to 15 business days; partner onboarding may extend.

About us

OpenFinance Lab is an independent studio focused on mobile-app protocol analysis and OpenData / OpenFinance / OpenBanking integrations. Our engineers come from telco billing, payment gateway and loyalty-platform backgrounds, and we ship end-to-end stacks under the data-protection regimes that matter — KVKK in Turkey, GDPR across the EU, PSD2 where account information services are involved.

• Loyalty ecosystems, telco data top-ups, FMCG promotion engines
• API gateway hardening, HMAC signing, anti-replay
• Custom Python / Node.js / Go SDKs with first-class typing
• Full pipeline: protocol analysis → build → validation → compliance
• Source code delivery from $300 — runnable API source plus full documentation; pay after delivery upon satisfaction
• Pay-per-call API billing — access our hosted endpoints and pay only per call, no upfront cost

Contact

For quotes, sandbox access or to submit your target requirements, open our contact page:

Contact page