Transactions service

Transactions service (1.0.0)

This is an API reference for the Transaction service API.

Download OpenAPI description

transaction.json

transaction.yaml

Servers

Production environment

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

Sandbox environment

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

Initiate a transaction

Request

The /transactions endpoint enables the initiation of transactions, supporting various transaction methods, including card and alternative payments. It facilitates authoristions, tokenisation, recurring payments, and incorporates security enhancements, offering a versatile solution for payment processing across both online and instore.

Bodyapplication/jsonrequired

Initiate a transaction

merchantstring(merchant)<= 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(site)<= 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"

merchantTransactionIdstring(merchantTransactionId)<= 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.

Example: "This_is_my_merchant_transaction_id"

merchantTransactionDatestring(date-time)(merchantTransactionDate)required

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"

transactionMethodobject(transactionMethod)required

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

transactionMethod.entryTypestring(entryType)required

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.

Enum"Ecom""Moto""Instore"

Example: "Ecom"

transactionMethod.fundingTypestring(fundingType)required

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.intentstring(intent)required

The purpose or action of the transaction, indicating the intended money flow direction. This field is crucial for categorising 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"

fundingDataobject(fundingData)required

Details about the payment method used to fund the transaction.

fundingData.cardApple Pay (object) or Card not present (object) or Card present (object) or Scheme token number (object) or Scheme token ID (object)(card)required

Details about the card.

One of:

Apple Pay transaction details, encapsulating the tokenised payment information. This is used for transactions processed through Apple Pay in Moto (Mail Order/Telephone Order) or Ecom (E-commerce) entry types. The token includes encrypted payment data, enhancing security and facilitating fraud prevention by utilising Apple's tokenisation technology.

fundingData.card.tokenstringrequired

A token generated by Apple Pay that encapsulates the customer's payment information. This token is used instead of actual card numbers, providing a secure method to process transactions without exposing sensitive card details. The token includes information such as the device-specific account number, cryptogram, and other necessary payment data for processing.

Example: "{ 'version': 'EC_v1', 'data': '...', 'signature': '...', 'header': { 'ephemeralPublicKey': '...', 'publicKeyHash': '...', 'transactionId': '...' } }"

fundingData.dynamicDescriptorsobject(dynamicDescriptors)

Merchant-defined descriptors that enhance transaction recognition on customer bank statements.

addressVerificationobject(addressVerification)

Address verification details, applicable for transactions with Moto or Ecom as the entry type. It aids in the validation and fraud prevention process by matching the provided address with the cardholder's address on file.

identityVerificationobject(identityVerification)

Provides a set of boolean flags that indicate the results of various identity verification checks. This object is applicable only when the transactionMethod.intent is set to Verification for transactions processed with Moto or Ecom entry types. These checks are essential to ensure that the information provided matches the cardholder's details on file, crucial for enhancing security and reducing fraud risks. Each property within this object represents a different aspect of the cardholder's identity being verified.

amountsobject(amounts)required

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.transactionnumber(transaction)required

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.gratuityValuenumber(gratuityValue)

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

shopperobject(shopper)

Details of the shopper involved in the transaction.

shopperSecurityDataobject(shopperSecurityData)

Security-related information to enhance transaction safety and fraud prevention.

recurringobject(recurring)

The recurring payment details associated with the transaction.

threeDSecureDataobject(threeDSecureData)

This field is relevant for transactions identified as Ecom in the transactionMethod.entryType. It contains data essential for the 3-D Secure authentication process, which enhances online transaction security by facilitating the verification of the cardholder's identity. This process adds an important layer of protection against fraud in digital transactions. If authenticationId is provided, it will be used by PXP to look up the associated 3-D Secure authentication data, and all other fields will be ignored. If authenticationId is not provided, you are expected to populate the fields relevant to the authentication.

psd2Dataobject(psd2Data)

Contains PSD2-related information for the transaction, including any applicable Strong Customer Authentication (SCA) exemptions.

dccDataobject(dccData)

Details about the Dynamic Currency Conversion (DCC).

riskScreeningDataobject(riskScreeningData)

Details about the transaction for risk screening purposes.

curl -i -X POST \
  https://api-services.pxp.io/api/v1/transactions \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "MERCHANT-1",
    "site": "SITE-1",
    "merchantTransactionId": "This_is_my_merchant_transaction_id",
    "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
    "transactionMethod": {
      "intent": "Authorisation",
      "entryType": "Ecom",
      "fundingType": "Card"
    },
    "fundingData": {
      "card": {
        "primaryAccountNumber": "4111111111111111",
        "expiryMonth": "03",
        "expiryYear": "2025",
        "holderName": "Mr John Doe"
      }
    },
    "amounts": {
      "transaction": 30.32,
      "currencyCode": "EUR"
    },
    "shopper": {
      "id": "Shopper_01",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-03-01",
      "email": "shopper@example.com"
    }
  }'

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.

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

approvalCodestring(approvalCode)^[A-Z]

A unique identifier code provided by the authorising 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(merchantTransactionId)<= 50 characters

Example: "This_is_my_merchant_transaction_id"

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

dccResultobject

Details about the DCC (Dynamic Currency Conversion) result, including the rate selected indicator, amounts, mark-up rate, commission percentage, exchange rate, provider data, and DCC disclosure.

Response

application/json

{
  "state": "Authorised",
  "approvalCode": "123456",
  "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",
    "schemeTokenNumber": "4837261112345678",
    "avsResult": "noInformationAvailable",
    "cvcResult": "noInformationAvailable",
    "providerResponse": { … }
  }
}

Create a 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. 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.

amountsobjectrequired

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

amounts.transactionnumber(transaction)required

Example: 30.32

amounts.gratuityValuenumber(gratuityValue)

Example: 5.01

merchantstring(merchant)<= 20 charactersrequired

Example: "MERCHANT-1"

merchantTransactionDatestring(date-time)(merchantTransactionDate)required

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

merchantTransactionIdstring(merchantTransactionId)<= 50 charactersrequired

Example: "This_is_my_merchant_transaction_id"

operationstring(operation)required

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""FinalCapture""Incremental""Refund""Void"

Example: "Capture"

sitestring(site)<= 20 charactersrequired

Example: "SITE-1"

curl -i -X POST \
  https://api-services.pxp.io/api/v1/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

statestring(state)required

The current state of the transaction.

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

Example: "Authorised"

stateDataobject(stateData)

Key value pair for various state data.

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

approvalCodestring(approvalCode)^[A-Z]

Example: "A123456"

merchantTransactionIdstring(merchantTransactionId)<= 50 characters

Example: "This_is_my_merchant_transaction_id"

systemTransactionIdstring(systemTransactionId)[ 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)(merchantTransactionDate)

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

fundingDataobject

Details about the payment method used for the transaction.

Response

application/json

{
  "state": "Captured",
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "maskedPrimaryAccountNumber": "***************5678",
    "expiryMonth": "03",
    "expiryYear": "2025",
    "paymentAccountReference": "PAR12345678901234567890",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "schemeTokenNumber": "4837261112345678"
  },
  "providerResponse": {
    "provider": "PXPFinancial",
    "code": "00",
    "message": "Approved",
    "merchantId": "77772182",
    "terminalId": "75836665",
    "schemeTransactionId": "TX1234567890123456",
    "settlementDate": "2024-01-25T00:00:00.000Z"
  }
}

Get transaction details

Request

Path

merchantstring<= 20 charactersrequired

The unique merchant identifier associated with the transaction, as assigned by PXP.

Example: MERCHANT-1

sitestring<= 20 charactersrequired

The unique site identifier associated with the transaction, as assigned by PXP.

Example: SITE-1

Query

merchantTransactionIdstring<= 50 characters

The unique identifier that you assigned to this transaction.

Example: merchantTransactionId=ECOM-001

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

The unique identifier assigned to this transaction by PXP.

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

curl -i -X GET \
  'https://app-reporting-dev-001.azurewebsites.net/api/v1/transactions/MERCHANT-1/SITE-1?merchantTransactionId=ECOM-001&systemTransactionId=1ed768bb-e88a-4636-91ae-67927ccbb02b'

Responses

Transaction details 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.

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

approvalCodestring(approvalCode)^[A-Z]

Example: "A123456"

merchantTransactionDatestring(date-time)(merchantTransactionDate)

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

merchantTransactionIdstring(merchantTransactionId)<= 50 characters

Example: "This_is_my_merchant_transaction_id"

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

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

Details about the payment method used for the transaction.

Response

application/json

{
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "state": "Authorised",
  "stateMessage": "Transaction Authorised",
  "transactionMethod": {
    "intent": "Authorisation",
    "fundingType": "Card",
    "entryType": "Ecom"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_transaction_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "amounts": {
    "transaction": 50.05,
    "currencyCode": "EUR"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "2022-01-26T00:00:00.000Z",
    "email": "shopper@example.com"
  }
}

Get order details

Request

Path

merchantstring<= 50 charactersrequired

Your unique merchant identifier, as assigned by PXP.

Example: MERCHANT-1

sitestringrequired

Your unique site identifier, as assigned by PXP.

Example: SITE-1

Query

fundingTypestringrequired

The funding type used for this transaction. Currently, only paypal is supported.

Example: fundingType=paypal

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

The unique identifier assigned to this transaction by PXP.

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

curl -i -X GET \
  'https://api-services.pxp.io/api/v1/transactions/MERCHANT-1/SITE-1/order-details?fundingType=paypal&systemTransactionId=1ed768bb-e88a-4636-91ae-67927ccbb02b'

Responses

Successful response

Bodyapplication/json

fundingDataobject

Details about the funding method.

Response

application/json

{
  "fundingData": {
    "shippingAddress": { … },
    "merchantTransactionId": "TRANSACTION-001",
    "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
  }
}

Transactions service (1.0.0)

Initiate a transaction

Request

Responses

Was this helpful?

Create a modification

Request

Responses

Was this helpful?

Get transaction details

Request

Responses

Was this helpful?

Get order details

Request

Responses

Was this helpful?

Transactions service (1.0.0)

Initiate a transaction

RequestExpand all

Responses

Was this helpful?

Create a modification

RequestExpand all

Responses

Was this helpful?

Get transaction details

Request

Responses

Was this helpful?

Get order details

Request

Responses

Was this helpful?

Request

Request