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"
  },
  "statusCallbackUrl": "http://192.168.204.43:5000/statuspacket",
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2031",
      "holderName": "John Doe"
    }
  }
}

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 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 required	The service charge amount.
`amounts.serviceCharge.percentage` number required	The service charge percentage.
`amounts.serviceCharge.optional` boolean required	Whether the service charge is optional.
`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
`statusCallbackUrl` string	The webhook URL that PXP should sent status updates to, if the Return status packets feature is enabled for the device. This overrides the webhook URL configured in the Unity Portal.

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"
    }
  },
  "amounts": {
    "gratuity": 0
  },
  "dccData": {
    "dccSelectedIndicator": "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
    }
  }
}

Card transaction

Initiate a card transaction

Request examples

Response examples

Was this helpful?