Initiate a transaction

Request

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

Bodyapplication/jsonrequired

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"

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"

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"

merchantTransactionDatestring, (date-time)required

The current date and time in ISO 8601 format.

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

transactionMethodobjectrequired

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

fundingDataobjectrequired

Funding details for the transaction. Send exactly one of card, payByBank, or paypal, matching transactionMethod.fundingType (Card, PayByBank, or Paypal).

addressVerificationobject

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

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.

amountsobjectrequired

Details of the amount including transaction, gratuity, and service charge values and its associated currency. Note that gratuity and serviceCharge can't be sent together.

shopperobject

Details of the shopper involved in the transaction.

shopperSecurityDataobject

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

recurringobject

The recurring payment details associated with the transaction.

threeDSecureDataobject

Details about 3D Secure for e-commerce transactions. Provide either authenticationId from PXP 3D Secure or inline authentication fields.

For digital wallets:

Apple Pay (encrypted): Omit threeDSecureData.
Apple Pay (decrypted): Provide cardHolderAuthenticationVerificationValue and electronicCommerceIndicator from the decryption response.
Google Pay (decrypted): Pass through existing authentication proof, or use PXP 3D Secure and send authenticationId.
- If the decryption response includes paymentMethodDetails.cryptogram (authMethod CRYPTOGRAM_3DS), pass through that proof: map cryptogram to cardHolderAuthenticationVerificationValue and eciIndicator to electronicCommerceIndicator. Don't run a separate PXP 3D Secure flow.
- If there's no cryptogram (authMethod PAN_ONLY), threeDSecureData is optional. If you choose to authenticate (e.g., due to SCA rules in your market), send authenticationId from PXP 3D Secure, or pass through inline fields from your own 3DS provider.

psd2Dataobject

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

dccDataobject

Details about the Dynamic Currency Conversion (DCC).

riskScreeningDataobject

Details about the transaction for risk screening purposes.

shippingAddressobject

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

transactionIdentifiersobject

Optional transaction identifiers. For payment links, supply linkId.

sessionMetadataobject

Provider-specific session metadata containing authentication and routing information. String key-value pairs.

Example:

{
  "sessionId": "sess_01HZX3K9EXAMPLE"
}

rulesetIdstring, (uuid)

An optional ruleset identifier for A/B testing. When provided, the transaction is evaluated against this ruleset instead of the currently active one.

Example:"550e8400-e29b-41d4-a716-446655440000"

systemTransactionIdstring

Optional system transaction identifier provided on transaction initiation.

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

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",
    "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
    "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
    "transactionMethod": {
      "intent": "Authorisation",
      "entryType": "Ecom",
      "fundingType": "Card"
    },
    "fundingData": {
      "card": {
        "primaryAccountNumber": "4111111111111111",
        "expiryMonth": "03",
        "expiryYear": "2027",
        "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

The transaction was accepted for processing. Inspect state and stateData for the outcome, and use systemTransactionId for later query or modification requests.

Bodyapplication/json

statestring

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"

merchantTransactionDatestring, (date-time)required

The current date and time in ISO 8601 format.

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

merchantTransactionIdstring or null, <= 50 charactersrequired

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.

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.

dccDataobject

Details about Dynamic Currency Conversion (DCC), when the cardholder pays in their home currency.

amountsobject

Details of the amount including transaction, gratuity, and service charge values and its associated currency. Note that gratuity and serviceCharge can't be sent together.

riskScreeningDataobject

Risk screening results for fraud detection and prevention.

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": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "primaryAccountNumber": "************1111",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "addressVerificationServiceResult": "NoInformationAvailable",
    "cardVerificationCodeResult": "NoInformationAvailable",
    "providerResponse": { … }
  }
}