Instore Card Authorisation

Overview

An Authorisation transaction is essential for securing funds before the final payment in various physical settings. This process involves the real-time, immediate pre-authorization of a customer's credit or debit card at the point of sale, which temporarily reserves the transaction amount but does not yet complete the purchase. This method is particularly useful in environments such as hotels, car rental agencies, and other scenarios where the final amount may not be known upfront. By using an authorisation transaction, merchants can ensure that sufficient funds are available on the customer's card, providing confidence that the full amount can be captured and settled at a later stage. This transaction type is crucial for businesses that require a guarantee of payment while offering flexibility to adjust the final charge.

Create an Instore Card Authorisation Transaction Request

{
  "pointOfInteraction": {
    "pointOfSaleId": "001",
      "culture": "en",
      "credentials": {
        "username": "User1",
        "password": "Password"  
      }
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00", 
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "entryType": "Instore",
    "fundingType": "Card",
    "intent": "Authorisation"
  }  
}

// Import necessary classes
import com.pxpfinancial.sdk.pos.TransactionRequest
import com.pxpfinancial.sdk.pos.PointOfInteraction
import com.pxpfinancial.sdk.pos.Amounts
import com.pxpfinancial.sdk.pos.TransactionMethod
import java.text.SimpleDateFormat
import java.util.Date

// Define the AnyPayCredentials data class
data class AnyPayCredentials(
    val username: String,
    val password: String
)

// Define merchant and transaction details
val merchant = "MERCHANT-1"
val site = "SITE-1"
val merchantTransactionId = "This_is_my_merchant_transaction_id"
val merchantTransactionDate = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSXXX").format(Date())

// Create an instance of AnyPayCredentials
val anyPayCredentials = AnyPayCredentials(
    username = "PxpUser",
    password = "PxpPassword"
)

// Point of Interaction details with AnyPayCredentials object
val pointOfInteraction = PointOfInteraction(
    pointOfSaleId = "001",
    culture = "en",
    anyPayCredentials = anyPayCredentials // Include the credentials object here if processing through the AnyPay Gateway
)

// Transaction amount details
val amounts = Amounts(
    currencyCode = "GBP",
    transaction = 20.00
)

// Create an instance of TransactionMethod
val transactionMethod = TransactionMethod(
    entryType = "Instore",
    fundingType = "Card",
    intent = "Authorisation"
)

// Function to build transaction request
fun buildTransactionRequest(): TransactionRequest {
    return TransactionRequest(
        merchant = merchant,
        site = site,
        pointOfInteraction = pointOfInteraction,
        merchantTransactionId = merchantTransactionId,
        merchantTransactionDate = merchantTransactionDate,
        amounts = amounts,
        transactionMethod = transactionMethod // Add the transactionMethod object here
    )
}

Handle an Instore Card Authorisation Transaction Response

After processing an instore card purchase, you'll receive a response containing several key fields.

// Import necessary classes
import com.pxpfinancial.sdk.pos.TransactionResponse
import kotlinx.coroutines.*
import java.text.SimpleDateFormat
import java.util.Date

// Function to handle transaction response
private fun handleTransactionResponse(response: TransactionResponse?) {
    response ?: run {
        println("Transaction timed out or no response received.")
        return
    }

    // Accessing fields in the base response
    val state = response.state
    val approvalCode = response.approvalCode
    val merchantOrderId = response.merchantOrderId
    val merchantTransactionId = response.merchantTransactionId
    val systemTransactionId = response.systemTransactionId
    val providerTransactionId = response.providerTransactionId
    
    // Accessing fields in card response
    val cardScheme = response.card.cardScheme
  	val cardScheme = response.card.gatewayTokenId  
  	
    // Accessing fields in provider response
    val provider = response.provider.provider
    val providerCode = response.provider.code
    val providerMessage = response.provider.message
  	
  	// Accessing fields for receipt data
    val merchantId = response.receiptData.merchantId
    val terminalId = response.receiptData.terminalId  
  	val entryTye = response.receiptData.entryType
    val maskedPrimaryAccountNumber = response.receiptData.maskedPrimaryAccountNumber
  	val expiryDateMonth = response.receiptData.expiryDateMonth
  	val expiryDateYear = response.receiptData.expiryDateYear
  	val holderName = response.receiptData.holderName    
  	val applicationId = response.receiptData.applicationId
  	val applicationLabel = response.receiptData.applicationLabel  
  	val preferredName = response.receiptData.preferredName	
  	val cardVerificaitonResults = response.receiptData.terminalVerificationResults	
  
    // Additional business logic based on the transaction state
    when (state) {
        "Authorised" -> {
            // Handle authorised transaction
            println("Transaction authorised successfully.")
            // Perform further actions like updating UI, saving transaction details, etc.
        }
        "Declined" -> {
            // Handle declined transaction
            println("Transaction declined.")
            // Perform actions based on the declined state
        }
        else -> {
            // Handle other transaction states if necessary
            println("Transaction state: $state")
        }
    }
}

// Simulated usage of request and response handling
fun main() {
    // Build transaction request
    val transactionRequest = buildTransactionRequest()

    // Simulate async processing and response handling
    CoroutineScope(Dispatchers.Default).launch {
        val pxpPosSdk = com.pxpfinancial.sdk.pos.Transaction("http://127.0.0.1:8080", "YOUR_API_KEY")

        // Process the transaction
        val result = withTimeoutOrNull(10000L) { // 10 seconds timeout
            suspendCancellableCoroutine<TransactionResponse?> { continuation ->
                pxpPosSdk.processTransaction(transactionRequest) { response ->
                    continuation.resume(response, onCancellation = null)
                }
            }
        }

        // Handle the transaction response
        handleTransactionResponse(result)
    }
}