PayCow
Swift SDK
Native Swift Package Manager library with Sendable models, Decimal monetary precision, structured concurrency (async/await), and CryptoKit HMAC-SHA256 webhook verification.
PayCowSDK (Swift Package)
Zero external dependencies. Supports iOS 15+, macOS 12+, tvOS 15+, watchOS 8+, and server-side Swift.
Installation (Swift Package Manager)
Extract paycow-swift-sdk.zip into your project workspace and add it as a local package in Package.swift (or via Xcode → File → Add Package Dependencies → Add Local):
// Package.swift
dependencies: [
.package(path: "./paycow-swift-sdk")
],
targets: [
.target(
name: "YourApp",
dependencies: [
.product(name: "PayCowSDK", package: "paycow-swift-sdk")
]
)
]
To run the included XCTest suite on macOS:
cd paycow-swift-sdk swift test
Client configuration
Initialize PayCowClient with your API credentials, optional custom URLSession, and request timeout:
import Foundation
import PayCowSDK
let config = try PayCowConfig(
apiKey: ProcessInfo.processInfo.environment["PAYCOW_API_KEY"] ?? "",
apiSecret: ProcessInfo.processInfo.environment["PAYCOW_API_SECRET"] ?? "",
baseURL: URL(string: "https://paycow.net")!,
timeoutInterval: 20
)
let paycow = PayCowClient(config: config)
Create a payment
Construct a validated CreatePaymentRequest using Decimal amounts and call createPayment(_:) asynchronously:
let request = try CreatePaymentRequest(
userId: "customer-2048",
amount: Decimal(string: "50.00")!,
network: .trc20,
currency: "USDT",
paymentMethod: .onchain,
addressSerialNo: "WAL-1002",
idempotencyKey: "order-2048-001"
)
let session = try await paycow.createPayment(request)
print("Session ID:", session.sessionId)
print("Payment URL:", session.paymentUrl)
if let payable = session.payableAmount {
print("Exact Payable USDT:", payable)
}
session.payableAmount to the buyer or on-ramp widget. Set paymentMethod: .onramp only for eligible Pro, Scale, or Enterprise merchant accounts.Retrieve payment status
Use getPaymentStatus(sessionId:) to inspect confirmations, transaction hash, and lifecycle helpers (isPaid, isConfirming, isExpired):
let status = try await paycow.getPaymentStatus(sessionId: "66ce30d74c0c51a48f2d2903")
if status.isPaid {
await creditOrderOnce(userId: status.userId, ref: status.paymentReference)
} else if status.isConfirming {
print("Confirmations:", status.confirmations ?? 0)
}
Verify webhooks (Server-side Swift / Vapor)
Pass the raw request body Data, timestamp header, and signature header to WebhookVerifier.verify:
import PayCowSDK
// Inside a Vapor route handler
let rawBody = Data(buffer: req.body.data ?? .init())
let timestamp = req.headers.first(name: "X-PayCow-Timestamp")
?? req.headers.first(name: "PayCow-Timestamp") ?? ""
let signature = req.headers.first(name: "X-PayCow-Signature")
?? req.headers.first(name: "PayCow-Signature") ?? ""
let event = try WebhookVerifier.verify(
rawBody: rawBody,
timestamp: timestamp,
signature: signature,
secret: Environment.get("PAYCOW_WEBHOOK_SECRET") ?? ""
)
if event.status?.uppercased() == "PAID" {
try await fulfillOrder(reference: event.paymentReference)
}
WebhookVerifier validates the v1=<64 hex> signature format using CryptoKit HMAC-SHA256 over timestamp.rawBody, performs constant-time byte comparison, and enforces the 300-second replay window.
Error handling
All client and verifier methods throw typed PayCowError cases:
do {
let session = try await paycow.createPayment(request)
return session.paymentUrl
} catch PayCowError.validation(let message) {
print("Invalid input:", message)
} catch PayCowError.api(let statusCode, let body) {
print("PayCow HTTP \(statusCode):", body)
} catch PayCowError.webhook(let reason) {
print("Webhook rejected:", reason)
} catch {
print("Unexpected error:", error)
}
iOS & macOS security architecture
PAYCOW_API_SECRET in client apps: Do not ship your API secret or webhook secret inside an iOS, macOS, or tvOS binary. Run PayCowSDK on your backend server (such as Vapor or Hummingbird), create the session there, and return only paymentUrl to the mobile app to open in ASWebAuthenticationSession or SFSafariViewController.API contract
| SDK method | Backend endpoint | Required values |
|---|---|---|
createPayment(_:) | POST /api/payment/create | userId, amount, network |
getPaymentStatus(sessionId:) | GET /api/payment/status/:id | sessionId |
WebhookVerifier.verify(...) | Local verification | rawBody, timestamp, signature, secret |