Last Updated: 04 December 2024 | Change Log

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":

Headers

Headers have been updated as below:

Endpoints

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

The version 6 endpoint structure was split by:

• Authorization / Sale
• oneTime / cardOnFile / recurring

Version 7 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: access.worldpay.com/payments/authorizations
• Card on File Authorize access.worldpay.com/payments/authorizations/cardOnFile
• Migrate Card on File Authorize: access.worldpay.com/payments/authorizations/migrateCardOnFile/
• Migrate Card on File Sale: access.worldpay.com/payments/sales/migrateCardOnFile/
• Recurring Authorize: access.worldpay.com/payments/authorizations/recurring/{resource}
• Migrate Recurring Authorize: access.worldpay.com/payments/authorizations/migrateRecurring
• Recurring Sale: access.worldpay.com/payments/sales/recurring/{resource}

Version 7 endpoints

• CIT payments: access.worldpay.com/cardPayments/customerInitiatedTransactions
• MIT payments: access.worldpay.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.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.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.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.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.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.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.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:

Currency exponent changes

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

Response field name changes

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

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.