Last Updated: 09 April 2024 | Change Log

Take a recurring authorization

Use our recurring authorize resources when you are initiating a payment using your customer's stored card details. Take a payment with or without verifying your customer's account first. 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)

Recurring authorization with verification

Verify your customer's account before submitting your first recurring payment for authorization.

Recurring payment request

POST your payment request to the payments:recurringAuthorize action link received in your successful cardOnFile intelligent or dynamicCardOnFile 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

Card
Apple Pay/Google Pay

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

Parameter	Required	Description
`transactionReference`	✅	A 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.
`merchant`	✅	An object that contains information about the merchant.
`merchant.entity`	✅	Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for Authentication and Queries. Contact your Implementation Manager for more details.
`merchant.mcc`	❌	You 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.paymentFacilitator`	❌	An 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 recurring request only if you are a Payment Facilitator. You can find more formatting information here.
`instruction.intent`	✅	A parameter detailing the reason for this particular recurring agreement. Valid intents: `subscription` `unscheduled` `instalment`
`instruction`	✅	An object that contains all the information related to the payment.
`instruction.narrative`	✅	The text that appears on your customer's statement. Used to identify the merchant. See narrative format for more details and the best practices.
`narrative.line1`	✅	The 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.line2`	❌	Additional details about the payment e.g. order number, telephone number.
`instruction.value`	✅	An object that contains information about the value of the payment.
`value.currency`	✅	The 3 digit currency code. See list of supported currencies.
`value.amount`	✅	The 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.paymentInstrument`	✅	An 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.
`paymentInstrument.cardExpiryDate`	✅	An object that contains your customer's card expiry date. Mandatory for all `"type": "card/plain"` requests.
`paymentInstrument.cardNumber`	✅	An object that contains your customer's card number. Mandatory for `"type": "card/plain"` requests.
`paymentInstrument.cvc`	❌	CVC 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.cardHolderName`	❌	An 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.billingAddress`	❌	An 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.debtRepayment`	❌	DRI 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 authorization request (all parameters)

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

Full recurring payment request body

Card
Apple Pay/Google Pay

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

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 payment

an HTTP code 201
an "outcome": "authorized"
risk factors (only returned if issuer identifies conflict)
an issuer authorization code
a scheme reference (supported by major card schemes, but may not be returned for all schemes/regions)
a paymentInstrument
links to cancel, settle, partially settle or track 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.

Parameter	Description
`paymentInstrument.type`	The type of paymentInstrument. Eg: `card/plain+masked` `card/network+masked` `card/network`
`paymentInstrument.card.brand`	The card brand. Sometimes referred to as the network or scheme. Eg: `"visa"` `"mastercard"` `"amex"`
`paymentInstrument.card.number.bin`	The card bin. Eg: `444433` Note this may contain the ``* character.
`paymentInstrument.card.number.last4Digits`	The 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.month`	The card expiry month. Eg: `11`
`paymentInstrument.card.expiryDate.year`	The card expiry year. Eg: `2025`
`paymentInstrument.card.fundingType`	How the card is funded. Eg: `credit` `debit` `prepaid` `deferredDebit` `chargeCard`
`paymentInstrument.card.category`	Whether the card is classed as a consumer card or a card for commercial use. Eg: `consumer` `commercial`
`paymentInstrument.card.countryCode`	The 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.name`	The name of the card issuer. Eg: `Some Issuer PLC.`
`paymentInstrument.card.paymentAccountReference`	The 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 payment

You receive:

an HTTP code 201
an "outcome": "refused"
a refusal code
a description which gives additional context on the refusal
risk factors (only returned if issuer identifies conflict)

Example response

Card/Token response
Refusal

{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "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": "ABC123DEF456GHI789JKL123M"
        }
    },
    "_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:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        }
    }
}

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

Note

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

Next steps

Refund a payment

Recurring authorization without verification

Use our migrate recurring authorize resource when you are initiating a payment using your customer's stored card details, without verifying their account first.

Recurring payment request

POST your recurring authorization request to our payments:migrateRecurringAuthorize action link received in your query the payments root resource request.

`migrateRecurring` authorization example request

POST https://try.access.worldpay.com/payments/authorizations/migrateRecurring

Note

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

migrateRecurring authorization request body:

Card
Token
Apple Pay decrypted

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

Parameter	Required	Description
`instruction.paymentInstrument`	✅	An object that contains the payment type and details. Use `card/networkToken+applepay` for a decrypted wallet flow. This `paymentInstrument` includes the `dpan` which replaces the original card number. It is generated by the card network/ wallet provider.
`scheme.reference`	❌	Unique reference provided by the schemes that identifies a repeat payment agreement between you and the customer. A new reference is generated for every subsequent payment in the agreement. You can only submit this for `card/plain` requests. Most but not all issuers return this.

You can find the full parameter description here.

Optional Parameters

Example Migrate Recurring Authorization request (all parameters)

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

Complete `migrateRecurring` authorization request schema

Full migrateRecurring authorization request body:

Card
Token
Apple Pay decrypted

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

`migrateRecurring` authorization 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 payment

an HTTP code 201
an "outcome": "authorized"
risk factors (only returned if issuer identifies conflict)
an issuer authorization code
a scheme reference (supported by major card schemes, but may not be returned for all schemes/regions)
a paymentInstrument (for Apple Pay decrypted only)
links to cancel, settle, partially settle 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.

Parameter	Description
`paymentInstrument.type`	The type of paymentInstrument. Eg: `card/plain+masked` `card/network+masked` `card/network`
`paymentInstrument.card.brand`	The card brand. Sometimes referred to as the network or scheme. Eg: `"visa"` `"mastercard"` `"amex"`
`paymentInstrument.card.number.bin`	The card bin. Eg: `444433` Note this may contain the ``* character.
`paymentInstrument.card.number.last4Digits`	The 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.month`	The card expiry month. Eg: `11`
`paymentInstrument.card.expiryDate.year`	The card expiry year. Eg: `2025`
`paymentInstrument.card.fundingType`	How the card is funded. Eg: `credit` `debit` `prepaid` `deferredDebit` `chargeCard`
`paymentInstrument.card.category`	Whether the card is classed as a consumer card or a card for commercial use. Eg: `consumer` `commercial`
`paymentInstrument.card.countryCode`	The 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.name`	The name of the card issuer. Eg: `Some Issuer PLC.`
`paymentInstrument.card.paymentAccountReference`	The 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 payment

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 response

Card/Token
Token
Refusal

{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "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": "ABC123DEF456GHI789JKL123M"
        }
    },
    "_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:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        }
    }
}

You can use the payments:settle action link to settle the payment straight away. Alternatively you can cache the response and use the link to settle the payment later.

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

Note

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

Next steps

Settle or cancel a payment

Take a recurring authorization

What are recurring payments?

On this page:

Recurring authorization with verification

Recurring payment request

Example request

Request body

Parameter descriptions

Optional parameters

Response

Successful payment

`paymentInstrument`

Refused payment

Example response

Recurring authorization without verification

Recurring payment request

`migrateRecurring` authorization example request

Parameter descriptions

Optional Parameters

Complete `migrateRecurring` authorization request schema

`migrateRecurring` authorization response

Successful payment

`paymentInstrument`

Refused payment

Example response

Was this helpful?

Take a recurring authorization

What are recurring payments?

On this page:

Recurring authorization with verification

Recurring payment request

Example request

Request body

Parameter descriptions

Optional parameters

Response

Successful payment

paymentInstrument

Refused payment

Example response

Recurring authorization without verification

Recurring payment request

migrateRecurring authorization example request

Parameter descriptions

Optional Parameters

Complete migrateRecurring authorization request schema

migrateRecurring authorization response

Successful payment

paymentInstrument

Refused payment

Example response

Was this helpful?

`paymentInstrument`

`migrateRecurring` authorization example request

Complete `migrateRecurring` authorization request schema

`migrateRecurring` authorization response

`paymentInstrument`