Cards & Wallets · Mobile SDK

Payment Setup

Configure the payment, create the payment processor and wire up its callbacks before presenting any payment method.

Environment

There are currently only two environments: MITE (test) and LIVE. You choose between them in two steps:

Use your environment-specific credentials (username, password, installationId) to generate your authentication (client) token.
Set the Environment enum inside the PaymentConfig to that environment.

Available enums: Environment.TEST or Environment.LIVE (lowercase for iOS).

Payment Config

To set up a payment and its details, you need to create a data class called PaymentConfig:

Parameter	Description
`installationId`	Your installationId received in the setup
`countryCode`	(Nullable) The country code of the transaction. It might enable some payment methods in specific countries. Country code format: ISO 3166 ALPHA-3 (e.g. `GBR`).
`currencyCode`	The currency code of the transaction. Currency code format: ISO 4217 ALPHA-3 (e.g. `GBP`).
`transactionType`	The type of transaction: TransactionType.PAYMENT or TransactionType.AUTHORIZATION. PAYMENT should be used for any and all transactions that will result in money being deducted; AUTHORIZATION should be used when you only want to verify the cardholder’s card information to make sure it is valid.
`clientToken`	Your client token obtained earlier
`transaction.amount`	The transaction amount, as a double. Can be set to 0.00 for verification.
`transaction.currency`	The same transaction currency code (equal to currencyCode)
`transaction.merchantRef`	The merchant reference of the transaction (e.g. "Order_123"). Recommended to be unique; it can be used to identify the transaction afterwards.
`transaction.recurring`	Set this field if you want to start a recurring Continuous Authority relationship from this transaction. Possible values: `true`, `false`, `null`. If the value is not `null`, make sure you define the continuous authority agreement of the transaction.
`transaction.deferred`	Use the “deferred” indicator with the payment request to indicate that you only want to perform an authorisation. Possible values: `true`, `false`, `null`.
`transaction.continuousAuthorityAgreement`	The continuous authority agreement of the transaction.
`customer.email`	The customer’s email address
`customer.dob`	Date of birth, formatted as `YYYYMMDD`
`customer.telephone`	The customer’s telephone number
`customer.customerRef`	Your unique customer reference. This reference can be used to identify the customer and their details, while also verifying the transactions made under it.
`customer.registered`	Indicates whether the customer is registered with the merchant. If set to true, the `customerRef` field is mandatory. If set to false, `customerRef` is not required but is supported, and can be used to store a reference to the customer without registering them. Default value: `null` — setting to null keeps the previous behaviour, meaning the `customerRef` field is available only if the payment is going through a registered customer.
`financialServices.dateOfBirth`	Date of birth of the loan recipient, in `YYYYMMDD` format. For example, for 2 Jan 1980 this would be “19800102”.
`financialServices.surname`	Surname of the loan recipient; up to six characters, excluding numbers or special characters. If the name is longer than six characters, provide the first six.
`financialServices.accountNumber`	Account number used to identify the customer or loan. If this is a PAN, provide the first six and last four digits of the PAN.
`financialServices.postCode`	First part of the postal code of the loan recipient; up to six characters. For example, if the postal code is “EC2A 1AE”, this would be “EC2A”.
`environment`	Payment environment: `TEST` or `LIVE`

Kotlin

import com.accesspaysuite.mobilesdk.PaymentConfig

val myPaymentConfig = PaymentConfig(
  installationId = installationId,
  countryCode = "GBR",
  currencyCode = "GBP",
  transactionType = TransactionType.PAYMENT,
  clientToken = clientToken,
  transaction = TransactionDetails(
      amount = 10.0,
      currency = "GBP",
      merchantRef = "Test_order",
      recurring = false,
      deferred = false,
      continuousAuthorityAgreement = null
  ),
  customer = CustomerDetails(
      email = "[email protected]",
      dob = "19870818",
      telephone = "0123 456 789",
      customerRef = "your_unique_customer_ref"
      registered = true,
  ),
  financialServices = FinancialDetails(
      dateOfBirth = "19870818",
      surname = "John",
      accountNumber = "1234561234",
      postCode = "EC2A"
  ),
  environment = Environment.TEST
)

Payment Processor setup

The setup is required to register all the necessary callbacks: when the user enters a card successfully or not, if the payment method is cancelled by the user, and if the payment result was a success or a failure and why.

Android

The only difference between the Android and iOS setup is the Android Context in the constructor of the payment processor.

Create the PaymentProcessor

Kotlin

val processor = PaymentProcessor(
  config = myPaymentConfig,
  context = context // The Android Context
)

Payment result callback

Kotlin

processor.setPaymentResultCallback(
  object : PaymentResultCallback {
      override fun onPaymentResult(status: Status) {
          when (status) {
              Status.Canceled -> {
                  // User canceled the payment method
                  // This usually happens when the user proceeds the Google/Apple Pay process but cancels before completing.
              }

              is Status.Error -> {
                  // Payment method failed
                  val error = status.message
                  val traceId = status.traceId
                  // Trace id can be sent over for further information about the error.
              }

              Status.SessionExpired -> {
                  // Session expired
              }

              Status.Success -> {
                  // Payment was successful
              }

              else -> {
                  // Handle unknown cases
              }
          }
      }
  }
)
// OR
processor.setPaymentResultCallback(
  onPaymentSuccess = {
      // Payment was successful
  },
  onPaymentFailed = { error, traceId ->
      // Payment method failed
      // If session expires, then the error argument will be "Session expired"
  },
  onPaymentMethodCanceled = {
      // User canceled the payment method
  }
)

Card submission callback

Kotlin

// This callback can be used to control your UI to respond
// properly when the Cardholder information is complete or
// contains errors
processor.setCardCallback(
  onCardSubmittedSuccessfully = {
      // Card submitted successfully
  },
  onCardSubmittedWithErrors = { errors ->
      // Card submitted with errors

      // All errors mapped to a single string
      val errorsToString = errors.mapToString(separator = "\n")
  }
)

Payment initiation

Required before attempting any payment methods.

Kotlin

processor.initiate {
  if (status == Status.Initiated) {
      // Initiated successfully
  } else {
      // Could not initiate
      // Can be casted as Status.Error for further details
  }
}

Compose Multiplatform

Kotlin

// The PaymentProcessor for Compose does not require any extra setup
// The initiate process is called after declaration
val processor = rememberPaymentProcessor(
  paymentConfig = myPaymentConfig,
  onPaymentSuccess = {
      // Payment was successful
  },
  onPaymentFailed = { reason, traceId ->
      // Payment method failed
      // If session expires, then the error argument will be "Session expired"
  },
  onPaymentMethodCanceled = {
      // User canceled the payment method
  },
  onCardSubmittedSuccessfully = {
      // Card submitted successfully
  },
  onCardSubmittedWithErrors = { errors ->
      // Card submitted with errors
  },
  onInitiate = { status ->
      if (status == Status.Initiated) {
          // Initiated successfully
      } else {
          // Could not initiate
      }
  }
)

iOS

Create the PaymentProcessor

Swift

var processor = PaymentProcessor(config: paymentConfig)

Payment result callback

Swift

processor.setPaymentResultCallback {
  // Success
} onPaymentFailed: { reason, traceId in
  // Failed
  // traceId is a nullable String
} onPaymentMethodCanceled: {
  // Method canceled
}
// OR
processor.setPaymentResultCallback(callback: <any PaymentResultCallback>)

Card submission callback

Swift

// This callback can be used to control your UI to respond
// properly when the Cardholder information is complete or
// contains errors
processor.setCardCallback {
  // Card submitted successfully
} onCardSubmittedWithErrors: { errors in
  // Card has errors
}

Payment initiation

Required before attempting any payment methods.

Swift

processor.initiate { status in
  if (status is Status.Initiated) {
      // Initiated successfully
  } else {
      // Could not initiate
      // Can be casted as Status.Error for further details
  }
}

Card Management

Card Management is a page where you can let the user manage their own saved cards. The implementation requires an access token with an additional scope — see Authentication Token. This is how you start the Card Management page:

Android (Kotlin)

Kotlin

val intent: Intent = CardManagementPage.createManagementPage(
  context = androidContext,
  authToken = myAuthToken,
  installationId = myInstallationId,
  customerReference = myCustomerReference,
  environment = mobileSDKEnvironment
)
if (context !is Activity) {
  intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}
context.startActivity(intent)

iOS

Swift

let page = CardManagementPage()
// Setup the card management
page.setCredentials(
  myAuthToken,
  myInstallationId,
  myCustomerReference
)
page.setCustomerReference(customerReference = customerRef)
// Display the card management
page.display()