Documentation/Swift SDK
SWIFT 5.9+ / ASYNC-AWAIT

PayCow
Swift SDK

Native Swift Package Manager library with Sendable models, Decimal monetary precision, structured concurrency (async/await), and CryptoKit HMAC-SHA256 webhook verification.

SW

PayCowSDK (Swift Package)

Zero external dependencies. Supports iOS 15+, macOS 12+, tvOS 15+, watchOS 8+, and server-side Swift.

SWIFT 5.9+ASYNC / AWAITCRYPTOKITSENDABLE

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)
}
Always pass 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

Never embed 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 methodBackend endpointRequired values
createPayment(_:)POST /api/payment/createuserId, amount, network
getPaymentStatus(sessionId:)GET /api/payment/status/:idsessionId
WebhookVerifier.verify(...)Local verificationrawBody, timestamp, signature, secret