Last Updated: 08 October 2024 | Change Log
Store a card only
Create a customer agreement to store card details for future customer initiated transactions (CIT). No initial payment is being made. Either using API only or our Checkout SDK for low PCI hosted card.
The request must contain:
customerAgreement.type
=cardOnFile
- used to indicate the customer has agreed to storing their card for the purpose of future merchant initiated transactions (MIT)customerAgreement.storedCardUsage
=first
instruction.value.amount
- Set to0
- A card verification to check the card details is performed instead of a full payment request.
Optionally:
tokenCreation.type
=worldpay
- include if you're storing the card as a Worldpay Token
Collect the card details and send an API request with these details to the Payments
resource.
Request
{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "default" }, "instruction": { "method": "card", "paymentInstrument": { "type": "plain", "cardNumber": "4000000000001091", "expiryDate": { "month": 5, "year": 2035 } }, "tokenCreation": { "type": "worldpay" }, "customerAgreement": { "type": "cardOnFile", "storedCardUsage":"first" }, "narrative": { "line1": "trading name" }, "value": { "currency": "GBP", "amount": 0 } } }
Enable additional features
Fraud assessment | Prevent fraudulent transactions. | |
3DS authentication | Shift Liability to the issuer / for EEA countries this is required as part of SCA compliance. | |
SCA Exemptions | Meet SCA compliance without the added friction of 3DS. | Not Applicable |
Auto Settlement | Request 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 totrue
, the outcome will besentForSettlement
. If set tofalse
it will beauthorized
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