**Last updated**: 14 November 2025 | [**Change log**](/products/payments/changelog/)

# Store a card during the payment

Enterprise

SMB (Worldpay eCommerce)

Make a card payment and store those card details for future Customer Initiated Transactions (CIT).

The request must contain:


```JSON
"customerAgreement": {
    "type": "cardOnFile",  // used to indicate the customer has agreed to storing their card (future CIT)
    "storedCardUsage": "first" // the first in the series
},
```

To avoid the PCI implications of storing card numbers in most cases you will want to create a Worldpay token for future use.


```JSON
"tokenCreation": {
    "type": "worldpay" // include if you're storing the card as a Worldpay Token
},
```

If [PSD2/SCA or other regional mandates apply](/products/3ds-sca-exemptions#when-sca-applies) you should follow the steps for [enabling 3DS](/products/payments/enable-features/3ds-authentication)

 Whilst you can [use a Network Token](/products/payments/use-a-stored-card), it is not yet possible to create a network token as part of the payments API flow. You can create a network token using a separate request to the  [Access Tokens API](/products/tokens/create-a-network-token) as well as [provision the network token cryptogram](/products/tokens/querying-network-tokens-and-provisioning-cryptograms#provisioning-network-token-cryptograms) each time its used. 

 Important: You must have agreement from your customer to store their card details.

## 1. Integration type

Apply card details directly in our Payments API, or use our PCI-compliant Checkout SDK to create a `session`

API only
Collect the card details and send an API request with these details to the [`payments`](/products/payments/openapi/) resource.

## 2. Basic request

Checkout SDK
Use our Checkout SDK for a lower PCI burden, receive a short lived `session` representing the card and apply in the [`Payments`](/products/payments/openapi/) resource.

## 2. Add the SDK & create a session

Web SDK
Add JavaScript to your checkout


Android SDK
Set up your Android application

iOS SDK
Set up your iOS application

React Native SDK
Set up your React Native application

### Add the session to the request

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "method": "card",
        "paymentInstrument": {
            "type": "checkout",
            "cardHolderName": "Sherlock Holmes",
            "sessionHref": "https://try.access.worldpay-bsh.securedataplatform.com/sessions/eyJrIjoxLCJkIjoialRBL0FFelB....."
        },
        "tokenCreation": {
            "type": "worldpay"
        },
        "customerAgreement": {
            "type": "cardOnFile",
            "storedCardUsage":"first"
        },
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 42
        }
    }
}
View the full API Request schema
## 3. Add additional features

In most cases you will need to add some additional features such as 3DS, auto settlement or a risk assessment

3DS Authentication
Perform 3DS authentication for liability shift and/or SCA compliance. An issuer based risk assessment with identity check.
Enterprise
Worldpay eCommerce

SCA Exemptions
Ask for an SCA Exemption to be applied automatically.
Enterprise

Risk Assessment
We assess the payment for fraud before proceeding with authorization.
Enterprise
Worldpay eCommerce

Auto Settlement
Automatically settle a payment following the authorization.
Enterprise
Worldpay eCommerce

Account Funding Transactions (AFT)
Transfer funds from a card account to another destination, rather than for the provision of goods or services.
Enterprise

Financial Service (MCC 6012/6051)
For domestic Financial Services providers (MCC 6012) based in the Visa Europe Region, you must supply this additional data.
Enterprise

Latin America Installments
Fulfill a one-time installment charge, to allow the customer's acquirer bank collecting the payments over time.
Enterprise

Payment Facilitator
Facilitate transactions on behalf of your sub-merchants.
Enterprise

MOTO transactions
Take Mail Order/ Telephone Orders on behalf of your customers.
Enterprise
Worldpay eCommerce

Account Updater
Automatically update card details to prevent declines due to expired or changed cards.
Enterprise

Pay via AI Agent (Delegate session)
OpenAI's instant checkout using Agentic Commerce Protocol (ACP)
Enterprise
Preview

## 4. Response

Features that change the API flow
Certain features add additional requests and responses:

- [3DS](/products/payments/enable-features/3ds-authentication) - you will receive a `201` - `3dsDeviceDataRequired` as well as the possibility of an issuer challenge
- [FraudSight](/products/payments/enable-features/fraud-assessment) - you may receive a `201` - `fraudHighRisk` outcome, stopping the payment
- [Auto Settlement](/products/payments/enable-features/auto-settlement) - automatic `202` - `sentForSettlement` following authorization.
  - If any of the AVS/CVC response riskFactors are marked as `notMatched` the payment will be `sentForCancellation` automatically by default but can be disabled.


View the full API Response schema
## Sequence diagram

Worldpay Token
Setup a customerAgreement to store credentials for future CIT payments.

* Set the `customerAgreement.type` to `cardOnFile` and `storedCardUsage` to `first`
* Set `tokenCreation.type` to `worldpay` in order to store the credentials.
* The example includes 3DS for [SCA or 3DS mandated countries](/products/3ds-sca-exemptions/)
* If no initial payment is to be made (e.g. free trial), set the `value.amount` to `0`. A card verification is performed instead.



```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Issuer
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Set customerAgreement <br> type: cardOnFile <br> storedCardUsage: first
    Note over Merchant_Backend,Payments_API: Set tokenCreation.type: worldpay
    Note over Merchant_Backend,Payments_API: For `store a card only` (no payment) <br> Set value.amount: 0
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Merchant_Frontend: DeviceData - BIN/JWT/URL
    Merchant_Frontend->>Browser: 3DS Device Data form
    Browser-->>Issuer: Form post
    Issuer-->>Browser: PostMessage: dfReferenceId
    Merchant_Backend->>Payments_API: 3dsDeviceData request
    Payments_API->>Merchant_Backend: 3dsDeviceData response
    Merchant_Backend->>Merchant_Frontend: Challenge JWT/URL
    Merchant_Frontend->>Browser: 3DS challenge form
    Browser-->>Issuer: Form post
    Issuer-->>Browser: Return to merchant site
    Merchant_Backend->>Payments_API: 3dsChallenges request
    Payments_API->>Issuer: Authorization Request
    Note over Issuer: payment authorized
    Issuer->>Payments_API: Authorization Response
    Note over Merchant_Backend,Payments_API: Worldpay Token provided
    Payments_API->>Merchant_Backend: 3dsChallenges response
    alt For payment without auto settlement
        Merchant_Backend->>Payments_API: Settlement request
        Payments_API->>Merchant_Backend: Settlement 
    end
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

Network Token (NPT) - before payment
Support for NPT creation directly from the payments API is coming soon. For now you must call the [Tokens API](/products/tokens/) to convert from a Worldpay Token to a Network Token.

Setup a customerAgreement to store credentials for future CIT payments. Creating an Network Token `before` the initial payment is made.

**First request to Payments API:**

* Set `tokenCreation.type` to `worldpay`
* Set the `value.amount` to `0`
* Do not perform 3DS at this point.


**Request to [Tokens API](/products/tokens/)**

* Convert the Worldpay Token to a Network Token


**Second request to Payments API**

* Set the `customerAgreement.type` to `cardOnFile` and `storedCardUsage` to `first`
* Use the Network Token
* The example includes 3DS for [SCA or 3DS mandated countries](/products/3ds-sca-exemptions/).
* If no initial payment is to be made (e.g. free trial), set the `value.amount` to `0`. A card verification is performed instead.



```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Tokens
    participant Issuer
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Set tokenCreation.type: worldpay
    Note over Merchant_Backend,Payments_API: Set amount.value: 0
    Payments_API->>Merchant_Backend: Payment response
    Note over Merchant_Backend,Payments_API: Worldpay Token provided
    Merchant_Backend->>Tokens: Create network token request
    Tokens->>Merchant_Backend: Create network token response
    Note over Merchant_Backend,Payments_API: Network Token (NPT) provided
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Using NPT / Cryptogram auto provisioned
    Note over Merchant_Backend,Payments_API: Set customerAgreement <br> type: cardOnFile <br> storedCardUsage: first
    Merchant_Backend->>Merchant_Frontend: DeviceData - BIN/JWT/URL
    Merchant_Frontend->>Browser: 3DS Device Data form
    Browser-->>Issuer: Form post
    Issuer-->>Browser: PostMessage: dfReferenceId
    Merchant_Backend->>Payments_API: 3dsDeviceData request
    Payments_API->>Merchant_Backend: 3dsDeviceData response
    Merchant_Backend->>Merchant_Frontend: Challenge JWT/URL
    Merchant_Frontend->>Browser: 3DS challenge form
    Browser-->>Issuer: Form post
    Issuer-->>Browser: Return to merchant site
    Merchant_Backend->>Payments_API: 3dsChallenges request
    Payments_API->>Issuer: Authorization Request
    Note over Issuer: payment authorized
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: 3dsChallenges response
    alt For payment without auto settlement
        Merchant_Backend->>Payments_API: Settlement request
        Payments_API->>Merchant_Backend: Settlement
    end
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

Network Token (NPT) - after payment
Support for NPT creation directly from the payments API is coming soon. For now you must call the [Tokens API](/products/tokens/) to convert from a Worldpay Token to a Network Token.

Setup a customerAgreement to store credentials for future CIT payments. Creating an Network Token `after` the initial payment is made.

**Request to Payments API:**

* Set the `customerAgreement.type` to `cardOnFile` and `storedCardUsage` to `first`
* Set `tokenCreation.type` to `worldpay`
* The example includes 3DS for [SCA or 3DS mandated countries](/products/3ds-sca-exemptions/).
* If no initial payment is to be made (e.g. free trial), set the `value.amount` to `0`. A card verification is performed instead.


**Request to [Tokens API](/products/tokens/):**

* Convert the Worldpay Token to a Network Token for use in a subsequent CIT



```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Tokens
    participant Issuer
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Set customerAgreement <br> type: cardOnFile <br> storedCardUsage: first
    Note over Merchant_Backend,Payments_API: Set tokenCreation.type: worldpay
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Merchant_Frontend: DeviceData - BIN/JWT/URL
    Merchant_Frontend->>Browser: 3DS Device Data form
    Browser-->>Issuer: Form post
    Issuer-->>Browser: PostMessage: dfReferenceId
    Merchant_Backend->>Payments_API: 3dsDeviceData request
    Payments_API->>Merchant_Backend: 3dsDeviceData response
    Merchant_Backend->>Merchant_Frontend: Challenge JWT/URL
    Merchant_Frontend->>Browser: 3DS challenge form
    Browser-->>Issuer: Form post
    Issuer-->>Browser: Return to merchant site
    Merchant_Backend->>Payments_API: 3dsChallenges request
    Payments_API->>Issuer: Authorization Request
    Note over Issuer: payment authorized
    Issuer->>Payments_API: Authorization Response
    Note over Merchant_Backend,Payments_API: Worldpay Token provided
    Payments_API->>Merchant_Backend: 3dsChallenges response
    alt For payment without auto settlement
        Merchant_Backend->>Payments_API: Settlements request
        Payments_API->>Merchant_Backend: Settlements 
    end
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
    Merchant_Backend->>Tokens: Create network token request
    Tokens->>Merchant_Backend: Create network token response
    Note over Merchant_Backend,Payments_API: Network Token (NPT) provided <br> Store and use for next CIT
```