Getting Started

BluePosGoSDK lets an iOS app launch BluePOS Go, send a payment request, and receive the result when BluePOS Go returns to the app. It supports initialization, payments, transaction history, refunds, capture, clear-data reads, and rebooting the paired reader.

This is the developer entry point for the package. For refund, capture, transaction-list, clear-data, and reboot examples, see the Operations Guide.

Requirements

• Xcode with Swift Package Manager support.
• iOS 13 or later. This is the package minimum, not a compatibility promise for every installed BluePOS Go build.
• BluePOS Go installed and provisioned on the physical test device. Pin the SDK version and the BluePOS Go build you tested, and verify that pair on a physical device.
• A unique URL scheme that BluePOS Go can use to reopen your app.

The package product is named BluePosGoSDK and the package links the system z library automatically.

Sample Application

This guide walks you through setting up the BluefinPOSGoSDK for iOS, step by step. For a complete example of how the SDK components work together, see our sample application on GitHub.

Add the package

Obtain BluePosGoSDK from your Bluefin distribution channel. In Xcode, choose File > Add Package Dependencies…, enter the package location supplied by Bluefin, then add the BluePosGoSDK product to the application target.

To use a local checkout, choose Add Local… and select the directory that contains Package.swift.

Import the module in the code that launches a BluePOS Go operation:

import BluePosGoSDK

Register a callback URL scheme

BluePOS Go returns control to your app through a custom URL. Register a private URL scheme in the application target settings under URL Types, for example:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>mymerchantapp</string>
    </array>
  </dict>
</array>

Use the scheme in every request callback URL, such as mymerchantapp://bluepos/payment. Pick a scheme unique to your organization.

The SDK consumes a callback only when its scheme, host, and path match the callback URL of the active request. Query values are parsed as the operation result. Every request requires a request ID. Retain that ID so the callback can be correlated with the request that started it.

Scheme, host, and path matching identifies which active request the callback belongs to. It is not authentication. This documentation does not specify replay protection, callback authentication, or whether an active request survives process death. A matching callback is not proof of payment.

Verify these properties in your own integration:

• Whether a repeated callback for the same request ID is accepted or ignored.
• Whether a callback is accepted without proof that it came from BluePOS Go.
• Whether an in-flight request is still matched if the app is killed and relaunched before the callback arrives.

Confirm the final payment state independently on your backend. Reconcile with the request ID. Do not fulfill an order from callback query values alone.

For more on trace and request ids and their use cases, please refer to API Endpoint Overview | Correlation Identifier and Debugging.

Forward incoming URLs to the SDK

Call handleCallback(url:) for every URL that opens the app. This completes the closure passed to the active SDK operation.

SwiftUI

@main
struct MerchantApp: App {
    var body: some Scene {
        WindowGroup {
            CheckoutView()
                .onOpenURL { url in
                    let handled = BluePosGoSDK.shared.handleCallback(url: url)
                    if !handled {
                        // Route deep links that do not belong to BluePosGoSDK.
                    }
                }
        }
    }
}

UIKit

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    BluePosGoSDK.shared.handleCallback(url: url)
}

If your app handles other deep links, call the SDK first and route the URL yourself only when it returns false.

Building BasicToken and PaymentCredentials

To build your basic token for your SDK instance, please create your respective API key under your PayConex account ID and use the following code to generate the basic authentication. For more details, refer to API Authentication | Basic Authentication.

import Foundation

func buildBasicToken(apiKey: String, apiSecret: String) -> String {
    let credentials = "\(apiKey):\(apiSecret)"
    let encoded = Data(credentials.utf8).base64EncodedString()
    return "Basic \(encoded)"
}

/// The credentials variable used throughout this iOS integration guidelines
private var credentials: PaymentCredentials {
    PaymentCredentials(
        basicToken: buildBasicToken(apiKey, apiSecret),
        accountId: accountId.trimmingCharacters(in: .whitespacesAndNewlines),
        environment: environment
    )
}

Initialize BluePOS Go

Initialize before attempting a payment. Retrieve credentials from your authenticated backend or protected configuration; never commit a Basic token to source control.

let request = InitializationRequest(
    requestId: UUID().uuidString,
    callbackURL: URL(string: "mymerchantapp://bluepos/initialize")!,
    basicToken: credentials.basicToken,
    accountId: credentials.accountId,
    environment: "STAGING"
)

BluePosGoSDK.shared.initialize(request: request) { result in
    switch result {
    case .initialized(let response):
        print("Initialized: \(response.status ?? "unknown")")
    case .failure(let error, let response):
        print("Initialization failed: \(error); \(response?.message ?? "")")
    }
}

When supplied, environment must be STAGING, CERT, or PROD; the SDK normalizes it to uppercase. basePath is optional and should be provided only when Bluefin directs you to use a specific endpoint.

Start a payment

Use a new request ID for each payment and provide a three-letter ISO 4217 currency. credentials is optional for a payment, but if present it must contain a non-empty Basic token, account ID, and valid environment.

let request = PaymentRequest(
    requestId: UUID().uuidString,
    amount: Decimal(string: "19.99")!,
    tip: Decimal(string: "2.00"),
    transactionType: .sale, /// .sale | .auth
    currency: "USD",
    callbackURL: URL(string: "mymerchantapp://bluepos/payment")!,
    customId: "ORDER-1001",
    notes: "In-store sale",
    credentials: PaymentCredentials(
        basicToken: credentials.basicToken,
        accountId: credentials.accountId,
        environment: "STAGING"
    ),
    requiresReaderReady: true
)

BluePosGoSDK.shared.startPayment(request: request) { result in
    switch result {
    case .success(let response):
        print("Approved: \(response.transactionId ?? "")")
    case .cancelled:
        print("Customer cancelled")
    case .declined(let response):
        print("Declined: \(response.processorMessage ?? "")")
    case .failure(let error, let response):
        print("Payment error: \(error); status: \(response?.status ?? "")")
    }
}

Only one payment can be active at a time. Do not permit a duplicate action until the completion closure has run, or explicitly call BluePosGoSDK.shared.cancelPendingPayment() if the user abandons the flow.

Payment transport

The default startPayment(request:completion:) uses .urlScheme. An overload accepts PaymentLaunchTransport:

Alternative transports depend on the deployed BluePOS Go app. Start with .urlScheme. Separately qualify .gzip, .pasteboard, and .automatic against the version you ship, including the payload size where the SDK switches handoff. Do not enable a non-default transport until that check has passed.

Integration checklist

• Add BluePosGoSDK to the app target.
• Register a unique URL scheme and use it in every callback URL.
• Forward app-open URLs to handleCallback(url:).
• Generate a unique request ID per operation.
• Block duplicate UI actions while an operation is pending.
• Keep credentials and cardholder data out of source control and logs.
• Test success, decline, cancellation, missing-app, and app-return flows on a physical device.