Initiate a cloud device transaction

Request

Initiate a new cloud device transaction for the specified point-of-sale device. This endpoint supports various transaction intents including authorisation, purchase, refund, and verification.

Security

PXP-POS

Path

merchantPointOfSaleIdstringrequired

The unique merchant point-of-sale device identifier.

Example:POS-001

Bodyapplication/json

Initiate a cloud device 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.

Example:"MERCHANT-1"

sitestring, <= 50 charactersrequired

The unique identifier for the site associated with the transaction, as assigned by PXP. This could represent a physical location, website, or any other distinct entity where the transaction occurs.

Example:"SITE-1"

pointOfInteractionobjectrequired

Information about the POS device where the transaction takes place.

merchantTransactionIdstring, <= 50 charactersrequired

A unique transaction reference assigned by you. Must be unique per transaction.

Example:"TXN-001"

merchantTransactionDatestring, (date-time)required

The date and time when you initiated the transaction, in ISO 8601 format.

Example:"2025-01-27T08:51:02.826445+00:00"

amountsobjectrequired

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

transactionMethodobjectrequired

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

recurringobject

Details about recurring or card-on-file payment processing.

statusCallbackUrlstring

The webhook URL for PXP to send status updates to. Overrides the URL configured in the Unity Portal.

Example:"http://192.168.1.1:5000/statuspacket"

curl -i -X POST \
  https://api-services.pxp.io/api/v1/cloud-device/POS-001/transactions \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "TXN-001",
    "merchantTransactionDate": "2025-01-27T08: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.1.1:5000/statuspacket"
  }'

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. Learn more about how this works.

Example:

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

approvalCodestring

The authorisation approval code returned by the issuer or authorising entity.

Example:"460070"

merchantTransactionDatestring, (date-time)

The date and time when you initiated the transaction, in ISO 8601 format.

Example:"2025-01-27T08:51:02.826445+00:00"

merchantTransactionIdstring, <= 50 characters

A unique transaction reference assigned by you. Must be unique per transaction.

Example:"TXN-001"

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

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

Details about the payment method used for the transaction, including masked card data, scheme, gateway token, verification results, EMV data, and the provider response.

amountsobject

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

dccDataobject

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": "A123456",
  "merchantTransactionId": "TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2025-01-27T08:51:02.826445+00:00",
  "providerTransactionId": "PROV-98765",
  "fundingData": {
    "maskedPrimaryAccountNumber": "************1234",
    "cardScheme": "Visa",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "pointOfInteraction": { … },
    "providerResponse": { … }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  }
}