Recurring payments

Recurring payments allow you to charge a customer's card multiple times using stored card information. This is essential for subscription services, instalments, and scenarios where you need to charge a customer after the initial transaction.

When processing recurring payments, it's important to understand the distinction between different transaction types based on who initiates the payment and whether the cardholder is present.

There are two types of recurring transactions:

• Card-on-file transactions
• Merchant-initiated transactions

Card-on-file transactions are payments where the cardholder is present and actively initiates the payment using their previously stored card details. These are also called customer-initiated transactions (CITs).

Strong Customer Authentication (SCA) is required for both the initial card storage and subsequent cardholder-initiated payments.

Common use cases include:

• One-click checkout: The customer selects their saved card to complete a purchase.
• Manual payments: The customer triggers a payment using previously stored credentials.
• Additional purchases: The customer buys extra services or products using their saved payment method.
• In-app purchases: The customer confirms and completes a transaction within an application

Use COF processing models (cardOnFileShopperConsent and cardOnFileShopperInitiated) when your customer is actively making a purchase decision and completing the transaction themselves.

Merchant-initiated transactions are payments where you initiate the charge without the cardholder being present, using their previously stored card details and consent.

SCA is required for the initial setup transaction, but not required for subsequent merchant-initiated transactions. This exemption from SCA is what makes MITs suitable for automated recurring payments.

Common use cases include:

• Subscriptions: Monthly streaming service charges, annual memberships
• Instalments: Payment plans split over several months
• Delayed charges: Hotel mini-bar charges added after checkout, rental car damage fees
• No-show fees: Restaurant or hotel reservation no-show penalties
• Automatic top-ups: Account balance replenishment when it falls below a threshold
• Usage-based billing: Utility bills charged at the end of a billing period

Use MIT processing models (all merchantInitiated* models) when you need to charge the customer automatically without their active involvement in each transaction.

The typical workflow involves two stages:

1. Initial setup (requires SCA):

   • The customer completes a transaction with their card details.
   • The customer provides consent for you to store their card information.
   • You use cardOnFileShopperConsent or merchantInitiatedInitialRecurring.
   • You receive a gatewayTokenId and scheme transaction identifiers in the response.
   • You store these values for future use.

2. Subsequent transactions:

   • If the customer initiates, use cardOnFileShopperInitiated (requires SCA).
   • If you initiate, use the appropriate merchantInitiated* model (no SCA required).
   • In both cases, include the gatewayTokenId and scheme transaction identifiers from the initial transaction.

When setting up the initial card-on-file payment, you'll receive scheme transaction identifiers in the providerResponse. You must store these values and include them in all subsequent merchant-initiated transactions.

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.

{
  "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"
  }
}

{
  "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,
      "schemeTransactionId": "MC123456789012345678",
      "schemeTransactionLinkId": "TLID1234567890123456789012",
      "settlementDate": "2025-04-08T00:00:00"
    },
    "processorTransactionId": "c2dbfd3d-837d-48f7-b4e6-9e37c226c2d6"
  }
}

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"
  }
}

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,
      "schemeTransactionId": "MC123456789012345678",
      "schemeTransactionLinkId": "TLID1234567890123456789012",
      "settlementDate": "2025-04-08T00:00:00"
    },"processorTransactionId": "50f52fd5-9059-4a96-94ce-b5ede7ce7799"
  }
}