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"
)

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.EstimatedAuthorisation 
 ), 
 merchantDeeplink = "app://merchantsimulator/main"
)

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.Purchase
 ), 
 merchantDeeplink = "app://merchantsimulator/main"
)

val authRequest = TransactionRequest(
 merchantTransactionId = "Refund-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.StandaloneRefund 
 ), 
 merchantDeeplink = "app://merchantsimulator/main"
)

Parameter	Description
`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 Financial 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"
    )
  )
)

Property	Description
`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 identified 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.