Last Updated: 23 October 2024 | Change Log

Repeat Wallet Payments

Use our card on file resource to authorize a payment with a digital wallet.

Note

You must integrate with Google Pay or Apple Pay before you can submit repeat wallet payments to our Payments API.

What are card on file payments?

The customer is actively participating 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)

Read more about card on file mandates here.

Card on file authorization request

POST your initial card on file authorizations to our payments:cardOnFileAuthorize action link resource received in your query the payments root resource request.

Card on file authorization example request:

POST https://try.access.worldpay.com/payments/authorizations/cardOnFile

cardOnFile authorization request body

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/wallet+applepay",
            "walletToken": "{\"version\": \"EC_v1\",\"data\": \"kdHd..GQ==\",\"signature\": \"MIAGCSqGSIb3DQEH...AAA\",\"header\": {\"transactionId\": \"d3b28af..f8\",\"ephemeralPublicKey\": \"MFkwE..Q==\",\"publicKeyHash\": \"dxCK..6o=\"}}"
        }
    }
}

Descriptions of your authorization 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 format for more details and best practices.
`narrative.line1`	✅	The first line of the narrative which appears on your customer's statement (24 characters max. If character is not supported it is replaced with a space.). See narrative `line1` format for more details.
`instruction.value`	✅	An object that contains information about the value of the payment.
`value.currency`	✅	The three 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. You must integrate with Apple Pay first to use the `card/wallet+applepay` `paymentInstrument`.

Optional parameters

Optional parameters and descriptions

Parameter	Required	Description
`instruction.intent`	❌	A parameter detailing the reason for this particular repeat agreement. Possible value: `instalment`
`narrative.line2`	❌	Additional details about the payment e.g. order number, telephone number.

The requests below contain all the mandatory and optional fields needed for a successful card on file authorization request.

Full authorization request body:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "intent": "instalment",
        "narrative": {
            "line1": "Mind Palace Ltd",
            "line2": "Memory265-13/08/1876"
        },
        "value": {
            "currency": "GBP",
            "amount": 1000
        },
        "paymentInstrument": {
            "type": "card/wallet+applepay",
            "walletToken": "{\"version\": \"EC_v1\",\"data\": \"kdHd..GQ==\",\"signature\": \"MIAGCSqGSIb3DQEH...AAA\",\"header\": {\"transactionId\": \"d3b28af..f8\",\"ephemeralPublicKey\": \"MFkwE..Q==\",\"publicKeyHash\": \"dxCK..6o=\"}}",
            "billingAddress": {
                "address1": "221B Baker Street",
                "address2": "Marylebone",
                "address3": "Westminster",
                "postalCode": "NW1 6XE",
                "city": "London",
                "state": "Greater London",
                "countryCode": "GB"
            }
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/wallet+applepay",
            "walletToken": "{
                \"version\": \"EC_v1\",
                \"data\": \"kdHd..GQ==\",
                \"signature\": \"MIAGCSqGSIb3DQEH...AAA\",
                \"header\": {
                    \"transactionId\": \"d3b28af..f8\",
                    \"ephemeralPublicKey\": \"MFkwE..Q==\",
                    \"publicKeyHash\": \"dxCK..6o=\" 
                }
            }"
        }
    }
}

Card on file response

Best Practice

Access Worldpay returns a WP-correlationId in the headers of service responses. We highly recommend you log this. The WP-correlationId is used by us to examine individual service requests.

Successful response

You receive:

an HTTP code 201
an "outcome": "authorized"
risk factors (only returned if issuer identifies conflict)
a scheme reference
a paymentInstrument detailing brand information about the card that was used
links to cancel, settle, partially settle or track payment events
an authorization link for the next card on file payment in your repeat payment agreement
an authorization link for the next recurring payment in your repeat payment agreement
a token link, you must use for all subsequent payments in your repeat payment agreement

Refused response