Last Updated: 04 December 2024 | Change Log

Take a sale

Use our recurring sale resource to authorize a payment and initiate a settlement request with one call.

Recurring sale

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:

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

Descriptions of your recurring sale request parameters

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 fields in a sale request

Optional fields and descriptions

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

Full recurring sale 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": {
            "cvc": "123",
            "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": 5,
                "year": 2035
            }
        }
    }
}

Additional parameter descriptions

The descriptions of the additional parameters in your complete sale request.

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: `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.
`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.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` This information is required for every sale request only if you are a Payment Facilitator. You can find more formatting information here.

Recurring sale response

Successful payment

You receive:

an HTTP code 201
an "outcome": "Sent for Settlement"
an issuer response code
links to refund, partially refund or query your payment
an authorization link for the next payment in your repeat payment 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": "Sent for Settlement",
    "issuer": {
        "authorizationCode": "0"
    },
    "scheme": {
        "reference": "1260019172"
    },
    "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 request.

Next steps

Refund a payment