Opayo migration v3.0 to v4.0


The existing SagePay v3 integration has been updated to support the new Opayo v4 integration. This is in order to be compliant with the new 3d secure v2 requirements. As a consequence of these industry changes, Opayo have mandated that developers move away from the v3.00 protocol, even if the changes did not affect the transactions they process.


  • MOTO (Mail Order Telephone Order) are not subject to 3d secure processing that eCommerce transactions are.
  • Stored cards using Opayo/SagePay tokens will now provide additional information, primarily the TokenSwap functionality. TokenSwap means that Instead of storing encrypted card details, card details are swapped for a re-usable token. The token is then available to be used on subsequent payments.


Once you have applied the Khaos Control update including the changes, you do not need to change the integration you are using, but you do need to review some settings for each of your credit card integrations. For any existing SagePay/Opayo integrations you will need to review your Credit Card Integration settings:

  1. Open [ System Operations | Edit Credit Card Integration Settings ].
  2. For each Opayo integration which exists you will need to review its usage and Account Type:
    • If you are processing payments using Opayo/SagePay from a website and your back-office system, you will need to ensure you have selected the appropriate Account type for the account being used for the back office and for the web. These should be configured separately even if they feed into the same merchant account within Opayo / SagePay.
    • In order to be exempt from the 3D secure processing which is not applicable to MOTO transactions, tick the account type of MOTO on the [ Options ] sub-tab in the card settings dialog.
      Credit Card setup dialog
    • If you import transactions from your website, you may need a separate setup for this. Please discuss this with your web developer as they may need to include a separate <ACCOUNT_NUMBER> value in the data they send to Khaos Control.
    • The most common outcome will be that your primary CT Account Setting [0] will be for your MOTO transactions and a secondary setup will be required (if you do not already have one) for your web transactions. Most customers already have two setups configured in Khaos Control for this reason.
    • If you have any questions surrounding your set up, please email Support.


For each Opayo integration which is using TokenSwap, the MITType should reviewed, otherwise the default "Unscheduled" will be used. The currently supported options are 'Unscheduled' and 'Reauthorisation'. To change the MITTYPE:

  1. Open [ System Operations | Edit Credit Card Integration Settings ].
  2. Select the Account from the drop down at the top.
  3. In the bottom right of the Options tab is the Opayo MIIType.
  4. Select the option you require.
  5. Continue editing or click OK to close the dialog.


  • This is only applicable if you are using TokenSwap, as Khaos Control must provide additional information for re-used card information as part of the "Card On File" scheme, mandated by the Credit Card authorities.
  • MITYPE is the terminology used by Opayo in their documentation Opayo Migration v3.0 to v4.0 Guide.


Sales Order

First time using a new card:

  1. Create the sales order as normal.
  2. Move to the [ Sales Order | Payment ] tab.
  3. Tick the Card checkbox in the Payment grid if it is not ticked.
  4. Click on the new credit card button in the Payment by Credit Card area.
  5. In the Confirm popup click yes to create a new credit card.
  6. Enter the credit card number.
  7. Tab to the Expiry field.
  8. Enter the Expiry date from the credit card.
  9. Tab to the Sig Digit field and enter the sig digit, the three-digit CV2 number.
  10. Press Ctrl+S or click the disk icon is the button bar's SAVE button to save.
  11. A popup appears to confirm that a token has been successfully created:
    Credit card token created
  12. Ctrl+ Shift+O or right click and select Authorise Credit Card, to authorise the payment.
    Note: you can also pre-authorise the card at this point and then authorise it in [ Sales Invoice Manager | Authorise Payment ], see How To: Release a deferred payment.

This card can now be used for subsequent payments upon each authorisation.

Customer Statement Screen

For first-time use of New Card from Customer Statement Screen:

  1. Open a Customer screen (show me how).
  2. Open the [ Customer/Supplier | Detail | Statement ] tab.
  3. Right-click on the 'Allocate From (Credit Notes, Payments)' grid, found in the top-right section of the statement tab.
  4. Select 'New Payment' from the right-click context menu.
    1. Select Card Payment Type.
    2. Enter Payment Amount.
    3. Click on the Credit card button button.
    4. Click on the Create New Card button.
    5. Enter the card details:
      1. Card Number.
      2. Expiry Date.
      3. CSC number.
    6. Click OK, a popup appears to confirm that a token has been successfully created:
      Credit card token created

This card can now be used for subsequent payments upon each authorisation.

See Also

Did you find this article helpful?