Last Updated: 09 April 2024 | Change Log

Repeat Wallet Payments

Use our Customer Initiated Transactions endpoint to authorize a payment with a digital wallet, and store the payment information for future payments (i.e. subscriptions, installments, and unscheduled).

Note

You must integrate with Google Pay or Apple Pay before you can submit repeat wallet payments to our Card 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.

Authorization request

POST your initial payment request to our https://try.access.worldpay.com/cardPayments/customerInitiatedTransactions endpoint, ensuring you include the customerAgreement object to store payment details.

Example request:

POST https://try.access.worldpay.com/cardPayments/customerInitiatedTransactions

Authorization request body:

Apple Pay
Google Pay

{
    "transactionReference": "Memory265-13/08/1876",
    "channel": "ecom",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "requestAutoSettlement": {
            "enabled": false
        },
        "customerAgreement": {
            "type": "subscription",
            "storedCardUsage": "first"
        },
        "narrative": {
            "line1": "Mind Palace"
        },
        "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=\" 
                }
            }"
        }
    }
}

See Customer Initiated Transactions for full descriptions of all request parameters.

Response

Successful response

Along with our standard response data, you receive a token href, for use in all subsequent payments in your repeat payment agreement. Refer to our repeat payments documentation for how to send subsequent payments.

Example response

Successful
Refused

{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "scheme": {
        "reference": "schemeReference"
    },
    "paymentInstrument": {
        "type": "card/network+masked",
        "card": {
            "number": {
                "bin": "444433",
                "last4Digits": "1111",
                "dpan": "4444333322221111"
            },
            "countryCode": "GB",
            "expiryDate": {
                "month": 6,
                "year": 2021
            },
            "brand": "visa",
            "fundingType": "debit",
            "issuer": {
                "name": "VALID_ISSUER"
            },
            "paymentAccountReference": "somePAR"
        }
    },
    "_links": {
        "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA=="
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA=="
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA=="
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA=="
        },
        "payments:cardOnFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.R6PzeBs1kC+VT5dtn2WKHquYi:0CPtdsTmoC0CiPjw6CkE+Ujvons6ZVs+R2JwUJmXAx1+34Kz67cP9hSVZNkQ=="
        },
        "payments:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.R6PzeBs1kC+VT5dtn2WKHquYi:0CPtdsTmoC0CiPjw6CkE+Ujvons6ZVs+R2JwUJmXAx1+34Kz67cP9hSVZNkQ=="
        },
        "tokens:token": {
            "href": "https://access.worldpay.com/tokens/linkData"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }]
    }
}

You can use the payments:settle action link to settle the payment straight away. Alternatively you can cache the response and use the link to settle the payment later.

Next Steps

Take a subsequent repeat payment with the token you have received in your response.