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}
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
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. |
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 formatfor 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. |
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. |
Optional parameters
Optional parameters and descriptions
Parameter | Required | Description |
---|---|---|
narrative.line2 | ❌ | Additional details about the payment e.g. order number, telephone number. |
paymentInstrument.billingAddress | ❌ | An object containing the billing address information. If included you must send at least:
|
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. |
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. |
merchant.paymentFacilitator | ❌ | An object containing Payment Facilitator information. If required you must send:
|
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