Access Worldpay
/
Card payment and store a card

Last Updated: 22 July 2024 | Change Log

Card payment & store a card

Provide the card details in an API request or use our Checkout SDK for low PCI hosted card fields. Save those card details for future custom initiated transactions (CIT).

The request must contain:

  • customerAgreement.type = cardOnFile - used to indicate the customer has agreed to storing their card for the purpose of future customer initiated transactions
  • customerAgreement.storedCardUsage = first

Optionally:

  • tokenCreation.type = worldpay - include if you're storing the card as a Worldpay Token

Important: You must have agreement from your customer to store their card details.

Collect the card details and send an API request with these details to the payments resource.

Request

application/json

Card payment using a plain card number that will also create a Worldpay Token for use with future customer initiated transactions (CIT)

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "method": "card",
    "paymentInstrument": {
      "type": "plain",
      "cardHolderName": "Sherlock Holmes",
      "cardNumber": "4000000000001091",
      "expiryDate": {
        "month": 5,
        "year": 2035
      }
    },
    "tokenCreation": {
      "type": "worldpay"
    },
    "customerAgreement": {
      "type": "cardOnFile",
      "storedCardUsage": "first"
    },
    "narrative": {
      "line1": "trading name"
    },
    "value": {
      "currency": "GBP",
      "amount": 42
    }
  }
}

Enable additional features

Fraud assessmentPrevent fraudulent transactions.
3DS authenticationShift Liability to the issuer / for EEA countries this is required as part of SCA compliance.
SCA ExemptionsMeet SCA compliance without the added friction of 3DS.
Not Applicable
Auto SettlementRequest that payment authorizations are automatically sent for settlement (sometimes referred to as "capture").
Financial Services
(MCC 6012 / 6051)		If you provide financial services, debt repayment, or consumer bill payments, you should supply additional details in the authorization request for compliance reasons.

Response

Flow differences

API responses differ based on the features you have enabled:

  • If 3DS is enabled you receive a response to perform device data collection and additionally, if prompted by the card issuer, a challenge response.

  • If FraudSight is enabled, you can receive a fraudHighRisk response, stopping the transaction.

  • If settlement.auto is set to true, the outcome will be sentForSettlement. If set to false it will be authorized with an addtional settlement action required.

See sequence diagrams to get a clear overview.

Payment response

The payment response contains the following details:

  • riskFactors (avs/cvc) - if billing address & cvc are provided, these details are checked against the customer's issuing bank
  • refusal code and description which gives additional context on the refusal
  • 3DS authentication details - details on the 3DS authentication outcome (e.g. challenged)
  • fraud assessment details - details on the fraud assessment outcome (e.g. lowRisk, review)
  • token creation - details of the card tokenized and the token href itself
  • paymentInstrument - details of the paymentInstrument used

View the full API Response schema