Last Updated: 26 March 2025 | Change Log

Setup a recurring payment

Create an initial customer agreement to perform subsequent recurring merchant initiated payments. Either using API only or our Checkout SDK for low PCI hosted card fields.

Subscription payments involve recurring charges made at regular intervals in exchange for continuous access to a product or service. This model is commonly used for digital services, software, and memberships, providing customers with a seamless experience without the need for repeated purchases.

The request must contain:

customerAgreement.type = subscription - used to indicate the customer has agreed to storing their card for the purpose of future merchant initiated transactions (MIT)
customerAgreement.storedCardUsage = first

If PSD2/SCA or other regional mandates apply you should follow the steps for enabling 3DS and set the following:

threeDS.challenge.preference to challengeMandated

Optionally:

tokenCreation.type = worldpay - include if you're storing the card as a Worldpay token
instruction.value.amount - Set to 0 if no initial payment is being made. A card verification, to check the card details, is performed instead of a full payment request

Apple Pay & Google Pay are not yet supported when setting up a subscription.

Important: You must have agreement from your customer to store their card details.

Collect the card details and send an API request with these details to the Payments resource.

Request

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "method": "card",
        "paymentInstrument": {
            "type": "plain",
            "cardNumber": "4000000000001091",
                "expiryDate": {
                "month": 5,
                "year": 2035
            }
        },
        "tokenCreation": {
            "type": "worldpay"
        },
        "customerAgreement": {
            "type": "subscription",
            "storedCardUsage":"first"
        },
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 42
        }
    }
}

View the full API Request schema

Enable additional features

Feature	Description	Details
Fraud assessment	Prevent fraudulent transactions.	How to enable
3DS authentication	Shift Liability to the issuer / for EEA countries this is required as part of SCA compliance.	How to enable
Auto Settlement	Request that payment authorizations are automatically sent for settlement (sometimes referred to as "capture").	How to enable
Financial Services (MCC 6012 / 6051)	If you provide financial services, debt repayment, or consumer bill payments, you should supply additional details in the authorization request for compliance reasons.	How to enable
Latam America Installments	If you provide financial services, debt repayment, or consumer bill payments, you should supply additional details in the authorization request for compliance reasons.	How to enable

Response

Flow differences

API responses differ based on the features you have enabled:

If 3DS is enabled you will receive a 3dsDeviceDataRequired outcome and additionally, if prompted by the card issuer, a 3dsChallenged response.
If FraudSight is enabled, you can receive a fraudHighRisk response, stopping the transaction.
If settlement.auto is set to true, the outcome will be sentForSettlement. If set to false it will be authorized with an addtional settlement action required.
- If any of the AVS/CVC response riskFactors are marked as notMatched the payment will be sentForCancellation automatically.

See sequence diagrams to get a clear overview.

Payment response

The payment response contains the following details:

riskFactors (avs/cvc) - if billing address & cvc are provided, these details are checked against the customer's issuing bank
refusal code and description which gives additional context on the refusal
3DS authentication details - details on the 3DS authentication outcome (e.g. challenged)
fraud assessment details - details on the fraud assessment outcome (e.g. lowRisk, review)
Worldpay token creation - details of the card tokenized and the token href itself
paymentInstrument - details of the paymentInstrument used