Last Updated: 30 April 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":

Version 6Version 7
access.worldpay.com/paymentsaccess.worldpay.com/cardPayments

Headers

Headers have been updated as below:

HeaderVersion 6Version 7
Acceptapplication/vnd.worldpay.payments-v6.hal+json
(was optional)
application/vnd.worldpay.payments-v7+json
(now mandatory)
Content-Typeapplication/vnd.worldpay.payments-v6+jsonapplication/vnd.worldpay.payments-v7+json

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

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:

FieldVersion 6Version
Payment Facilitator IDpaymentFacilitator.pfIdpaymentFacilitator.schemeId
Payment Facilitator ISO IDpaymentFacilitator.isoIdpaymentFacilitator.independentSalesOrganizationId
Payment Facilitator Tax IDpaymentFacilitator.taxIdpaymentFacilitator.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.dpaninstruction.paymentInstrument.tokenNumber
Payment Instrument expiry dateinstruction.paymentInstrument.cardExpiryDateinstruction.paymentInstrument.expiryDate
Network Token cryptogramcustomer.authentication.authenticationValueauthentication.networkToken.cryptogram

Currency exponent changes

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

CurrencyOld exponentNew exponent
CLP02
CVE02
ISK02
UGX02

Response field name changes

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

FieldVersion 6VersionNotes
riskFactors.risk valuesnot_checked / not_matched / not_suppliednotChecked / notMatched / notSuppliedCasing changed
Card BINcard.number.bincardBin"card" dropped from paymentInstrument
Card Last Four Digitscard.number.last4DigitslastFour"card" dropped from paymentInstrument
Card Brandcard.brandbrand"card" dropped from paymentInstrument
Card Funding Type (credit, debit, pre-paid, etc)card.fundingTypefundingType"card" dropped from paymentInstrument
Card Category (commercial, consumer)card.categorycategory"card" dropped from paymentInstrument
Payment Account Reference (PAR)card.paymentAccountReferencepaymentAccountReference"card" dropped from paymentInstrument
Card issuer name has been flattenedpaymentInstrument.card.issuer.namepaymentInstrument.issuerName"card" dropped from paymentInstrument
Refusal code renamedcoderefusalCodeRemains at top level
Refusal description renameddescriptionrefusalDescriptionRemains at top level
Refusal advice code (MAC)refusalAdvice.codeadvice.codeRenamed 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 refusalCoderawCoderefusalCodeThis will now depend on whether the merchant code is enabled for raw codes
"_links" namespacing updatedeg "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.