# Initiate transactions

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 Purchase
val authRequest = TransactionRequest(
 merchantTransactionId = "Purchase-001", 
 merchantTransactionDate = OffsetDateTime.now(), 
 pointOfInteraction = PointOfInteraction( 
   pointOfSaleId = "001", 
   language = "en"
 ), 
 amounts = Amounts(
   currencyCode = "GBP",
   transaction = BigDecimal("100.00")
 ),
 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"
 ), 
 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. |
| `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. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.intent`IntentType | The payment intent.Possible values:`Purchase``StandaloneRefund` |
| `merchantDeeplink`string | The URL that the SDK will navigate back to upon transaction completion, if applicable. For more information, see [Callback navigation](/guides/tap-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 = "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"
    )
  )
)
```

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