# Initiate POS transactions

Process a card payment on a cloud-invoked point-of-sale device.

## Overview

You initiate card transactions on a cloud-invoked POS+ device through `POST /v1/cloud-device/{merchantPointOfSaleId}/transactions`. The same request covers authorisations, estimated authorisations, purchases, refunds, standalone refunds, and verifications.

To refund an existing purchase by `systemTransactionId`, use the modifications endpoint. See [Refund](/guides/point-of-sale/pos-plus/cloud/api/refund).

This page also covers:

- **Save card details (card-on-file):** Include `recurring` on the initial transaction so you can store `gatewayTokenId` and scheme identifiers for later use.
- **Invoke keyed:** Prompt the device for manual card entry with `pointOfInteraction.invokeKeyed`.
- **Store and Forward:** Keep processing when gateway connectivity is disrupted, including forced store and forward.
- **DCC:** When Dynamic Currency Conversion is enabled for the site and device, approved responses can include `dccData`.
- **Device language:** Set `pointOfInteraction.language` to control the display language for the transaction.
- **Webhooks:** Use merchant webhooks as the authoritative final outcome for authorised, captured, cancelled, and refused card states.


For what appears on printed merchant and customer receipts, see [Generate receipts](/guides/point-of-sale/pos-plus/cloud/api/generate-receipts).

To capture, increment, refund, or void a previously initiated transaction, use the cloud device modifications endpoint. See [Capture](/guides/point-of-sale/pos-plus/cloud/api/capture), [Final capture](/guides/point-of-sale/pos-plus/cloud/api/final-capture), [Incremental authorisation](/guides/point-of-sale/pos-plus/cloud/api/incremental-authorisation), [Refund](/guides/point-of-sale/pos-plus/cloud/api/refund), and [Void](/guides/point-of-sale/pos-plus/cloud/api/void).

## Initiate a card transaction

/v1/cloud-device/{merchantPointOfSaleId}/transactions

Initiate a new cloud device transaction for the specified point-of-sale device. This endpoint supports various transaction intents including authorisation, purchase, refund, and verification.

### Request examples

Use the following requests to initiate a card transaction on a cloud-invoked point-of-sale device. Replace `{merchantPointOfSaleId}` in the path with the device identifier.

Set `pointOfInteraction.language` to control the language shown on the device for that transaction. See the parameter table below for supported values.

Authorisation
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Estimated authorisation
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-EST-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "EstimatedAuthorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": false
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Purchase
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-PUR-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": false
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Verification
Use intent `Verification` to confirm a card is valid without reserving funds. You can combine it with `recurring` to collect card-on-file consent. See [Save card details (card-on-file)](#save-card-details-card-on-file).

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "COF-VER-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 0,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "Verification",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "recurring": {
    "processingModel": "cardOnFileShopperConsent"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Refund
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-RFD-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "Refund",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": false
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Standalone refund
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-REF-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "StandaloneRefund",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": false
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Service charge
Enable service charges before you send `amounts.serviceCharge`. See [Enable gratuity and service charges](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#enable-gratuity-and-service-charges).

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-003",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR",
    "serviceCharge": {
      "amount": 2.5,
      "percentage": 1.5,
      "optional": false
    }
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Cashback
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-004",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 50,
    "currencyCode": "EUR",
    "cashback": 10
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Shipping
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-005",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 40,
    "currencyCode": "EUR",
    "shipping": 5
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

| Parameter | Description |
|  --- | --- |
| `merchantPointOfSaleId`string | The unique merchant point-of-sale device identifier. Path parameter. |
| `merchant`string (≤ 20 characters) | A unique identifier assigned by PXP to represent a merchant entity, such as a store, hotel, or website, within the payment processing system. |
| `site`string (≤ 50 characters) | The unique identifier for the site associated with the transaction, as assigned by PXP. This could represent a physical location, website, or any other distinct entity where the transaction occurs. |
| `merchantTransactionId`string (≤ 50 characters) | A unique transaction reference assigned by you. Must be unique per transaction. |
| `merchantTransactionDate`date-time | The date and time when you initiated the transaction, in ISO 8601 format. |
| `amounts`object | Details about the transaction amount, including the currency and optional gratuity, cashback, shipping, or service charge values. Note that `gratuity` and `serviceCharge` can't be sent together. Enable gratuity and service charges in [Configure device settings](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#enable-gratuity-and-service-charges) before you rely on these fields. |
| `amounts.transaction`number | The transaction amount. Values after the decimal are zero-padded to the currency exponent (e.g., GBP 1.1 becomes 1.10). Requests are rejected if there are too many decimal places for the currency, or if a decimal is supplied for a zero-exponent currency (e.g., JPY 1.0). |
| `amounts.currencyCode`string (3 characters) | The currency code in ISO 4217 format. |
| `amounts.gratuity`number | The tip amount added by the customer, separate from the main transaction amount. Can't be used together with `serviceCharge`. |
| `amounts.cashback`number | The cashback amount for the authorisation. |
| `amounts.shipping`number | The shipping amount. |
| `amounts.serviceCharge`object | Information about the service charge applied to the transaction. Can't be used together with `gratuity`. |
| `amounts.serviceCharge.amount`number | The fixed service charge amount. |
| `amounts.serviceCharge.percentage`number | The service charge as a percentage of the transaction amount. |
| `amounts.serviceCharge.optional`boolean | Whether the service charge is optional. If `true`, the service charge may be declined by the cardholder. |
| `transactionMethod`object | How the transaction is initiated: intent, entry type, and funding type. |
| `transactionMethod.intent`string | The purpose or action of the transaction. [Learn more about intents](/guides/point-of-sale/pos-plus/cloud/how-it-works#intents).Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Refund``StandaloneRefund``Verification` |
| `transactionMethod.entryType`string | How the transaction is initiated. Use `Instore` for card-present retail, or `Moto` for mail order or telephone order.Possible values:`Instore``Moto` |
| `transactionMethod.fundingType`string | The payment method that funds the transaction. For cloud device, this is always `Card`. |
| `pointOfInteraction`object | Information about the POS device where the transaction takes place. |
| `pointOfInteraction.pointOfSaleId`string (≤ 20 characters) | A PXP unique identifier for the specific point-of-sale device, often assigned by the merchant or payment processor. |
| `pointOfInteraction.language`string (≤ 2 characters) | The display language, in ISO 639-1 format.Possible values:`CA`: Catalan`DA`: Danish`DE`: German`EN`: English`ES`: Spanish`FR`: French`HU`: Hungarian`IS`: Icelandic`IT`: Italian`NL`: Dutch`NO`: Norwegian`PL`: Polish`PT`: Portuguese`SV`: Swedish |
| `pointOfInteraction.storeAndForwardType`string (enum) | The type of store and forward mechanism to use when your connection to the PXP gateway is disrupted. Transactions can be stored offline until communications are re-established.Possible values:`None`: No store and forward mechanism is used.`ForcedStoreAndForward`: Transactions are forced into store and forward mode. When communication is restored, transactions are sent to the gateway for online authorisation. |
| `pointOfInteraction.invokeKeyed`boolean | Whether to initiate a keyed transaction on the device. Keyed transactions involve manually entering the card details on the device. Defaults to `false`. The **Keyed** terminal capability must already be enabled. See [Configure device settings](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#terminal-capabilities). |
| `recurring`object | Details about recurring or card-on-file payment processing. [Learn more](#save-card-details-card-on-file). |
| `recurring.processingModel`string (enum) | The recurring processing model. Use `cardOnFileShopperConsent` when the shopper is present and provides consent for card storage, or `merchantInitiatedInitialRecurring` for the initial transaction in a merchant-initiated recurring series.Possible values:`cardOnFileShopperConsent``merchantInitiatedInitialRecurring` |
| `recurring.frequencyInDays`integer | The frequency of the recurring charge in days. |
| `recurring.schemeTransactionId`string | A unique identifier assigned by the card scheme (e.g., Visa Transaction Identifier or MasterCard Banknet Reference Number). |
| `recurring.schemeTransactionLinkId`string | The scheme-assigned MasterCard Transaction Link Identifier (TLID) of the initial transaction in a series. Submit it on subsequent economically related transactions to link them to the original. |
| `statusCallbackUrl`string | The webhook URL for PXP to send status updates to. Overrides the status packet URL configured in the Unity Portal. [Learn more](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#receive-status-packets). |


### Response examples

Authorisation
If your request is successful, you'll receive a `200` response that includes the transaction's `state` and `systemTransactionId`. Store `systemTransactionId` for later modifications.

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "460070",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "merchantTransactionId": "TXN-EMV-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "PROV-98765",
  "fundingData": {
    "maskedPrimaryAccountNumber": "541333******0078",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "MasterCard",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "pointOfInteraction": {
      "entryType": "Instore"
    },
    "emvDataResponse": {
      "applicationId": "A0000000041010",
      "applicationLabel": "MASTERCARD",
      "authorisationResponseCode": "00",
      "cardHolderVerificationMethodResults": "1F0302",
      "panSequenceNumber": "01",
      "preferredName": "MASTERCARD",
      "issuerAuthenticationData": "C9DF3CA29138D5E83030"
    },
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "schemeTransactionId": "SCHEME-TXN-001",
      "issuerResponseCode": "00",
      "schemeTransactionLinkId": "LINK-001",
      "settlementDate": "2025-01-28T00:00:00Z"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  }
}
```

Authorisation (with gratuity)
If your request is successful, you'll receive a `200` response that includes the authorised amount and gratuity.

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "460070",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "merchantTransactionId": "TXN-002",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "PROV-98766",
  "fundingData": {
    "maskedPrimaryAccountNumber": "541333******0078",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "MasterCard",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "pointOfInteraction": {
      "entryType": "Instore"
    },
    "emvDataResponse": {
      "applicationId": "A0000000041010",
      "applicationLabel": "MASTERCARD",
      "authorisationResponseCode": "00",
      "cardHolderVerificationMethodResults": "1F0302",
      "panSequenceNumber": "01",
      "preferredName": "MASTERCARD"
    },
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "schemeTransactionId": "SCHEME-TXN-002",
      "issuerResponseCode": "00",
      "schemeTransactionLinkId": "LINK-002",
      "settlementDate": "2025-01-28T00:00:00Z"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR",
    "gratuity": 5.01
  }
}
```

Authorisation (with DCC)
When DCC is enabled and the cardholder accepts conversion, the response includes `dccData`. Enable DCC for the site and device first. See [Enable DCC](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#enable-dcc).

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "123456",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "merchantTransactionId": "TXN-DCC-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "PROV-98765",
  "amounts": {
    "transaction": 100,
    "currencyCode": "EUR",
    "gratuity": 5
  },
  "fundingData": {
    "maskedPrimaryAccountNumber": "************1234",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "Visa",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "pointOfInteraction": {
      "entryType": "Instore"
    },
    "emvDataResponse": {
      "applicationId": "A0000000031010",
      "applicationLabel": "VISA DEBIT",
      "authorisationResponseCode": "00",
      "cardHolderVerificationMethodResults": "1F0302",
      "panSequenceNumber": "01",
      "preferredName": "VISA DEBIT"
    },
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "schemeTransactionId": "SCHEME-TXN-001",
      "issuerResponseCode": "00",
      "schemeTransactionLinkId": "LINK-001"
    }
  },
  "dccData": {
    "rateSelectedIndicator": "Selected",
    "exchangeRate": {
      "rate": 1.2345,
      "markUpPercentage": 3.5
    },
    "amounts": {
      "local": {
        "currencyCode": "EUR",
        "transaction": 100
      },
      "cardholder": {
        "currencyCode": "USD",
        "transaction": 123.45
      }
    },
    "providerData": {
      "provider": "Elavon"
    }
  }
}
```

Refused
If the issuer refuses the transaction, you'll receive a `200` response with `state` `Refused`. Check `stateData` and `providerResponse.merchantAdvice` for next steps.

```json
{
  "state": "Refused",
  "stateData": {
    "code": "CRD100",
    "message": "Do not honour"
  },
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "merchantTransactionId": "TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "PROV-98770",
  "fundingData": {
    "maskedPrimaryAccountNumber": "************1234",
    "cardScheme": "Visa",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "pointOfInteraction": {
      "entryType": "Instore"
    },
    "emvDataResponse": {
      "applicationId": "A0000000031010",
      "applicationLabel": "VISA CREDIT",
      "authorisationResponseCode": "05"
    },
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "05",
      "message": "Do not honour",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "issuerResponseCode": "05",
      "merchantAdvice": {
        "code": "01",
        "message": "New account information available"
      }
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  }
}
```

Error
If the device or gateway can't complete the transaction (for example a timeout or malfunction), you'll receive a `200` response with `state` `Error`. Check `stateData` for the code and message.

```json
{
  "state": "Error",
  "stateData": {
    "code": "CRD183",
    "message": "Timeout / Malfunction"
  },
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "merchantTransactionId": "TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "maskedPrimaryAccountNumber": "************1234",
    "cardScheme": "Visa",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "pointOfInteraction": {
      "entryType": "Instore"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  }
}
```

## Save card details (card-on-file)

Include `recurring` in your transaction request when you want to save the customer's card for future use. This applies to initial transactions with intents such as `Purchase`, `Authorisation`, `EstimatedAuthorisation`, or `Verification`, and entry types `Instore` or `Moto`.

When the transaction is approved, store the `gatewayTokenId` from `fundingData` and the scheme identifiers from `fundingData.providerResponse` (including `schemeTransactionId` and, for MasterCard, `schemeTransactionLinkId`). You need these values for subsequent card-on-file or merchant-initiated transactions.

### Request examples

Purchase (shopper consent)
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "COF-PUR-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 45.5,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": false
  },
  "recurring": {
    "processingModel": "cardOnFileShopperConsent"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Estimated authorisation (merchant-initiated series)
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "REC-EST-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 50,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "EstimatedAuthorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": false
  },
  "recurring": {
    "processingModel": "merchantInitiatedInitialRecurring",
    "frequencyInDays": 30
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Authorisation (Moto, keyed)
Use `entryType` `Moto` with `invokeKeyed` set to `true` when the shopper provides card details manually and consents to card storage.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "COF-MOTO-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 75,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Moto",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": true
  },
  "recurring": {
    "processingModel": "cardOnFileShopperConsent"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Verification (shopper consent)
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "COF-VER-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 0,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "Verification",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "recurring": {
    "processingModel": "cardOnFileShopperConsent"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

Verification (merchant-initiated series)
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "REC-VER-001",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 0,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "Verification",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "recurring": {
    "processingModel": "merchantInitiatedInitialRecurring",
    "frequencyInDays": 30
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

### Response example

If your request is successful, the response includes a `gatewayTokenId` and scheme identifiers for use in later transactions:

```json
{
  "state": "Authorised",
  "fundingData": {
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "providerResponse": {
      "schemeTransactionId": "SCHEME-TXN-001",
      "schemeTransactionLinkId": "LINK-001"
    }
  }
}
```

## Invoke keyed

Before you can use this feature, enable the **Keyed** terminal capability for the device. See [Configure device settings](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#terminal-capabilities).

### Initiate a keyed transaction

To initiate a keyed transaction, add the following snippet to your transaction request.

```json
{
  "pointOfInteraction": {
    "invokeKeyed": true
  }
}
```

| Parameter | Description |
|  --- | --- |
| `pointOfInteraction`object | Information about the POS device where the transaction takes place. |
| `pointOfInteraction.invokeKeyed`boolean | Whether to initiate a keyed transaction on the device. Keyed transactions involve manually entering the card details on the device. Defaults to `false`. |


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

For card-on-file transactions, set `entryType` to `Moto` and include `recurring` with the appropriate `processingModel`. See [Save card details (card-on-file)](#save-card-details-card-on-file).

## Dynamic Currency Conversion (DCC)

DCC is offered on the device during the payment journey when it is enabled for the site and device. You do not send DCC fields on the initiate request. If the cardholder accepts conversion, the response includes `dccData` with local and cardholder amounts, the exchange rate, and provider details.

Enable DCC before you rely on this behaviour. See [Enable DCC](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#enable-dcc).

See the **Authorisation (with DCC)** response example under [Initiate a card transaction](#initiate-a-initiate-transaction).

## Store and Forward

Store and Forward is a mechanism used for handling transactions when your connection to the PXP Unity Gateway is disrupted. It securely stores transactions offline until communications are re-established with the Gateway.

There are two types:

* **(Regular) Store and Forward:** Used as a fallback method in case of temporary connectivity loss. For example, if the Wi-Fi stops working in a shop.
* **Forced Store and Forward:** Used for all transactions. For example, aboard a cruise liner that has poor satellite communications.


Enable Store and Forward for the device before you rely on either behaviour. See [Store and Forward settings](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#store-and-forward-settings).

When regular Store and Forward is enabled as an automatic fallback, you don't need to pass any additional parameters in your transaction request.

### Forced Store and Forward

Before you can use this feature, enable Store and Forward for the device. See [Store and Forward settings](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#store-and-forward-settings).

To force Store and Forward on a request, set `storeAndForwardType` to `ForcedStoreAndForward` in your transaction request.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TXN-006",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "ForcedStoreAndForward"
  },
  "statusCallbackUrl": "http://192.168.1.1:5000/statuspacket"
}
```

| Parameter | Description |
|  --- | --- |
| `pointOfInteraction`object | Information about the POS device where the transaction takes place. |
| `pointOfInteraction.storeAndForwardType`string (enum) | The type of store and forward mechanism to use when your connection to the PXP gateway is disrupted. Transactions can be stored offline until communications are re-established.Possible values:`None`: No store and forward mechanism is used.`ForcedStoreAndForward`: Transactions are forced into store and forward mode (for example, environments with unreliable connectivity). When communication is restored, transactions are sent to the gateway for online authorisation. |


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

## Webhooks

Cloud device card outcomes use the shared card transaction webhook set. Treat merchant webhooks as the authoritative final outcome for settlement and follow-up states. Always key follow-up API calls on `systemTransactionId`.

You can override the status packet URL configured in the Unity Portal by including `statusCallbackUrl` in your initiate request. Configure status packets first if you need in-journey device updates. See [Receive status packets](/guides/point-of-sale/pos-plus/cloud/api/configure-settings#receive-status-packets).

The following outcomes commonly apply to cloud device card transactions:

| Outcome  | State | Description  |
|  --- | --- | --- |
| Authorised | `Authorised` | A card initiation, such as an authorisation or purchase, was approved. |
| Captured | `Captured` | A card capture completed. |
| Cancelled | `Cancelled` | A card void completed. |
| Refused | `Refused` | A card initiation was refused. |


### Examples

Authorised
A successful card initiation uses a card authorised webhook with state `Authorised`.

```json
{
  "eventDate": "2021-10-27T08:51:04.8264455Z",
  "eventCategory": "transaction",
  "eventData": {
    "state": "Authorised",
    "stateData": {
      "code": "CRD000",
      "message": "Approved"
    },
    "approvalCode": "123456",
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "transactionMethod": {
      "intent": "Authorisation",
      "fundingType": "Card",
      "entryType": "Ecom"
    },
    "amounts": {
      "transactionValue": 50.05,
      "currencyCode": "EUR"
    },
    "merchantOrderId": "merchant_order_id",
    "merchantTransactionId": "merchant_transaction_id",
    "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
    "fundingData": {
      "cardScheme": "Visa",
      "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
      "schemeTokenNumber": "4837261112345678",
      "providerResponse": {
        "provider": "PXPFinancial",
        "code": "00",
        "message": "Approved",
        "merchantId": "77772182",
        "addressVerificationServiceResult": "D",
        "cardVerificationCodeResult": "A",
        "schemeTransactionId": "TX1234567890123456",
        "paymentAccountReference": "PAR12345678901234567890",
        "electronicCommerceIndicatorAdjustment": "01",
        "settlementDate": "2024-01-25"
      }
    }
  }
}
```

Captured
A successful card capture uses a card captured webhook with state `Captured`.

```json
{
  "eventDate": "2021-10-27T08:51:04.8264455Z",
  "eventCategory": "transaction",
  "eventData": {
    "state": "Captured",
    "stateData": {
      "code": "CRD000",
      "message": "Approved"
    },
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "transactionMethod": {
      "intent": "Capture",
      "fundingType": "Card",
      "entryType": "Ecom"
    },
    "amounts": {
      "transactionValue": 50.05,
      "currencyCode": "EUR"
    },
    "merchantOrderId": "This_is_my_merchant_order_id",
    "merchantTransactionId": "This_is_my_merchant_transaction_id",
    "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
    "fundingData": {
      "cardScheme": "Visa",
      "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
      "schemeTokenNumber": "4837261112345678",
      "providerResponse": {
        "provider": "PXPFinancial",
        "code": "00",
        "message": "Approved",
        "merchantId": "77772182",
        "paymentAccountReference": "PAR12345678901234567890",
        "schemeTransactionId": "TX1234567890123456",
        "settlementDate": "2024-01-25T00:00:00Z"
      }
    }
  }
}
```

Cancelled
A successful card void uses a card cancelled webhook with state `Cancelled`.

```json
{
  "eventDate": "2021-10-27T08:51:04.8264455Z",
  "eventCategory": "transaction",
  "eventData": {
    "state": "Cancelled",
    "stateData": {
      "code": "CRD000",
      "message": "Approved"
    },
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "transactionMethod": {
      "intent": "Void",
      "fundingType": "Card",
      "entryType": "Ecom"
    },
    "amounts": {
      "transactionValue": 50.05,
      "currencyCode": "EUR"
    },
    "merchantOrderId": "This_is_my_merchant_order_id",
    "merchantTransactionId": "This_is_my_merchant_transaction_id",
    "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
    "fundingData": {
      "cardScheme": "Visa",
      "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
      "schemeTokenNumber": "4837261112345678",
      "providerResponse": {
        "provider": "PXPFinancial",
        "code": "00",
        "message": "Approved",
        "merchantId": "77772182",
        "paymentAccountReference": "PAR12345678901234567890",
        "schemeTransactionId": "TX1234567890123456"
      }
    }
  }
}
```

Refused
A refused card initiation uses a card refused webhook with state `Refused`.

```json
{
  "eventCategory": "transaction",
  "eventData": {
    "amounts": {
      "currencyCode": "GBP",
      "transaction": 40
    },
    "eventCode": "TXN_RFU",
    "fundingData": {
      "card": {
        "cardScheme": "JCB",
        "gatewayTokenId": "821e3173-5c21-4a39-8495-627dcdfc12e8",
        "nameVerificationResult": null,
        "providerResponse": {
          "addressVerificationServiceResult": "",
          "authorisedAmount": 0,
          "cardVerificationCodeResult": "",
          "code": "30",
          "issuerResponseCode": "",
          "merchantAdvice": {},
          "merchantId": "000100800004485",
          "message": "Format error.",
          "provider": "lloydscardnet",
          "settlementDate": "2026-06-26T00:00:00.000Z",
          "terminalId": "30121285"
        }
      }
    },
    "merchant": "Unity",
    "merchantTransactionDate": "2026-06-26T11:14:02.123445+00:00",
    "merchantTransactionId": "283996_11",
    "providerTransactionId": null,
    "site": "UnityLLD",
    "state": "Refused",
    "stateData": {
      "code": "CRD182",
      "message": "Bad format"
    },
    "systemTransactionId": "2eb35ccd-fa18-4fe9-adb6-33f395851482",
    "transactionMethod": {
      "entryType": "Instore",
      "fundingType": "Card",
      "intent": "Purchase"
    }
  },
  "eventDate": "2026-06-26T10:34:43.2760930Z",
  "eventOwner": {
    "merchant": "Unity",
    "merchantGroup": "UnityGroup",
    "site": "UnityLLD"
  }
}
```

To learn how to set up and process webhooks, see [Manage webhooks](/guides/get-started/manage-webhooks).