Skip to content
/
Create a modification

Create a modification

Request

Process modifications on previously initiated transactions. Supported operations include captures, refunds, incremental authorisations, and voids. This endpoint 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. Always use the first systemTransactionId returned for an authorisation or purchase if you want to perform an increment, capture, refund, or void. This ensures that the correct transaction is referenced for any subsequent operations.

Example:1ed768bb-e88a-4636-91ae-67927ccbb02b
Bodyapplication/jsonrequired

Modifications to a previous transaction.

fundingTypestringrequired

The type of funding source used for the transaction.

Enum:"Card""Paypal""PayByBank"
Example:"Card"
apmProviderstring

The alternative payment method (APM) provider that processes the pay-by-bank transaction, such as Aeropay, Spei, Cvu, Breb, or Flashflow.

On modifications where fundingType is PayByBank, this field is required — if omitted, the gateway defaults to Aeropay.

For SPEI refunds, set this to Spei. For CVU refunds, set this to Cvu. For Bre-B refunds, set this to Breb. FlashFlow doesn't support capture, void, or refund.

Enum:"Aeropay""Spei""Cvu""Breb""Flashflow"
Example:"Aeropay"
amountsobjectrequired

Details of the modification amount, including the transaction value and optional gratuity. Send the currency as the top-level currencyCode on the modification request, not inside amounts.

merchantstring, <= 10 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"
merchantTransactionDatestring, (date-time)

The current date and time in ISO 8601 format.

Example:"2024-01-27T08:51:02.826Z"
merchantTransactionIdstring or null, <= 50 charactersrequired

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. On create responses it is always present. On query responses it may be null for some flows (for example certain CVU deposits) when no merchant reference was supplied.

Example:"This_is_my_merchant_transaction_id"
merchantTransactionGroupIdstring, <= 50 characters

An optional identifier assigned by you to group related transactions together, enabling easier tracking and reporting.

Example:"This_is_my_merchant_transaction_group_id"
operationstringrequired

Describes the operation to be applied to the previous transaction.

Supported operations by funding type:

  • Card: Capture, FinalCapture, Incremental, Refund, Void
  • Paypal: Capture, FinalCapture, Refund, Void, Authorisation, Update
  • PayByBank - Aeropay: Capture, Incremental, Refund, Void
  • PayByBank - SPEI: Refund only
  • PayByBank - CVU: Refund only
  • PayByBank - Bre-B: Refund only
  • PayByBank - FlashFlow: not supported (no capture, void, or refund)
Enum:"Capture""FinalCapture""Incremental""Refund""Void""Authorisation""Update"
Example:"Capture"
sitestring, <= 50 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"
remarkstring or null

Optional remark or note about the modification.

Example:"Customer requested partial refund"
dccDataobject

Details about the Dynamic Currency Conversion (DCC).

currencyCodestring, = 3 characters

The currency code for the modification amount, in ISO 4217 format. For SPEI refunds, this must be MXN. For CVU refunds, this must be ARS.

Example:"EUR"
curl -i -X POST \
  https://api-services.pxp.io/api/v1/transactions/1ed768bb-e88a-4636-91ae-67927ccbb02b/modifications \
  -H 'Content-Type: application/json' \
  -d '{
    "fundingType": "Card",
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "This_is_my_merchant_transaction_id",
    "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_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""Refused""Cancelled""Captured""Error""Executed""Confirmed""Pending""Refunded""Updated"
Example:"Authorised"
stateDataobject

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

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

A unique identifier code provided by the authorising entity, indicating approval or reference for the transaction. This code typically consists of numeric characters and serves as a key reference for authorisation verification.

Example:"123456"
merchantTransactionIdstring or null, <= 50 charactersrequired

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. On create responses it is always present. On query responses it may be null for some flows (for example certain CVU deposits) when no merchant reference was supplied.

Example:"This_is_my_merchant_transaction_id"
systemTransactionIdstring, [ 36 .. 40 ] characters^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

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.

merchantTransactionDatestring, (date-time)required

The current date and time in ISO 8601 format.

Example:"2024-01-27T08:51:02.826Z"
amountsobject

Details of the various amounts associated with the transaction.

fundingDataobject

Funding details returned on create, modify, and query responses.

  • Card: flat card fields at the fundingData root (cardScheme, obfuscated primaryAccountNumber, expiry, tokens, AVS/CVC results, and providerResponse).
  • Pay by bank: wrap details under fundingData.payByBank.
  • PayPal: providerResponse and optional payer.

Responses return exactly one of these shapes for a given fundingType.

riskScreeningDataobject or null

Details about risk screening results for the transaction.

dccDataobject or null

Dynamic Currency Conversion data for the transaction response.

shippingAddressobject

The shipping address for the order. All fields are optional.

paymentAgreementIdstring

The provider agreement identifier for payment methods that create a reusable recurring agreement.

Example:"agr_01HZX3K9EXAMPLE"
tokenIdstring

The token identifier returned for transactions that use an AnyPay credential.

Example:"tok_01HZX3K9EXAMPLE"
attemptsHistoryArray of objects

Ordered list of provider attempts. Present when a payment was retried or routed to a fallback provider.

transactionMethodobject

The transaction method echoed on the response.

Response
{
  "state": "Captured",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "654321",
  "merchantTransactionId": "MOD-20251203-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "PROV-TX-123456",
  "merchantTransactionDate": "2025-12-03T11:00:00Z",
  "amounts": {
    "transaction": 45,
    "currencyCode": "EUR"
  },
  "fundingData": {
    "cardScheme": "Visa",
    "primaryAccountNumber": "************1111",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "gatewayTokenId": "TOKEN-GTW-123",
    "schemeTokenNumber": "4837261112345678",
    "cardVerificationCodeResult": "CardSecurityCodeMatched",
    "addressVerificationServiceResult": "PostCodeMatchedAddressMatched",
    "providerResponse": { … }
  },
  "dccData": {
    "dccSelectedIndicator": "Selected",
    "amounts": { … },
    "providerData": { … },
    "providerResponse": { … },
    "exchangeRate": 1.0778,
    "markupRate": 3,
    "disclaimer": "Exchange rate includes 3% margin."
  }
}
©2026 PXP. PXP Registered Office: The Corn Mill - 1 Roydon Road - Stanstead Abbotts - Hertfordshire - SG12 8XL - United Kingdom Phone +44 2038850598. PXP Financial is Authorised By The Financial Conduct Authority And Our Financial Services Register Number is 504318.