# 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.

```kotlin Authorisation
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")
 ),
 transactionMethod = TransactionMethod( 
   intent = IntentType.Authorisation 
 ), 
 merchantDeeplink = "app://merchantsimulator/main"
)
```

```kotlin Estimated authorisation
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")
 ),
 transactionMethod = TransactionMethod( 
   intent = IntentType.EstimatedAuthorisation 
 ), 
 merchantDeeplink = "app://merchantsimulator/main"
)
```

```kotlin Purchase
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"
)
```

```kotlin Standalone refund
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")
 ),
 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`storeAndForwardType | 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.`ForcedStoreAndForward`: 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. |
| `amounts.gratuity`BigDecimal | The gratuity or tip amount added by the customer to the transaction total. This field is only for purchases and can't be used together with `serviceCharge`. |
| `amounts.serviceCharge`object | Details about the service charge applied to the transaction. This field is only for purchases and can't be used together with `gratuity`. |
| `amounts.serviceCharge.amount`BigDecimal | The service charge amount. |
| `amounts.serviceCharge.percentage`BigDecimal | The service charge percentage. |
| `amounts.serviceCharge.optional`boolean | Whether the service charge is optional. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.intent`IntentType | The payment intent.Possible values:`Authorisation``EstimatedAuthorisation``Purchase``StandaloneRefund` |
| `recurring`object | Details about recurring or card-on-file processing. See [Save card details (card-on-file)](/guides/pos-plus/api/card-transaction#save-card-details-card-on-file). |
| `merchantDeeplink`string | The URL that the SDK will navigate back to upon transaction completion, if applicable. For more information, see [Callback navigation](/guides/pos-plus/sdk/callback-navigation). |


### Response example

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

```kotlin
structureTransactionResponse(
  state = "Authorised",
  stateData = StateData(
    code = "CRD000",
    message = "Approved"
	),
  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 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. |