Skip to content
Tap+/
/
Card transaction

Card transaction

Process an in-store (card present) transaction.

Initiate a transaction

Request examples

Use the following requests to initiate a card transaction on a point-of-sale device.

val authRequest = TransactionRequest(
 merchantTransactionId = "Purchase-001", 
 merchantTransactionDate = OffsetDateTime.now(), 
 pointOfInteraction = PointOfInteraction( 
   pointOfSaleId = "001", 
   language = "en", 
   storeAndForwardType = StoreAndForwardType.None 
 ), 
 amounts = Amounts(
   currencyCode = "GBP",
   transaction = BigDecimal("100.00"),
   gratuity = BigDecimal(0)
 ),
 transactionMethod = TransactionMethod( 
   intent = IntentType.Authorisation 
 ), 
 merchantDeeplink = "app://merchantsimulator/main"
)
ParameterDescription
merchantTransactionId
string (≤ 50 characters)		A unique identifier for this transaction.
merchantTransactionDate
OffSetDateTime		The date and time when the transaction happened, in ISO 8601 format.
pointOfInteraction
PointOfInteraction		Details about the device and environment where a card present transaction takes place. It includes various attributes that help identify and describe the capabilities and configurations of the point of sale (POS) device.
pointOfInteraction.pointOfSaleId
string		The unique identifier for the specific point of sale device, often assigned by the merchant or payment processor.
pointOfInteraction.language
string		The display language, in ISO 639-1 format.
pointOfInteraction.storeAndForwardType
TBD		Store and Forward is a mechanism used for handling transactions when the merchant's connection to the PXP gateway is disrupted. It securely stores transactions offline until communications are re-established with the gateway.

Possible values:
  • None: Default behaviour. Transactions require immediate online authorisation. If the network is unavailable, the transaction will be declined.
  • StoreAndForward: Used when the merchant is configured for transactions that fail to reach the PXP gateway. Transactions are securely stored offline until communication with the gateway is re-established.
  • ForceStoreAndForward: Forces the transaction to be processed in offline mode. The transaction data is stored locally and will be forwarded to the gateway when connectivity is restored. This option should be used with caution as it carries the risk of later declined transactions.
amounts
object		Details about the transaction amount.
amounts.currencyCode
string		The currency code associated with the transaction, in ISO 4217 format.
amounts.transaction
BigDecimal		The transaction amount.
amount.gratuity
BigDecimal		The optional gratuity amount.
transactionMethod
object		Details about the transaction method.
tansactionMethod.intent
IntentType		The payment intent.

Possible values:
  • Authorisation
  • EstimatedAuthorisation
  • Purchase
  • Refund
merchantDeeplink
string		The URL that the SDK will navigate back to upon transaction completion, if applicable. For more information, see Callback navigation.

Response example

If your request is successful, you'll receive a response that includes the transaction's updated state.

structureTransactionResponse(
  state = "Authorised",
  stateData = StateData(
    code = "Success",
    message = "Transaction successful"
	),
  approvalCode = "123456",	
  merchantTransactionId = "MERCH-001",
  merchantTransactionDate = "2024-03-19T10:30:00Z",
  systemTransactionId = "PXP-123456789",
  providerTransactionId = "PROV-987654321",
  fundingData = FundingData(
    maskedPrimaryAccountNumber = "************1234",
    expiryMonth = "12",
    expiryYear = "2025",
    cardScheme = "Visa",
    gatewayTokenId = "123e4567-e89b-12d3-a456-426614174000",
    emvDataResponse = EmvDataResponse(
      applicationId = "A0000000031010",
      applicationLabel = "VISA CREDIT",
      authorisationResponseCode = "00",
      cardHolderVerificationMethodResults = "410000",
      panSequenceNumber = "01",
      preferredName = "VISA CREDIT"
    ),
    providerResponse = ProviderResponse(
      provider = "PROVIDER_NAME",
      code = "00",
      message = "Approved",
      merchantId = "MERCH123",
      terminalId = "TERM456",
      paymentAccountReference = "PAR-123456",
      schemeTransactionId = "VISA-789012"
    )
  )
)
PropertyDescription
state
string		The current state of the transaction.

Possible values:
  • Authorised
  • Captured
  • Cancelled
  • Error
  • Refused
stateData
object		Details about the state.
stateData.code
string		The state code.
stateData.message
string		The state message.
approvalCode
string		A unique identifier code provided by the authorising entity, indicating approval or reference for the transaction. This code typically consists of alphanumeric characters, starting with an uppercase letter, and serves as a key reference for authorisation verification.
merchantTransactionId
string		The merchant transaction ID.
merchantTransactionDate
date-time		The date and time when the transaction happened, in ISO 8601 format.
systemTransactionId
string		The system transaction ID.
providerTransactionId
string		The transaction ID set by the provider.
fundingData
object		Details about the funding method.
fundingData.maskedPrimaryAccountNumber
string		The masked primary account number.
fundingData.expiryMonth
string		The card's expiry month (MM).
fundingData.expiryYear
string		The card's expiry year (YYYY).
fundingData.cardScheme
string		The card scheme.
fundingData.gatewayTokenId
string		The gateway token ID.
fundingData.emvDataResponse
object		Details about the EMV (Europay, Mastercard, and Visa) response.
fundingData.emvDataResponse.applicationId
string		EMV tag 9F06: a unique identifier for the application, according to ISO/IEC 7816-5.
fundingData.emvDataResponse.applicationLabel
string		EMV tag 50: a mnemonic associated with the Application Identifier (AID) according to ISO/IEC 7816-5.
fundingData.emvDataResponse.authorisationResponseCode
string		The authorisation response code.
fundingData.emvDataResponse.cardHolderVerificationMethodResults
string		EMV tag 9F34: the results of the last cardholder verification method performed.
fundingData.emvDataResponse.panSequenceNumber
string		EMV tag 5F34: the PAN sequence number, which identifies and differentiates cards with the same PAN.
fundingData.emvDataResponse.preferredName
string		The preferred name of the application as designated by the card issuer.
providerResponse
object		Details about the provider response.
providerResponse.provider
string		The name of the provider that processed the transaction.
providerResponse.code
string		The raw result code returned by the provider that processed the transaction.
providerResponse.message
string		The raw message associated with the result code from the provider that processed the transaction.
providerResponse.merchantId
string		The unique identifier assigned to you by the provider.
providerResponse.terminalId
string		The unique identifier assigned to the terminal by the provider.
providerResponse.paymentAccountReference
string		The unique identifier assigned to a payment account, independent of the card number. It remains constant over the account's lifetime, even if the card number (PAN) changes.
providerResponse.schemeTransactionId
string		The scheme transaction ID.
©2025 PXP Financial. PXP Financial Registered Office: The Corn Mill - 1 Roydon Road - Stanstead Abbotts - Hertfordshire - SG12 8XL - United Kingdom Phone +44 2038850598. PXP Financial is Authorised By The Financial Conduct Authority And Our Financial Services Register Number is 504318.