Last Updated: 30 April 2024 | Change Log

Take a recurring sale

Use our recurring sale resource when you are initiating a payment using your customer's stored card details, and you want to instantly trigger the settlement process. Read more about recurring mandates here.

What are recurring payments?

  • A transaction that is triggered by a process when your customer is not actively participating at the point of authorization
  • Can only be performed as a follow up from an original card on file payment when your customer was authenticated and agreed to a standing instruction
  • You must declare the intent for all recurring payments, either: subscription, instalment or unscheduled
  • Sometimes referred to as Merchant Initiated Transaction (MIT)

Prerequisite

You must verify your customer's account before submitting your first recurring payment for authorization.

Recurring sales

Use our recurring sale resource to authorize and settle merchant initiated transactions where you have stored the card details.

POST your recurring sale request to the payments:recurringSale action link received in your successful cardOnFile intelligent or dynamicCardOnFile verification.

Recurring sale example request

POST https://try.access.worldpay.com/payments/sales/recurring/{resource}

Note

Click the tabs below to see all the mandatory fields for all supported paymentInstrument parameters.

Recurring sale request body:

  1. Card
  2. Token
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 12,
                "year": 2020
            }
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "intent": "subscription"
    }
}

Parameter descriptions

ParameterRequiredDescription
transactionReferenceA unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format, for more details and the best practices.
merchantAn object that contains information about the merchant.
merchant.entityDirect your payment to assist with billing, reporting and reconciliation. This is mandatory for Authentication and Queries.
Contact your Implementation Manager for more details.
merchant.mccYou can apply a merchant category code (mcc) to an individual request. You can only provide an mcc if we have enabled the dynamic mcc feature during boarding. If enabled but not provided, merchant.mcc defaults to a configured value. For more information contact your Relationship Manager.
merchant.paymentFacilitatorAn object containing Payment Facilitator information. If required you must send:
  • pfId
  • isoId
  • subMerchant.merchantId
  • subMerchant.postalcode
  • subMerchant.street
  • subMerchant.city
  • subMerchant.countryCode
  • subMerchant.telephone (mandatory for Amex)
  • subMerchant.email (mandatory for Amex)
This information is required for every sale request only if you are a Payment Facilitator. You can find more formatting information here.
instructionAn object that contains all the information related to the payment.
instruction.intentA parameter detailing the reason for this particular recurring agreement. Valid intents:
  • subscription
  • unscheduled
  • instalment
instruction.narrativeThe text that appears on your customer's statement. Used to identify the merchant.
See narrative format for more details and the best practices.
narrative.line1The first line of the narrative which appears on your customer's statement (24 character max. If character is not supported it is replaced with a space.).
See narrative line1 format for more details.
narrative.line2Additional details about the payment e.g. order number, telephone number.
instruction.valueAn object that contains information about the value of the payment.
value.currencyThe 3 digit currency code.
See list of supported currencies.
value.amountThe payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our currency table.
instruction.paymentInstrumentAn object that contains the payment type and details.
To use tokens as a paymentInstrument you must first create a token, see our Tokens API on how to create a token.
payoutInstrument.cardExpiryDateAn object that contains your customer's card expiry date.
Mandatory for all "type": "card/plain" requests.
payoutInstrument.cardNumberAn object that contains your customer's card number. Mandatory for "type": "card/plain" requests.
paymentInstrument.cvcCVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.
paymentInstrument.cardHolderNameAn object that contains your customer's card name.
This is not a mandatory field however it is recommended that you supply this to improve authorization rates. If not sent the default is "Not Supplied".
paymentInstrument.billingAddressAn object containing the billing address information. If included you must send at least:
  • address1
  • city
  • countryCode
  • postalCode
This is used for Address Verification Service (AVS) and can only be supplied with a card/plain payment instrument. Our API checks the submitted AVS to see if it matches the address registered with the issuing bank. If the address supplied does not match the registered address it means that the payment carries additional risk.
instruction.debtRepaymentDRI is a flag which identifies a payment as being for the purpose of repaying a debt. Possible value :
  • true (only supply if true)
For more information contact your Relationship Manager.

Optional parameters

Example recurring sale request (all parameters)

The requests below contain all the mandatory and optional fields needed for a successful recurring sale request.

Full recurring sale request body:

  1. Card
  2. Token
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6432",
        "paymentFacilitator": {
            "pfId": "12345",
            "isoId": "12345",
            "subMerchant": {
                "name": "John",
                "merchantId": "12345",
                "postalCode": "SW1 1AA",
                "street": "Regent Street",
                "city": "London",
                "state": "WSM",
                "countryCode": "826",
                "taxId": "ABC-123456789",
                "email": "test@email.com",
                "telephone": "+447987 654321"
            }
        }
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd",
            "line2": "Memory265-13/08/1876"
        },
        "scheme": {
            "reference": "28379213"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "billingAddress": {
                "address1": "221B Baker Street",
                "address2": "Marylebone",
                "address3": "Westminster",
                "postalCode": "NW1 6XE",
                "city": "London",
                "state": "Greater London",
                "countryCode": "GB"
            },
            "type": "card/plain",
            "cardHolderName": "Sherlock Holmes",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 12,
                "year": 2020
            }
        },
        "intent": "instalment"
    }
}

Recurring sale response

Best Practice

Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

Successful response

  • an HTTP code 201
  • an "outcome": "Sent for Settlement"
  • risk factors (only returned if issuer identifies conflict)
  • an issuer authorization code
  • scheme reference (supported by major card schemes, but may not be returned for all schemes/regions)
  • a paymentInstrument
  • links to refund, partially refund, reverse or query payment events
  • an authorization link for the next payment in your repeat payment agreement

paymentInstrument

The "paymentInstrument" object is returned if we are able to provide information related to the underlying card used in the authorization request.

Note

Note that if the paymentInstrument object is returned, there is no guarantee that each field listed below will be returned with every transaction.

ParameterDescription
paymentInstrument.typeThe type of paymentInstrument. Eg:
  • card/plain+masked
  • card/network+masked
  • card/network
paymentInstrument.card.brandThe card brand. Sometimes referred to as the network or scheme. Eg:
  • "visa"
  • "mastercard"
  • "amex"
paymentInstrument.card.number.binThe card bin. Eg:
444433
Note
this may contain the * character.
paymentInstrument.card.number.last4DigitsThe last four digits of the card. Eg:
1111
Note
this may contain the * character, where the card number is less than 16 digits.
paymentInstrument.card.expiryDate.monthThe card expiry month. Eg:
11
paymentInstrument.card.expiryDate.yearThe card expiry year. Eg:
2025
paymentInstrument.card.fundingTypeHow the card is funded. Eg:
  • credit
  • debit
  • prepaid
  • deferredDebit
  • chargeCard
paymentInstrument.card.categoryWhether the card is classed as a consumer card or a card for commercial use. Eg:
  • consumer
  • commercial
paymentInstrument.card.countryCodeThe alpha-2 ISO-3166 country code that the card was issued in. May return "N/A" where the country is unknown. Eg:
GB
paymentInstrument.card.issuer.nameThe name of the card issuer. Eg:
Some Issuer PLC.
paymentInstrument.card.paymentAccountReferenceThe payment account reference (PAR) is a non-financial reference that uniquely identifies the underlying cardholder account. This allows you to correlate payments made with differing instruments (e.g. "card/plain" and "card/wallet+applepay"), where the same account funds the transaction. A PAR cannot be used to intiate a payment. Eg:
ABC123DEF456GHI789JKL123MNO45

Refused response

You receive:

  • an HTTP code 201
  • an "outcome": "refused"
  • a refusal code
  • a description which gives additional context on the refusal
  • a refusal advice code (only if returned by the card scheme and acquirer)
  • risk factors (only returned if issuer identifies conflict)

Example responses

  1. Successful
  2. Refusal
{
    "outcome": "Sent for Settlement",
    "issuer": {
        "authorizationCode": "12345A"
    },
    "scheme": {
        "reference": "1260019172"
    },
    "paymentInstrument": {
        "type": "card/plain+masked",
        "card": {
            "brand": "visa",
            "number": {
                "bin": "444433",
                "last4Digits": "1111"
            },
            "expiryDate": {
                "month": 12,
                "year": 2025
            },
            "fundingType": "credit",
            "category": "consumer",
            "issuer": {
                "name": "Some Issuer PLC"
            },
            "paymentAccountReference": "ABC123DEF456GHI789JKL"
        }
    },
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "_links": {
        "payments:refund": {
            "href": "https://try.access.worldpay.com/payments/settlements/refunds/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialRefund": {
            "href": "https://try.access.worldpay.com/payments/settlements/refunds/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:reversal": {
            "href": "https://try.access.worldpay.com/payments/sales/reversals/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }],
        "payments:recurringSale": {
            "href": "https://try.access.worldpay.com/payments/sales/recurring/eyJrIjoiazNhYjYzMiJ9"
        }
    }
}

You must always store and use the link returned in the payments:recurringSale action link for your next recurring sale requests.

Note
In case of an error, you can get further information in our error reference.


Next steps


Refund a payment