POS transaction service API (1.0.0)

This is an API reference for the Point of Sale transaction service.

Download OpenAPI description

point-of-sale-transaction.json

point-of-sale-transaction.yaml

Servers

Production environment

https://api-services.pxp.io/api/v1/

Sandbox environment

https://api-services.test.pxp.io/api/v1/

Initiate a POS transaction

Request

The /pos-transactions endpoint enables the initiation of instore transactions, supporting various transaction methods, including card and alternative payments.

Bodyapplication/json

Initiate a transaction

merchantstring<= 20 charactersrequired

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<= 20 charactersrequired

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

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 charactersrequired

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)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"

amountsobjectrequired

Details of the amount including transaction and gratuity values and its associated currency.

amounts.currencyCodestring= 3 charactersrequired

Denotes the currency code associated with the transaction, conforming to the ISO 4217 standard. This three-character code specifies the currency in which the transaction is processed, ensuring clarity and consistency across international transactions.

Example: "EUR"

amounts.transactionnumberrequired

This is the amount of the transaction. 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, for example, GBP 1.234, or if a decimal is supplied when the currencyCode of exponent does not require it, for example, JPY 1.0.

Example: 30.32

amounts.gratuitynumber

An optional field that captures the gratuity or tip amount added by the customer to the transaction total. This amount is separate from the main transaction and is specifically allocated as a gratuity for the service provider. Specifying this field allows for accurate reporting and distribution of tips to service staff, enhancing transparency and fairness in transactions where tipping is customary.

Example: 5.01

transactionMethodobjectrequired

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

transactionMethod.entryTypestringrequired

Specifies the environment and method by which the transaction is initiated, reflecting the nature of the transaction's origin. This classification is crucial for applying the appropriate security measures and compliance standards. The entry types include 'Ecom' for online transactions, 'Moto' for mail order/telephone order transactions, and 'Instore' for physical retail environments, each representing different transaction contexts and risk profiles.

Value"Instore"

Example: "Instore"

transactionMethod.fundingTypestringrequired

Specifies the method of payment used to fund the transaction. This field categorises the transaction by the payment medium, enabling tailored processing rules and security measures for each type. Understanding the funding type is crucial for processing the transaction correctly and ensuring compatibility with your capabilities.

Value"Card"

Example: "Card"

transactionMethod.intentstringrequired

Specifies the purpose or action of the transaction, indicating the intended money flow direction. This field is crucial for categorizing the transaction type and guiding the processing logic accordingly. Options include 'Authorisation' for reserving funds on the customer's payment method, 'Purchase' for immediate fund capture following authorisation, and 'Payout' for sending funds to a recipient. Each intent dictates a specific transaction flow and affects how the transaction is handled by the system.

Enum"Authorisation""EstimatedAuthorisation""Purchase""Payout""Refund""Verification"

Example: "Authorisation"

curl -i -X POST \
  https://api-services.pxp.io/api/v1/pos-transactions \
  -H 'Content-Type: application/json' \
  -d '{
    "pointOfInteraction": {
      "pointOfSaleId": "POS-1",
      "language": "EN",
      "storeAndForwardType": "None",
      "invokeKeyed": "False"
    },
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "This_is_my_merchant_transaction_id",
    "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
    "amounts": {
      "transaction": 30.32,
      "currencyCode": "EUR"
    },
    "transactionMethod": {
      "intent": "Authorisation",
      "entryType": "Instore",
      "fundingType": "Card"
    }
  }'

Responses

Successful Response

Bodyapplication/json

statestring

The current state of the transaction.

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

Example: "Authorised"

stateDataobject

Key value pair for various state data

Example: {"code":"12345","message":"Merchant not found"}

approvalCodestring^[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)

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

merchantTransactionIdstring<= 50 characters

Example: "This_is_my_merchant_transaction_id"

systemTransactionIdstring[ 36 .. 36 ]^[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

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

fundingDataobject

Funding data specifying the payment method used for the transaction. It includes essential information about a card involved in a transaction, such as its scheme, payment account reference, and token IDs. Additionally, it provides verification results for enhanced security, such as CVC and AVS checks, enabling you to ensure transaction integrity and mitigate fraud risks efficiently. This object is returned if the transactionMethod.fundingType is card or schemeToken.

Response

application/json

{
  "state": "Authorised",
  "approvalCode": "123456",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "providerResponse": { … }
  }
}

Initiate a POS transaction (legacy)

Request

The /pos-transactions endpoint enables the initiation of instore transactions, supporting various transaction methods, including card and alternative payments.

Bodyapplication/json

Initiate a transaction

credentialsobject

Credentials used for authentication. This is only to be used when processing transactions to the PXP ANYpay platform.

merchantstring<= 20 charactersrequired

Example: "MERCHANT-1"

sitestring<= 20 charactersrequired

Example: "SITE-1"

pointOfInteractionobject

merchantTransactionIdstring<= 50 charactersrequired

Example: "This_is_my_merchant_transaction_id"

merchantTransactionDatestring(date-time)required

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

amountsobjectrequired

Details of the amount including transaction and gratuity values and its associated currency.

amounts.currencyCodestring= 3 charactersrequired

Example: "EUR"

amounts.transactionnumberrequired

Example: 30.32

amounts.gratuitynumber

Example: 5.01

transactionMethodobjectrequired

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

transactionMethod.entryTypestringrequired

Value"Instore"

Example: "Instore"

transactionMethod.fundingTypestringrequired

Value"Card"

Example: "Card"

transactionMethod.intentstringrequired

Enum"Authorisation""EstimatedAuthorisation""Purchase""Payout""Refund""Verification"

Example: "Authorisation"

curl -i -X POST \
  https://api-services.pxp.io/api/v1/pos-transactions/legacy \
  -H 'Content-Type: application/json' \
  -d '{
    "pointOfInteraction": {
      "pointOfSaleId": "POS-1",
      "language": "EN",
      "storeAndForwardType": "None",
      "invokeKeyed": "False"
    },
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "This_is_my_merchant_transaction_id",
    "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
    "amounts": {
      "transaction": 30.32,
      "currencyCode": "EUR"
    },
    "transactionMethod": {
      "intent": "Authorisation",
      "entryType": "Instore",
      "fundingType": "Card"
    }
  }'

Responses

Successful Response

Bodyapplication/json

statestring

The current state of the transaction.

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

Example: "Authorised"

stateDataobject

Key value pair for various state data

Example: {"code":"12345","message":"Merchant not found"}

approvalCodestring^[A-Z]

Example: "A123456"

merchantTransactionDatestring(date-time)

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

merchantTransactionIdstring<= 50 characters

Example: "This_is_my_merchant_transaction_id"

systemTransactionIdstring[ 36 .. 36 ]^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

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

providerTransactionIdstring

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

fundingDataobject

Response

application/json

{
  "state": "Authorised",
  "approvalCode": "123456",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "providerResponse": { … }
  }
}

Create a POS modification

Request

This endpoint facilitates the processing of modifications on previously initiated transactions that have not yet been fully processed or captured. Supported modification actions include refunds, captures, incremental authorisations, and voids. Upon successful execution, it returns a unique reference for the modification request, allowing for easy tracking and reconciliation.

Path

systemTransactionIdstring[ 36 .. 36 ]^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

The unique systemTransactionId with which you want to process an operation.

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

Bodyapplication/jsonrequired

Modifications to a previous transaction.

amountsobjectrequired

Details of the amount including transaction and gratuity values and its associated currency.

amounts.transactionnumberrequired

Example: 30.32

amounts.gratuitynumber

Example: 5.01

merchantstring<= 20 charactersrequired

Example: "MERCHANT-1"

merchantTransactionIdstring<= 50 charactersrequired

Example: "This_is_my_merchant_transaction_id"

merchantTransactionDatestring(date-time)required

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

operationstringrequired

Describes the operation to be applied to the previous transaction. This field specifies actions such as refund, void, capture, or incremental adjustments to a transaction.

Enum"Capture""Incremental""Refund""Void"

Example: "Capture"

sitestring<= 20 charactersrequired

Example: "SITE-1"

curl -i -X POST \
  https://api-services.pxp.io/api/v1/pos-transactions/1ed768bb-e88a-4636-91ae-67927ccbb02b/modifications \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "This_is_my_merchant_transaction_id",
    "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
    "amounts": {
      "transaction": 30.32
    },
    "operation": "Refund"
  }'

Responses

Modifications Response

Bodyapplication/json

statestringrequired

The current state of the transaction.

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

Example: "Authorised"

stateDataobject

Key value pair for various state data

Example: {"code":"12345","message":"Merchant not found"}

approvalCodestring^[A-Z]

Example: "A123456"

merchantTransactionIdstring<= 50 characters

Example: "This_is_my_merchant_transaction_id"

systemTransactionIdstring[ 36 .. 36 ]^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...

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

merchantTransactionDatestring(date-time)

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

fundingDataobject

Response

application/json

{
  "state": "Captured",
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "fundingData": {
    "cardScheme": "Visa",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a"
  },
  "providerResponse": {
    "provider": "PXPFinancial",
    "code": "00",
    "message": "Approved",
    "merchantId": "77772182",
    "paymentAccountReference": "PAR12345678901234567890",
    "schemeTransactionId": "TX1234567890123456"
  }
}

POS transaction service API (1.0.0)

Initiate a POS transaction

Request

Responses

Was this helpful?

Initiate a POS transaction (legacy)

Request

Responses

Was this helpful?

Create a POS modification

Request

Responses

Was this helpful?

POS transaction service API (1.0.0)

Initiate a POS transaction

RequestExpand all

Responses

Was this helpful?

Initiate a POS transaction (legacy)

RequestExpand all

Responses

Was this helpful?

Create a POS modification

RequestExpand all

Responses

Was this helpful?

Request

Request

Request