# Payments API - sequence diagrams

Below are some common flows when using the Payments API.

- [Payments API - sequence diagrams](#payments-api---sequence-diagrams)
  - [Guest card payment](#guest-card-payment)
  - [FraudSight](#fraudsight)
  - [3DS](#3ds)
  - [SCA Exemptions](#sca-exemptions)
  - [Storing credentials for future CIT / Store a card only](#storing-credentials-for-future-cit--store-a-card-only)
  - [Subsequent CIT](#subsequent-cit)
  - [Storing credentials for future MIT](#storing-credentials-for-future-mit)
  - [Subsequent MIT](#subsequent-mit)


For greater control of the payment flow, view the sequence diagrams for our [Modular APIs](/products/modular/).

## Guest card payment

Payment
A basic card payment with no additional features such as 3DS or FraudSight enabled.


```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
    Payments_API->>Issuer: Authorization request
    Issuer->>Payments_API: Authorization response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlement request
    Payments_API->>Merchant_Backend: Settlement response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

Payment (auto settlement)
A basic card payment with no additional features such as 3DS or FraudSight enabled.

[`settlement.auto`](/products/payments/enable-features/auto-settlement) is set to `true`


```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
    Payments_API->>Issuer: Authorization Request
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

Checkout SDK (Web)
A basic card payment using the Checkout SDK to collect card details.


```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Checkout_Sessions as Checkout Sessions
    participant Issuer
    Note over Merchant_Frontend: Checkout JS added to page 
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Checkout_Sessions: Create session
    Checkout_Sessions->>Merchant_Frontend: Return session 
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Using Checkout SDK session
    Payments_API->>Issuer: Authorization Request
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

Checkout SDK (iOS/Android)
A basic card payment using the Checkout SDK on native devices to collect card details.


```mermaid

sequenceDiagram
    participant Merchant_App
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Checkout_Sessions as Checkout Sessions
    participant Issuer 
    Merchant_App->>Checkout_Sessions: Click pay - Create session
    Checkout_Sessions->>Merchant_App: Return session 
    Merchant_App->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Using Checkout SDK session
    Payments_API->>Issuer: Authorization Request
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_App: Transaction complete
    Note over Merchant_App: Order receipt page
```

## FraudSight

FraudSight (highRisk)
Card payment with [FraudSight enabled](/products/payments/enable-features/fraud-assessment) that results in a highRisk assessment outcome that stops the payment.


```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Payments_API->>Payments_API: Fraud assessment
    Note over Payments_API: outcome: highRisk <br> Payment stopped
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Merchant_Frontend: Transaction failed
    Note left of Merchant_Frontend: Transaction failed
```

FraudSight (lowRisk/review)
Card payment with [FraudSight enabled](/products/payments/enable-features/fraud-assessment) that results in a lowRisk assessment outcome and continues with the payment.


```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
    Payments_API->>Payments_API: fraud assessment
    Note over Payments_API: outcome: lowRisk or review <br> Proceed with payment
    Payments_API->>Issuer: Authorization Request
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

## 3DS

3DS Web (frictionless)
Card payment with [3DS authentication enabled](/products/payments/enable-features/3ds-authentication), resulting in a frictionless issuer response.


```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
    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->>Issuer: Authorization request
    Issuer->>Payments_API: Authorization response
    Payments_API->>Merchant_Backend: 3dsDeviceData response
    Merchant_Backend->>Payments_API: Settlement request
    Payments_API->>Merchant_Backend: Settlement response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

3DS Web (challenge)
Card payment with [3DS authentication enabled](/products/payments/enable-features/3ds-authentication), resulting in a challenged issuer response.


```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
    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
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: 3dsChallenges response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

3DS iOS/Android (challenge)
Card payment with [3DS authentication enabled](/products/payments/enable-features/3ds-authentication), resulting in a challenged issuer response.


```mermaid

sequenceDiagram
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Issuer
    Merchant_App->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Merchant_App: DeviceData - JWT
    Note over Merchant_App: Cardinal SDK: Initialize
    Merchant_App-->>Issuer: Device App data
    Issuer-->>Merchant_App: consumerSessionId  
    Merchant_Backend->>Payments_API: 3dsDeviceData request
    Note left of Payments_API: Includes consumerSessionId
    Payments_API->>Merchant_Backend: 3dsDeviceData response
    Merchant_Backend->>Merchant_App: Challenge - Payload
    Note over Merchant_App: Cardinal SDK: Display Challenge
    Merchant_App-->>Issuer: Challenge Data
    Issuer-->>Merchant_App: Challenge Complete
    Merchant_Backend->>Payments_API: 3dsChallenges request
    Payments_API->>Issuer: Authorization Request
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: 3dsChallenges response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_App: Transaction complete
    Note left of Merchant_App: Order receipt page
```

Example using Checkout SDK
An example using the Checkout SDK to provide the card details using a low PCI set of hosted card fields. The rest of the flow is the same as the `3DS Web (challenge)` tab.


```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Checkout_Sessions as Checkout Sessions
    participant Issuer
    Note over Merchant_Frontend: Checkout JS added to page 
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Checkout_Sessions: Create session
    Checkout_Sessions->>Merchant_Frontend: Return session 
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Using Checkout SDK session
    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
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: 3dsChallenges response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

## SCA Exemptions

Exemption in Authorization
Exemption granted with a placement of `authorization` and is honored by the issuer (payment authorized)


```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
    Payments_API->>Payments_API: Exemption assessment
    Note over Payments_API: Exemption granted <br> Placement: authorization <br> Type: lowRisk or lowValue
    Payments_API->>Issuer: Authorization request
    Note over Issuer: Exemption honored <br> payment authorized
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlement request
    Payments_API->>Merchant_Backend: Settlement response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

Exemption in Authorization - Soft Decline Loop
Exemption granted with a placement of `authorization`, but the issuer does not honor the exemption and returns a refused outcome (soft decline - code: 65).

Payments API automatically starts the steps for 3DS authentication and upon completion results in a successful 2nd attempt to authorize the payment.


```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
    Payments_API->>Payments_API: Exemption Assessment
    Note over Payments_API: Exemption granted <br> Placement: authorization <br> Type: lowRisk or lowValue
    Payments_API->>Issuer: Authorization Request
    Note over Issuer: Exemption not honored <br> payment refused (code: 65)
    Issuer->>Payments_API: Authorization Response
    Note over Payments_API: Start 3DS authentication (automatic)  
    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
    Note over Payments_API: 3DS authenticated (successful)
    Payments_API->>Issuer: Authorization Request
    Note over Issuer: payment authorized
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: 3dsChallenges response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

Exemption in Authentication (3DS)
Exemption is granted with a placement of `authentication`, 3DS authentication is started and the challenge preference is auto set to `noChallengeRequestedTRAPerformed`.

The issuer honors the challenge preference and no challenge is given in 3DS. The successful 3DS authentication details are used in the payment request resulting in an authorized payment.


```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
    Payments_API->>Payments_API: Exemption Assessment
    Note over Payments_API: Exemption granted <br> Placement: authentication <br> Type: lowRisk
    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->>Issuer: Authorization Request
    Note over Issuer: Exemption honored <br> payment authorized
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: 3dsDeviceData response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

No Exemption Granted
No exemption is granted so 3DS authentication is automatically performed.


```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
    Payments_API->>Payments_API: Exemption Assessment
    Note over Payments_API: Exemption not granted  
    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
    Note over Payments_API: 3DS authenticated (successful)
    Payments_API->>Issuer: Authorization Request
    Note over Issuer: payment authorized
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: 3dsChallenges response
    Merchant_Backend->>Payments_API: Settlements request
    Payments_API->>Merchant_Backend: Settlements response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

## Storing credentials for future CIT / Store a card only

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
```

## Subsequent CIT

Subsequent CIT
Using a previously stored card to make a payment


```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Issuers
    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: subsequent
    Note over Merchant_Backend,Payments_API: Use Network Token <br> or Worldpay Token
    Payments_API->>Issuer: Authorization Request
    Note over Issuer: payment authorized
    Issuer->>Payments_API: Authorization Response
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlement request
    Payments_API->>Merchant_Backend: Settlement response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

## Storing credentials for future MIT

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

* Set the `customerAgreement.type` to `subscription` 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/) and has the `threeDS.challenge.preference` set to `challengeMandated`.
* 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: subscription <br> storedCardUsage: first
    Note over Merchant_Backend,Payments_API: Set threeDS.challenge <br> preference: challengeMandated
    Note over Merchant_Backend,Payments_API: Set tokenCreation.type: worldpay
    Note over Merchant_Backend,Payments_API: For no initial 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 <br> and schemeReference 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 MIT 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 `subscription` and `storedCardUsage` to `first`
* Set `paymentInstrument.type` as `networkToken` and apply the token details here.
* The example includes 3DS for [SCA or 3DS mandated countries](/products/3ds-sca-exemptions/) and has the `threeDS.challenge.preference` set to `challengeMandated`.
* 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 <br> Cryptogram auto provisioned
    Note over Merchant_Backend,Payments_API: Set customerAgreement <br> type: subscription <br> storedCardUsage: first
    Note over Merchant_Backend,Payments_API: Set threeDS.challenge <br> preference: challengeMandated
    Note over Merchant_Backend,Payments_API: For no initial payment <br> Set value.amount: 0
    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: schemeReference 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
```

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 MIT payments. Creating an Network Token `after` the initial payment is made.

**Request to Payments API:**

* Set the `customerAgreement.type` to `subscription` and `storedCardUsage` to `first`
* Set `tokenCreation.type` to `worldpay`
* The example includes 3DS for [SCA or 3DS mandated countries](/products/3ds-sca-exemptions/) and has the `threeDS.challenge.preference` set to `challengeMandated`.
* 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 next CIT



```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: subscription <br> storedCardUsage: first
    Note over Merchant_Backend,Payments_API: Set threeDS.challenge <br> preference: challengeMandated
    Note over Merchant_Backend,Payments_API: Set tokenCreation.type: worldpay
    Note over Merchant_Backend,Payments_API: For no initial 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 <br> and schemeReference 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 MIT
```

Example using Checkout SDK
Setup a customerAgreement to store credentials for future MIT payments. Use the Checkout SDK to provide the card details using a low PCI set of hosted card fields.

* Set `paymentInstrument.type` as `checkout` and apply the sessionHref here
* Set the `customerAgreement.type` to `subscription` 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/) and has the `threeDS.challenge.preference` set to `challengeMandated`.
* 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
    Note over Merchant_Frontend: Checkout JS added to page 
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Checkout_Sessions: Create session
    Checkout_Sessions->>Merchant_Frontend: Return session 
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Using Checkout SDK session
    Note over Merchant_Backend,Payments_API: Set customerAgreement <br> type: subscription <br> storedCardUsage: first
    Note over Merchant_Backend,Payments_API: Set threeDS.challenge <br> preference: challengeMandated
    Note over Merchant_Backend,Payments_API: Set tokenCreation.type: worldpay
    Note over Merchant_Backend,Payments_API: For no initial 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: Settlements request
        Payments_API->>Merchant_Backend: Settlements 
    end
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```

## Subsequent MIT

Subsequent MIT
Send a Merchant Initiated Transaction (MIT) request for subsequent recurring transactions.


```mermaid

sequenceDiagram
    participant Browser
    participant Merchant_Frontend as Merchant Frontend
    participant Merchant_Backend as Merchant Backend
    participant Payments_API as Payments API
    participant Issuers
    Browser->>Merchant_Frontend: Click Pay
    Merchant_Frontend->>Merchant_Backend: Pay 
    Merchant_Backend->>Payments_API: Payment request
    Note over Merchant_Backend,Payments_API: Set `customerAgreement.type = subscription` <br> `customerAgreement.storedCardUsage = subsequent`
    Payments_API->>Merchant_Backend: Payment response
    Merchant_Backend->>Payments_API: Settlement request
    Payments_API->>Merchant_Backend: Settlement response
    Merchant_Backend->>Merchant_Frontend: Transaction complete
    Note left of Merchant_Frontend: Order receipt page
```