Create a cloud device modification

Request

Process a modification on a previously-initiated cloud device transaction. Supported operations include captures, refunds, incremental authorisations, and voids.

Security

PXP-POS

Path

merchantPointOfSaleIdstringrequired

The unique merchant point-of-sale device identifier.

Example:POS-001

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

The systemTransactionId from the original transaction to be modified.

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

Bodyapplication/jsonrequired

Modification request for a previously initiated 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"

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"

operationstringrequired

The operation to apply.

Enum:"Capture""FinalCapture""Incremental""Refund""Void"

Example:"Capture"

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.

curl -i -X POST \
  https://api-services.pxp.io/api/v1/cloud-device/POS-001/transactions/1ed768bb-e88a-4636-91ae-67927ccbb02b/modifications \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "TXN-001-CAPTURE",
    "merchantTransactionDate": "2025-01-27T09:00:00.000Z",
    "operation": "Capture",
    "amounts": {
      "currencyCode": "EUR",
      "transaction": 30.32
    }
  }'

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": "Captured",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "A123456",
  "merchantTransactionId": "TXN-001-CAPTURE",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2025-01-27T09:00:00.000Z",
  "providerTransactionId": "PROV-98765",
  "fundingData": {
    "maskedPrimaryAccountNumber": "************1234",
    "cardScheme": "Visa",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "providerResponse": { … }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  }
}