Last Updated: 04 December 2024 | Change Log

Take a card on file sale

Use our card on file sale resource when your customer is initiating a payment using stored card details, and you want to instantly trigger the settlement process. Read more about card on file mandates here.

What are card on file payments?

• The customer is actively particpating in making a payment at the point of authorization using card details you have previously stored/ intend to store
• Does not follow a schedule
• Requires explicit permission from the customer to store the card on their account for use in a “one-click” model
• Sometimes referred to as Customer Initiated Transactions (CIT)

migrateCardOnFileSale request

POST your card on file sale request to our payments:migrateCardOnFileSale action link resource received in your query the payments root resource request.

POST https://try.access.worldpay.com/payments/sales/migrateCardOnFile

The requests below contain all the mandatory fields needed for a successful authorization request.

migrateCardOnFileSale request body:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    }
}

Sale request parameters

3DS

The below table describes the mandatory 3DS authorization request parameters:

|Parameter|Required|Description| |---|---| |customer|✅|An object containing the result of your customer's verification. For more details see 3DS verification.| |authentication.type|✅|3DS| |authentication.version|✅|The version of 3DS used to process the transaction.
For 3DS1 - 1.0.2
For 3DS2 - 2.1.0 or 2.2.0

• 02 or 05 - Fully Authenticated Transaction
• 01 or 06 - Attempted Authentication Transaction
• 00 or 07 - Non 3-D Secure Transaction
• Mastercard - 02, 01, 00
• Visa - 05, 06, 07
• Amex - 05, 06, 07
• JCB - 05, 06, 07
• Diners - 05, 06, 07

• Visa - Cardholder Authentication Verification Value (CAVV)
• Mastercard - Universal Cardholder Authentication Field (UCAF)

• noPrefrence
• noChallengeRequested
• challengeRequested
• challengeMandated

• challenge - Your customer was redirected to their bank to complete authentication
• frictionless - Your customer completed authentication without needing to be redirected to their bank

• - 01 - Cardholder selected cancel
• - 02 - Reserved for future use
• - 03 - Authentication timed out
• - 04 & 05 - Authentication timed out at ACS provider
• - 06 - Transaction error
• - 07 - Unknown
• - 08 - Transaction timed out at SDK

Optional Parameters

Example request (all parameters)

The requests below contain all the mandatory and optional fields for a migrateCardOnFileSale request.

Full migrateCardOnFileSale request body:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default",
        "mcc": "6432",
        "paymentFacilitator": {
            "pfId": "12345",
            "isoId": "12345",
            "subMerchant": {
                "name": "John",
                "merchantId": "12345",
                "postalCode": "SW1 1AA",
                "street": "Regent Street",
                "city": "London",
                "state": "WSM",
                "countryCode": "826",
                "taxId": "ABC-123456789",
                "email": "test@email.com",
                "telephone": "+447987 654321"
            }
        }
    },
    "channel": "moto",
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd",
            "line2": "Memory265-13/08/1876"
        },
        "scheme": {
            "reference": "28379213"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "billingAddress": {
                "address1": "221B Baker Street",
                "address2": "Marylebone",
                "address3": "Westminster",
                "postalCode": "NW1 6XE",
                "city": "London",
                "state": "Greater London",
                "countryCode": "GB"
            },
            "type": "card/plain",
            "cardHolderName": "Sherlock Holmes",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 12,
                "year": 2020
            }
        },
        "intent": "instalment"
    },
    "customer": {
        "riskProfile": "https://try.access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsC"
    }
}

migrateCardOnFileSale response

Successful response

You receive:

• an HTTP code 201
• an "outcome": "Sent for Settlement"
• risk factors (only returned if issuer identifies conflict)
• an exemption result and reason (only if you supplied a risk profile to request an SCA exemption)
• an issuer authorization code
• a scheme reference (supported by major card schemes, but may not be returned for all schemes/regions)
• a paymentInstrument
• links to refund, partially refund, reverse your request or query your payment.
• an authorization link for the next payment in your repeat payment agreement

paymentInstrument

The "paymentInstrument" object is returned if we are able to provide information related to the underlying card used in the authorization request.

Refused response

You receive:

• an HTTP code 201
• an "outcome": "refused"
• a refusal code
• a description which gives additional context on the refusal
• a refusal advice code (only if returned by the card scheme and acquirer)
• risk factors (only returned if issuer identifies conflict)
• an exemption result and reason (only if you supplied a risk profile to request an SCA exemption)

Example response:

{
    "outcome": "Sent for Settlement",
    "riskFactors": [{
            "type": "cvc",
            "risk": "not_matched"
        },
        {
            "type": "avs",
            "detail": "address",
            "risk": "not_checked"
        },
        {
            "type": "avs",
            "detail": "postcode",
            "risk": "not_checked"
        }
    ],
    "issuer": {
        "authorizationCode": "12345A"
    },
    "scheme": {
        "reference": "1260019172"
    },
    "exemption": {
        "result": "honored",
        "reason": "issuerHonored"
    },
    "paymentInstrument": {
        "type": "card/plain+masked",
        "card": {
            "brand": "visa",
            "number": {
                "bin": "444433",
                "last4Digits": "1111"
            },
            "expiryDate": {
                "month": 12,
                "year": 2025
            },
            "fundingType": "credit",
            "category": "consumer",
            "issuer": {
                "name": "Some Issuer PLC"
            },
            "paymentAccountReference": "ABC123DEF456GHI789JKL123M"
        }
    },
    "_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
            }]
    }
}

riskFactors

To reduce the probability of processing a fraudulent payment, supply your customer's billing address and cvc in your authorization request.

We check this with your customer's issuing bank and include any conflicts in our response.

The riskFactors array is returned only if there is a risk associated with the authorization request. The riskFactors array returns an object for avs, cvc or riskProfile only if this information was included in the authorization request and if any risk was identified.

The table below describes the response parameters:

exemption

An exemption result and reason if a risk profile was included in your authorization request.

The table below describes the response parameters:

Soft decline

The issuer responds with a soft decline (refusal code 65), if no exemption has been applied to the payment. The next logical step for this is to proceed with 3DS authentication.