# Card transaction

Process an in-person card payment.

## Initiate a card transaction

/v1/pos-transactions

### Request examples

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

Authorisation
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "POS_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 1.00,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS001",
    "language": "EN",
    "storeAndForwardType": "None"
  }
}
```

Estimated authorisation
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "POS_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 1.00,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "EstimatedAuthorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS001",
    "language": "EN",
    "storeAndForwardType": "None"
  }
}
```

Purchase
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "POS_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 1.00,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS001",
    "language": "EN",
    "storeAndForwardType": "None"
  }
}
```

Standalone refund
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "POS_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 1.00,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "StandaloneRefund",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS001",
    "language": "EN",
    "storeAndForwardType": "None"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters)  | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 50 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `amounts.gratuity`number | The gratuity or tip amount added by the customer to the transaction total. This field can't be used together with `serviceCharge`. |
| `amounts.serviceCharge`object | Details about the service charge applied to the transaction. This field can't be used together with `gratuity`. |
| `amounts.serviceCharge.amount`number | The service charge amount. |
| `amounts.serviceCharge.percentage`number | The service charge percentage. |
| `amounts.serviceCharge.optional`boolean | Whether the service charge is optional. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.intent`string | The payment intent. [Learn more about intents](/guides/pos-plus/how-it-works#intents).Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout` `StandaloneRefund` |
| `transactionMethod.entryType`string | The entry type. Use `Instore` for card-present transactions. Use `Moto` for mail order or telephone order transactions, such as [keyed card-on-file consent](/guides/pos-plus/api/invoke-keyed).Possible values:`Instore``Moto` |
| `transactionMethod.fundingType`string | The funding type. For card transactions, this is always `Card`. |
| `pointOfInteraction`object | 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 (≤ 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 of the POS device, 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 Store and Forward mechanism for handling transactions when connectivity is disrupted. [Learn more](/guides/pos-plus/api/store-and-forward).Possible values:`None``ForcedStoreAndForward` |
| `pointOfInteraction.invokeKeyed`boolean | Whether to initiate a keyed transaction on the device. Keyed transactions involve manually entering card details. Defaults to `false`. [Learn more](/guides/pos-plus/api/invoke-keyed). |
| `recurring`object | Details about recurring or card-on-file processing. Use this on initial transactions when the shopper consents to store their card, or when starting a merchant-initiated recurring series. [Learn more](#save-card-details-card-on-file). |
| `recurring.processingModel`string (enum) | The card-on-file processing model.Possible values:`cardOnFileShopperConsent`: The shopper is present and consents to card storage.`merchantInitiatedInitialRecurring`: The initial transaction in a merchant-initiated recurring series. |
| `statusCallbackUrl`string | The webhook URL that PXP should send status updates to, if the *Return status packets* feature is enabled for the device. This overrides the webhook URL configured in the Unity Portal. |
| `merchantDeeplink`string | A deeplink URL to redirect users back to your app after the transaction completes on the device. |


## 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 `Purchase`, `Authorisation`, or `EstimatedAuthorisation`, and entry types `Instore` or `Moto`.

When the transaction is approved, store the `gatewayTokenId` and `schemeTransactionId` from `fundingData` in the response. You need these values for subsequent card-on-file or merchant-initiated transactions.

Purchase (shopper consent)
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "COF_Purchase_001",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 45.50,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "recurring": {
    "processingModel": "cardOnFileShopperConsent"
  }
}
```

Estimated authorisation (merchant-initiated series)
```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "Recurring_EstAuth_001",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 50.00,
    "currencyCode": "EUR"
  },
  "transactionMethod": {
    "intent": "EstimatedAuthorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None"
  },
  "recurring": {
    "processingModel": "merchantInitiatedInitialRecurring"
  }
}
```

Authorisation (Moto, keyed)
Use `entryType` `Moto` with `invokeKeyed` when the shopper provides card details manually and consents to card storage. [Learn more about keyed transactions](/guides/pos-plus/api/invoke-keyed).

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "COF_MOTO_Auth_001",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 75.00,
    "currencyCode": "GBP"
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Moto",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN",
    "storeAndForwardType": "None",
    "invokeKeyed": true
  },
  "recurring": {
    "processingModel": "cardOnFileShopperConsent"
  }
}
```

### Response example

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

```json
{
  "state": "Authorised",
  "fundingData": {
    "gatewayTokenId": "91889084-9611-4774-a02a-63a8d25116fc",
    "providerResponse": {
      "schemeTransactionId": "SCHEME-TXN-001"
    }
  }
}
```

Action required: Store scheme transaction ID for Diners (from 1 July 2026)
If you process Diners card-on-file or merchant-initiated transactions, you must store `schemeTransactionId` for all Diners transactions from 1 July 2026. [Learn more](/guides/pos-plus/how-it-works#receiving-a-response).

### Response examples

Authorisation
If your request is successful, you'll receive a `200` response that includes the transaction's updated `state`. You'll also receive a Transaction (Card Authorised) webhook notification.

```json Contactless
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "260050",
  "merchantTransactionDate": "2025-03-25T09:07:40.974520+00:00",
  "merchantTransactionId": "POS_001",
  "systemTransactionId": "53696628-1453-4138-8ecb-22e61113e29f",
  "providerTransactionId": "",
  "fundingData": {
    "maskedPrimaryAccountNumber": "222360******0011",
    "expiryMonth": "12",
    "expiryYear": "2049",
    "cardScheme": "MasterCard",
    "gatewayTokenId": "db2d6ff1-d67e-44d2-9e56-4bcdacad753f",
    "emvDataResponse": {
      "applicationId": "A0000000041010",
      "applicationLabel": "MCD01 v1 2",
      "authorisationResponseCode": "00",
      "cardHolderVerificationMethodResults": "Signature verified",
      "panSequenceNumber": "01",
      "preferredName": ""
    },
    "providerResponse": {
      "provider": "PXP Financial",
      "code": "00",
      "message": "",
      "merchantId": "7171910017",
      "terminalId": "21443892",
      "paymentAccountReference": "",
      "schemeTransactionId": "",
      "merchantAdvice": {
        "code": "",
        "message": ""
      },
      "settlementDate": "2025-04-11T09:14:54.846915+01:00",
      "issuerResponseCode": "00"
    }
  },
  "amounts": {
    "gratuity": 0
  },
  "dccData": {
    "rateSelectedIndicator": "Selected",
    "amounts": {
      "local": {
        "transaction": 100.00,
        "currencyCode": "USD"
      },
      "cardholder": {
        "transaction": 85.50,
        "currencyCode": "EUR"
      }
    },
    "exchangeRate": 0.855,
    "markupRate": 3.92,
    "disclaimer": "You are offered to pay in EUR. This includes a 3.5% commission above the base rate of 0.9245 provided by Elavon.",
    "providerData": {
      "provider": "Elavon",
      "referenceId": "REF123456789",
      "merchantId": "MERCH001",
      "terminalId": "TERM001",
      "markupTextIndicator": 1
    }
  }
}
```

```json Swiped
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "548148",
  "merchantTransactionDate": "2025-03-25T09:07:40.974520+00:00",
  "merchantTransactionId": "POS_001",
  "systemTransactionId": "f20836af-cf09-49be-9eb6-6cb8d849bd90",
  "providerTransactionId": "",
  "fundingData": {
    "maskedPrimaryAccountNumber": "541333******0029",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "MasterCard",
    "gatewayTokenId": "ba2791a3-294d-4cc1-b059-4524dd167b4e",
    "providerResponse": {
      "provider": "PXP Financial",
      "code": "00",
      "message": "",
      "merchantId": "7171910017",
      "terminalId": "10848424",
      "paymentAccountReference": "",
      "schemeTransactionId": "",
      "merchantAdvice": {
        "code": "",
        "message": ""
      },
      "settlementDate": "2025-04-11T09:08:59.295647+01:00",
      "issuerResponseCode": "00"
    }  
  },
  "dccData": {
    "rateSelectedIndicator": "Selected",
    "amounts": {
      "local": {
        "transaction": 100.00,
        "currencyCode": "USD"
      },
      "cardholder": {
        "transaction": 85.50,
        "currencyCode": "EUR"
      }
    },
    "exchangeRate": 0.855,
    "markupRate": 3.92,
    "disclaimer": "You are offered to pay in EUR. This includes a 3.5% commission above the base rate of 0.9245 provided by Elavon.",
    "providerData": {
      "provider": "Elavon",
      "referenceId": "REF123456789",
      "merchantId": "MERCH001",
      "terminalId": "TERM001",
      "markupTextIndicator": 1
    }
  }
}
```

```json Keyed
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "783254",
  "merchantTransactionDate": "2025-03-25T09:07:40.974520+00:00",
  "merchantTransactionId": "POS_001",
  "systemTransactionId": "f64fd47b-362c-418d-8aa3-8dd873871545",
  "providerTransactionId": "",
  "fundingData": {
    "maskedPrimaryAccountNumber": "541333******0029",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "MasterCard",
    "gatewayTokenId": "ba2791a3-294d-4cc1-b059-4524dd167b4e",
    "providerResponse": {
      "provider": "PXP Financial",
      "code": "00",
      "message": "",
      "merchantId": "7171910017",
      "terminalId": "31913549",
      "paymentAccountReference": "",
      "schemeTransactionId": "",
      "merchantAdvice": {
        "code": "",
        "message": ""
      },
      "settlementDate": "2025-04-11T08:19:24.504482+01:00",
      "issuerResponseCode": "00"
    }
  },
  "amounts": {
    "gratuity": 0
  },
  "dccData": {
    "rateSelectedIndicator": "Selected",
    "amounts": {
      "local": {
        "transaction": 100.00,
        "currencyCode": "USD"
      },
      "cardholder": {
        "transaction": 85.50,
        "currencyCode": "EUR"
      }
    },
    "exchangeRate": 0.855,
    "markupRate": 3.92,
    "disclaimer": "You are offered to pay in EUR. This includes a 3.5% commission above the base rate of 0.9245 provided by Elavon.",
    "providerData": {
      "provider": "Elavon",
      "referenceId": "REF123456789",
      "merchantId": "MERCH001",
      "terminalId": "TERM001",
      "markupTextIndicator": 1
    }
  }
}
```

Purchase
If your request is successful, you'll receive a `200` response that includes the transaction's updated `state`. You'll also receive a Transaction (Card Authorised) webhook notification.

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "212934",
  "merchantTransactionDate": "2025-03-25T09:07:40.974520+00:00",
  "merchantTransactionId": "POS_001",
  "systemTransactionId": "52c8c45e-f922-4208-9c83-23ec0df2d37c",
  "providerTransactionId": "",
  "fundingData": {
    "maskedPrimaryAccountNumber": "541333******0011",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "MasterCard",
    "gatewayTokenId": "136c92af-da26-411d-8925-388ff2fc7a71",
    "emvDataResponse": {
      "applicationId": "A0000000041010",
      "applicationLabel": "MASTERCARD",
      "authorisationResponseCode": "00",
      "cardHolderVerificationMethodResults": "Pin verified",
      "panSequenceNumber": "03",
      "preferredName": "MasterCard"
    },
    "providerResponse": {
      "provider": "PXP Financial",
      "code": "00",
      "message": "",
      "merchantId": "7171910017",
      "terminalId": "71134563",
      "paymentAccountReference": "",
      "schemeTransactionId": "",
      "merchantAdvice": {
        "code": "",
        "message": ""
      },
      "settlementDate": "2025-04-11T09:11:45.737607+01:00",
      "issuerResponseCode": "00"
    }
  },
  "amounts": {
    "gratuity": 0
  },
  "dccData": {
    "rateSelectedIndicator": "Selected",
    "amounts": {
      "local": {
        "transaction": 100.00,
        "currencyCode": "USD"
      },
      "cardholder": {
        "transaction": 85.50,
        "currencyCode": "EUR"
      }
    },
    "exchangeRate": 0.855,
    "markupRate": 3.92,
    "disclaimer": "You are offered to pay in EUR. This includes a 3.5% commission above the base rate of 0.9245 provided by Elavon.",
    "providerData": {
      "provider": "Elavon",
      "referenceId": "REF123456789",
      "merchantId": "MERCH001",
      "terminalId": "TERM001",
      "markupTextIndicator": 1
    }
  }
}
```

Standalone refund
If your request is successful, you'll receive a `200` response that includes the transaction's updated `state`. You'll also receive a Transaction (Card Authorised) webhook notification.

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "490113",
  "merchantTransactionDate": "2025-04-17T10:07:40.974520+01:00",
  "merchantTransactionId": "ASR_170425_02",
  "systemTransactionId": "fe94ae54-7f87-4aff-b9d0-85a0bde76735",
  "providerTransactionId": "",
  "fundingData": {
    "maskedPrimaryAccountNumber": "373953*****1004",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "AmericanExpress",
    "gatewayTokenId": "101afa0c-b427-497a-992b-d78a09bdeb27",
    "providerResponse": {
      "provider": "American Express",
      "code": "000",
      "message": "",
      "merchantId": "0371518531",
      "terminalId": "12345678",
      "paymentAccountReference": "99999999999999999999999999999999999",
      "schemeTransactionId": "000003542490113",
      "merchantAdvice": {
        "code": "",
        "message": ""
      },
      "settlementDate": "2025-04-17T08:41:50.801604+01:00",
      "issuerResponseCode": "00"
    }
  },
  "amounts": {
    "gratuity": 0
  },
  "dccData": {
    "rateSelectedIndicator": "Selected",
    "amounts": {
      "local": {
        "transaction": 100.00,
        "currencyCode": "USD"
      },
      "cardholder": {
        "transaction": 85.50,
        "currencyCode": "EUR"
      }
    },
    "exchangeRate": 0.855,
    "markupRate": 3.92,
    "disclaimer": "You are offered to pay in EUR. This includes a 3.5% commission above the base rate of 0.9245 provided by Elavon.",
    "providerData": {
      "provider": "Elavon",
      "referenceId": "REF123456789",
      "merchantId": "MERCH001",
      "terminalId": "TERM001",
      "markupTextIndicator": 1
    }
  }
}
```