Versioning and change log

We have created a migration guide which consolidates the changes for an easier upgrade from version 6 to version 7.

• header change to "Content-Type: application/vnd.worldpay.payments-v6+json"
• new mandatory field intent for all recurring resources
• removed code and type from error messages

• header change to "Content-Type: application/vnd.worldpay.payments-v5+json"
• new mandatory field type
• new mandatory field version
• xid to transactionId

• Header change to "Content-Type: application/vnd.worldpay.payments-v0.4+json"
• New mandatory field entityReference

You can now submit a reference in your refund, settle and cancelation request. This allows you to identify a payment throughout its lifecycle.

You can now include a customerData object in your authentication object. This allows you to submit additional customer details necessary to meet local authentication, as required by country-specific regulations. Currently, the customerData object is used solely for domestic Toss Pay payments in South Korea.

You can now submit:

• emailAddress - allowing your customer to receive an email with the transaction outcome (if configured)
• ipAddress - as required for certain jurisdictions and/or MCCs
• phoneNumber - added for future enhancements for Amex

You can now submit a surchargeAmount and convenienceAmount in your authorization, settlement and refund requests within the value object. This allows you to report the amount charged for card processing or online booking fees to remain compliant with scheme mandates. Ensure that the surcharge or convenience fee complies with local regulations and card network rules before applying.

You can now enable partial authorization by setting the acceptPartialAuthorization object to true. This allows you to accept a partial payment if the full amount is not available, and then charge the remaining balance using a different payment method through a new authorization request.

You can now send a splitFundingReference in your settlement and refund requests. Available for marketplaces and other merchant types, a splitFundingReference allows you to split acquiring funding into your secondary bank account.

You can now send paymentFacilitator.subMerchant.url field in your authorization request.

You now receive a paymentInstrument.debitNetwork field in your authorization response. This field advises which debit network the transaction was routed through. Receiving this field requires additional configuration, please contact your Implementation Manager.

You can now send sender.dateOfBirth in your funds transfer (AFT) requests which is required for some cross border funding transactions.

We now return a commandId and a paymentId in the following responses:

• CIT authorization response
• MIT authorization response
• settle
• partial settle
• refund
• partial refund

The paymentId is a unique identifier for a payment that ties together payment lifecycle events.
The commandId is a unique identifier for a single instance of an interaction with our API. This will support new future business type flows.

In your authorization request, you can now include:

• a 3rd party Transaction Risk Analysis (TRA) tool exemption
• a 3DS authenticationOutage exemption (if returned by 3DS), to increase the chance of an authorized outcome (no liability shift is granted)

Both require additional configuration and permission, please contact your Implementation Manager.

You can now use the "card/networkToken+googlepay" paymentInstrument in your authorization request to process decrypted Google Pay payments.

You can now send additional fund transfer type and purpose values in the fundsTransfer object in your authorization request. This allow you to be compliant with card scheme requirements for fund transfers.

You can now submit an incremental authorization for an estimated initial authorization.

You can now also cancel an authorization partially using a new next action link received in your authorization response.

You can now submit additional L2/L3 and airline data in your authorization or settlement request. Supplying this information means you may benefit from reduced cost and more efficient processing.

You can now submit preferredCardBrand in your authorization request to honor your customer's card brand choice for co-badged cards.

You can now submit the following additional values for customerAgreement.type in your MIT request:

• reauthorization - use this where the original authorization has expired before funds could be sent for settlement
• resubmission - use this where the original authorization was declined due to insufficient funds, but the customer has already received goods or services
• noShow - use this to charge a customer who fails to attend a previously-made reservation (in line with a pre-agreed cancellation policy) e.g. a guaranteed reservation is made at a restaurant but the customer does not turn up
• delayedCharge - use this to charge a customer for additional items after you have processed an original CIT payment (in line with previously agreed terms), e.g. charges for hotel mini-bar usage after the customer has checked-out and the original payment has been sent for settlement

You can now request real-time account updates (Visa cards only) when using a previously stored card using instruction.requestAccountUpdater. If the supplied card has been updated, we will return updated card details in the updatedPaymentInstrument object in the authorization response.

You can now submit the fundingType and salesTax field in payment requests for Latin America.

We have now added support for Merchant Initiated Transactions (MIT) to Card Payments Version 7.

You can now submit funds transfers (otherwise known as Account Funding Transactions or AFTs) using the instruction.fundsTransfer object in your authorization request. Non-purchase money movements from a Visa or Mastercard to another account should typically use this.

You can now submit Latin America installment payments using the instruction.customerAgreement object in your authorization request. This allows your customers to opt to pay the full value in installments.

You can now submit the customer.documentReference in your authorization request. This is used in some Latin America regions to verify the identity of the cardholder using a tax or document reference. It is strongly recommended to include this for Brazil domestic processing.

You can now submit the recipient object in your authorization request. If you are using MCC 6012 in Europe, you should include data about the recipient of financial services within this object.

You can now submit a consumerBillPayment flag in your authorization request. If you are registered with Visa as a Consumer of the Bill Payment Service (CBPS), you must set this to true for any payments associated with the CBPS.

We now provide additional values in the authentication and 3DS verification responses when the card brand is Cartes Bancaires. These additional values must then be applied in the authorization request.

Raw code in refused responses (28 November 2023)

Payment instrument returned for cards and tokens (06 November 2023)

Card network token support for authorization and migrate card on file authorization endpoint (v6) (06 November 2023)

Apple Pay decrypted support for authorization endpoint (v6) (06 November 2023)

New intent for card on file endpoints (06 July 2023)

New action link in partial refund response (11 May 2023)

New Mastercard test values (20 April 2023)

New payment facilitator fields (14 March 2023)

Payment facilitator field state validation change (14 March 2023)

MOTO payments (v6) (29 November 2022)

riskProfile in card on file (with verification) payment requests (v6) (04 July 2022)

Card network token for card on file sale endpoint (v6) (09 November 2021)

Optional scheme reference parameter for token requests (v6) (10 September 2021)

Additional exemption result for card on file payments (v6) (18 June 2021)

Additional exemption result for one off payments(v6) (25 May 2021)

Additional risk factor result (v6) (09 April 2021)

Cardholder name is now an optional field (v6) (09 March 2021)

riskProfile in payment requests (v6) (21 January 2021)

Apple Pay decrypted for recurring (v6) (27 November 2020)

Apple Pay decrypted for card on file (v6) (17 November 2020)

Additional element for mobile wallet requests (v6) (06 October 2020)

Additional element for mobile wallet responses (v6) (22 September 2020)

New optional request parameter for repeat payments (v6) (28 May 2020)

New action link in partialSettle response (v6) (20 May 2020)

Additional allowed character for transactionReference (v6) (05 May 2020)

New paymentInstrument for card on file payments (v5 + v6) (24 April 2020)

Additional fields in wallet response (v6) (16 April 2020)

Additional action link (v6) (03 March 2020)

New optional field (v6) (11 February 2020)

Additional fields in response (v6) (04 February 2020)

CVC for token requests (v6) 28 January 2020)

New optional field (v6) (16 January 2020)

Additional action links (v6) (21 November 2019)

Extended error description for card expiry (v5) (13 November 2019)

Formatting update for transactionReference (v5) (15 October 2019)