Initiate a POS transaction

Request

The /pos-transactions endpoint enables you to initiate instore transactions. It supports various transaction methods including card and alternative payments.

Security

PXP-POS

Bodyapplication/json

Initiate a transaction

merchantstring, <= 20 characters(merchant)required

A unique identifier assigned by PXP to represent a merchant entity, such as a store, hotel, or website, within the payment processing system. This identifier is crucial for routing transactions to the correct merchant account, ensuring accurate processing, settlement, and reporting. Merchants receive this value upon registration or integration with PXP, and it must be included in transaction requests to identify the merchant for whom the transaction is being processed.

Example:"MERCHANT-1"

sitestring, <= 50 characters(site)required

The unique site identifier associated with the transaction. This could represent a physical location, website, or any other distinct entity where the transaction occurs. The value for this field is generated by PXP.

Example:"SITE-1"

pointOfInteractionobject(pointOfInteraction)required

The pointOfInteraction object captures detailed information 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.

merchantTransactionIdstring, <= 50 characters(merchantTransactionId)required

Represents a unique transaction reference assigned by you, the merchant, to identify individual transactions. This identifier serves as a primary means of communication regarding the transaction status between you and PXP. It is essential to maintain uniqueness for each transaction, ensuring accurate tracking and communication throughout the transaction lifecycle.

Example:"This_is_my_merchant_transaction_id"

merchantTransactionDatestring, (date-time)(merchantTransactionDate)required

Specifies the date and time when the transaction was initiated by the merchant. This timestamp is crucial for tracking the transaction throughout its lifecycle and for chronological order analysis. The date and time format follows the ISO 8601 standard, ensuring consistency and ease of interpretation in global contexts. It facilitates the accurate and precise logging of transaction initiation times, aiding in transaction management and reconciliation processes between the merchant and PXP.

Example:"2021-10-27 08:51:02.826445+00:00"

amountsobject(amounts)required

Details about the transaction amount, including the currency and optional gratuity or service charge values. Note that gratuity and serviceCharge can't be sent together.

transactionMethodobject(transactionMethod)required

The transaction method provides comprehensive details about the intent, capture method, and origin of a transaction.

recurringobject(recurring)

Details about recurring payment processing for card-on-file transactions. This parameter applies to initial transactions (Purchase, Authorisation, EstimatedAuthorisation) with Instore or Moto entry types. When provided, the customer's card will be saved on file with their consent, and the gateway token and scheme transaction ID will be returned in the response.

statusCallbackUrlstring(statusCallbackUrl)

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.

Example:"http://192.168.204.43:5000/statuspacket"

merchantDeeplinkstring, (uri)(merchantDeeplink)

A custom URI scheme that allows the merchant's mobile app to handle payment callbacks. When provided, the payment terminal or SDK will use this deeplink to redirect users back to the merchant's app after the transaction is completed. This is commonly used in mobile payment flows to create a seamless user experience.

Example:"myapp://payment/callback"

curl -i -X POST \
  https://api-services.pxp.io/api/v1/pos-transactions \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
    },
    "transactionMethod": {
      "intent": "Authorisation",
      "entryType": "Instore",
      "fundingType": "Card"
    },
    "pointOfInteraction": {
      "pointOfSaleId": "POS-1",
      "language": "EN",
      "storeAndForwardType": "None"
    },
    "statusCallbackUrl": "http://192.168.204.43:5000/statuspacket",
    "merchantDeeplink": "myapp://payment/callback"
  }'

Responses

Successful response

Bodyapplication/json

statestring(state)

The current state of the transaction.

Enum:"Authorised""Captured""Cancelled""Error""Refused"

Example:"Authorised"

stateDataobject(stateData)

Key value pair for various state data. Learn more about how this works.

Example:

{
  "code": "CRD000",
  "message": "Approved"
}

approvalCodestring(approvalCode)^[A-Z]

A unique identifier code provided by the authorizing 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.

Example:"A123456"

merchantTransactionDatestring, (date-time)(merchantTransactionDate)

Example:"2021-10-27 08:51:02.826445+00:00"

merchantTransactionIdstring, <= 50 characters(merchantTransactionId)

Example:"This_is_my_merchant_transaction_id"

systemTransactionIdstring, [ 36 .. 36 ](systemTransactionId)^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

The system transaction Id is a unique identifier generated by PXP for each transaction. It serves as a reference for tracking and querying transactions within the PXP system. This Id is crucial for performing modifications or querying transaction details.

Example:"1ed768bb-e88a-4636-91ae-67927ccbb02b"

providerTransactionIdstring(providerTransactionId)

A unique identifier assigned by the financial service provider for the transaction. It facilitates tracking, reconciliation, and support processes.

fundingDataobject(cardResponse)

The cardResponse object encapsulates essential information about a card involved in a transaction, including its scheme, payment account reference, and token IDs. Additionally, it provides verification results for enhanced security, such as CVC and AVS checks, enabling merchants to ensure transaction integrity and mitigate fraud risks efficiently. This object is returned if the fundingType under the transactionMethod is of type 'Card' or 'SchemeToken'.

amountsobject(amountsResponse)

Details about the transaction amounts, including the transaction value, currency, and optional gratuity.

dccDataobject(dccData)

Details about the Dynamic Currency Conversion (DCC) for the transaction, including rate selection, amounts in local and cardholder currencies, exchange rate, and provider details.

Response

{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "460070",
  "merchantTransactionDate": "2025-11-14T16:07:40.974520+07:00",
  "merchantTransactionId": "KD_141125_24",
  "systemTransactionId": "375421d2-326d-4df9-8324-98772991f41a",
  "providerTransactionId": "PROV-98765",
  "fundingData": {
    "maskedPrimaryAccountNumber": "541333******0078",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cardScheme": "MasterCard",
    "gatewayTokenId": "91889084-9611-4774-a02a-63a8d25116fc",
    "pointOfInteraction": { … },
    "emvDataResponse": { … },
    "providerResponse": { … }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "dccData": {}
}