Card transaction

Process an in-person card payment.

Initiate a card transaction

POST

/v1/pos-transactions

Request examples

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

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "POS_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR",
    "gratuity": 0
  },
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Instore",
    "fundingType": "Card"
  },
  "pointOfInteraction": {
    "pointOfSaleId": "POS-1",
    "language": "EN"
  },
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2031",
      "holderName": "John Doe"
    }
  },
  "statusUpdateUrl": "https://example.com/pos-status-updates"
}

Parameter	Description
`merchant` string (≤ 20 characters) required	Your unique merchant identifier, as assigned by PXP.
`site` string (≤ 20 characters) required	Your unique site identifier, as assigned by PXP.
`merchantTransactionId` string (≤ 50 characters) required	A unique identifier for this transaction.
`merchantTransactionDate` date-time required	The date and time when the transaction happened, in ISO 8601 format.
`transactionMethod` object required	Details about the transaction method.
`transactionMethod.entryType` string required	The entry type. For POS transactions, this is always `Instore`.
`transactionMethod.fundingType` string required	The funding type. For card transactions, this is always `Card`.
`transactionMethod.intent` string required	The payment intent. Learn more about intents. Possible values: `Authorisation` `EstimatedAuthorisation` `Purchase` `Payout` `StandaloneRefund`
`amounts` object required	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 (1-3 characters) required	The currency code associated with the transaction, in ISO 4217 format.
`amounts.gratuity` number	The optional gratuity amount.
`pointOfInteraction` object required	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
`statusUpdateUrl` string	The URL that you want status updates to be sent to. You can then display these on your device.

Response examples

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.

{
  "state": "Authorised",
  "stateData": {},
  "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"
    }
  }
}

If you passed the statusUpdateUrl parameter in your request, you'll also receive the following statusUpdate object to your chosen URL.

{
  "statusUpdate": {
    "deviceIsDisplaying": "PinOk",
    "customerInteraction": "None",
    "merchantTransactionId": "POS_001",
    "eventId": "41b43c87-59c0-4b2e-9e10-09f939a5860c"
  }
}

Parameter	Description
`statusUpdate` object	Details about the status update.
`statusUpdate.deviceIsDisplaying` string (enum)	The message displayed on the device. Possible values: `None` `InsertTapOrSwipeCard` `EnterPin` `PinOk` `ChooseDcc` `ProcessingTransaction` `RemoveCard` `Welcome` `ConfirmAmount` `RemoveAndReinsertCard` `SwipeCard` `ReSwipeCard` `InsertCard` `AppSelection` `EnterCard` `EnterExpiryDate` `EnterCvc` `RetryEnterPin` `LastEnterPin` `PinEntrySuccessful` `PinEntryFailed` `TransactionCancelledByShopper` `PosError` `LanguageSelection` `QRCodeData`
`statusUpdate.customerInteraction` string (enum)	The interaction that the customer had with the device. Possible values: `None` `CardInserted` `CardTapped` `CardSwiped` `CardRemoved` `CardSwipedFail` `CardInsertedFail` `AppSelected` `MultipleCardsTapped` `CancelPressed` `CardPresentedFail` `CardInsertedSwipedFail` `EnteringCard` `EnteringExpiryDate` `EnteringCvc` `EnteringPin` `LanguageSelected`
`statusUpdate.merchantTransactionId` string	The unique identifier for this transaction, as assigned by you.
`statusUpdate.eventId` string (UUID)	The unique identifier associated with this event.

Card transaction

Initiate a card transaction

Request examples

Response examples

Was this helpful?