Menu

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 mandateshere.

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 card on file Sometimes referred to as Merchant Initiated Transaction (MIT)

On this page:

Recurring authorization with verification

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

Recurring payment request

POST your payment request to thepayments:recurringAuthorizeaction link received in your successfulcardOnFile intelligentordynamicCardOnFileverification.

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

Copied!
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "an-entity"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardHolderName": "John Appleseed",
            "cardExpiryDate": {
                "month": 12,
                "year": 2020
            }
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "intent": "subscription"
    }
}
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}"
        },
        "intent": "unscheduled"
    }
}

Parameter descriptions

ParameterRequiredDescription
transactionReferenceA unique reference generated by you that is used to identify a payment throughout its lifecycle. Seetransaction 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 yourImplementation Managerfor more details.
instruction.intentA parameter detailing the reason for this particular recurring agreement. Valid intents:
  • subscription
  • unscheduled
  • instalment
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.
Seenarrative 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.).
Seenarrative line1 formatfor more details.
instruction.valueAn object that contains information about the value of the payment.
value.currencyThe 3 digit ISO currency code.
See list ofsupported 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 ourcurrency table.
instruction.paymentInstrumentAn object that contains the payment type and details.
To use tokens as a paymentInstrument you must first create a token, see ourTokens APIon how to create a token.

Optional parameters

Response

Successful payment

  • an HTTP code 201
  • an "outcome": "authorized"
  • risk factors (only returned if issuer identifies conflict)
  • an issuer authorization code
  • a scheme reference
  • links tocancel,settle,partially settleortrack payment events
  • an authorization link for the next payment in your repeat payment agreement

Refused payment

You receive:

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

Example response

Copied!
{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "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:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        }
    }
}
{
    "outcome": "refused",
    "description": "CARD EXPIRED",
    "code": "33",
    "riskFactors": [{
            "risk": "not_supplied",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        }
    ]
}

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


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 ourpayments:migrateRecurringAuthorizeaction link received in yourquery the payments root resourcerequest.

migrateRecurring authorization example request

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

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

migrateRecurring authorization request body:

Copied!
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "an-entity"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardHolderName": "John Appleseed",
            "cardExpiryDate": {
                "month": 12,
                "year": 2020
            }
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "intent": "subscription"
    }
}
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}"
        },
        "intent": "unscheduled"
    }
}
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/networkToken+applepay",
            "dpan": "4444333322221111",
            "cardHolderName": "John Appleseed",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    }
}

Description of migrateCardOnFileAuthorize parameter fields

ParameterDescription
instruction.paymentInstrumentAn object that contains the payment type and details.
  • Use card/networkToken+applepay for a decrypted wallet flow. This paymentInstrument includes dpan, which is a surrogate value that replaces the card number. It is generated by the card network/ wallet provider.

You can find the full parameter descriptionhere.

migrateRecurring authorization response

Successful payment

  • an HTTP code 201
  • an "outcome": "authorized"
  • risk factors (only returned if issuer identifies conflict)
  • an issuer authorization code
  • scheme reference
  • links tocancel,settle,partially settleortrackpayment events
  • an authorization link for the next payment in your repeat payment agreement

Refused payment

You receive:

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

Example response

Copied!
{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "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:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        }
    }
}
{
    "outcome": "refused",
    "description": "CARD EXPIRED",
    "code": "33",
    "riskFactors": [{
            "risk": "not_supplied",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        }
    ]
}

You can use thepayments:settleaction link tosettle the paymentstraight 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 thepayments:recurringAuthorizeaction link to authorize your next recurring payments.


Next steps


Settle or cancel a payment