**Last updated**: 11 November 2025 | [**Change log**](/products/card-payments/changelog/) # Take a card on file payment Use our CardOnFile resource to authorize a CardOnFile payment. details summary What are Card on File payments? **Card on File payments** are made by the cardholder using the payment instrument details that have already been stored, such as one-click or in-app purchases. They differ from recurring payments as they don't follow a schedule and are not initiated by the merchant. A Card on File payment is an example of a Cardholder Initiated Transaction (CIT). ## CardOnFile request `POST` your CardOnFile request to the `payments:cardonFileAuthorize` action link received in your successful [`oneTime` intelligent](/products/card-verifications/v5/verifications#onetime-intelligent-verification) or [`dynamicOneTime`](/products/card-verifications/v5/verifications#dynamic-cardonfile-verification) verification. ### CardOnFile example request POST `https://try.access.worldpay.com/payments/authorizations/cardonFile/{resource}` Note Click the tabs below to see all the mandatory fields for all supported `paymentInstrument` parameters. #### CardOnFile request body: Card { "transactionReference": "unique-transactionReference", "merchant": { "entity": "default" }, "instruction": { "narrative": { "line1": "trading name" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardHolderName": "John Appleseed", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 5, "year": 2035 } } } } Token { "transactionReference": "unique-transactionReference", "merchant": { "entity": "default" }, "instruction": { "narrative": { "line1": "trading name" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/token", "href": "https://try.access.worldpay.com/tokens/{}", "cvc": "898" } } } Checkout with CVC { "transactionReference": "unique-transactionReference", "merchant": { "entity": "default" }, "instruction": { "narrative": { "line1": "trading name" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/checkout", "tokenHref": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ", "cvcHref": "https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoiNjQxbUswTlVFYW05NWY2R0IvUEtqWXY0QjVyY2V5VHBBU0Q1TDNuSFQrMGtEc3RIZm1NQnFtNDhKcVB1TkoySDkycWhpRHVwSHBZY3F6NEZiUGwxVHc9PSJ9" } } } #### Parameter descriptions | Parameter | Required | Description | | --- | --- | --- | | `transactionReference` | ✅ | A unique reference generated by you that is used to identify a payment throughout its lifecycle. See [transaction reference format](/products/reference/formatting#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](/products/reference/formatting#narrative-format) for more details and the best practices. | | `narrative.line1` | ✅ | The first line of the narrative which appears on your customer's statement (24 character max. If character is not supported it is replaced with a space.).See [narrative `line1`](/products/reference/formatting.md#narrative-line1 format) for more details. | | `value.currency` | ✅ | The 3 digit currency code.See list of [supported currencies](/products/reference/useful-tables-v5-v6#currency-codes). | | `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](/products/reference/useful-tables-v5-v6#currency-codes). | | `instruction.paymentInstrument` | ✅ | An object that contains the payment type and details. To use "tokens" as a `paymentInstrument` you must first [create a token](/products/tokens/create-a-token). To use "checkout with CVC" as `paymentInstrument` you must first use our [checkout SDK](/products/checkout/web) and [create a token](/products/verified-tokens/create-verified-token). | ### Optional parameters details summary Optional parameters and descriptions | Parameter | Required | Description | | --- | --- | --- | | `narrative.line2` | ❌ | Additional details about the payment e.g. order number, telephone number. | | `paymentInstrument.billingAddress` | ❌ | An object containing the billing address information. **If included you must send** at least:`address1``city``countryCode``postalCode` This is used for Address Verification Service (AVS). Our API checks the submitted AVS to see if it matches the address registered with the issuing bank. If the address supplied does not match the registered address it means that the payment carries additional risk. | | `merchant.mcc` | ❌ | You can apply a merchant category code (`mcc`) to an individual request. You can only provide an `mcc` if we have enabled the dynamic mcc feature during [boarding](https://www.worldpay.com/en-GB/merchant-support#still-need-help). If enabled but not provided, `merchant.mcc` defaults to a configured value. For more information contact your [Relationship Manager](https://www.worldpay.com/en-GB/merchant-support#still-need-help). | | `paymentInstrument.cvc` | ❌ | CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank. | | `merchant.paymentFacilitator` | ❌ | An object containing Payment Facilitator information. **If required you must send**:`pfId``isoId``subMerchant.merchantId``subMerchant.postalcode``subMerchant.street``subMerchant.city``subMerchant.countryCode` This information is required for every card on file request **only if you are a Payment Facilitator**. You can find more formatting information [here](/products/reference/formatting#payment-facilitator-format). | The requests below contain all the mandatory and optional fields needed for a successful card on file request. Full card on file request body Card complete request { "transactionReference": "unique-transactionReference", "merchant": { "entity": "default", "mcc": "1234", "paymentFacilitator": { "pfId": "12345", "isoId": "12345", "subMerchant": { "name": "John", "merchantId": "12345", "postalCode": "SW1 1AA", "street": "Regent Street", "city": "London", "countryCode": "GB" } } }, "instruction": { "narrative": { "line1": "trading name", "line2": "order number" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "cvc": "123", "billingAddress": { "address1": "Worldpay", "address2": "1 Milton Road", "address3": "The Science Park", "postalCode": "CB4 0WE", "city": "Cambridge", "state": "Cambridgeshire", "countryCode": "GB" }, "type": "card/plain", "cardHolderName": "John Appleseed", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 5, "year": 2035 } }, "intent": "instalment" } } Token complete request { "transactionReference": "unique-transactionReference", "merchant": { "entity": "default", "mcc": "1000", "paymentFacilitator": { "pfId": "12345", "isoId": "12345", "subMerchant": { "name": "John", "merchantId": "12345", "postalCode": "SW1 1AA", "street": "Regent Street", "city": "London", "countryCode": "GB" } } }, "instruction": { "narrative": { "line1": "trading name", "line2": "order number" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/token", "href": "https://try.access.worldpay.com/tokens/{}", "cvc": "898" }, "intent": "instalment" } } Checkout with CVC { "transactionReference": "unique-transactionReference", "mcc": "1000", "merchant": { "entity": "default", "paymentFacilitator": { "pfId": "1111", "isoId": "222", "subMerchant": { "city": "SubMCity", "name": "SMName", "state": "US", "postalCode": "SM8989", "merchantId": "62738", "countryCode": "GB", "street": "SMLondon", "taxId": "1234567" } } }, "instruction": { "narrative": { "line1": "trading name", "line2": "order number" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/checkout", "tokenHref": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ", "cvcHref": "https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoiNjQxbUswTlVFYW05NWY2R0IvUEtqWXY0QjVyY2V5VHBBU0Q1TDNuSFQrMGtEc3RIZm1NQnFtNDhKcVB1TkoySDkycWhpRHVwSHBZY3F6NEZiUGwxVHc9PSJ9" }, "intent": "instalment" } } ## Card on file response ### Successful payment You receive: * an HTTP code `201` * an `"outcome": "authorized"` * an issuer response code * links to [settle](/products/card-payments/v5/settle-or-cancel-an-authorization#settle-an-authorization) , [partially settle](/products/card-payments/v5/settle-or-cancel-an-authorization#partially-settle-an-authorization) or [query](/products/card-payments/v5/query-a-payment) your payment * an authorization link for the next payment in your recurring agreement ### Refused payment You receive: * an HTTP code `201` * an `"outcome": "refused"` * an issuer response code * a `description` which gives additional context on the refusal #### Example response Card/Token { "outcome": "authorized", "issuer": { "authorizationCode": "0" }, "scheme": { "reference": "1260019172" }, "_links": { "payments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9" }, "payments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9" }, "payments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/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 }], "payments:CardOnFileAuthorize": { "href": "https://try.access.worldpay.com/payments/authorizations/CardOnFile/eyJrIjoiazNhYjYzMiJ9" } } } Card/Token complete response { "outcome": "authorized", "riskFactors": [{ "risk": "not_matched", "type": "cvc" }, { "risk": "not_checked", "detail": "postcode", "type": "avs" }, { "risk": "not_checked", "detail": "address", "type": "avs" } ], "issuer": { "authorizationCode": "0" }, "scheme ": { "reference": "1260019172" }, "_links": { "payments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9" }, "payments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9" }, "payments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/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 }], "payments:CardOnFileAuthorize": { "href": "https://try.access.worldpay.com/payments/authorizations/CardOnFile/eyJrIjoiazNhYjYzMiJ9" } } } Checkout with CVC { "transactionReference": "unique-transactionReference", "mcc": "1000", "merchant": { "entity": "default", "paymentFacilitator": { "pfId": "1111", "isoId": "222", "subMerchant": { "city": "SubMCity", "name": "SMName", "state": "US", "postalCode": "SM8989", "merchantId": "62738", "countryCode": "GB", "street": "SMLondon", "taxId": "1234567" } } }, "instruction": { "narrative": { "line1": "trading name", "line2": "order number" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/checkout", "tokenHref": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ", "cvcHref": "https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoiNjQxbUswTlVFYW05NWY2R0IvUEtqWXY0QjVyY2V5VHBBU0Q1TDNuSFQrMGtEc3RIZm1NQnFtNDhKcVB1TkoySDkycWhpRHVwSHBZY3F6NEZiUGwxVHc9PSJ9" }, "intent": "instalment" } } You must always store and use the link returned in the `payments:CardOnFileAuthorize` action link to authorize your next CardOnFile payment. br **Next steps** [Refund a payment](/products/card-payments/v5/refund-a-payment)