text

iPhone App (Swift SDK)          HL Hunt Backend           HL Hunt Payments
       |                              |                        |
       |  1. Store API key (sk_test_ or sk_live_)              |
       |     in iOS Keychain          |                        |
       |                              |                        |
       |  2. GET /terminal/tap-to-pay/config                   |
       |  Authorization: Bearer sk_test_xxx                    |
       |----------------------------->|                        |
       |  credentials + merchant + deviceId                    |
       |<-----------------------------|                        |
       |                              |                        |
       |  3. POST /terminal/tap-to-pay/device                  |
       |  Authorization: Bearer sk_test_xxx                    |
       |  { readerIdentifier, appBundleId }                    |
       |----------------------------->|  Create + activate     |
       |  deviceId (DV...)            |  terminal device       |
       |<-----------------------------|----------------------->|
       |                              |                        |
       |  4. SDK initializes with config (in-memory only)      |
       |  5. SDK links Apple account (Apple UI)                 |
       |  6. SDK starts transaction                             |
       |     Buyer taps card                                     |
       |     SDK → HL Hunt Payments (direct, TLS)               |
       |     Transfer result                                     |
       |<-------------------------------------------------------|
       |                              |                        |
       |  7. POST /terminal/tap-to-pay/record                   |
       |  Authorization: Bearer sk_test_xxx                    |
       |  { transferId, amount, currency }                      |
       |----------------------------->|  Fetch + verify         |
       |  { id, processorTransactionId, state }                |
       |<-----------------------------|  Upsert Transaction row |
       |                              |----------------------->|

text

Authorization: Bearer sk_test_your_secret_key

text

Authorization: Bearer sk_test_xxx

json

{
  "success": true,
  "data": {
    "environment": "sandbox",
    "credentials": {
      "username": "USxxxxxxxxxxxxx",
      "password": "..."
    },
    "merchant": {
      "merchantId": "MUxxxxxxxxxxxxx",
      "merchantMid": "123456789012345",
      "merchantName": "My Business"
    },
    "deviceId": "DVxxxxxxxxxxxxx"
  }
}

text

Authorization: Bearer sk_test_xxx
Content-Type: application/json

json

{
  "readerIdentifier": "apple-reader-id-from-iphone",
  "appBundleId": "org.hlhunt.payments"
}

json

{
  "success": true,
  "data": {
    "deviceId": "DVxxxxxxxxxxxxx",
    "enabled": true,
    "created": true
  }
}

text

Authorization: Bearer sk_test_xxx
Content-Type: application/json

json

{
  "transferId": "TRxxxxxxxxxxxxx",
  "amount": 1500,
  "currency": "USD"
}

json

{
  "success": true,
  "data": {
    "id": "clxxxxxxxxxxxxxxxxxx",
    "processorTransactionId": "TRxxxxxxxxxxxxx",
    "state": "SUCCEEDED",
    "created": true
  }
}

swift

import HLHuntTapToPay
import ProximityReader

// ─── 0. API Key Setup ───────────────────────────────────────
// Store your HL Hunt API key in the iOS Keychain (NOT in code).
// Use sk_test_ for sandbox, sk_live_ for production.
// Create keys in the Developers section of the HL Hunt dashboard.

let apiKey = KeychainHelper.read("hlhunt_api_key")!  // e.g. "sk_test_xxx"

// Helper: attach the API key to every HL Hunt request
func hlRequest(_ url: String, method: String = "GET", body: Data? = nil) -> URLRequest {
    var req = URLRequest(url: URL(string: url)!)
    req.httpMethod = method
    req.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
    if let body { req.httpBody = body }
    return req
}

// ─── 1. GET config from HL Hunt backend ─────────────────────
let (configData, _) = try await URLSession.shared.data(
    for: hlRequest("https://payments.hlhunt.org/api/terminal/tap-to-pay/config")
)
let config = try JSONDecoder().decode(
    TapToPayConfigResponse.self, from: configData
).data

// ─── 2. Get the iPhone's reader identifier ──────────────────
let readerId = try await PaymentCardReader().readerIdentifier

// ─── 3. POST device to HL Hunt (provisions + activates) ─────
let deviceBody = try JSONEncoder().encode([
    "readerIdentifier": readerId,
    "appBundleId": Bundle.main.bundleIdentifier!,
])
let (deviceData, _) = try await URLSession.shared.data(
    for: hlRequest(
        "https://payments.hlhunt.org/api/terminal/tap-to-pay/device",
        method: "POST", body: deviceBody
    )
)
let deviceId = try JSONDecoder().decode(
    TapToPayDeviceResponse.self, from: deviceData
).data.deviceId

// ─── 4. Initialize the HL Hunt Tap to Pay SDK ───────────────
let configuration = TapToPayConfiguration(
    credentials: APICredentials(
        username: config.credentials.username,
        password: config.credentials.password
    ),
    merchant: MerchantInfo(
        merchantId: config.merchant.merchantId,
        merchantMid: config.merchant.merchantMid,
        merchantName: config.merchant.merchantName
    ),
    environment: config.environment == "sandbox" ? .sandbox : .production,
    deviceId: deviceId
)
let tapToPay = HLHuntTapToPay(configuration: configuration)

// ─── 5. Link the merchant's Apple Account (one-time, Apple UI)
try await tapToPay.linkAccount()

// ─── 6. Warm up the reader ──────────────────────────────────
try await tapToPay.prepareReader()

// ─── 7. Start a transaction (SDK handles the tap + charge) ──
let result = try await tapToPay.startTransaction(
    amount: 1500,          // cents
    currency: "USD",
    type: .purchase,
    identityId: config.merchant.merchantId
)

// ─── 8. POST the transferId to HL Hunt for reconciliation ───
let recordBody = try JSONEncoder().encode([
    "transferId": result.transferId,
    "amount": "\(1500)",
    "currency": "USD",
])
let (recordData, _) = try await URLSession.shared.data(
    for: hlRequest(
        "https://payments.hlhunt.org/api/terminal/tap-to-pay/record",
        method: "POST", body: recordBody
    )
)
let record = try JSONDecoder().decode(
    TapToPayRecordResponse.self, from: recordData
).data

print("Payment complete: \(record.processorTransactionId) — \(record.state)")
// record.id is the HL Hunt dashboard transaction ID
// record.processorTransactionId is the TR... from the SDK

text

GET /api/terminal/tap-to-pay/config
  → returns { "processor": "...", "environment": "...", "credentials": { ... }, "merchant": { ... }, "deviceId": ... }