Last Updated: 23 October 2024 | Change Log

Take a recurring payment

Authorize a repeat payment using our recurring payment resource.

What are recurring payments?

Recurring payments follow a schedule, such as subscription or installment payments. A recurring payment is an example of a Merchant Initiated Transaction (MIT) as the cardholder has agreed the merchant may bill them on an ongoing basis.

Recurring payment request

POST your payment request to the payments:recurringAuthorize action link received in your successful oneTime intelligent or dynamicOneTime verification.

Example request

POST http://try.access.worldpay.com/payments/authorizations/recurring/{resource}

Note

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

Request body

{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardHolderName": "John Appleseed",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    }
}

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.
instructionAn object that contains all the information related to the payment.
instruction.narrativeThe text that appears on your customer's statement. Used to identify the merchant.
See narrative formatfor 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.
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.

Optional parameters

Optional parameters and descriptions
ParameterRequiredDescription
narrative.line2Additional details about the payment e.g. order number, telephone number.
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). 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.
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.
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.
merchant.paymentFacilitatorAn object containing Payment Facilitator information. If required you must send:
  • pfId
  • isoId
  • subMerchant.merchantId
  • subMerchant.postalcode
  • subMerchant.street
  • subMerchant.city
  • subMerchant.countryCode
This information is required for every recurring request only if you are a Payment Facilitator. You can find more formatting information here.

The requests below contain all the mandatory and optional fields needed for a successful recurring payment request. The full request schemas are also available in our API reference.

Full recurring payment request body

{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default",
        "mcc": "1234",
        "paymentFacilitator": {
            "pfId": "12345",
            "isoId": "12345",
            "subMerchant": {
                "name": "John",
                "merchantId": "12345",
                "postalCode": "SW1 1AA",
                "street": "Regent Street",
                "city": "London",
                "countryCode": "GB"
            }
        }
    },
    "instruction": {
        "narrative": {
            "line1": "trading name",
            "line2": "order number"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "billingAddress": {
                "address1": "Worldpay",
                "address2": "1 Milton Road",
                "address3": "The Science Park",
                "postalCode": "CB4 0WE",
                "city": "Cambridge",
                "state": "Cambridgeshire",
                "countryCode": "GB"
            },
            "type": "card/plain",
            "cardHolderName": "John Appleseed",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 12,
                "year": 2020
            }
        }
    }
}

Recurring payment response

Successful payment

You receive:

  • an HTTP code 201
  • an outcome:authorized
  • an issuer response code
  • links to settle , partially settle or query your payment
  • an authorization link for the next payment in your recurring agreement

Refused payment

You receive:

  • an HTTP code 201
  • an outcome:refused
  • an issuer response code
  • a description which gives additional context on the refusal

Example response

{
    "outcome": "authorized",
    "issuer": {
        "authorizationCode": "0"
    },
    "scheme": {
        "reference": "1260019172"
    },
    "_links": {
        "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/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:CardOnFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/CardOnFile/eyJrIjoiazNhYjYzMiJ9"
        }
    }
}

You must always store and use the link returned in the payments:recurringAuthorize action link to authorize your next recurring payment.

Next steps


Refund a payment