Take a sale

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

Recurring sales

Use our recurring sale resource to authorize and settle merchant initiated transactions where you have stored the card details.

POST your recurring sale request to the payments:recurringSale action link received in your successfulcardOnFile intelligentordynamicCardOnFileverification.

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:

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

Descriptions of your recurring sale request parameters

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.
instructionAn object that contains all the information related to the payment.
instruction.intentA parameter detailing the reason for this particular recurring agreement. Valid intents:
  • subscription
  • unscheduled
  • instalment
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 fields in a sale request

Recurring sale response

Successful response

  • an HTTP code 201
  • an "outcome": "Sent for Settlement"
  • risk factors (only returned if issuer identifies conflict)
  • an issuer authorization code
  • scheme reference
  • links torefund,partially refund,reverseortrack payment events
  • an authorization link for the next payment in your repeat payment agreement

Refused response

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 responses

Copied!
{
    "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"
        }
    }
}
{
    "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 the payments:recurringSale action link for your next recurring sale requests.


Next steps


Refund a payment