ARISE Mobile SDK for iOS

Integration Guide | Version 1.0.0 | March 23, 2026

Changelog

Version	Date	What’s Changed
1.0.0	2026-01-21	Base version with Authentication, Payments, Settings, Device Info, Tap to Pay functionalities

Overview

The ARISE Mobile SDK for iOS enables developers to integrate Aurora Payments' payment processing capabilities directly into their iOS applications. Whether you're building a point-of-sale app, a mobile commerce platform, or adding payment acceptance to an existing business application, the SDK provides a comprehensive set of tools to handle the full transaction lifecycle.

Who Should Use This SDK

The ARISE Mobile SDK is designed for:

• Independent Software Vendors (ISVs) building payment-enabled applications for merchants
• Merchants developing custom mobile point-of-sale solutions
• Platform developers adding payment acceptance to marketplace or commerce apps

What You Can Build

With the ARISE Mobile SDK, you can create applications that:

• Accept contactless payments using Tap to Pay on iPhone — no external hardware required
• Process card-present and card-not-present transactions including sales, authorizations, captures, voids, and refunds
• Support flexible pricing models including Zero Cost Processing (ZCP) options like dual pricing, cash discounts, and credit card surcharges
• Manage transaction history with powerful filtering, pagination, and detailed reporting
• **Accept tips **with configurable tip options and calculations

Key Features

Tap to Pay on iPhone

Transform any compatible iPhone into a payment terminal. Customers can pay by holding their contactless credit card, debit card, Apple Pay, or other digital wallet just by tapping near the iPhone. No dongles, no external card readers — just the iPhone your merchants already carry.

Unified Transaction API

A single, consistent API surface for all transaction types. Whether you're authorizing a payment, capturing funds, or processing a refund, the SDK follows predictable patterns that reduce integration complexity.

Secure by Design

The SDK handles sensitive operations securely:

• Authentication tokens are stored in the iOS Keychain
• Token refresh is managed automatically in the background
• Card data is processed in compliance with PCI DSS requirements
• Tap to Pay leverages Apple's Secure Element for contactless transactions

Zero Cost Processing Support

Built-in support for ZCP pricing models allows merchants to offset processing costs. The SDK provides amount calculation utilities that automatically apply surcharges or discounts based on payment method, ensuring accurate totals are displayed to customers before they pay.

Architecture Overview

The SDK is organized into logical modules that map to common payment workflows:

Module	Purpose
Session Management	Obtain and manage API access tokens
Transactions	Submit, query, and manage payment transactions
Tap to Pay	Accept contactless payments using iPhone's NFC
Settings	Retrieve merchant configuration and payment options
Device Management	Manage registered devices and their Tap to Pay status

Integration Patterns

The SDK supports multiple integration approaches depending on your use case:

Simple Payment Flow

For straightforward payment acceptance, you can process a transaction in just a few lines:

do {
  // Initialize and authenticate
  let ariseSdk = try AriseMobileSdk(environment: .uat)
  try await ariseSdk.authenticate(clientId: "your-client-id", clientSecret: " your-client-secret ")
  // Process a Tap to Pay transaction
     try await ariseSdk.ttp.prepare()
     let result = try await ariseSdk.ttp.performTransaction(amount: 49.99)
     print("Transaction \(result.status): \(result.transactionId ?? "")")
} catch {
    // Unified error handling
    print(" An error occurred \(error.localizedDescription)")
}

Advanced Payment Flow

For applications requiring more control — such as inline tips, surcharge calculations, or custom UI during card reading — the SDK provides granular methods and event streams to support complex workflows.

Asynchronous Tasks Support

The SDK is built with Swift's modern concurrency model. All network operations and asynchronous tasks use async/await, making it easy to write clean, readable code without callback pyramids or manual thread management.

do {
    let settings = try await ariseSdk.getPaymentSettings()
    let transactions = try await ariseSdk.getTransactions()
    // Both calls complete sequentially with clear, linear code
} catch {
    // Unified error handling
}

Getting Help

If you encounter issues during integration:

• Documentation: You're here! Browse the complete API reference in the following sections.
• Developer Portal: Visit developer.risewithaurora.com for additional API documentation and guides.
• Support: Contact Aurora Payments developer support for technical assistance.

Ready to start? Head to the Get Started section to set up your credentials and configure your development environment.

Get Started

This section guides you through the prerequisites and setup required before integrating the ARISE Mobile SDK into your iOS application.

Obtain Client Credentials

To authenticate with the ARISE Mobile SDK, you need a Client ID and Client Secret. The process differs depending on your relationship with Aurora Payments.

For Merchants

1. Log in to the ARISE Portal
2. Navigate to Settings > API Tokens
3. Click New API Token
4. Copy both the Client ID and Client Secret

⚠️ Important: The Client Secret is displayed only once for security reasons. Store it securely immediately after generation. If you lose the secret, you will need to generate a new API token.

For Affiliates / ISV Partners

You can obtain credentials by accessing the ARISE API using your partner credentials. First, follow the same steps above for creating your pair of Client ID and Client Secret.

Then, use the Merchant API Tokens endpoint to programmatically create and manage API tokens for your merchant accounts. See the Merchant API Tokens documentation for details.

Environments

The ARISE Mobile ƒSDK supports two environments, specified during initialization:

Environment	Enum Value	Description
UAT (Sandbox)	.uat	Test environment for development and integration testing. Transactions are simulated and no real charges occur.
Production	.production	Live environment for real transactions. Cards will be charged and funds will be transferred.

UAT (Sandbox) Environment

Use the UAT environment during development and testing:

let ariseSdk = try AriseMobileSdk(environment: .uat)

In UAT mode:

• No real money is transferred
• Test card numbers can be used to simulate various scenarios (approvals, declines, specific error codes)
• Tap to Pay can be tested with compatible devices
• All API functionality behaves identically to production

Refer to the Testing section of this documentation for test card numbers, AVS test data, and instructions for simulating specific transaction outcomes.

Production Environment

Use the Production environment for connecting to real data and performing real transactions:

let ariseSdk = try AriseMobileSdk(environment: .production)

⚠️ Warning: In production mode, all transactions are real. Cards will be charged, and refunds will transfer actual funds. Ensure thorough testing in UAT before switching to production.

System Requirements

Minimum iOS Version

Requirement	Version
iOS	18.0 or later
Swift	5.0 or later

Supported Devices

The SDK supports all iPhone models compatible with iOS 18. However, Tap to Pay on iPhone has additional device requirements:

Feature	Supported Devices
General SDK functionality	All iPhones running iOS 18+
Tap to Pay on iPhone	iPhone XS or later

Dependencies

The SDK includes the following dependencies, which are automatically resolved when you add the SDK to your project:

Library	Version
CryptoSwift	1.8.2 – < 2.0.0
Swift Certificates	1.4.0 – < 2.0.0
Swift ASN1	1.2.0 – < 2.0.0

Required Entitlements and Capabilities

For General Integration

No special entitlements are required for basic SDK functionality (authentication, transaction submission, reporting).

For Tap to Pay on iPhone

If your app will accept contactless payments using Tap to Pay on iPhone, you must complete additional setup:

1. Apply for the Tap to Pay on iPhone Entitlement

Apple requires approval before you can use Tap to Pay. Submit a request through your Apple Developer account:

1. Sign in to your Apple Developer account
2. Navigate to Certificates, Identifiers & Profiles
3. Go to Identifiers and select your App ID
4. Under Additional Capabilities, request the Tap to Pay on iPhone entitlement
5. Complete Apple's application form with your business details
6. Wait for Apple's approval (typically 1–5 business days)

2. Configure Xcode Capabilities

Once approved, enable the following in your Xcode project:

1. Open your project in Xcode
2. Select your app target and go to Signing & Capabilities
3. Click + Capability and add:
4. Near Field Communication Tag Reading (required for NFC access)
5. Ensure your provisioning profile includes the Tap to Pay entitlement

3. Update Info.plist

Add the following keys to your Info.plist:

<key>NFCReaderUsageDescription</key>
<string>This app uses NFC to accept contactless payments.</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location is required to verify payment acceptance eligibility.</string>

4. Entitlements File

Ensure your app's entitlements file includes:

<key>com.apple.developer.proximity-reader.payment.acceptance</key>
<true/>

Testing

[to be written]

Include:

How to use UAT* (including creating a Sandbox Apple ID)*

https://developer.apple.com/help/app-store-connect/test-in-app-purchases/create-a-sandbox-apple-account/* *

Sample test cards / test values

How to simulate failures (e.g., declined cards)

How to test Tap to Pay flows

How to switch environments easily

Quick Start Checklist

Before you begin integration, verify you have completed the following:

• Created a merchant account in the ARISE Portal
• Generated API credentials (Client ID and Client Secret)
• Stored credentials securely
• Added the ARISE Mobile SDK to your Xcode project
• Set the SDK framework to "Embed & Sign"
• (Tap to Pay only) Applied for and received Apple's Tap to Pay entitlement
• (Tap to Pay only) Configured NFC capability in Xcode
• (Tap to Pay only) Added required Info.plist keys

Next Steps

Once you have completed the setup above, proceed to:

1. Installation & Setup – Add the SDK to your project
2. Initialization – Create an SDK instance connected to your chosen environment
3. Authenticate – Authenticate using your Client ID and Client Secret
4. Transactions or Tap to Pay – Begin processing payments or reading reports

Installation & Setup

When you get the ARISE Mobile SDK Swift package, drag-and-drop it into Xcode to add it as a project dependency.

• Ensure that the ARISE Mobile SDK is visible in the project navigator.
• Once it is uploaded, select the option “Embed & Sign”.

Methods Specification – Init and Session Management

Init

Creates an instance of the ARISE Mobile SDK connected to a specific environment.

Important: Main Thread Requirement

To ensure Tap to Pay on iPhone functions correctly, the ARISE Mobile SDK must be initialized on the app’s main thread. The underlying framework performs mandatory system integrity and security checks that are restricted to the main run loop. Attempting to initialize the SDK from a background thread will cause these checks to fail and result in initialization errors.

This can be achieved by initializing the SDK from the AppDelegate, SceneDelegate, or by wrapping the call inside a DispatchQueue.main.async block.

Signature:

init(environment: Environment) throws

Parameters:

Parameter Name	Type	Required	Description
environment	Environment	Yes	Target ARISE environment (.production or .uat). See Get Started for environment details.

Returns:

None

Throws: An error if the SDK fails to initialize.

Code example:

import AriseMobileSdk

init() {
    let ariseSdk = try AriseMobileSdk(environment: .uat)

}

// Option 1: AppDelegate
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // This runs on the main thread by default
    let ariseSdk = try AriseMobileSdk(environment: .uat)
    return true
}

// Option 2: SwiftUI
@main
struct YourApp: App {
    @StateObject private var ariseSdk = try! AriseMobileSdk(environment: .uat)

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(ariseSdk)
        }
    }
}

// Option 3: Explicitly wrapping in the Main Thread
// Use this if you are initializing inside a background task or closure
DispatchQueue.main.async {
    let ariseSdk = try AriseMobileSdk(environment: .uat)
}

Authenticate

Start a new session used to authenticate to the ARISE API and enable communication between the mobile client app and the ARISE backend. Once the Access Token and Refresh Token are generated, they are stored in secure storage and reused on upcoming calls.

The ARISE Mobile SDK automatically manages the authentication tokens, including refreshing it when it is about to expire.

Note: To use the ARISE Mobile SDK methods, you will first need to provide the clientId and clientSecret parameters from your Merchant Account. Read Obtain Client Credentials for more information on how to retrieve these credentials.

Method signature:

func authenticate(clientId: String, clientSecret: String) async throws -> Bool

Parameters:

Parameter Name	Type	Required	Description
clientId	String	Yes	The merchant account’s Client ID
clientSecret	String	Yes	The merchant account’s Client Secret

Returns:

Bool: true if authentication succeeded.

Throws:

AuthenticationError

• invalidCredentials - Your client ID or secret is incorrect

• networkError - Network connection problem

• invalidResponse - Server returned unexpected data

Code example:

let result = try await ariseSdk.authenticate(
     clientId: "your-client-id",
     clientSecret: "your-client-secret"
)

Get Access Token

Returns the current Access Token, which can be used to directly call the ARISE API.

Note: Calling the ARISE API directly is only recommended for calling endpoints related to features that are not yet available on the ARISE Mobile SDK, such as Quick Payments, Invoices, etc.

Method signature:

func getAccessToken() async -> String?

Parameters:

None

Returns:

String``? - The access token if valid and not expired, nil otherwise

Code example:

if let **token = **await** `arise`Sdk.getAccessToken() {

    // Use token to call ARISE API directly

    print("Access token: \(token)")


} else {

print("No valid access token available")

}

Refresh Access Token

Generate a new Access Token in case the current token is about to expire.

Note: The Access/Refresh Tokens are automatically managed by the ARISE Mobile SDK in the background, so implementing a custom logic for refreshing the token is not required.

Method signature:

func refreshAccessToken() async throws -> Bool

Parameters:

None

Returns:

Bool: true if token refresh succeeded.

Throws:

AuthenticationError

• invalidCredentials - Your client ID or secret is incorrect

• networkError - Network connection problem

• invalidResponse - Server returned unexpected data

Code example:

let result = try await ariseSdk.refreshAccessToken()

Clear Stored Token

Remove all stored authentication tokens. Useful to close the session (logout) with the ARISE backend.

Method signature:

func clearStoredToken()

Parameters:

None

Returns:

Nothing (void method)

Code example:

ariseSdk.clearStoredToken()

Methods Specification – Transactions

Get Transactions List

Retrieves a paginated list of transactions of the merchant account. Optionally set filters to scope the response by pagination, date ranges, or batch identifiers.

Method signature:

func getTransactions(filters: TransactionFilters? = nil) async throws -> TransactionsResponse

Parameters:

TransactionFilters

Property Name	Type	Required	Description
page	Int?	No	Page number
pageSize	Int?	No	Page size - number of items per page. Must be between 1 and 100.
orderBy	String?	No	Field used to sort the transactions list. Case-insensitive. Options: - date [default] - totalAmount - status - customerPan - cardTokenType - id - paymentMethodType - operationMode - customerName - customerCompany - merchant
asc	Bool?	No	Specifies the sort direction for the results. When true, results are sorted in ascending order. When false, results are sorted in descending order. true: ascending order false [default]: descending order
createdById	String?	No	CreatedById - Identifier of the specific entity that created the transaction (e.g.: terminal ID, invoice ID, quick payment ID, etc.)
batchId	String?	No	BatchId
noBatch	Bool?	No	If true – return only transactions that haven’t been settled yet (open batch)

Returns:

TransactionsResponse - Result of getTransactions request containing a paged list with TransactionSummaries.

Throws:

AriseApiError if the ARISE API rejects the request.

Code Example:

let filters = try TransactionFilters(
    page: 0,
    pageSize: 20,
    orderBy: "date",
    asc: false
)
let result = try await ariseSdk.getTransactions(filters: filters)

Get Transaction Details

Get transaction receipt (detailed transaction information). Retrieves complete details for a specific transaction.

Method signature:

func getTransactionDetails(id: String) async throws -> TransactionDetails

Parameters:

Property Name	Type	Required	Description
id	String	Yes	Transaction unique identifier (UUID format)

Returns:

TransactionDetails - describing the transaction, or nil when the transaction cannot be found.

**Throws: **

AriseApiError if the ARISE API rejects the request.

Code Example:

let transactionId = "123e4567-e89b-12d3-a456-426614174000"
if let details = try await ariseSdk.getTransactionDetails(id: transactionId) {
     print("Transaction ID: \(details.transactionId ?? "N/A")")
     print("Amount: \(details.amount?.totalAmount ?? 0)")
     print("Status: \(details.status ?? "N/A")")
 }

Submit an Authorization Transaction (AUTH)

Initiate a payment authorization, placing a temporary hold on the customer's funds without immediate capture. This hold is valid for 7 days. To complete the transaction, a "Capture" transaction must be submitted within this window; otherwise, the authorization expires and the funds hold is automatically released to the customer.

PCI-DSS Responsibility Notice

This method may process cardholder data depending on the integration method used. Sending raw card data through this API significantly increases PCI-DSS compliance requirements. Integrators are responsible for ensuring PCI-DSS compliance applicable to their implementation.

Method signature:

func submitAuthTransaction(input: CardTransactionRequest) async throws -> AuthorizationResponse

Parameters:

Name	Type	Required	Description
request	CardTransactionRequest	Yes	Authorization transaction input parameters

**Returns: **

CardTransactionResponse containing authorization status, transaction ID, etc.

Throws:

AriseApiError if the ARISE API rejects the request.

Code Example:

let input = try CardTransactionRequest(
    paymentProcessorId: "197c05e0-f99a-49bb-905c-d3da9d1e7200",
    amount: 123.45,
    currency: .usd,
    cardDataSource: .manual
    accountNumber: "4111111111111111",
    expirationMonth: 12,
    expirationYear: 24,
    securityCode: "123"
)


let result = try await ariseSdk.submitAuthTransaction(input: input)
print("Transaction ID: \(result.transactionId ?? "N/A")")

Submit a Sale Transaction (SALE)

Executes a combined authorization and capture actions. This method immediately charges the customer’s card and marks the funds for settlement. Use this method for transactions where goods or services are delivered instantly.

PCI-DSS Responsibility Notice

This method may process cardholder data depending on the integration method used. Sending raw card data through this API significantly increases PCI-DSS compliance requirements. Integrators are responsible for ensuring PCI-DSS compliance applicable to their implementation.

Method signature:

func submitSaleTransaction (input: CardTransactionRequest) async throws -> AuthorizationResponse

Parameters:

Name	Type	Required	Description
request	CardTransactionRequest	Yes	Authorization transaction input parameters

**Returns: **

CardTransactionResponse containing authorization status, transaction ID, etc.

**Throws: **

AriseApiError if the ARISE API rejects the request.

Code Example:

let input = try CardTransactionRequest (
    paymentProcessorId: "197c05e0-f99a-49bb-905c-d3da9d1e7200",
    amount: 123.45,
    currency: .usd,
    cardDataSource: .manual
    accountNumber: "4111111111111111",
    expirationMonth: 12,
    expirationYear: 24,
    securityCode: "123"
)


let result = try await ariseSdk.submitSaleTransaction(input: input)
print("Transaction ID: \(result.transactionId ?? "N/A")")

Void a Transaction (VOID)

Cancels a transaction before it has been settled. Use this to cancel an Authorization or Sale transaction. Voiding a transaction prevents any charges from the customer.

Note: Voids are only possible for unsettled transactions. If the transaction has already been processed in your daily batch, you must use the Refund method instead.

Method signature:

func voidTransaction (transactionId: String) async throws -> TransactionResponse

Parameters:

VoidTransactionRequest - Input parameters for voiding a transaction

Name	Type	Required	Description
transactionId	String	Yes	Transaction unique identifier (UUID format) to void

Returns:

TransactionResponse - containing updated transaction details.

**Throws: **

AriseApiError if the ARISE API rejects the request.

Code Example:

let transactionId = "123e4567-e89b-12d3-a456-426614174000"
do {
    let result = try await ariseSdk.voidTransaction(transactionId: transactionId)
    print("Transaction voided successfully")
    print("New status: \(result.status ?? "N/A")")
    print("Response: \(result.responseDescription ?? "N/A")")
} catch AriseApiError.apiError(let message) {
    print("Cannot void transaction: \(message)")
}

Capture a Transaction (CAPTURE)

Completes a previously authorized payment. This method converts the "hold" created by an Authorization (AUTH) transaction into an actual charge. You can capture the full authorized amount or a partial amount. Once successful, the funds are marked for settlement and will be transferred to the merchant account.

Note: Captures must typically be performed within 7 days of the initial authorization; otherwise, the authorization expires.

Method signature:

func captureTransactionRequest (transactionId: String, amount: Double
) async throws -> TransactionResponse

Parameters:

Property	Type	Description
transactionId	String	Identifier of the authorization transaction to capture
amount	Double	Amount to capture If the amount is lower than the authorized amount, the difference will be released, and the customer will be charged only the captured amount.

Returns:

TransactionResponse - containing updated transaction details.

**Throws: **

AriseApiError if the ARISE API rejects the request.

Code Example:

do {
   let result = try await ariseSdk.captureTransaction(
    transactionId: transactionId,
    amount: amountToCapture)
    print("Transaction voided successfully")
    print("New status: \(result.status ?? "N/A")")
    print("Response: \(result.responseDescription ?? "N/A")")
} catch AriseApiError.apiError(let message) {
    print("Cannot void transaction: \(message)")
}

Refund a Transaction (REFUND)

Returns funds to a customer for a transaction that has already been settled. This method initiates a reversal of the payment flow, moving money from the merchant account back to the customer’s card.

Note: Unlike a void, a refund can be issued days or weeks after the original sale. You can perform a Full Refund of the entire amount or a Partial Refund.

Method signature:

func refundTransaction (transactionId: String, amount: Double
) async throws -> TransactionResponse

Parameters:

Property	Type	Description
transactionId	String	Identifier of the authorization transaction to capture
amount	Double	Amount to capture If the amount is lower than the authorized amount, the difference will be released, and the customer will be charged only the captured amount.

**Returns: **

TransactionResponse containing authorization status, transaction ID, authorization code, transaction receipt, and other transaction details..

Throws:

AriseApiError if the ARISE API rejects the request.

Code Example:
 let partialResult = try await ariseSdk.refundTransaction(
transactionId: transactionId,
amount: 25.00)


print("Partial refund approved:
\(partialResult.transactionReceipt?.amount?.totalAmount ?? 0)")

// Full remaining refund
let fullResult = try await ariseSdk.refundTransaction(
 RefundRequest(
 transactionId: transactionId,
 cardDataSource: .manual))

print("Remaining amount refunded. New status:
\(fullResult.status ?? "N/A")")

Calculate Amount

Calculates the final transaction amount based on the merchant settings. This method is useful for merchant accounts that have ZCP (Zero Cost Processing) such as Dual Pricing, Cash Discount or Credit Card Surcharge enabled.

By providing the base amount of the transaction, the method calculates the final amount for each payment method, allowing the customer to acknowledge the final amounts and choose the preferred payment method to use.

Method signature:

func calculateAmount(request: CalculateAmountRequest) async throws -> CalculateAmountResponse

Parameters:

Property Name	Type	Required	Description
request	CalculateAmountRequest	Yes	Amount calculation inputs such as base amount, percentage-off, surcharge, tips, and currency.

Returns:

CalculateAmountResponse containing currency metadata and per-tender breakdown (credit card, debit card, ACH and cash).

**Throws: **

AriseApiError if the ARISE API rejects the request.

Code Example:

let calculation = try await ariseSdk.calculateAmount(
request: CalculateAmountRequest(
amount: 100.0,
currency: .usd
percentageOffRate: 5.0,
surchargeRate: 3.0,
tipAmount: 10.0,
useCardPrice: true
)
)
print("Card total: \(calculation.creditCard?.totalAmount ?? 0)")
print("Cash total: \(calculation.cash?.totalAmount ?? 0)")

Methods Specification - Tap to Pay

Tap to Pay requires iPhone XS or later running iOS 18+. See Get Started for requirements and entitlement setup.

Check Compatibility

Checks whether the current device can use Tap to Pay on iPhone feature.

Method signature:

func checkCompatibility() -> TTPCompatibilityResult

Parameters:

None

Returns:

TTPCompatibilityResult containing detailed compatibility information. The isCompatible property is true when all prerequisites are met.

Code Example:

let result = ariseSdk.ttp.checkCompatibility()
if result.isCompatible {
print("Device is compatible with Tap to Pay")
print("Device: \(result.deviceModelCheck.modelIdentifier)")
print("iOS Version: \(result.iosVersionCheck.version)")
} else {
print("Device is not compatible:")
for reason in result.incompatibilityReasons {
print("- \(reason)")
}
}

Get Status

Retrieves the Tap to Pay activation status for the current device.

Method signature:

func getStatus() async throws -> TTPStatus

Code Example

do {
let status = try await ariseSdk.ttp.getStatus()
if status == .active {
print("Tap to Pay is active")
} else {
print("Tap to Pay is inactive - guide user through activation")
}
} catch AriseApiError.apiError(let message) {
print("Failed to get status: \(message)")
}

Parameters:

None

Returns:

TTPStatus Tap to Pay activation status for a device

Throws:

AriseApiError when the API returns an error or the response cannot be decoded.

Activate

Activates Tap to Pay on the current device. This method initiates Apple's Tap to Pay activation workflow (by showing the Apple’s Terms & Conditions to use Tap To Pay on iPhone) and then updates the device’s Tap To Pay status to Active.

Note: Ensure this method is only called if the phone user is an actual business administrator of the merchant account or has been authorized by a business administrator to enable Tap To Pay on iPhone.

Method Signature func** activate() async throws** Parameters:**

None

Throws

TTPError if:

• Tap to Pay status is not active (returns specific error)

• Tap to Pay is not initialized

• Tap to Pay configuration fails

Code Example:

do {
          try await ariseSdk.ttp. activate()
} catch let error as TTPError {
    print("❌ Activation failed: \(error.localizedDescription)")
} catch let error as AriseApiError {
    print("❌ API error: \(error.localizedDescription)")
}

Show Educational Information

Shows educational information about Tap to Pay. This method presents an SDK-provided educational screen/modal with content generated by Apple. The educational content helps merchants understand setup, best practices, and device handling before accepting payments.

Method Signature

func showEducationalInfo(viewController: UIViewController) async throws

Parameters

Name	Type	Required	Description
viewController	UIViewController	Yes	The view controller from which to present the educational content.

Throws

AriseApiError when the API returns an error or the response cannot be decoded.

TTPError if:

• Tap to Pay status is not active (returns specific error)

• Tap to Pay SDK is not initialized

• Tap to Pay SDK configuration fails

Code Example:

do {
          try await ariseSdk.ttp.showEducationalInfo(from: self)
          print("Educational content was shown and dismissed")
       } catch let error as TTPError {
          print("Failed to show educational content: \(error.localizedDescription)")
       }

Prepare the Card Reader

Prepares Tap to Pay by initializing the Proximity Reader and configuring the SDK with merchant information.

This method warms up the device and initializes the Proximity Reader so that Tap to Pay operations can start faster when needed. The initialization happens in the background without presenting any UI.

When to call this method:

• Recommended: Call once at application startup (e.g., after user login) to prepare the reader

• After activate() has been called successfully (Tap to Pay must be active)

Important: You do NOT need to call this method before every transaction. The SDK handles reader initialization and token refresh internally during transaction operations. This method is for one-time setup at application startup to optimize performance.

Important: This method does NOT activate Tap to Pay. If Tap to Pay is not active, this method will throw TTPError.notActive. To activate Tap to Pay, first you need to call activate().

Method signature:

func prepare() async throws

Parameters:

None

Throws

TTPError if:

• Tap to Pay status is not active (returns specific error)

• SDK is not initialized

• SDK configuration fails

Examples

do {
try await ariseSdk.ttp.prepare()
print("Tap to Pay is ready")
} catch let error as TTPError {
print("Failed to prepare: \(error.localizedDescription)")
}

Perform a Tap To Pay Transaction

Method Signature

public func performTransaction(amount:)(amount: Decimal) async throws  -> TTPTransactionResult

Performs a Tap to Pay transaction by passing the total amount. Once called, this method brings up Apple's Tap to Pay screen for the customer to present the card.

Before calling this method, ensure that the proximity reader has been initiated by calling the prepare() method.

Note: This method is recommended for merchants that don’t have the Zero Cost Processing (ZCP) mode “Credit Card Surcharge” enabled. If the merchant has the Credit Card Surcharge enabled, this method will throw an error indicating to use the alternate performTransaction method with additional parameters.

Parameters

Name	Type	Required	Description
amount	Decimal	Yes	Transaction amount as Decimal.

Returns

Returns: TTPTransactionResult

Throws

TTPError if:

• Tap to Pay status is not active (returns specific error)

• Tap to Pay is not initialized

• Tap to Pay configuration fails

PaymentCardReaderError if the card reader encounters an error

AriseApiError if API calls fail (network errors, authentication errors, etc.)

Code Example:

do** {
**let** result = **try** await** ariseSdk.ttp.performTransaction(amount: Decimal(100.0))
print("Transaction ID: \(result.transactionId ?? "N/A")")
print("Status: \(result.status)")
} **catch** let** error **as** TTPError {
print("❌ Transaction failed: \(error.localizedDescription)")
}

Tap To Pay Transaction with Credit Card Surcharge

Performs a Tap to Pay transaction with extended amount calculation information. Once called, this method brings up Apple's Tap to Pay screen for the customer to present the card.

This method must be used for card payments when the merchant account has enabled the Zero Cost Processing mode “Credit Card Surcharge”. It uses a pre-calculated amount result from method calculateAmount() and allows specifying whether customer card is a debit card or credit card. The surcharge is only applied if the card is a credit card.

Method Signature func** performTransaction(calculationResult:isDebitCard:) async throws** ->** TTPTransactionResult

Parameters

Name	Type	Required	Description
calculationResult	CalculateAmountResponse	Yes	Result from calculateAmount() method containing amount breakdowns for different payment types.
isDebitCard	Bool	Yes	true: debit card (surcharge will not be applied) false: credit card (surcharge will be applied to the final amount)

Returns

TTPTransactionResult containing normalized transaction data suitable for subsequent API posting.

Throws

TTPError if:

• Tap to Pay status is not active (returns specific error)

• Tap to Pay is not initialized

• Tap to Pay configuration fails

PaymentCardReaderError if the card reader encounters an error

AriseApiError if API calls fail (network errors, authentication errors, etc.)

Code Example:

do** {
**let** calculation = **try** await** ariseSdk.calculateAmount(
request: CalculateAmountRequest(amount: 100.0)
)
**let** result = **try** await** ariseSdk.ttp.performTransaction(
calculationResult: calculation,
isDebitCard: **false**
)
print("Transaction ID: \(result.transactionId ?? "N/A")")
print("Status: \(result.status)")
} **catch** let** error **as** TTPError {
print("❌ Transaction failed: \(error.localizedDescription)")
}

Abort Transaction

This method cancels the transaction while the “present card” screen is visible.

Method Signature:
 func abortTransaction() async throws -> Bool

Parameters:

None

Returns:

true if the transaction was successfully aborted.

Throws:

TTPError if:

• .sdkNotInitialized: SDK is not initialized
• .failedToAbortTransaction Transaction cannot be aborted because card reading has begun,

Code Example:

do** {
     **let** aborted = **try await** ariseSdk.ttp.abortTransaction()
     **if** aborted {
         print("Transaction was successfully aborted")
         // UI is automatically dismissed
     } **else** {
         print("No active transaction to abort")
     }
 } **catch** {
     print("Error: \(error.localizedDescription)")
 }

Events Stream

Provides a real-time stream of events from Tap to Pay operations. This method returns an asynchronous stream that delivers events as they occur during. Tap to Pay transactions and operations. Use this to monitor transaction progress, card reader state changes, and receive real-time updates for your UI.

Method Signature

func eventsStream() throws -> AsyncStream<TTPEvent>

Parameters:

None

Return Value

Returns **AsyncStream<TTPEvent>:

Throws

TTPError if:

• Tap to Pay status is not active (returns specific error)

• Tap to Pay is not initialized

• Tap to Pay configuration fails

Code Example:

do {
         for await event in try ariseSdk.ttp.eventsStream() {
             switch event {
             case .readerEvent(let readerEvent):
                 switch readerEvent {
                 case .updateProgress(let progress):
                     print("Reader progress: \(progress)%")
                 case .cardDetected:
                     print("Card detected")
                 case .readCompleted:
                     print("Card read completed")
                 default:
                     print("Reader event: \(readerEvent)")
                 }
             case .customEvent(let customEvent):
                 switch customEvent {
                 case .preparing:
                     print("Preparing terminal...")
                 case .ready:
                     print("Terminal is ready")
                 case .approved:
                     print("Transaction approved!")
                 case .declined:
                     print("Transaction declined")
                 case .readerNotReady(let reason):
                     print("Reader not ready: \(reason)")
                 default:
                     print("Custom event: \(customEvent)")
                 }
             }
         }
     } catch TTPError.sdkNotInitialized {
         print("SDK is not initialized")
     }

Methods Specification - Settings

Get Payment Settings

Retrieves payment configuration settings for the merchant account.

Method signature:

func getPaymentSettings() async throws -> PaymentSettingsResponse

Parameters:

None

Returns:

PaymentSettingsResponse containing normalized configuration data.

Throws:

AriseApiError if the ARISE API rejects the request or the response cannot be decoded.

Code Example:

let settings = try await ariseSdk.getPaymentSettings()
print("Available currencies: \(settings.availableCurrencies.map {
    $0.name ?? "" })")
print("ZCP mode: \(settings.zeroCostProcessingOption ?? "None")")
print("Tips enabled: \(settings.isTipsEnabled)")
print("Default surcharge rate: \(settings.defaultSurchargeRate ?? 0)%")

Get Permissions

Returns the list of enabled API permissions for the currently authenticated user.

Method signature:

func getPermissions() async throws -> ApiPermissionsResponse

Parameters:

None

Returns:

ApiPermissionsResponse containing list of enabled API permissions.

Throws:

AriseApiError if the ARISE API rejects the request or the response cannot be decoded.

Code Example:

let permissions = try await ariseSdk.getPermissions()
print("Enabled permissions: \(permissions.permissions)")

Methods Specification – Device Management

Get Devices

Retrieves smartphone devices linked to the merchant account, along with device information and the status for the Tap To Pay functionality for each device.

Method signature:

func getDevices() async throws -> DevicesResponse

Parameters:

None

Returns:

DevicesResponse containing device metadata straight from the merchant devices API (identifier, device name, Tap to Pay status text/id, last login timestamp, associated profiles).

Throws:

AriseApiError when the API returns an error or the response cannot be decoded.

Code Example

let devices = try await ariseSdk.getDevices()
devices.devices.forEach { device in
    print("\(device.deviceName) -> \(device.tapToPayStatus ?? "Unknown")")
}

Get Device Info

Retrieves detailed information for a specific device by its identifier.

Method signature:

func getDeviceInfo(deviceId: String) async throws -> DeviceInfo

Parameters:

Name	Type	Required	Description
deviceId	String	Yes	Unique device identifier

Returns:

DeviceInfo containing device details.

Throws:

AriseApiError when the API returns an error or the response cannot be decoded.

Code Example

let deviceId = "123e4567-e89b-12d3-a456-426614174000"
do {
let deviceInfo = try await ariseSdk.getDeviceInfo(deviceId: deviceId)
print("Device: \(deviceInfo.deviceName ?? "Unknown")")
print("TTP Status: \(deviceInfo.tapToPayStatus ?? "Unknown")")
print("TTP Enabled: \(deviceInfo.tapToPayEnabled)")
print("Last Login: \(deviceInfo.lastLoginAt?.description ?? "Never")")
} catch AriseApiError.apiError(let message) {
print("Error retrieving device: \(message)")
}

Get Device ID

Returns the persistent device identifier stored in Keychain.

Method Signature

 func getDeviceId() -> String

Parameters:

None

Returns:

String - A UUID string in lowercase format (e.g., "123e4567-e89b-12d3-a456-426614174000").

Code example:

let deviceId = ariseSdk.getDeviceId()
print("Device ID: \(deviceId)")

Methods Specification – General Information

Get SDK Version

Returns the version of the ARISE Mobile SDK for iOS that is embedded in your application.

Method Signature

 func getVersion() -> String

Parameters:

None

Returns:

String - The version of the ARISE Mobile SDK framework (e.g., “1.0.0”).

Code example:

let version = ariseSdk.getVersion()
print("ARISE Mobile SDK version: \(version)")

API Models

Transactions

TransactionFilters

Property Name	Type	Required	Description
page	Int?	No	Page number
pageSize	Int?	No	Page size
asc	Bool?	No	If true - sort by ascending. If false - sort by descending
orderBy	String?	No	Field to order by
createMethodId	CreateMethodId?	No	CreateMethodId
createdById	String?	No	CreatedById
batchId	String?	No	BatchId
noBatch	Bool?	No	If true - filter not settled transactions

CreateMethodId

Transaction creation method identifier

Enum Values

Value	Raw Value	Display Name	Description
portal	1	Portal	Portal
apiToken	2	API Token	API Token
terminal	3	Terminal	Terminal
invoice	4	Invoice	Invoice
quickPayment	5	Quick Payment	Quick Payment
webComponent	6	Web Component	Web Component
subscription	7	Subscription	Subscription
mobileApp	8	Mobile App	Mobile App
tapToPay	9	Tap to Pay	Tap to Pay

Currency

Description: Currency type used for transaction amounts.

Case	Raw Value	Description
usd	1	United States Dollar

ZeroCostProcessingOption

Description: Zero cost processing option for merchant payment settings. Determines how surcharges or discounts are applied to transactions.

Case	Raw Value	Description
noZeroCost	1	No zero cost processing
cashDiscount	2	Cash discount pricing
dualPricing	3	Dual pricing
surcharge	4	Surcharge

OperationType

Description: Operation type for transaction operations. Represents the type of operation performed on a transaction.

Case	Raw Value	Description
authorization	1	Authorization - reserves funds but does not capture
sale	2	Sale - immediate payment with capture
capture	3	Capture - captures previously authorized funds
void	4	Void - cancels a transaction before settlement
refund	5	Refund - returns funds after settlement

PaymentMethodType

Description: Payment method type for transactions. Represents the type of payment method used for a transaction.

Case	Raw Value	Description
card	1	Card payment (credit or debit)
electronicCheck	2	Electronic check (ACH) payment
cash	3	Cash payment

AccountType

Description: Account type for ACH transactions. Represents the type of bank account used for ACH payments.

Case	Raw Value	Description
checking	1	Checking account
savings	2	Savings account

AccountHolderType

Description: Account holder type for ACH transactions. Represents whether the account belongs to a person or a business.

Case	Raw Value	Description
business	1	Business account
personal	2	Personal account

TransactionType

Description: Transaction type. Represents the type of transaction operation.

Case	Raw Value	Description
authorization	“Authorization”	Authorization - reserves funds but does not capture
sale	“Sale”	Sale - immediate payment with capture
capture	“Capture”	Capture - captures previously authorized funds
void	“Void”	Void - cancels a transaction before settlement
refund	“Refund”	Refund - returns funds after settlement
cardAuthentication	“CardAuthentication”	Card authentication transaction
refundWORef	“RefundWORef”	Refund without reference transaction
tipAdjustment	“TipAdjustment”	Tip adjustment transaction
achDebit	“AchDebit”	ACH debit transaction
achRefund	“AchRefund”	ACH refund transaction
achHold	“AchHold”	ACH hold transaction
achUnHold	“AchUnHold”	ACH unhold transaction
achCancel	“AchCancel”	ACH cancel transaction
achCredit	“AchCredit”	ACH credit transaction

TransactionStatus

Description: Transaction status. Represents the aggregated status of a transaction.

Case	Raw Value	Description
authorized	“Authorized”	Funds reserved but not captured
captured	“Captured”	Funds have been captured
voided	“Voided”	Cancelled before settlement
refunded	“Refunded”	Funds returned after settlement
verified	“Verified”	Card verification completed
settled	“Settled”	Funds transferred
partiallyAuthorized	“PartiallyAuthorized”	Partially authorized
informational	“Informational”	Informational transaction
scheduled	“Scheduled”	ACH transaction is scheduled
cancelled	“Cancelled”	ACH transaction is cancelled
chargedBack	“ChargedBack”	ACH transaction has been charged back
inProgress	“InProgress”	ACH transaction is in progress
cleared	“Cleared”	ACH transaction is cleared
held	“Held”	ACH transaction is held
heldByProcessor	“HeldByProcessor”	ACH transaction is held by processor

TransactionsResponse

propertyName	Type	Description
items	Array<TransactionSummary>	List of transactions
total	Int	Pagination metadata - total count of items

TransactionSummary

Summary information about a transaction

propertyName	Type	Description
id	String	Transaction unique identifier (UUID format)
paymentProcessorId	String	Payment processor unique identifier (UUID format)
date	Date?	Transaction date and time (nullable)
baseAmount	Double	Base amount of the transaction before surcharges, tips, taxes
totalAmount	Double	Total amount of the transaction including all fees
surchargeAmount	Double?	Surcharge amount applied to the transaction (nullable)
surchargePercentage	Double?	Surcharge percentage applied to the transaction (nullable)
currencyCode	String?	Currency code (e.g., USD, EUR) (nullable)
currency	Currency	Currency for the transaction
merchant	String?	Merchant name (nullable)
merchantId	String	Merchant unique identifier (UUID format, required)
operationMode	String?	Operation mode of the transaction (nullable)
paymentMethodType	PaymentMethodType ?	Payment method type
customerName	String?	Customer name (nullable)
customerCompany	String?	Customer company name (nullable)
customerPan	String?	Customer Primary Account Number (masked card number) (nullable)
cardTokenType	CardTokenType?	Card token type enum - Local (1) or Network (2) (nullable)
customerEmail	String?	Customer email address (nullable)
customerPhone	String?	Customer phone number (nullable)
status	TransactionStatus?	Transaction status (e.g., approved, declined)
operationType	OperationType?	Transaction type
type	String?	Transaction type name (e.g., Authorization, Sale, Capture) (nullable)
batchId	String?	Batch identifier for settlement (UUID format, nullable)
source	SourceResponseDto	Source information of the transaction (required)
availableOperations	Array<AvailableOperation>?	List of available operations that can be performed on this transaction (nullable)
amount	AmountDto	Detailed amount breakdown including all fees, discounts, and taxes (required)

CardTokenType

Card token type enumeration

propertyName	Type	Description
local	Int	Local token type (value: 1) - Regular local tokenization
network	Int	Network token type (value: 2) - Network tokenization

SourceResponseDto

Source information for the transaction

propertyName	Type	Description
operationType	OperationType?	Transaction type
id	String?	Source unique identifier (UUID format, nullable)
name	String	Source name (required)

AvailableOperation

Available operation that can be performed on a transaction

propertyName	Type	Description
operationType	OperationType?	Transaction type
availableAmount	Double?	Available amount for this operation (nullable)
suggestedTips	Array<SuggestedTipsDto>?	List of suggested tip amounts and percentages (nullable)

SuggestedTipsDto

Suggested tip information

propertyName	Type	Description
tipPercent	Double	Tip percentage
tipAmount	Double	Tip amount in currency

AmountDto

Detailed amount breakdown for the transaction

propertyName	Type	Description
baseAmount	Double	Base amount before any adjustments
percentageOffAmount	Double	Amount discounted by percentage off
percentageOffRate	Double	Percentage off rate applied
cashDiscountAmount	Double	Cash discount amount applied
cashDiscountRate	Double	Cash discount rate applied
surchargeAmount	Double	Surcharge amount applied
surchargeRate	Double	Surcharge rate applied
tipAmount	Double	Tip amount applied
tipRate	Double	Tip rate applied
taxAmount	Double	Tax amount applied
taxRate	Double	Tax rate applied
totalAmount	Double	Total amount after all adjustments, fees, and taxes

TransactionDetails

propertyName	Type	Description
transactionId	String?	Unique transaction identifier
transactionDateTime	Date?	Date and time when the transaction occurred. Format: ISO 8601 date-time
orderNumber	String?	Optional order identifier provided by the merchant
amount	TransactionAmountDto?	Complete amount information including base amount, surcharges, tips, discounts, and total amount
currency	Currency	Currency for the transaction
processorId	String?	Payment processor identifier
processor	String?	Payment processor name
operationTypeId	Int32?	Operation type identifier. Numeric identifier for the operation type (e.g., Sale, Auth, Capture, Void, Refund)
operationType	String?	Operation type name. Human-readable operation type name
transactionType	TransactionType?	Transaction type (e.g., sale, auth)
paymentMethodType	PaymentMethodType ?	Payment method type
customerId	String?	Customer identifier. Unique identifier for the customer in the merchant’s system
customerPan	String?	Customer PAN (Primary Account Number). Masked card number or account number for security compliance
cardTokenType	CardTokenType?	Card token type. Indicates whether the card is stored locally or on the network
status	TransactionStatus?	Transaction status (e.g., approved, declined)
merchantName	String?	Merchant name
merchantAddress	String?	Merchant address
merchantPhoneNumber	String?	Merchant phone number
merchantEmailAddress	String?	Merchant email address
merchantWebsite	String?	Merchant website
authCode	String?	Authorization code. Authorization code returned by the payment processor. Only present for approved transactions
source	SourceResponseDto?	Transaction source information. Information about the source of the transaction (e.g., POS terminal, online, mobile)
responseCode	String?	Response code. Response code from the payment processor indicating transaction result
responseDescription	String?	Response description. Human-readable description of the transaction response
cardholderAuthenticationMethodId	CardholderAuthenticationMethod?	Cardholder authentication method identifier. Numeric identifier for the cardholder authentication method used
cardholderAuthenticationMethod	String?	Cardholder authentication method name. Human-readable cardholder authentication method name
cvmResultMsg	String?	CVM (Cardholder Verification Method) result message. Result message from cardholder verification
cardDataSourceId	CardDataSource?	Card data source identifier. Numeric identifier for the card data source (e.g., Swipe, Chip, Contactless)
cardDataSource	String?	Card data source name. Human-readable card data source name
cardProcessingDetails	CardDetailsDto?	Card processing details. Detailed information about card processing
achProcessingDetails	ElectronicCheckDetails?	ACH (Electronic Check) processing details. Detailed information about ACH/electronic check processing
availableOperations	Array?	Available operations for this transaction. List of operations that can be performed on this transaction (e.g., Void, Refund, Capture)
avsResponse	AvsResponseDto?	AVS (Address Verification System) response. Response from address verification system
emvTags	EmvTagsDto?	EMV tags information. EMV (Europay, Mastercard, Visa) tag data from chip card transactions
tsysCardDetails	TsysCardDetailsDto?	TSYS card details. Additional card details specific to TSYS processor
achDetails	AchDetailsDto?	ACH details. Additional ACH transaction details

TransactionAmountDto

propertyName	Type	Description
baseAmount	Double?	Base transaction amount before any fees, surcharges, or tips. This is the original transaction amount entered by the merchant
percentageOffAmount	Double?	Percentage off amount. Discount amount calculated from percentage off rate
percentageOffRate	Double?	Percentage off rate. Discount rate as decimal (e.g., 0.10 for 10%)
cashDiscountAmount	Double?	Cash discount amount. Discount amount for cash payments
cashDiscountRate	Double?	Cash discount rate. Discount rate for cash payments as decimal (e.g., 0.05 for 5%)
surchargeAmount	Double?	Surcharge amount added to the base amount. Additional fee charged to the customer, typically calculated from surcharge rate
surchargeRate	Double?	Surcharge rate. Surcharge rate as decimal (e.g., 0.03 for 3%)
tipAmount	Double?	Tip amount. Gratuity amount added by the customer
tipRate	Double?	Tip rate. Tip rate as decimal (e.g., 0.15 for 15%)
totalAmount	Double?	Total transaction amount. Final amount including base amount, surcharges, tips, and discounts. This is the amount that will be charged to the customer

CardDetailsDto - TransactionDetails

propertyName	Type	Description
raw	Dictionary<String, Any>?	Raw card details data.

ElectronicCheckDetails - TransactionDetails

propertyName	Type	Description
raw	Dictionary<String, Any>?	Raw ACH details data. Placeholder for ACH details until full structure is defined

AvsResponseDto - TransactionDetails

propertyName	Type	Description
raw	Dictionary<String, Any>?	Raw AVS response data. Placeholder for AVS response until full structure is defined. Response from address verification system used to verify cardholder billing address

EmvTagsDto - TransactionDetails

propertyName	Type	Description
raw	Dictionary<String, Any>?	Raw EMV tags data. Placeholder for EMV tags until full structure is defined. EMV (Europay, Mastercard, Visa) tag data from chip card transactions

TsysCardDetailsDto

propertyName	Type	Description
raw	Dictionary<String, Any>?	Raw TSYS card details data. Placeholder for TSYS card details until full structure is defined. Additional card details specific to TSYS processor

AchDetailsDto

Property	Type	Description
customerAccountNumber	String?	Account number for ACH transaction
customerRoutingNumber	String?	Routing number
accountHolderType	AccountHolderType?	Account holder type (Personal/Business)
accountType	AccountType?	Account type (Checking/Savings)
taxId	String?	Tax identifier

CardTokenType - TransactionDetails

propertyName	Type	Description
local	Int	Card stored locally in merchant’s system. Raw value: 1
network	Int	Card stored on payment network (tokenized). Raw value: 2

CardholderAuthenticationMethod - TransactionDetails

propertyName	Type	Description
rawValue	Int	Cardholder authentication method with raw integer value (0-8). Represents the method used to authenticate the cardholder during transaction

CardDataSource - TransactionDetails

propertyName	Type	Description
rawValue	Int	Card data source with raw integer value (1-7). Represents the source of card data (e.g., Swipe, Chip, Contactless)

CardTransactionRequest

Input parameters for submitting an authorization transaction

Property	Type	Description
paymentProcessorId	String	Payment processor identifier
amount	Double	Transaction amount
currency	Currency	Currency for the transaction
cardDataSource	CardDataSource	Card data source
paymentMethodId	String?	Customer payment method ID
accountNumber	String?	Account number (card number)
expirationMonth	Int32?	Expiration month
expirationYear	Int32?	Expiration year
securityCode	String?	Security code (CVV/CVC)
track1	String?	Track 1 data
track2	String?	Track 2 data
emvTags	[String]?	EMV tags
emvPaymentAppVersion	String?	EMV payment application version
customerId	String?	Customer identifier
tipAmount	Double?	Tip amount
tipRate	Double?	Tip rate
percentageOffRate	Double?	Percentage off rate
surchargeRate	Double?	Surcharge rate
useCardPrice	Bool?	Use card price flag
billingAddress	AddressDto?	Billing address
shippingAddress	AddressDto?	Shipping address
contactInfo	ContactInfoDto?	Contact information
pin	String?	PIN
pinKsn	String?	PIN KSN (Key Serial Number)
emvFallbackCondition	EMVFallbackCondition?	EMV fallback condition
emvFallbackLastChipRead	EMVFallbackLastChipRead?	EMV fallback last chip read
referenceId	String?	Reference ID
customerInitiatedTransaction	Bool?	Customer initiated transaction flag

CardTransactionResponse

Result of authorization transaction submission

Property	Type	Description
transactionId	String?	Unique transaction identifier
transactionDateTime	Date?	Date and time of transaction execution
operationType	OperationType?	Transaction type
status	TransactionStatus?	Transaction status (e.g., approved, declined)
processedAmount	Double?	Processed amount
details	TransactionResponseDetailsDto?	Transaction response details
transactionReceipt	TransactionReceiptDto?	Transaction receipt
avsResponse	AvsResponseDto?	AVS (Address Verification System) response

CardDataSource - AuthRequest

Case	Description
rawValue

AddressDto

Address information structure

Property	Type	Description
line1	String?	Address line 1
line2	String?	Address line 2
city	String?	City
postalCode	String?	Postal code (ZIP code)
stateName	String?	State name
stateId	Int32?	State identifier
countryId	Int32?	Country identifier

ContactInfoDto

Contact information

Property	Type	Description
firstName	String?	First name
lastName	String?	Last name
companyName	String?	Company name
email	String?	Email address
mobileNumber	String?	Mobile phone number
smsNotification	Bool?	SMS notification enabled

EMVFallbackCondition

EMV fallback condition enumeration

Case	Description
iccTerminalError	ICC Terminal Error
noCandidateList	No Candidate List

EMVFallbackLastChipRead

EMV fallback last chip read enumeration

Case	Description
successful	Successful
failed	Failed
notAChipTransaction	Not A Chip Transaction
unknown	Unknown

TransactionResponseDetailsDto

Transaction response details

Property	Type	Description
hostResponseCode	String?	Host response code
hostResponseMessage	String?	Host response message
hostResponseDefinition	String?	Host response definition
code	String?	High-level operation response code
message	String?	Response message
processorResponseCode	String?	Processor response code
authCode	String?	Authorization code
maskedPan	String?	Masked PAN (Primary Account Number)

TransactionReceiptDto

Transaction receipt information

Property	Type	Description
transactionId	String?	Unique transaction identifier
transactionDateTime	Date?	Date and time when the transaction occurred
orderNumber	String?	Merchant order number
amount	TransactionAmountDto?	Complete amount information including base amount, surcharges, tips, discounts, and total amount
currency	Int32?	Currency for the transaction
currency	String?	Currency code
processorId	String?	Payment processor identifier
processor	String?	Payment processor name
operationTypeId	Int32?	Operation type identifier
operationType	String?	Operation type name
transactionType	TransactionType?	Transaction type (e.g., sale, auth)
paymentMethodType	PaymentMethodType ?	Payment method type
customerId	String?	Customer identifier
customerPan	String?	Customer PAN (Primary Account Number)
cardTokenType	CardTokenType?	Card token type
status	TransactionStatus?	Transaction status (e.g., approved, declined)
merchantName	String?	Merchant name
merchantAddress	String?	Merchant address
merchantPhoneNumber	String?	Merchant phone number
merchantEmailAddress	String?	Merchant email address
merchantWebsite	String?	Merchant website
authCode	String?	Authorization code
source	SourceResponseDto?	Transaction source information
responseCode	String?	Response code
responseDescription	String?	Response description
cardholderAuthenticationMethodId	CardholderAuthenticationMethod?	Cardholder authentication method identifier
cardholderAuthenticationMethod	String?	Cardholder authentication method name
cvmResultMsg	String?	CVM (Cardholder Verification Method) result message
cardDataSourceId	CardDataSource?	Card data source identifier
cardDataSource	String?	Card data source name
cardProcessingDetails	CardDetailsDto?	Card processing details
achProcessingDetails	ElectronicCheckDetails?	ACH (Electronic Check) processing details
availableOperations	[TransactionOperation]?	Available operations for this transaction
avsResponse	AvsResponseDto?	AVS (Address Verification System) response
emvTags	EmvTagsDto?	EMV tags information

CardTokenType - Receipt

Case	Description
local	Card stored locally in merchant's system
network	Card stored on payment network (tokenized)

CardholderAuthenticationMethod - Receipt

Case	Description
rawValue

CardDetailsDto - Receipt

Card details for a transaction

Property	Type	Description
raw	[String: Any]?	Raw card details data

ElectronicCheckDetails - Receipt

Electronic check (ACH) details

Property	Type	Description
raw	[String: Any]?	Raw ACH details data

TransactionOperation

propertyName	Type	Description
operationType	OperationType?	Transaction type
availableAmount	Double?	Available amount for this operation. Maximum amount that can be processed for this operation
suggestedTips	Array< SuggestedTipsDto>?	Suggested tip amounts. List of suggested tip amounts and percentages

AvsResponseDto - AuthResult-Receipt

AVS (Address Verification System) response

Property	Type	Description
raw	[String: Any]?	Raw AVS response data

EmvTagsDto - Receipt

EMV tags information

Property	Type	Description
raw	[String: Any]?	Raw EMV tags data

TransactionResponse

Property	Type	Description
transactionId	String?	Unique transaction identifier
transactionDateTime	Date?	Date and time when the transaction was performed
status	TransactionStatus?	Transaction status (e.g., approved, declined)
operationType	OperationType?	Transaction type

RefundRequest

CalculateAmountRequest

Property	Type	Description
amount	Double	Base transaction amount before any discounts or surcharges.
percentageOffRate	Double (optional)	Percentage-off or discount rate (e.g. 5.0 for a 5% discount).
surchargeRate	Double (optional)	Surcharge rate to apply (e.g. 3.0 for a 3% surcharge).
tipAmount	Double (optional)	Absolute tip amount to add on top of the base amount.
tipRate	Double (optional)	Tip rate expressed as percentage (e.g. 10.0 for a 10% gratuity).
currency	Currency	Currency for the transaction
useCardPrice	Bool (optional)	Indicates whether the provided amount represents the card price (true) or cash price (false) in Dual Pricing mode.

CalculateAmountResponse

Property Name	Type	Description
currency	Currency	Currency for the transaction
currency	String (optional)	Human-readable currency code (e.g. USD).
zeroCostProcessingOption	ZeroCostProcessingOption (optional)	Active Zero Cost Processing option
useCardPrice	Bool (optional)	Indicates whether card pricing was applied during calculation.
cash	AmountDto	Breakdown for cash payments, if available.
creditCard	AmountDto	Breakdown for credit card payments, if available.
debitCard	AmountDto	Breakdown for debit card payments, if available.
ach	AmountDto	Breakdown for ACH payments, if available.

Settings

PaymentSettingsResponse

Payment configuration settings for the merchant organization.

Property	Type	Description
availableCurrencies	[NamedOption]	Available currencies for transactions.
zeroCostProcessingOption	ZeroCostProcessingOption?	Active Zero Cost Processing option
defaultSurchargeRate	Double?	Default surcharge rate (as a percentage).
defaultCashDiscountRate	Double?	Default cash discount rate (as a percentage).
defaultDualPricingRate	Double?	Default dual pricing rate (as a percentage).
isTipsEnabled	Bool	Whether tips are enabled for transactions.
defaultTipsOptions	[Double]?	Default tip options (as percentages).
availableCardTypes	[NamedOption]	Available card types supported by the merchant.
availableTransactionTypes	[NamedOption]	Available transaction types supported by the merchant.
availablePaymentProcessors	[PaymentProcessor]	Available payment processors configured for the merchant.
avs	AvsOptions?	AVS configuration and settings.
isCustomerCardSavingByTerminalEnabled	Bool	Whether the terminal can save customer's card after transaction processing.
ttpIosTerminalProfileId	String?	Tap to Pay Terminal Profile ID for iOS devices.

ApiPermission

API permission types

Case	Description
posStartTransaction	POS: Start a transaction.
posGetTransactions	POS: Get transactions list.
posGetTransactionDetails	POS: Get transaction details.
posCancelTransaction	POS: Cancel a transaction.
posPrintReceipt	POS: Print receipt.
getTerminalList	Terminals: Get terminal list.
getTerminalInformation	Terminals: Get terminal information.
ecommerceAuth	eCommerce: Authorization.
ecommerceSale	eCommerce: Sale.
ecommerceCapture	eCommerce: Capture.
ecommerceVoid	eCommerce: Void.
ecommerceRefund	eCommerce: Refund.
ecommerceRefundWithoutReference	eCommerce: Refund without reference (unlinked refund).
achDebit	ACH: Debit.
achCredit	ACH: Credit.
achVoid	ACH: Void.
achHold	ACH: Hold.
achUnhold	ACH: Unhold.
listTransactions	Transactions: List transactions.
getTransactionDetails	Transactions: Get transaction details.
calculateTransactionAmount	Transactions: Calculate transaction amount.
submitTipAdjustment	Tips: Submit tip adjustment.
getSettlementBatches	Settlement: Get settlement batches.
submitBatchForSettlement	Settlement: Submit batch for settlement.
sendReceiptBySms	Receipts: Send receipt by SMS.
listCustomers	Customers: List customers.
getCustomerDetails	Customers: Get customer details.
manageCustomers	Customers: Manage customers (create/update/delete).
hostedInvoices	Hosted Solutions: Invoices.
hostedQuickPayment	Hosted Solutions: Quick Payment.
hostedSubscriptions	Hosted Solutions: Subscriptions.
hostedWebComponents	Hosted Solutions: Web Components.
hostedWooCommerce	Hosted Solutions: WooCommerce.
featureTapToPayOnMobile	Features: Tap to Pay on Mobile (required for Mobile SDK Tap to Pay integration).
generalPing	General: Ping.
generalStatus	General: Status.
generalConfigurations	General: Configurations.

ApiPermissionsResponse

Response containing list of enabled API permissions

Property	Type	Description
permissions	[ApiPermission]	List of enabled API permissions

AvsOptions

Address Verification System (AVS) options.

Property	Type	Description
isEnabled	Bool?	Whether AVS is enabled.
profileId	Int32?	AVS profile identifier.
profile	String?	AVS profile name (i.e., "Strict", "Moderate", “Tolerant”).

CurrencyOption

Currency option with identifier and name.

Property	Type	Description
id	Int32	Numeric currency identifier (ISO 4217).
name	String?	Currency code (e.g., "USD", "EUR").

NamedOption

Generic enum option with identifier and name. Generic structure for representing enumerated options with an identifier and optional name. Used for currencies, card types, transaction types, and other enumerated options.

Property	Type	Description
id	Int32	Numeric identifier.
name	String?	Readable name.

PaymentProcessor

Payment processor configuration.

Property	Type	Description
id	String?	Unique processor identifier (UUID).
name	String?	Processor name (e.g., "TSYS").
isDefault	Bool?	Whether this is the default processor.
operationType	OperationType?	Transaction type
settlementBatchTimeSlots	[SettlementBatchTimeSlot]?	Settlement batch time slots with timezone information.

SettlementBatchTimeSlot

Settlement batch time slot with timezone.

Property	Type	Description
hours	Int32?	Hours component of the time.
minutes	Int32?	Minutes component of the time.
timezoneName	String?	IANA timezone name (e.g., "America/New_York").

Devices

DevicesResponse

Property	Type	Description
devices	[DeviceInfo]	Flattened list of devices.

DeviceInfo

Property	Type	Description
deviceId	String	Device Id.
deviceName	String?	Device name.
lastLoginAt	Date?	Last login time.
tapToPayStatus	String?	Tap To Pay status text (e.g., Inactive, Requested).
tapToPayStatusId	Int?	Tap To Pay status identifier (0–4).
tapToPayEnabled	Bool	Indicates whether Tap To Pay feature is enabled.
userProfiles	[DeviceUser]	Profiles associated with this device.

DeviceUser

Property	Type	Description
id	String?	Unique identifier of the user profile.
firstName	String?	First name of the user.
lastName	String?	Last name of the user.
email	String?	Email address associated with the profile.

Tap to Pay

TTPCompatibilityResult

Property	Type	Description
isCompatible	Bool	Overall compatibility status.
deviceModelCheck	DeviceModelCheck	Device model compatibility check result.
iosVersionCheck	IOSVersionCheck	iOS version compatibility check result.
locationPermission	LocationPermissionStatus	Location permission status.
tapToPayEntitlement	TapToPayEntitlementStatus	Tap to Pay entitlement availability status.
incompatibilityReasons	[String]	List of reasons why the device is not compatible (empty if compatible is true).

DeviceModelCheck

Property	Type	Description
isCompatible	Bool	Whether the device model is compatible (iPhone XS or newer).
modelIdentifier	String	Device model identifier (e.g., "iPhone14,2").

IOSVersionCheck

Property	Type	Description
isCompatible	Bool	Whether the iOS version is compatible (iOS 18 or newer).
version	String	Current iOS version string (e.g., "18.0").
minimumRequiredVersion	String	Required minimum iOS version (e.g., "18.0").

LocationPermissionStatus

Case	Description
granted	Location permission has been granted.
denied	Location permission has been denied.
undetermined	Location permission status is undetermined (not yet requested).

TapToPayEntitlementStatus

Case	Description
available	Tap to Pay entitlement is available.
unavailable	Tap to Pay entitlement is unavailable.

TTPStatus

Case	Description
active	Tap to Pay is activated and ready to use.
inactive	Tap to Pay is not activated.

TTPCVMData

Property	Type	Description
tag	String?	CVM tag identifier.
value	String?	CVM tag value.

TTPTransactionRequest

Property	Type	Description
amount	Decimal	Transaction amount.
tip	String?	Tip amount as string (optional).
discount	String?	Discount amount as string (optional).
subTotal	String?	Subtotal amount as string (optional).
orderId	String?	Order identifier (optional).
surchargeRate	String?	Surcharge rate as string (optional).

TTPTransactionResult

Property	Type	Description
transactionId	String?	Transaction identifier from the payment processor.
transactionOutcome	String?	Transaction outcome (APPROVED, DECLINED, etc.).
status	TTPTransactionStatus	Transaction status derived from transactionOutcome.
orderId	String?	Order identifier.
authorizedAmount	String?	Authorized amount as string.
authorizationCode	String?	Authorization code from the payment processor.
authorisationResponseCode	String?	Authorization response code (British spelling).
authorizedDate	String?	Authorized date as string.
authorizedDateFormat	String?	Format of the authorized date.
cardBrandName	String?	Card brand name (e.g., Visa, Mastercard).
maskedCardNumber	String?	Masked card number (last 4 digits).
externalReferenceID	String?	External reference ID.
applicationIdentifier	String?	Application identifier.
applicationPreferredName	String?	Application preferred name.
applicationCryptogram	String?	Application cryptogram.
applicationTransactionCounter	String?	Application transaction counter.
terminalVerificationResults	String?	Terminal verification results.
issuerApplicationData	String?	Issuer application data.
applicationPANSequenceNumber	String?	Application PAN sequence number.
partnerDataMap	[String: String]?	Partner data map.
cvmTags	[TTPCVMData]?	CVM tags.
cvmAction	String?	CVM action.

TTPTransactionStatus

Case	Description
approved	Transaction was approved by the payment processor.
declined	Transaction was declined by the payment processor.
cancelled	Transaction was cancelled by the user or system.
failed	Transaction failed due to an error.

TTPEvent

Case Name	Associated Value	Description
.readerEvent	TTPReaderEvent	Low-level events from the card reader. These events come directly from the ProximityReader framework and represent physical card reader state changes and progress updates.
.customEvent	TTPCustomEvent	High-level business logic events from the SDK. These events represent transaction lifecycle and business logic states.

TTPReaderEvent

Case Name	Associated Value	Description
.updateProgress	Int	Progress update during firmware update or initialization.
.notReady	-	Reader is not ready.
.readyForTap	-	Reader is ready for card tap.
.cardDetected	-	Card has been detected.
.removeCard	-	Card should be removed.
.readCompleted	-	Card read completed successfully.
.readRetry	-	Card read failed, retry needed.
.readCancelled	-	Card read was cancelled.
.pinEntryRequested	-	PIN entry requested on reader.
.pinEntryCompleted	-	PIN entry completed.
.userInterfaceDismissed	-	User interface was dismissed.
.readNotCompleted	-	Reader interface not completed.

TTPCustomEvent

Case Name	Associated Value	Description
.preparing	-	Terminal is preparing.
.ready	-	Terminal is ready.
.readerNotReady	String	Reader is not ready.
.cardDetected	-	Card has been detected.
.cardReadSuccess	-	Card read succeeded.
.cardReadFailure	-	Card read failed.
.authorizing	-	Payment is being authorized.
.approved	-	Transaction was approved.
.declined	-	Transaction was declined.
.errorOccurred	-	An error occurred during the transaction.
.inProgress	-	Transaction is in progress.
.updateReaderProgress	Int	Reader progress update.
.unknownEvent	String	Unknown event.

Error Handling

The ARISE Mobile SDK can throw three main error types to handle different categories of errors:

• AriseApiError: Errors that occur during API operations (network errors, HTTP errors, validation errors) • TTPError: Errors specific to Tap to Pay operations (activation failures, transaction errors, reader errors) • authenticationError: Errors that occur during authentication operations (invalid credentials, token expiration)

All error types conform to Swift's Error and LocalizedError protocols, providing consistent error handling across the SDK.

AriseApiError

Errors that can occur during API operations. Centralized error handling for all ARISE API clients.

Error Name	Error Code	Description	Recovery Strategy
badRequest	400	The request was malformed or contained invalid parameters.	Please verify the request parameters and try again.
unauthorized	401	Authentication is required or the access token is invalid or expired.	Please call authenticate() method to obtain a valid access token.
forbidden	403	You do not have permission to perform this action.	You do not have permission to perform this action. Please check your access rights.
notFound	404	The requested resource does not exist.	You are trying to access a resource that does not exist. Please verify the resource identifier.
serverError	500	The server encountered an error while processing the request.	The server encountered an error. Please try again after a short delay.
unknown	N/A	An unexpected error occurred that doesn't match any known error type.	An unexpected error occurred. Please try again or contact support if the issue persists.
invalidResponse	N/A	The server returned an unexpected response format.	The server returned an unexpected response. This may indicate an API change or a temporary server issue.
networkError	N/A	A network error occurred (connection timeout, no internet, etc.).	Check your internet connection and try again.

TTPError

Errors that can occur during Tap to Pay operations.

Error Name	Error Code	Description	Recovery Strategy
notCompatible	N/A	Thrown when the device fails one or more compatibility checks required for Tap to Pay.	Check the incompatibilityReasons array to identify specific issues For location permission: Request location permission in your app before calling activate(). The SDK does not request permissions — this is the app's responsibility For device/iOS version: Inform the user that their device does not support Tap to Pay For entitlement issues: Verify the device supports Tap to Pay hardware (NFC capability)
notActive	N/A	Tap to Pay is not activated on the device. The status is not active.	Call activate() method to activate Tap to Pay. This may show Apple's terms and conditions screen.
sdkNotInitialized	N/A	The Tap to Pay SDK is not initialized.	Ensure the SDK is properly initialized before calling Tap to Pay methods.
configurationFailed	TTP Error Code	Failed to configure the Tap to Pay SDK with merchant information.	Check that all required merchant configuration (company name, MCC code, currency code, country code) is available in payment settings.
activationFailed	TTP Error Code	Failed to activate Tap to Pay. This may occur during the activation workflow.	Check device compatibility, ensure Apple Terms & Conditions are accepted, and verify merchant configuration. Try calling activate() again.
transactionFailed	TTP Error Code	The Tap to Pay transaction failed. This can occur due to card reader errors, payment processing errors, or other transaction-related issues.	Check the error code and message for specific details. Ensure the card is properly positioned, the reader is ready, and the transaction amount is valid.
failedToAbortTransaction	TTP Error Code	Failed to abort an in-progress transaction. This typically occurs when card reading has already begun.	The transaction cannot be aborted because card reading has already begun. The transaction will complete normally.
unknown	TTP Error Code	An unknown error occurred during a Tap to Pay operation.	Check the error code and message for specific details. If the issue persists, contact support.

TTP Error Codes

Error Code	Message	Description	Recoverable	Use case for error occurrence	Possible resolution
DEV003	The device does not support Tap to Pay on iOS device.	-	No	When a device does not support Tap to Pay on an iOS device. Currently requires iPhone Xs or later.	Try a different device.
GPS003	The device could not be located. Move to a location where a GPS signal can be received	-	Yes	Configure method or Resume Session method.	Restart the app. If not resolved, then contact customer care. This error is also known to be thrown when the ARISE Mobile SDK is not initiated in the main thread. Check the Init section for details and examples for proper SDK initialization.
GPS005	Partner is not allowed to operate in the current country.	-	Yes	Configure method or Resume Session method.
GPS006	The device could not be located. Move to a location where the GPS signal can be received.	-	Yes	Configure method or Resume Session method.
ATT018	Unable to connect to the server. Please try again later.	A failed attempt to contact the App Attest service during an attestation.	Yes	Configure method, Resume, or Perform Transaction methods.	If the user is logged in, try logging out and log in back in. Alternatively, reinstall the app.
ATT019	The app is missing a team identifier.	Team Identifier not available.	Yes	Configure method, Resume, or Perform Transaction methods.	Specify the team identifier in the information list.
ATT020	The app is missing a bundle identifier.	Bundle Identifier not available.	Yes	Configure method, Resume, or Perform Transaction methods.	Verify the info.plist file, specifically the CFBundleShortVersionString.
ATT021	Attestation failed. Please try again.	A one-time challenge from the server is missing, required reduce the risk of replay attacks.	Yes	Configure method, Resume, or Perform Transaction methods.	If the user is logged in, try logging out and log in back in. Alternatively, reinstall the app.
ATT022	Attestation failed. Please try again	The App Attest Service rejects the KeyId. This occurs if there is an issue with generating, retrieving, or using an App Attest cryptographic key.	Yes	Configure method, Resume Session, or Perform Transaction methods.	If the user is logged in, try logging out and log in back in. Alternatively, reinstall the app.
ATT023	Attestation failed. Please try again.	Possible Issues: The app may provide incorrectly formatted data, fail to generate a token, or be unable to access Device Check on this device.	Yes	Configure method, Resume Session, or Perform Transaction methods.	If the user is logged in, try logging out and log in back in. Alternatively, reinstall the app.
ATT024	Attestation failed. Please try again.	App Attestation Service not initialized properly.	Yes	Configure method, Resume Session, or Perform Transaction methods.	If the user is logged in, try logging out and log in back in. Alternatively, reinstall the app.
DATA001	The requested object is not found.	Request object JSON is not valid	No	_	Check the request object parameters and their expected value.
DATA002	Invalid request	Request object. JSON is not valid	No	-	Check the request object parameters and their expected value.
DATA003	Malformed JSON Request	Request object. JSON is not valid	No	-	Check request object parameters and their expected value.
DATA005	Access denied	Attestation for the device has failed in the past or device linked with POS instance does not match with the device making the request.	No	-	Contact customer care.
DATA008	Error storing information. Please try again.	Keychain data storage error	Yes	Configure method or Clear Session methods.	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
DATA009	Error removing information. Please try again.	Keychain data deletion error	Yes	Configure method or Clear Session methods.	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
DATA010	Error occurred.	Keychain security key error	Yes	Configure method or Clear Session methods.	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
DATA011	Null or empty value encountered.	The encryption algorithm is empty	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
DATA012	Unexpected or empty value is encountered.	Server response error when JSON decoded	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
CRYPTO001	Something went wrong on our end. Please try again.	Data from public key get failed once performing Certificate pinning.	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
CRYPTO002	Something went wrong on our end. Please try again.	JWT decoder or JSON error	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
CRYPTO003	Something went wrong on our end. Please try again.	Private key attributes error	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
CRYPTO004	Something went wrong on our end. Please try again.	Payload data decryption error.	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
CRYPTO005	Something went wrong on our end. Please try again.	Public key not found.	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
CRYPTO006	Something went wrong on our end. Please try again.	Unsupported encrypted algorithm.	Yes	-	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
SEC005	Sorry, something went wrong at our end. Please try again.	Public key expired.	Yes	Configure method, Perform Transaction, and Resume Session methods.	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
SEC008	A potential security concern has been identified. Please install the application on another device or contact customer support.	Security protection error.	No	Configure method, Perform Transaction, and Resume Session methods.	Reinstall the application on your device and contact customer care.
SEC001	Authentication token expired.	Authentication token expired.	Yes	Configure method, Perform Transaction, and Resume Session methods.	Ask for re-login.
DEC_04	We could not validate the information. Please try again.	Certificate chain is invalid when fetched from public key data	Yes	-	Ask for re-login.
MER003	Merchant configuration not found.	-	No	Configure method.	Contact customer care.
MER004	Merchant display name not found.	-	No	Configure method.	Contact customer care.
MER005	Merchant category code not found.	-	No	Configure method.	Contact customer care.
MER006	Terminal Profile ID not found.	-	No	Configure method.	Contact customer care.
MER007	Merchant currency code not found.	-	No	Configure method.	Contact customer care.
MER008	Merchant country code not found.	-	No	Configure method.	Contact customer care.
EC_02	Some error occurred. Please try again later.	Some internal error occurs at the server.	Yes	Configure method, Perform Transaction, and Resume Session methods.	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
EC_500	Internal Server Error.	Some internal error occurs at the server.	Yes	Configure method, Perform Transaction, and Resume Session methods.	Try again after some time. If the issue continues after multiple attempts, contact customer care for assistance.
EC_502	Bad Gateway	The origin server did not send a valid response to the API Gateway.	Yes	Configure method, Perform Transaction, and Resume Session methods.	Ask the user to try again.
EC_503	Service temporarily unavailable.	Origin server not available.	Yes	Configure method, Perform Transaction, and Resume Session methods.	Ask the user to try again.
EC_504	Gateway time-out	The origin server did not send a valid response to the API Gateway.	Yes	Configure method, Perform Transaction, and Resume Session methods.	Ask the user to try again.
AUTH_001	Unauthorized or authentication Error	This can occur if the JWT is expired or invalid.	Yes	-	Provide a valid JWT authorization token.
MISSING_REQUIRED_FIELD	Missing required field subMerchantId/displayName.	The request is invalid.	No	For the Payment Gateway - Delegated model, this is a mandatory field.	Provide sub merchantId/displayName for Payment Gateway - Delegated model.
PARTNER_UNAUTHORIZED	We are sorry, but this partner does not currently support the operating system. Please contact your partner for assistance.	-	No	There is no support for the iOS Operating system.	Please contact your partner for assistance.

AuthenticationError

Errors that can occur during authentication operations.

Error Name	Error Code	Description	Recovery Strategy
invalidCredentials	N/A	The provided client credentials (clientId and clientSecret) are invalid.	Verify that the clientId and clientSecret are correct. Ensure credentials are not expired or revoked.
networkError	N/A	A network error occurred during authentication (connection timeout, no internet, etc.).	Check your internet connection and try again.
invalidResponse	N/A	The authentication server returned an invalid or unexpected response.	The server returned an unexpected response. This may indicate an API change or a temporary server issue. Try again after a short delay.
tokenExpired	N/A	The access token has expired.	Call refreshAccessToken() to obtain a new access token, or call authenticate() again with valid credentials.
unknown	N/A	An unknown error occurred during authentication.	An unexpected error occurred. Please try again or contact support if the issue persists.

PaymentCardReaderError

Errors that can be thrown by iOS ProximityReader framework.

Error Name	Error Code	Description	Recovery Strategy
ProximityReader.PaymentCardReaderError error 0	Error 0 (notAllowed)	Error 0 (notAllowed) in ProximityReader means the system has blocked the Tap to Pay session. This usually happens because the app's configuration, merchant account, or Apple ID environment doesn't match the required security or entitlement settings.	Check Entitlements: Ensure com.apple.developer.proximity-reader.payment.acceptance is in your .entitlements file and active in the Apple Developer Portal. Match Environments: Use a Sandbox Apple ID (not a real one) for non-production testing to avoid environment conflicts. Verify Device: Ensure you are using an iPhone XS or later, it has a passcode enabled, and the region is supported.