Last Updated: 23 October 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}
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:
|
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:
|
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