Skip to content
Transactions/Initiate transactions/
/
Recurring payments

Recurring payments

Charge a credit or debit card on a recurring basis.

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.

ParameterDescription
CardOnFileShopperConsentThe 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.
CardOnFileShopperInitiatedThe cardholder is making a transaction and has previously consented to you saving their card details.
MerchantInitiatedReAuthorisationYou 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.
MerchantInitiatedResubmissionYou 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.
MerchantInitiatedDelayedChargeYou 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.
MerchantInitiatedNoShowYou 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.
MerchantInitiatedInitialRecurringYou 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.
MerchantInitiatedSubsequentRecurringYou 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"
  }
}
ParameterDescription
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
object		Details about the transaction amount
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

POST
/v1/transactions

Request examples

To set up a card-on-file recurring payment, 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": "CardOnFileShopperConsent"
}
}
ParameterDescription
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.gatewayTokenId
string (≤ 100 characters)		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
object
required		Details about the transaction amount.
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

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": "182765",
  "merchantTransactionDate": "2025-04-07T09:18:01",
  "merchantTransactionId": "003cd998-38a2-4da3-9a5f-5540ba76d653",
  "systemTransactionId": "0283ae6a-1bc1-46a7-96fe-1f3ab0765850",
  "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": "50f52fd5-9059-4a96-94ce-b5ede7ce7799"
  }
}
©2025 PXP Financial. PXP Financial 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.