Upgrade to Checkout API v72

Find what you must do to upgrade to Checkout API v72.

Checkout API v72 introduces validations to the values that you send in API requests, and removes the additionalData parameters for enhanced scheme data. To upgrade to this version, you must make sure that the data you send meets our validations, and that you send enhanced scheme data in the enhancedSchemeData object. These are breaking changes, so you must update your integration before using v72.

Requirements

Requirement	Description
Integration type	An online payments integration that uses Checkout API.
API credential roles	Make sure that you have the following role: Checkout webservice role
Customer Area roles	Make sure that you have one of the following roles: Merchant admin role Manage API credentials

Validate the data that you send

Check that the values that you send in each parameter in the following table meets the validations.

Parameter	Validation requirement
`billingAddress.postalCode`	Maximum length: 10 characters.
`billingAddress.stateOrProvinceCode`	Maximum length: 10 characters.
`captureDelayHours`	Maximum value: 672. This maximum value corresponds to 28 (twenty-eight) days.
`dateOfBirth`	Format requirement: Must be in ISO-8601 format with the date (`YYYY-MM-DD`). Example: 2005-03-01 (March 1, 2025).
`deliveryAddress.postalCode`	Maximum length: 10 characters.
`deliveryAddress.stateOrProvinceCode`	Format requirement: Must be an ISO 3166-1 alpha-2 code. Maximum length: 2 characters.
`entityType`	Possible values: NaturalPerson CompanyName
`metadata`	Maximum lengths: For the key: 20 characters. For the value: 80 characters.
`reference`	Maximum length: 80 characters.
`returnUrl`	Format requirement: Must meet the RFC 2396 standard. If the URL to return to includes non-ASCII characters, like spaces or special letters, you must URL encode the value. Maximum length: 1024 characters.
`shopperEmail`	Format requirements: Must not have spaces. Must contain the at symbol character(`@`) . Must contain text before and after the at symbol character (`@`). The email domain must not start with the period character (`.`). The username must not include the quotation marks character (`"`), unless the whole name is in quotation marks. Maximum length: 256 characters.
`shopperIP`	Maximum length: 256 characters.
`shopperName.firstName`	Maximum length: 100 characters.
`shopperName.lastName`	Maximum length: 100 characters.
`socialSecurityNumber`	Maximum length: 50 characters.
`telephoneNumber`	Maximum length: 64 characters.

Use new parameters for enhanced scheme data

Checkout API v72 removes the additionalData parameters for enhanced scheme data. To keep sending enhanced scheme data, you must use the parameters in the enhancedSchemeData object. A v72 payment request that includes the additionalData parameters for enhanced scheme data returns a validation error.

To update your requests:

In your payment and capture requests, replace each additionalData parameter with the enhancedSchemeData parameter for your industry, as shown in the following tables.
Make a test payment and check that you get a successful response.

For temporary services, you must send two objects: enhancedSchemeData.levelTwoThree for the customer reference and tax fields, and enhancedSchemeData.temporaryServices for all other fields.

Airline

`additionalData` parameter	`enhancedSchemeData` parameter
`additionalData.airline.passenger_name`	`enhancedSchemeData.airline.passengerName`
`additionalData.airline.computerized_reservation_system`	`enhancedSchemeData.airline.computerizedReservationSystem`
`additionalData.airline.airline_code`	`enhancedSchemeData.airline.code`
`additionalData.airline.ticket_number`	`enhancedSchemeData.airline.ticket.number`
`additionalData.airline.flight_date`	`enhancedSchemeData.airline.flightDate`
`additionalData.airline.issue_date`	`enhancedSchemeData.airline.ticket.issueDate`
`additionalData.airline.customer_reference_number`	`enhancedSchemeData.airline.customerReferenceNumber`
`additionalData.airline.ticket_issue_address`	`enhancedSchemeData.airline.ticket.issueAddress`
`additionalData.airline.airline_designator_code`	`enhancedSchemeData.airline.designatorCode`
`additionalData.airline.travel_agency_code`	`enhancedSchemeData.airline.travelAgency.code`
`additionalData.airline.travel_agency_name`	`enhancedSchemeData.airline.travelAgency.name`
`additionalData.airline.agency_plan_name`	`enhancedSchemeData.airline.agency.planName`
`additionalData.airline.agency_invoice_number`	`enhancedSchemeData.airline.agency.invoiceNumber`
`additionalData.airline.boarding_fee`	`enhancedSchemeData.airline.boardingFee`
`additionalData.airline.document_type`	`enhancedSchemeData.airline.documentType`
`additionalData.airline.leg1.depart_airport`	`enhancedSchemeData.airline.legs.departureAirportCode`
`additionalData.airline.leg1.flight_number`	`enhancedSchemeData.airline.legs.flightNumber`
`additionalData.airline.leg1.carrier_code`	`enhancedSchemeData.airline.legs.carrierCode`
`additionalData.airline.leg1.fare_base_code`	`enhancedSchemeData.airline.legs.fareBasisCode`
`additionalData.airline.leg1.class_of_travel`	`enhancedSchemeData.airline.legs.classOfTravel`
`additionalData.airline.leg1.stop_over_code`	`enhancedSchemeData.airline.legs.stopOverCode`
`additionalData.airline.leg1.destination_code`	`enhancedSchemeData.airline.legs.destinationAirportCode`
`additionalData.airline.leg1.date_of_travel`	`enhancedSchemeData.airline.legs.dateOfTravel`
`additionalData.airline.leg1.depart_tax`	`enhancedSchemeData.airline.legs.departureTax`
`additionalData.airline.passenger1.first_name`	`enhancedSchemeData.airline.passengers.firstName`
`additionalData.airline.passenger1.last_name`	`enhancedSchemeData.airline.passengers.lastName`
`additionalData.airline.passenger1.traveller_type`	`enhancedSchemeData.airline.passengers.travellerType`
`additionalData.airline.passenger1.phone_number`	`enhancedSchemeData.airline.passengers.phoneNumber`
`additionalData.airline.passenger1.date_of_birth`	`enhancedSchemeData.airline.passengers.dateOfBirth`

Car rental

`additionalData` parameter	`enhancedSchemeData` parameter
`additionalData.carRental.rentalAgreementNumber`	`enhancedSchemeData.carRental.rentalAgreementNumber`
`additionalData.carRental.renterName`	`enhancedSchemeData.carRental.renterName`
`additionalData.carRental.returnCity`	`enhancedSchemeData.carRental.returnInfo.city`
`additionalData.carRental.returnStateProvince`	`enhancedSchemeData.carRental.returnInfo.stateOrProvince`
`additionalData.carRental.returnCountry`	`enhancedSchemeData.carRental.returnInfo.countryCode`
`additionalData.carRental.returnLocationId`	`enhancedSchemeData.carRental.returnInfo.locationId`
`additionalData.carRental.returnDate`	`enhancedSchemeData.carRental.returnInfo.date`
`additionalData.carRental.checkOutDate`	`enhancedSchemeData.carRental.pickupInfo.date`
`additionalData.carRental.locationCity`	`enhancedSchemeData.carRental.pickupInfo.city`
`additionalData.carRental.locationStateProvince`	`enhancedSchemeData.carRental.pickupInfo.stateOrProvince`
`additionalData.carRental.locationCountry`	`enhancedSchemeData.carRental.pickupInfo.countryCode`
`additionalData.carRental.customerServiceTollFreeNumber`	`enhancedSchemeData.carRental.customerServicePhoneNumber`
`additionalData.carRental.rate`	`enhancedSchemeData.carRental.rentalRate`
`additionalData.carRental.rateIndicator`	`enhancedSchemeData.carRental.rateType`
`additionalData.carRental.rentalClassId`	`enhancedSchemeData.carRental.rentalClassId`
`additionalData.carRental.daysRented`	`enhancedSchemeData.carRental.rentalDays`
`additionalData.carRental.taxExemptIndicator`	`enhancedSchemeData.carRental.taxExempt`
`additionalData.carRental.fuelCharges`	`enhancedSchemeData.carRental.rentalSurcharges.fuel`
`additionalData.carRental.insuranceCharges`	`enhancedSchemeData.carRental.rentalSurcharges.insurance`
`additionalData.carRental.oneWayDropOffCharges`	`enhancedSchemeData.carRental.rentalSurcharges.oneWayDropOff`
`additionalData.carRental.noShowIndicator`	`enhancedSchemeData.carRental.noShow`
`additionalData.travelEntertainmentAuthData.market`	No longer needed
`additionalData.travelEntertainmentAuthData.duration`	No longer needed

Level 2/3

`additionalData` parameter	`enhancedSchemeData` parameter
`additionalData.enhancedSchemeData.customerReference`	`enhancedSchemeData.levelTwoThree.customerReferenceNumber`
`additionalData.enhancedSchemeData.totalTaxAmount`	`enhancedSchemeData.levelTwoThree.totalTaxAmount`
`additionalData.enhancedSchemeData.freightAmount`	`enhancedSchemeData.levelTwoThree.freightAmount`
`additionalData.enhancedSchemeData.dutyAmount`	`enhancedSchemeData.levelTwoThree.dutyAmount`
`additionalData.enhancedSchemeData.orderDate`	`enhancedSchemeData.levelTwoThree.orderDate`
`additionalData.enhancedSchemeData.shipFromPostalCode`	`enhancedSchemeData.levelTwoThree.shipFromPostalCode`
`additionalData.enhancedSchemeData.destinationCountryCode`	`enhancedSchemeData.levelTwoThree.destination.countryCode`
`additionalData.enhancedSchemeData.destinationPostalCode`	`enhancedSchemeData.levelTwoThree.destination.postalCode`
`additionalData.enhancedSchemeData.destinationStateProvinceCode`	`enhancedSchemeData.levelTwoThree.destination.stateOrProvince`
`additionalData.enhancedSchemeData.itemDetailLine1.productCode`	`enhancedSchemeData.levelTwoThree.itemDetailLines.productCode`
`additionalData.enhancedSchemeData.itemDetailLine1.description`	`enhancedSchemeData.levelTwoThree.itemDetailLines.description`
`additionalData.enhancedSchemeData.itemDetailLine1.quantity`	`enhancedSchemeData.levelTwoThree.itemDetailLines.quantity`
`additionalData.enhancedSchemeData.itemDetailLine1.unitOfMeasure`	`enhancedSchemeData.levelTwoThree.itemDetailLines.unitOfMeasure`
`additionalData.enhancedSchemeData.itemDetailLine1.unitPrice`	`enhancedSchemeData.levelTwoThree.itemDetailLines.unitPrice`
`additionalData.enhancedSchemeData.itemDetailLine1.commodityCode`	`enhancedSchemeData.levelTwoThree.itemDetailLines.commodityCode`
`additionalData.enhancedSchemeData.itemDetailLine1.discountAmount`	`enhancedSchemeData.levelTwoThree.itemDetailLines.discountAmount`
`additionalData.enhancedSchemeData.itemDetailLine1.totalAmount`	`enhancedSchemeData.levelTwoThree.itemDetailLines.totalAmount`

Lodging

`additionalData` parameter	`enhancedSchemeData` parameter
`additionalData.lodging.checkInDate`	`enhancedSchemeData.lodging.checkInDate`
`additionalData.lodging.checkOutDate`	`enhancedSchemeData.lodging.checkOutDate`
`additionalData.lodging.customerServiceTollFreeNumber`	`enhancedSchemeData.lodging.customerServicePhoneNumber`
`additionalData.lodging.propertyPhoneNumber`	`enhancedSchemeData.lodging.propertyPhoneNumber`
`additionalData.lodging.folioNumber`	`enhancedSchemeData.lodging.folio.number`
`additionalData.lodging.folioCashAdvances`	`enhancedSchemeData.lodging.folio.cashAdvances`
`additionalData.lodging.room1.rate`	`enhancedSchemeData.lodging.rooms.rate`
`additionalData.lodging.room1.numberOfNights`	`enhancedSchemeData.lodging.rooms.numberOfNights`
`additionalData.lodging.fireSafetyActIndicator`	`enhancedSchemeData.lodging.fireSafetyCompliance`
`additionalData.lodging.foodBeverageCharges`	`enhancedSchemeData.lodging.foodBeverageCharges`
`additionalData.lodging.prepaidExpenses`	`enhancedSchemeData.lodging.prepaidExpenses`
`additionalData.lodging.totalTax`	`enhancedSchemeData.lodging.totalTax`
`additionalData.lodging.totalRoomTax`	`enhancedSchemeData.lodging.totalRoomTax`
`additionalData.lodging.specialProgramCode`	`enhancedSchemeData.lodging.lodgingChargeType`
`additionalData.lodging.noShowIndicator`	`enhancedSchemeData.lodging.noShow`
`additionalData.travelEntertainmentAuthData.market`	No longer needed
`additionalData.travelEntertainmentAuthData.duration`	No longer needed

Temporary services

`additionalData` parameter	`enhancedSchemeData` parameter
`additionalData.enhancedSchemeData.customerReference`	`enhancedSchemeData.levelTwoThree.customerReferenceNumber`
`additionalData.enhancedSchemeData.totalTaxAmount`	`enhancedSchemeData.levelTwoThree.totalTaxAmount`
`additionalData.enhancedSchemeData.employeeName`	`enhancedSchemeData.temporaryServices.employeeName`
`additionalData.enhancedSchemeData.jobDescription`	`enhancedSchemeData.temporaryServices.jobDescription`
`additionalData.enhancedSchemeData.tempStartDate`	`enhancedSchemeData.temporaryServices.startDate`
`additionalData.enhancedSchemeData.tempWeekEnding`	`enhancedSchemeData.temporaryServices.endDate`
`additionalData.enhancedSchemeData.requestName`	`enhancedSchemeData.temporaryServices.serviceRequestor`
`additionalData.enhancedSchemeData.regularHoursWorked`	`enhancedSchemeData.temporaryServices.hoursWorked`
`additionalData.enhancedSchemeData.regularHoursRate`	`enhancedSchemeData.temporaryServices.hourRate`