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

# Card Payments version 7: migration guide

This page details the main changes between Card Payments version 6 and version 7. These are listed below with a subheading per API change.

## Root resource naming

The API root resource has changed from "payments" to "cardPayments":

| Version 6 | Version 7 |
|  --- | --- |
| `access.worldpay-bsh.securedataplatform.com/payments` | `access.worldpay-bsh.securedataplatform.com/cardPayments` |


## Headers

Headers have been updated as below:

| Header | Version 6 | Version 7 |
|  --- | --- | --- |
| Accept | `application/vnd.worldpay.payments-v6.hal+json`(was optional) | `application/vnd.worldpay.payments-v7+json`(now mandatory) |
| Content-Type | `application/vnd.worldpay.payments-v6+json` | `application/vnd.worldpay.payments-v7+json` |


## Endpoints

We have reduced the number of endpoints for authorization and sale from 8 to 2.

The [version 6](/products/card-payments/v6/authorize-a-payment) endpoint structure was split by:

- Authorization / Sale
- oneTime / cardOnFile / recurring


[Version 7](/products/card-payments/authorize-a-payment) authorization endpoints are divided on whether the authorization is initiated by the customer, or by the merchant. This distinction affects much of what is possible or not possible in the request.

Some examples:

- CIT requests can include CVC; MIT cannot.
- CIT requests can include 3DS data; MIT cannot.
- Encrypted Apple Pay / Google Pay `paymentInstrument` types can be used with CIT; but not with MIT.
- Network token payments require a cryptogram for CITs; but not for MITs.
- MIT requests can have a scheme reference; CIT requests should not.


### Version 6 endpoints

- [One time Authorize](/products/card-payments/v6/authorize-a-payment): `access.worldpay-bsh.securedataplatform.com/payments/authorizations`
- [Card on File Authorize](/products/card-payments/v6/authorise-a-cardonfile-payment) `access.worldpay-bsh.securedataplatform.com/payments/authorizations/cardOnFile`
- [Migrate Card on File Authorize](/products/card-payments/v6/authorise-a-cardonfile-payment): `access.worldpay-bsh.securedataplatform.com/payments/authorizations/migrateCardOnFile/`
- [Migrate Card on File Sale](/products/card-payments/v6/migrate-cardonfile-sale): `access.worldpay-bsh.securedataplatform.com/payments/sales/migrateCardOnFile/`
- [Recurring Authorize](/products/card-payments/v6/authorise-a-recurring-payment): `access.worldpay-bsh.securedataplatform.com/payments/authorizations/recurring/{resource}`
- [Migrate Recurring Authorize](/products/card-payments/v6/authorise-a-recurring-payment): `access.worldpay-bsh.securedataplatform.com/payments/authorizations/migrateRecurring`
- [Recurring Sale](/products/card-payments/v6/take-a-sale): `access.worldpay-bsh.securedataplatform.com/payments/sales/recurring/{resource}`


### Version 7 endpoints

- CIT payments: `access.worldpay-bsh.securedataplatform.com/cardPayments/customerInitiatedTransactions`
- MIT payments: `access.worldpay-bsh.securedataplatform.com/cardPayments/merchantInitiatedTransactions`


## Requesting auto settlement (authorization vs sale)

A new mandatory object, `"requestAutoSettlement"` has been introduced to the request body to determine whether the request is sent for settlement or not:


```
"requestAutoSettlement":{
    "enabled": true / false
}
```

- `true` = we will send the authorization for settlement (this aligns with the "sale" endpoints in version 6)
- `false` = the payment will be sent for authorization only, and a next action link will be sent to you to request settlement (this aligns with the "authorizations" endpoints in version 6)


## Customer agreement (stored credentials)

Storing a card for later use is one of several agreements a customer might make for future processing at the time of payment. 

A new optional `"customerAgreement"` object has been added to the request body for CIT authorizations (POST: `access.worldpay-bsh.securedataplatform.com/cardPayments/customerInitiatedTransactions`). If the authorization is not either using a stored credential for the first time, or for a subsequent usage, then the object should not be included in the request body.

This is what we referred to as a "one time" authorization in version 6 of our API.

If, however, the CIT authorization is either the first use of a stored credential, or if the authorization is making use of a previously-stored credential, then the `"customerAgreement"` object should be included:

### CIT: Store credential for future cardOnFile processing

*Example use case:* A customer is storing a card for the first time on their account on an ecom website, with the expectation that they will return to that website in future and don't want to type in their card details next time (ie, "express checkout").

POST: `access.worldpay-bsh.securedataplatform.com/cardPayments/customerInitiatedTransactions`


```
"customerAgreement":{
    "type":"cardOnFile",
    "storedCardUsage":"first"
}
```

### CIT: Use a previously stored credential

*Example use case:* A customer returns to a website where they have previously stored a card, and selects the saved card at checkout for a subsequent purchase.

POST: `access.worldpay-bsh.securedataplatform.com/cardPayments/customerInitiatedTransactions`


```
"customerAgreement":{
    "type":"cardOnFile",
    "storedCardUsage":"subsequent"
}
```

### CIT: Store a card for future subscription payments

Example use case: A customer signs up to a subscription plan for the first time.

POST: `access.worldpay-bsh.securedataplatform.com/cardPayments/customerInitiatedTransactions`


```
"customerAgreement":{
    "type":"subscription",
    "storedCardUsage":"first"
}
```

### CIT: Store a card for future installment payments

Example use case: A customer uses a Buy Now Pay Later service to buy a new laptop. The balance will be collected in monthly installments.

The `"installmentType"` field distinguishes between the type of installment plan, eg where the merchant is the installment provider (BNPL use cases), or where a regional installment plan is being initiated (eg Latin America installments).

POST: `access.worldpay-bsh.securedataplatform.com/cardPayments/customerInitiatedTransactions`


```
"customerAgreement":{
    "type":"installment",
    "installmentType":"merchant",
    "storedCardUsage":"first"
}
```

### MIT: Take a subscription payment

Example use case: A merchant collects a payment for a previously-agreed subscription plan.

POST: `access.worldpay-bsh.securedataplatform.com/cardPayments/merchantInitiatedTransactions`


```
"customerAgreement":{
    "type":"subscription",
    "schemeReference":"MCCOLXT1C0104"
}
```

### MIT: Take a merchant installment payment

Example use case: A merchant collects a payment for a previously-agreed BNPL installment plan.

POST: `access.worldpay-bsh.securedataplatform.com/cardPayments/merchantInitiatedTransactions`


```
"customerAgreement":{
    "type":"installment",
    "installmentType":"merchant",
    "schemeReference":"MCCOLXT1C0104"
}
```

### Sending 3DS data for Network Tokens

3DS and Network Token authentication have moved out of the `"customer"."authentication"` object, and an `"authentication"` object now lives at the top level of the JSON schema. The authentication `"types"` are now explicitly-named objects: `"threeDS"`, `"networkToken"`. This allows both the cryptogram for network tokens and 3DS data to be sent in the same request:

3DS and Network Token in the same request (v7):


```
"authentication":{
    "threeDS":{
        "version":"2.1.0",
        "eci":"05",
    "authenticationValue":"MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "transactionId":"c5b808e7-1de1-4069-a17b-f70d3b3b1645"
        },
    "networkToken":{
        "cryptogram":"MAAAAAAAAAAAAAAAAAAAAAAAAAB=",
        "eci":"05"
    }
}
```

In version 6, **either** the network token cryptogram or 3DS authentication data could be sent, depending on the `"type"` selected:

Network token (v6):


```
"customer": {
    "authentication": {
        "type": "card/networkToken",
        "authenticationValue": "abc123=="
    }
}
```

3DS (v6):


```
"customer": {
    "authentication": {
        "version": "2.2.0",
        "type": "3DS",
        "eci": "05",
        "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}
```

### Risk profile placement

Since `"authentication"` is no longer housed within the `"customer"` object, `"riskProfile"` has also been moved to top level in the JSON schema. No other changes have been made to this field.

### Request field name changes

Several field name changes have been made, but no breaking validations have been made:

| Field | Version 6 | Version |
|  --- | --- | --- |
| Payment Facilitator ID | `paymentFacilitator.pfId` | `paymentFacilitator.schemeId` |
| Payment Facilitator ISO ID | `paymentFacilitator.isoId` | `paymentFacilitator.independentSalesOrganizationId` |
| Payment Facilitator Tax ID | `paymentFacilitator.taxId` | `paymentFacilitator.taxReference` |
| Payment Facilitator Address | `paymentFacilitator.subMerchant.street``paymentFacilitator.subMerchant.city``paymentFacilitator.subMerchant.postalCode``paymentFacilitator.subMerchant.countryCode` | Submerchant address fields moved within an `address` object:  `paymentFacilitator.subMerchant.address.street``paymentFacilitator.subMerchant.address.city``paymentFacilitator.subMerchant.address.postalCode``paymentFacilitator.subMerchant.address.countryCode` |
| DPAN (network token and Apple Pay Decrypted) | `instruction.paymentInstrument.dpan` | `instruction.paymentInstrument.tokenNumber` |
| Payment Instrument expiry date | `instruction.paymentInstrument.cardExpiryDate` | `instruction.paymentInstrument.expiryDate` |
| Network Token cryptogram | `customer.authentication.authenticationValue` | `authentication.networkToken.cryptogram` |


### Currency exponent changes

The exponent for the following currencies exponents have changed CLP, CVE, ISK, UGX

| Currency | Old exponent | New exponent |
|  --- | --- | --- |
| CLP | 0 | 2 |
| CVE | 0 | 2 |
| ISK | 0 | 2 |
| UGX | 0 | 2 |


### Response field name changes

Several field name changes have been made, but no breaking validations have been made:

| Field | Version 6 | Version | Notes |
|  --- | --- | --- | --- |
| `riskFactors.risk` values | `not_checked` / `not_matched` / `not_supplied` | `notChecked` / `notMatched` / `notSupplied` | Casing changed |
| Card BIN | `card.number.bin` | `cardBin` | `"card"` dropped from `paymentInstrument` |
| Card Last Four Digits | `card.number.last4Digits` | `lastFour` | `"card"` dropped from `paymentInstrument` |
| Card Brand | `card.brand` | `brand` | `"card"` dropped from `paymentInstrument` |
| Card Funding Type (credit, debit, pre-paid, etc) | `card.fundingType` | `fundingType` | `"card"` dropped from `paymentInstrument` |
| Card Category (commercial, consumer) | `card.category` | `category` | `"card"` dropped from `paymentInstrument` |
| Payment Account Reference (PAR) | `card.paymentAccountReference` | `paymentAccountReference` | `"card"` dropped from `paymentInstrument` |
| Card issuer name has been flattened | `paymentInstrument.card.issuer.name` | `paymentInstrument.issuerName` | `"card"` dropped from `paymentInstrument` |
| Refusal code renamed | `code` | `refusalCode` | Remains at top level |
| Refusal description renamed | `description` | `refusalDescription` | Remains at top level |
| Refusal advice code (MAC) | `refusalAdvice.code` | `advice.code` | Renamed because Mastercard can now return MAC for approvals |
| Raw code has been removed. We now map the normalized extended decline code or the raw code to `refusalCode` | `rawCode` | `refusalCode` | This will now depend on whether the merchant code is enabled for raw codes |
| `"_links"` namespacing updated | eg `"payments:refund"` | eg `"cardPayments:refund"` |  |


### Changes to error responses

#### JSON path errors

The `jsonPath` value for validation failures on JSON paths have been updated.

Version 6:


```
{
"errorName": "bodyDoesNotMatchSchema",
"message": "The json body provided does not match the expected schema",
"validationErrors": [
 {
    "errorName": "fieldIsMissing",
    "message": "Element at path must be supplied",
    "jsonPath": "/instruction/value"
    }
    ]
}
```

Version 7:


```
{
"errorName": "bodyDoesNotMatchSchema",
"message": "The json body provided does not match the expected schema",
"validationErrors": [
    {
    "errorName": "fieldIsMissing",
    "message": "Element at path must be supplied",
    "jsonPath": "$.instruction.value"
    }
    ]
}
```

#### Unexpected response from downstream

Unexpected responses from downstream systems now return a JSON object, rather than a string:

Version 6:


```
Unexpected response from downstream
```

Version 7:


```
{
    "errorName": "internalErrorOccurred",
    "message": "Unexpected response from downstream"
}
```

#### `AN` country code no longer supported

Country Code `AN` is no longer supported in `paymentFacilitator.subMerchant.address.countryCode`.