Processing models

The processing model describes the type of recurring payment associated with a transaction.

There are two categories of processing models:

Card-on-file (COF): the cardholder initiates the transaction after saving their card details.
Merchant-initiated: you initiate the transaction using a cardholder's previously saved card details.

The following table describes the supported processing models.

Parameter	Description
`CardOnFileShopperConsent`	The cardholder is consenting to you saving their card details so they don't have to re-enter them. For example, by ticking a box while on the payment screen. You should then use the `CardOnFileShopperInitiated` parameter in subsequent request.
`CardOnFileShopperInitiated`	The cardholder is making a transaction and has previously consented to you saving their card details.
`MerchantInitiatedReAuthorisation`	You have previously saved a customer's details and want to request a new authorisation. For example, if the initial authorisation is about to expire for a transaction that hasn't bee completed yet.
`MerchantInitiatedResubmission`	You have previously saved a customer's details and want to retry a transaction that was previously declined due to temporary issues. For example, in case of technical issues or insufficient funds.
`MerchantInitiatedDelayedCharge`	You have previously saved a customer's card details and need to add additional charges after the initial transaction has occurred. For example, to recover damage fees for a rented card.
`MerchantInitiatedNoShow`	You have previously saved a customer's card details and need to charge them a no-show fee. For example, if they have failed to show up after making a hotel reservation.
`MerchantInitiatedInitialRecurring`	You are saving a customer's card details so that you can take recurring payments in the future. You should then use the `MerchantInitiatedSubsequentRecurring` parameter in subsequent requests.
`MerchantInitiatedSubsequentRecurring`	You have previously saved a customer's card details and are processing a standard recurring payment, such as a subscription.

Set up a merchant-initiated recurring payment

POST

/v1/transactions

Request examples

To set up a merchant-initiated subscription, you'll need to add the recurring object to the payload of your first transaction request and provide the full card details in the fundingData.card object. In the response, you'll receive a gatewayTokenId containing the tokenised details of the card.

For subsequent charges, you'll have to provide an updated recurring object and the gatewayTokenId rather than the full card details.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "ECOM_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },  
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "expiryMonth": "09",
      "expiryYear": "2025",
      "cardVerificationCode": "788",
      "holderName": "John Doe"
    }
  },
  "amounts": {
    "transaction": 5,
    "currencyCode": "GBP"
  },
  "recurring": {
    "processingModel": "MerchantInitiatedInitialRecurring",
    "frequencyInDays": 30,
    "frequencyExpiration": "2025-12-31"
  }
}

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "ECOM_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },     
  "fundingData": {
    "card": {
      "gatewayTokenId": "5fbd77ce-02c1-40ed-94bc-1016660b7512"
    }
  },
  "amounts": {
    "transaction": 5,
    "currencyCode": "GBP"
  },
  "recurring": {
    "processingModel": "MerchantInitiatedSubsequentRecurring"
  }
}

Parameter	Description
`merchant` string (≤ 20 characters) required	Your unique merchant identifier, as assigned by PXP.
`site` string (≤ 20 characters) required	Your unique site identifier, as assigned by PXP.
`merchantTransactionId` string (≤ 50 characters) required	A unique identifier for this transaction.
`merchantTransactionDate` date-time required	The date and time when the transaction happened, in ISO 8601 format.
`transactionMethod` object required	Details about the transaction method.
`transactionMethod.entryType` string required	The entry type. For e-commerce transactions, this is always `Ecom`.
`transactionMethod.fundingType` string required	The funding type. For card transactions, this is always `Card`.
`transactionMethod.intent` string required	The payment intent. Learn more about intents. Possible values: `Authorisation` `EstimatedAuthorisation` `Purchase` `Payout` `Refund`
`fundingData` object required	Details about the payment method used for the transaction.
`fundingData.card` object	Details about the card.
`fundingData.card.primaryAccountNumber` string (10-19 characters)	The unique number assigned to a payment card, such as a credit or debit card. This number typically contains 16 digits, structured in a specific format to indicate the card network, issuing bank, and account number.
`fundingData.card.expiryMonth` string (2 characters)	The expiry month (`MM`) of the card.
`fundingData.card.expiryYear` string (4 characters)	The expiry year (`YYYY`) of the card.
`fundingData.card.cardVerificationCode` string (3-4 characters)	The Card Verification Code (CVC) associated with the payment card, which is used to verify that the cardholder is in possession of the card during non-face-to-face transactions.
`fundingData.card.holderName` string (≤ 100 characters)	The full name of the individual who owns the payment card. This name is printed on the physical card and is used for verifying the cardholder's identity during transactions.
`fundingData.card.gatewayTokenId` string	A securely stored token that corresponds to a previously saved payment card. This token is generated and maintained by PXP to facilitate recurring transactions or transactions using stored card details, ensuring enhanced security and convenience. When a transaction is performed with a saved card, this token ID should be provided instead of the full card details.
`amounts.transaction` number	The transaction amount. 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 (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0).
`amounts.currencyCode` string (1-3 characters) required	The currency code associated with the transaction, in ISO 4217 format.
`recurring` object	Details about the recurring payment details associated with the transaction.
`recurring.processingModel` string (enum) required	Indicates the type of recurring payment associated with the transaction. When you first create a token, this indicates what type of recurring payment the token is intended for. For subsequent payments, it indicates the type of recurring payment. Specifically, the `frequencyInDays` and `frequencyExpiration` properties are applicable only when this is set to `MerchantInitiatedInitialRecurring`. Possible values: `CardOnFileShopperConsent` `CardOnFileShopperInitiated` `MerchantInitiatedReAuthorisation` `MerchantInitiatedResubmission` `MerchantInitiatedDelayedCharge` `MerchantInitiatedNoShow` `MerchantInitiatedInitialRecurring` `MerchantInitiatedSubsequentRecurring`
`recurring.frequencyInDays` integer	The interval (in days) between each recurring transaction for the `MerchantInitiatedInitialRecurring` processing model. This defines how often the recurring payments are attempted following the initial charge.
`recurring.frequencyExpiration` date	The expiration date for the recurring transaction authorisation specific to the `MerchantInitiatedInitialRecurring` processing model. After this date, no further recurring transactions are processed.
`recurring.settlementDate` date	The date on which the transaction funds are settled between banks for MasterCard payments. This field is applicable and provided only for transactions processed using MasterCard. The settlement date is crucial for financial reconciliation and is formatted as `YYYY-MM-DD`.

Response examples

If your request is successful, you'll receive a 200 response that includes the transaction's state. You'll also receive a Transaction (Card Authorised) webhook notification.

{
  "state": "Authorised",
  "stateData": {},
  "approvalCode": "210693",
  "merchantTransactionDate": "2025-04-07T15:27:53",
  "merchantTransactionId": "34036779-08d2-4f92-88ad-e025fc6998d7",
  "systemTransactionId": "635b1b51-4a27-4d23-8c9f-8150ff7eb9dd",
  "fundingData": {
    "cardScheme": "MasterCard",
    "expiryMonth": null,
    "expiryYear": null,
    "gatewayTokenId": "5fbd77ce-02c1-40ed-94bc-1016660b7512",
    "providerResponse": {
      "provider": "pxpfinancial",
      "code": "00",
      "emvDataResponse": {},
      "paymentAccountReference": "637607302178175469",
      "electronicCommerceIndicatorAdjustment": "07",
      "merchantAdvice": {},
      "authorisedAmount": 5,
      "settlementDate": "2025-04-08T00:00:00"
    },
    "processorTransactionId": "c2dbfd3d-837d-48f7-b4e6-9e37c226c2d6"
  }
}

Set up a card-on-file recurring payment