Skip to main content
Skip table of contents

CIT/MIT Compliance - SOAP to REST API Conversion Developer Guide

This page explains how you can become compliant with the Stored Credential Framework from your existing SOAP integration.

CIT/MIT Compliance for Australia and NZ Partners

The Stored Credential Frameworks by Visa, introduces a number of policies and procedures relating to the processing of stored customer credit/debit card information that were previously not required, in an attempt to reduce fraud and improve customer experience and trust. Both merchants and payment facilitators are obligated to adhere to this framework as a way to enforce responsible usage of cardholder data. The same requirements apply for all card types, such as Visa, Mastercard and AMEX.

This framework has already been rolled out globally, and will eventually become mandatory for all merchants and payment facilitators. Further information on the framework can be found in this document from Visa: Visa Stored Credential Framework

Framework Summary

One of the key points of this framework is the differentiation of these two ways that a transaction on a stored card can be triggered:

  • Customer Initiated Transaction (CIT) - this is a payment on a stored card that has been actively triggered by your customer themselves (i.e. it involves the active participation of the cardholder).

  • Merchant Initiated Transaction (MIT) - this is a payment on a stored card that you as the business have initiated yourself as part of collecting money based upon a pre-agreed contract between your business and the cardholder as part of whatever product or service you are providing them.

 In practice, the framework requires doing the following:

  • Specifying whether you are processing a CIT or MIT.

  • Specifying the type of authorization you are performing.

  • Linking all subsequent payments on a stored card using an authorization reference.

Compliance Requirements

There are two critical parts to ensuring compliance with the Stored Credentials Framework:

1. Data Element Configuration

Ensuring all the relevant Data Elements relating to tagging a transaction as a Customer initiated transaction or a Merchant initiated transaction should be properly set.

The first step is to audit all your transaction flows and correctly tag each as a Customer Initiated or Merchant Initiated Transaction. If the first transaction isn't tagged correctly, all the associated recurring transactions will create a chain of non-compliant transactions.

A simpler way to think about it: If a customer is actively participating in the transaction in real-time, that's a Customer Initiated Transaction. Even when using a saved card, if the customer is actively making the purchase, it's still considered a CIT.

2. Specific Data Elements Required for Visa and Mastercard

For Initial Transactions (Both Visa and Mastercard):

  1. Credential On File (COF) Indicator: Must be marked as "First" or Initial transaction.

  2. Cardholder Authentication: For the first transaction, Strong Customer Authentication is typically required.

  3. Consent Verification: Indication that customer consent has been obtained.

For Subsequent Transactions:

  1. COF Indicator: Should be marked as "Subsequent" transaction.

  2. Transaction Identifier:

    1. For Visa: Network Transaction ID (NTI)

    2. For Mastercard: Mastercard Trace ID

  3. Transaction Type: Specify the type (recurring, installment, unscheduled)

We have built out CIT/MIT compliance on our side for REST API, eDDR and HPP which will require a small technical uplift required to become CIT/MIT compliant as you will need to convert a API requests from SOAP to REST. To assist you with this uplift and make the transition as smooth and simple as possible, we have a dedicated guide for the minimum changes required.

Steps to convert from SOAP to REST

In order to assist in the transition to convert from SOAP to REST, we can provide a test account in the sandbox environment to allow you to implement your current SOAP integration and develop the REST API integration as necessary.

A key point here is that with REST API, your application will need to be able to store another set of API credentials, specifically for REST. The REST API credentials will be idempotent and unique to each and every merchant, same as the current SOAP API.

From there you will need to identify whether you use any of the above SOAP functions and convert them to REST . Further below, we have a guide to assist you with the API flow required when implementing REST. There is sample JSON and direct hyperlinks to the associated endpoint in the REST API documentation. The REST API is documented in Postman with the ability for you to import the collection which allows you to test the code and API flow outlined prior to writing any new code.

Impacted SOAP API functions

We have highlighted the specific SOAP API function that require converting to REST API to allow CIT/MIT compatibility and be compliant with the framework. Further below will display sample code for the conversion.

  • PayerSavePaymentMethod

  • CreditCardTransaction

    • Also including the superseded functions:

      • ImmediateCreditCardTransaction

      • ImmediateCreditCardTransactionFullPayerInfo

      • ImmediateCreditCardTransactionFullReg

  • StoredCreditCardTransaction

    • Also including the superseded functions:

      • ChargeStoredCard

  • Hosted Payment Service

    • PreHostedRealTimePayment / PostHostedRealTimePayment

    • Javascript / Page Redirect / Transparent Redirect

  • Hosted Vault Service

    • PreAddToVault / PostAddtoVault

    • Javascript / Page Redirect / Transparent Redirect

  • Hosted eDDR Service

    • Pre-eDDR / Post eDDR

Function - PayerSavePaymentMethod

This function allows you to modify the payment method details of an existing payer.

Sample payload:

XML 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <tem:PayerSavePaymentMethod>         
         <tem:username>?</tem:username>         
         <tem:password>?</tem:password>         
         <tem:payerUniqueID>?</tem:payerUniqueID>         
         <tem:paymentMethod>?</tem:paymentMethod>         
         <tem:bankAccountBsb>?</tem:bankAccountBsb>         
         <tem:bankAccountNumber>?</tem:bankAccountNumber>         
         <tem:bankAccountName>?</tem:bankAccountName>         
         <tem:bankAccountType>?</tem:bankAccountType>         
         <tem:creditCardNumber>?</tem:creditCardNumber>         
         <tem:creditCardExpiryDate>?</tem:creditCardExpiryDate>         
         <tem:creditCardName>?</tem:creditCardName>         
         <tem:auditUsername>?</tem:auditUsername>
      </tem:PayerSavePaymentMethod>
   </soapenv:Body>
</soapenv:Envelope>

If you are using the PayerSavePaymentMethod function, your software will need to convert to the following REST API function flow:

For card details:

  1. POST Login

  2. POST Add a new Payer - this step can be skipped as the following API request can Add a new payer in the same request.

  3. POST Make a live tokenized card transaction

    1. At this stage your application can perform a Zero-Dollar Authentication ($0.00) against the end users card and store the card in our secure vault by specifying the ‘processtype’ in the payload as ‘VERIFY’ and ‘savepayer’ set to ‘true’.

    2. Alternatively, should you wish to take an actual $ value payment, you can do so by specifying the ‘processtype’ in the payload as ‘COMPLETE’ and ‘savepayer’ set to ‘true’.

For bank account details:

  1. POST Login

  2. POST Add a new Payer

  3. PUT Add or update a Payers bank account details

Sample API flow for card details:

  1. POST Login

    1. Request

      1. CODE 
        {{url-auth}}/login
      2. JSON 
        {
  "Username": "{{Api-Username}}",
  "Password": "{{Api-UserKey}}"
}

    2. Response

      1. JSON 
        {
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM4NkM3N.....gs6yufdyfdiukgjfdsDD"
    "expires_in": 3600,
    "token_type": "Bearer"
}

  2. POST Add a new Payer

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/payers
      2. JSON 
         '{
     "UniqueReference": "P1-UNIQUE-REF",
      "GroupReference": "P1-UNIQUE-REF",
      "FamilyOrBusinessName": "Citizen",
      "GivenName": "Jane",
      "Email": "support@example.com",
      "Phone": "0733332222",
      "Mobile": "0411228833",
      "Address": {
        "Line1": "1 Test St",
        "Line2": "Test Bulding",
        "Suburb": "Testville",
        "State": "QLD",
        "PostCode": "4001",
        "Country": null
    },
    "ExtraInfo": {
      "XeroAutoDebitEnabled": false,
      "SalesforceAutoDebitEnabled":false
    },
    "Audit": {
      "Username": "Example-User",
      "UserIP": "1.2.3.4"
    }
  }'

    2. Response

      1. JSON 
        {
  "payerId": "135032",
  "uniqueReference": "P1-UNIQUE-REF"
}

  3. POST Make a live tokenised card transaction

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/transactions/card-payments/token
      2. JSON 
        {
    "ProcessType": "VERIFY",
    "Reference": "ZeroDollarAuth-TXN-100",
    "Description": "This is an example real-time Zero Dollar Authentication",
    "Amount": 0.00,
    "CardToken": "cbd86c35289249eb86759453cea4025b",
    "CardAuthorizationType": "UNSCHEDULED",
    "ServiceDate": "2025-03-01T10:00:00+10:00",
    "CallBackUrl": "https://platforms.worldpay.com/en/",
    "Payer": {
    	"uniqueReference": "P1-UNIQUE-REF",
    	"groupReference":"P1-UNIQUE-REF",
    	"familyOrBusinessName":"Surname",
    	"givenName":"First Name",
    	"email":"test@test.com",
    	"phone":"0733331111",
    	"savePayer":"true"
    },
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
  }

    2. Response

      1. JSON 
        {
  "transactionId": "RT549168",
  "reference": "ZeroDollarAuth-TXN-100",
  "statusCode": "S",
  "subStatusCode": null,
  "statusDescription": null,
  "processedAmount": 0.00,
  "cardType": "Visa"
}

Function - CreditCardTransaction

This function supersedes the legacy functions, ImmediateCreditCardTransaction / ImmediateCreditCardTransactionFullPayerInfo/ ImmediateCreditCardTransactionFullReg and submits a credit card payment to the bank and returns a result in real- time.

Sample payload:

XML 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <tem:CreditCardTransaction>         
         <tem:username>?</tem:username>         
         <tem:password>?</tem:password>         
         <tem:processType>?</tem:processType>         
         <tem:payerUniqueID>?</tem:payerUniqueID>         
         <tem:transactionID>?</tem:transactionID>         
         <tem:transactionDescription>?</tem:transactionDescription>         
         <tem:creditCardNumber>?</tem:creditCardNumber>         
         <tem:creditCardExpiryDate>?</tem:creditCardExpiryDate>         
         <tem:creditCardCcv>?</tem:creditCardCcv>         
         <tem:creditCardName>?</tem:creditCardName>         
         <tem:transactionAmountInCents>?</tem:transactionAmountInCents>         
         <tem:currency>?</tem:currency>         
         <tem:transactionSource>?</tem:transactionSource>         
         <tem:validationLevel>?</tem:validationLevel>         
         <tem:payerFirstName>?</tem:payerFirstName>         
         <tem:payerLastName>?</tem:payerLastName>         
         <tem:payerAddressStreet>?</tem:payerAddressStreet>         
         <tem:payerAddressSuburb>?</tem:payerAddressSuburb>         
         <tem:payerAddressState>?</tem:payerAddressState>         
         <tem:payerAddressPostCode>?</tem:payerAddressPostCode>         
         <tem:payerAddressCountry>?</tem:payerAddressCountry>         
         <tem:payerEmail>?</tem:payerEmail>         
         <tem:payerPhone>?</tem:payerPhone>         
         <tem:payerMobile>?</tem:payerMobile>         
         <tem:extraFields>?</tem:extraFields>         
         <tem:auditUsername>?</tem:auditUsername>         
         <tem:auditUserIP>?</tem:auditUserIP>
      </tem:CreditCardTransaction>
   </soapenv:Body>
</soapenv:Envelope>

If you are using the CreditcardTransaction function or superseded ImmediateCreditCardTransaction / ImmediateCreditCardTransactionFullPayerInfo/ ImmediateCreditCardTransactionFullReg functions, your software will need to convert to the following REST API function flow:

  1. POST Login

  2. POST Make a live tokenized card transaction

Sample API flow:

  1. POST Login

    1. Request

      1. CODE 
        {{url-auth}}/login
      2. JSON 
        {
  "Username": "{{Api-Username}}",
  "Password": "{{Api-UserKey}}"
}

    2. Response

      1. JSON 
        {
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM4NkM3N.....gs6yufdyfdiukgjfdsDD"
    "expires_in": 3600,
    "token_type": "Bearer"
}

  2. POST Make a live tokenised card transaction

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/transactions/card-payments/token
      2. JSON 
        {
    "ProcessType": "COMPLETE",
    "Reference": "REAL-TXN-100",
    "Description": "This is an example real-time transaction",
    "Amount": 10.00,
    "CardToken": "cbd86c35289249eb86759453cea4025b",
    "CardAuthorizationType": "UNSCHEDULED",
    "ServiceDate": "2025-03-01T10:00:00+10:00",
    "CallBackUrl": "https://platforms.worldpay.com/en/",
    "Payer": {
    	"uniqueReference": "P1-UNIQUE-REF",
    	"groupReference":"P1-UNIQUE-REF",
    	"familyOrBusinessName":"Surname",
    	"givenName":"First Name",
    	"email":"test@test.com",
    	"phone":"0733331111",
    	"savePayer":"true"
    },
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
  }

    2. Response

      1. JSON 
        {
  "transactionId": "59581",
  "reference": "REAL-TXN-100",
  "statusCode": "S",
  "subStatusCode": null,
  "statusDescription": "Successful",
  "processedAmount": 10.00
}

Function - StoredCreditCardTransaction

This function processes a real-time credit card transaction on a credit card we have stored in our database for a payer you have previously added.

Sample payload:

XML 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <tem:StoredCreditCardTransaction>         
         <tem:username>?</tem:username>         
         <tem:password>?</tem:password>         
         <tem:processType>?</tem:processType>         
         <tem:payerUniqueID>?</tem:payerUniqueID>         
         <tem:transactionID>?</tem:transactionID>         
         <tem:transactionDescription>?</tem:transactionDescription>         
         <tem:transactionAmountInCents>?</tem:transactionAmountInCents>         
         <tem:currency>?</tem:currency>         
         <tem:transactionSource>?</tem:transactionSource>         
         <tem:validationLevel>?</tem:validationLevel>         
         <tem:extraFields>?</tem:extraFields>         
         <tem:applyToSchedule>?</tem:applyToSchedule>         
         <tem:auditUsername>?</tem:auditUsername>         
         <tem:auditUserIP>?</tem:auditUserIP>
      </tem:StoredCreditCardTransaction>
   </soapenv:Body>
</soapenv:Envelope>

If you are using the StoredCreditCardTransaction function, your software will need to convert to the following REST API function flow:

  1. POST Login

  2. POST Process a transaction using saved card details

Sample API flow:

  1. POST Login

    1. Request

      1. CODE 
        {{url-auth}}/login
      2. JSON 
        {
  "Username": "{{Api-Username}}",
  "Password": "{{Api-UserKey}}"
}

    2. Response

      1. JSON 
        {
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM4NkM3N.....gs6yufdyfdiukgjfdsDD"
    "expires_in": 3600,
    "token_type": "Bearer"
}

  2. POST Process a transaction using saved card details

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/payers/{{payer-reference}}/transactions/card
      2. JSON 
        {
    "ProcessType": "COMPLETE",
    "Reference": "Transaction-001",
    "Amount": 10.75,
    "Description": "This is a test transaction",
    "CardStorageType": "CIT_PAYFAC_STORED",
    "ServiceDate": "2025-03-01T10:00:00+10:00",
    "Audit": {
      "Username": "Example-User",
      "UserIP": "1.2.3.4"
    }
}

    2. Response

      1. JSON 
        {
  "transactionId": "71403",
  "reference": "Transaction-001",
  "statusCode": "S",
  "subStatusCode": null,
  "statusDescription": null,
  "processedAmount": 10.75
}

Function - Hosted Payment Services

Our platform offered 3 interfaces for integrating the Hosted Payment Services to your application or website. This includes Javascript, Page Redirect and Transparent Redirect. Should your software currently utilise any of the 3 interfaces, this will need to be converted to implement the REST API flow.

Sample payload:

XML 
<?xml version="1.0" encoding="utf-8"?> <request>
<username>?</username>
<password>?</password>
<command>PreHostedRealTimePayment</command>
<returnUrl>https://platforms.worldpay.com/en/</returnUrl> 
<transactionID>soapAPITxnHPPTest</transactionID>
<transactionamountincents>1000</transactionamountincents>
<auditUsername>SYS-101</auditUsername>
</request>

If you are using the Hosted Payment Services function, your software will need to convert to the following REST API function flow:

  1. POST Login

  2. POST Generate HPP Token

    1. The response provides a returnURL. This is the URL your application will need to direct the end-user to submit payment.

    2. After the end-user is directed to the Hosted Payment Page and complete the page by submitting payment details they will be directed back to the returnURL your application intially supplied in the payload. Once the end-user is bounced to the returnURL this indicates the payment page was completed and your application can call the next API to retrieve the result of the transaction.

  3. GET Token Lookup

Sample API flow:

  1. POST Login

    1. Request

      1. CODE 
        {{url-auth}}/login
      2. JSON 
        {
  "Username": "{{Api-Username}}",
  "Password": "{{Api-UserKey}}"
}

    2. Response

      1. JSON 
        {
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM4NkM3N.....gs6yufdyfdiukgjfdsDD"
    "expires_in": 3600,
    "token_type": "Bearer"
}

  2. POST Generate HPP Token

    1. Request

      1. CODE 
        {url}}/businesses/{{business-id}}/services/tokens/{{token}}
      2. JSON 
        {
    "ReturnUrl": "https://platforms.worldpay.com/en/",
    "Template": "Basic",
    "CardAuthorizationType": "RECURRING",
    "Transaction": {
      "ProcessType": "COMPLETE",
      "Reference": "HPP-TOKEN-001",
      "Description": "Test HPP API Token",
      "Amount": 23.00
    },
    "Payer": {
      "SavePayer": true,
      "UniqueReference": "HPP-TOKEN-PAYER-U-1",
      "GroupReference": "HPP-TOKEN-PAYER-GRP-1",
      "FamilyOrBusinessName": "Surname",
      "GivenName": "First Name",
      "Email": "support@example.com",
      "Phone": "0733332222",
      "Mobile": "0411228833",
      "Address": {
        "Line1": "1 Test St",
        "Line2": null,
        "Suburb": "Testville",
        "State": "QLD",
        "PostCode": "4001",
        "Country": null
      }
    },
    "Audit": {
      "Username": "Token Example",
      "UserIP": "1.2.3.4"
    }
  }

    2. Response

      1. JSON 
        {
  "token": "28e24e60-0fb8-44e2-918e-e38e038e52f3",
  "redirectToUrl": "https://sandbox.paymentsapi.io/ui/hpp/api/28e24e60-0fb8-44e2-918e-e38e038e52f3"
}

  3. GET Token Lookup

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/services/tokens/{{token}}

    2. Response

      1. JSON 
        {
  "token": "28e24e60-0fb8-44e2-918e-e38e038e52f3",
  "type": "HPP",
  "time": "2019-03-03T18:02:00+10:00",
  "status": "PROCESSED_SUCCESSFUL",
  "statusDescription": null,
  "returnUrl": "https://platforms.worldpay.com/en/",
  "redirectToUrl": "https://sandbox.paymentsapi.io/ui/hpp/api/28e24e60-0fb8-44e2-918e-e38e038e52f3",
  "template": "479B33AD-EE41-4F30-A7B5-0A900A765D4E",
  "templateName": "Basic",
  "transaction": {
    "business": {
      "businessId": "1391",
      "businessName": "Test Business Pty Ltd"
    },
    "time": "2019-03-03T18:01:37.307+10:00",
    "transactionId": "132426",
    "secondaryTransactionId": "RT80437",
    "reference": "HPP-TOKEN-001",
    "description": "Test HPP API Token",
    "scheduleReference": null,
    "amount": 23,
    "amountRequested": 23,
    "amountRefunded": 0,
    "currency": "AUD",
    "type": "RT",
    "typeDescription": "Realtime Payment - Website",
    "statusCode": "C",
    "subStatusCode": null,
    "statusDescription": "Cleared",
    "paymentMethod": "MASTERCARD",
    "payer": {
      "payerId": "140448",
      "uniqueReference": "HPP-TOKEN-PAYER-U-1",
      "groupReference": "HPP-TOKEN-PAYER-GRP-1",
      "familyOrBusinessName": "Surname",
      "givenName": "First Name",
      "address": null,
      "email": null,
      "phone": null,
      "mobile": null
    },
    "card": {
      "cardNumber": "555555xxxxxx4444",
      "cardholderName": "HPP CC",
      "cardExpires": "2027-11-01T00:00:00",
      "cardType": "Mastercard"
    },
    "bankAccount": null
  },
  "payer": {
    "business": {
      "businessId": "1391",
      "businessName": "Test Business Pty Ltd"
    },
    "payerId": "140448",
    "status": "ACTIVE",
    "statusCode": "A",
    "statusDescription": "Active",
    "statusChangeDate": null,
    "createdTime": "2019-03-03T18:01:37.223+10:00",
    "schedule": null,
    "uniqueReference": "HPP-TOKEN-PAYER-U-1",
    "groupReference": "HPP-TOKEN-PAYER-GRP-1",
    "familyOrBusinessName": "Surname",
    "givenName": "First Name",
    "email": "support@example.com",
    "phone": "0411228833",
    "mobile": "0411228833",
    "address": {
      "line1": "1 Test St",
      "line2": "",
      "suburb": "Testville",
      "state": "QLD",
      "postCode": "4883",
      "country": "AUS"
    },
    "extraInfo": {
      "xeroAutoDebitEnabled": false
    }
  },
  "schedule": null,
  "requestHpp": {
    "returnUrl": "https://platforms.worldpay.com/en/",
    "template": "TEST-84d463",
    "transaction": {
      "processType": "COMPLETE",
      "reference": "HPP-TOKEN-001",
      "description": "Test HPP API Token",
      "amount": 23,
      "currencyCode": "AUD"
    },
    "payer": {
      "savePayer": true,
      "uniqueReference": "HPP-TOKEN-PAYER-U-1",
      "groupReference": "HPP-TOKEN-PAYER-GRP-1",
      "familyOrBusinessName": "Surname",
      "givenName": "First name",
      "email": "support@example.com",
      "phone": "0733332222",
      "mobile": "0411228833",
      "address": {
        "line1": "1 Test St",
        "line2": null,
        "suburb": "Testville",
        "state": "QLD",
        "postCode": "4883",
        "country": null
      }
    },
    "audit": {
      "username": "HppTokenTests",
      "userIP": "1.2.3.4"
    }
  },
  "events": [
    {
      "event": "WAITING",
      "time": "2019-03-03T18:02:00+10:00",
      "description": null,
      "username": "API:  [HppTokenTests]",
      "ip": ""
    },
    {
      "event": "VALIDATED",
      "time": "2019-03-03T18:02:00+10:00",
      "description": null,
      "username": null,
      "ip": ""
    },
    {
      "event": "PROCESSED_SUCCESSFUL",
      "time": "2019-03-03T18:02:00+10:00",
      "description": null,
      "username": null,
      "ip": ""
    }
  ]
}

Function - Hosted Vault Service

Our platform offered 3 interfaces for integrating the Hosted Vault Service similar to Hosted Payment Service. This includes Javascript, Page Redirect and Transparent Redirect. This function is specifically to allow you to add or update card details to the associated payer record. Should your software currently utilise any of the 3 interfaces, this will need to be converted to implement the REST API flow.

Sample payload:

XML 
<?xml version="1.0" encoding="utf-8"?> <request>
<username>?</username>
<password>?</password>
<command>PreAddToVault</command>
<returnUrl>https://platforms.worldpay.com/en/</returnUrl> 
<payerUniqueID>soapAPIVaultPayerTest</payerUniqueID>
<auditUsername>SYS-101</auditUsername>
</request>

If you are using the Hosted Vault Service function, your software will need to convert to the following REST API function flow:

  1. POST Login

  2. POST Generate Vault Token

    1. The response provides a returnURL. This is the URL your application will need to direct the end-user to submit payment.

    2. After the end-user is directed to the Hosted Vault Page and complete the page by submitting payment details they will be directed back to the returnURL your application intially supplied in the payload. Once the end-user is bounced to the returnURL this indicates the payment page was completed and your application can call the next API to retrieve the result.

  3. GET Token Lookup

Sample API flow:

  1. POST Login

    1. Request

      1. CODE 
        {{url-auth}}/login
      2. JSON 
        {
  "Username": "{{Api-Username}}",
  "Password": "{{Api-UserKey}}"
}

    2. Response

      1. JSON 
        {
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM4NkM3N.....gs6yufdyfdiukgjfdsDD"
    "expires_in": 3600,
    "token_type": "Bearer"
}

  2. POST Generate Vault Token

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/services/tokens/vault/
      2. JSON 
        {
    "ReturnUrl": "https://platforms.worldpay.com/en/",
    "CardAuthorizationType": "RECURRING",
    "Payer": {
     "UniqueReference": "P1-UNIQUE-REF",
      "GroupReference": "P1-UNIQUE-REF",
      "FamilyOrBusinessName": "Citizen",
      "GivenName": "Jane",
      "Email": "support@example.com",
      "Phone": "0733332222",
      "Mobile": "0411228833",
      "Address": {
        "Line1": "1 Test St",
        "Line2": "Test Bulding",
        "Suburb": "Testville",
        "State": "QLD",
        "PostCode": "4001",
        "Country": null,
		"AddIfNotExists": false
      }
    },
     "Audit": {
      "Username": "VaultTokenTests",
      "UserIP": "444.888.000"
    }
  }

    2. Response

      1. JSON 
        {
  "token": "ef954e09-8802-4204-bada-3a72860e512c",
  "redirectToUrl": "https://sandbox.paymentsapi.io/ui/eddr/api/28e43e60-0fb8-78e2-912e-e38e038e52f3"
}

  3. GET Token Lookup

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/services/tokens/{{token}}

    2. Response

      1. JSON 
        {
    "token": "ef954e09-8802-4204-bada-3a72860e512c",
    "type": "VAULT",
    "time": "2026-02-18T03:53:00+00:00",
    "status": "PROCESSED_SUCCESSFUL",
    "statusDescription": "PROCESSED_SUCCESSFUL",
    "returnUrl": "https://platforms.worldpay.com/en/",
    "redirectToUrl": "https://sandbox.hosted.paymentsapi.io/ui/vault/api/ef954e09-8802-4204-bada-3a72860e512c",
    "template": null,
    "templateName": null,
    "transaction": null,
    "payer": {
        "business": {
        "businessId": "1391",
        "businessName": "Test Business Pty Ltd"
        },
        "payerId": "427599",
        "status": "ACTIVE",
        "statusCode": "A",
        "statusDescription": "Active",
        "statusChangeDate": null,
        "createdTime": "2022-07-18T01:42:46.06+00:00",
        "schedule": null,
        "uniqueReference": "P1-UNIQUE-REF",
        "groupReference": "P1-UNIQUE-REF",
        "familyOrBusinessName": "Citizen",
        "givenName": "Jane",
        "email": "support@example.com",
        "phone": "0733332222",
        "mobile": "0411228833",
        "address": {
            "line1": "1 Test St",
            "line2": "",
            "suburb": "Testville",
            "state": "QLD",
            "postCode": "4001",
            "country": "AUS"
        },
        "dateOfBirth": null,
        "extraInfo": {
            "xeroAutoDebitEnabled": true,
            "salesforceAutoDebitEnabled": true
        }
    },
    "schedule": null,
    "requestVault": {
        "returnUrl": "https://platforms.worldpay.com/en/",
        "payer": {
            "uniqueReference": "P1-UNIQUE-REF",
            "addIfNotExists": false,
            "groupReference": "P1-UNIQUE-REF",
            "familyOrBusinessName": "Citizen",
            "givenName": "Jane",
            "email": "support@example.com",
            "phone": "0733332222",
            "mobile": "0411228833",
            "address": {
                "line1": "1 Test St",
                "line2": "Test Bulding",
                "suburb": "Testville",
                "state": "QLD",
                "postCode": "4001",
                "country": null
            },
            "dateOfBirth": null,
            "extraInfo": null
        },
        "audit": {
            "username": "VaultTokenTests",
            "userIP": "444.888.000"
        }
    },
    "events": [
        {
            "event": "WAITING",
            "time": "2026-02-18T03:53:00+00:00",
            "description": null,
            "username": "API:  [VaultTokenTests]",
            "ip": ""
        },
        {
            "event": "VALIDATED",
            "time": "2026-02-18T03:53:00+00:00",
            "description": null,
            "username": null,
            "ip": ""
        },
        {
            "event": "PROCESSED_SUCCESSFUL",
            "time": "2026-02-18T03:53:00+00:00",
            "description": null,
            "username": null,
            "ip": ""
        }
    ]
}

Function - eDDR Service

This API function allows you to integrate your software with our hosted online Direct Debit Request forms (eDDR - electronic Direct Debit Request).

Sample payload:

XML 
<?xml version="1.0" encoding="utf-8"?> <request>
<username>?</username>
<password>?</password>
<command>PreDDR</command>

<returnUrl>https://platforms.worldpay.com/en/</returnUrl>
<payerUniqueID>soapAPIDDRPayerTEST</payerUniqueID>
<payerFirstName>Jane</payerFirstName> 
<payerLastName>Smith</payerLastName> 
<auditUsername>SYS-101</auditUsername>
</request>

If you are using the eDDR Service function, your software will need to convert to the following REST API function flow:

  1. POST Login

  2. POST Generate eDDR Token

    1. The response provides a returnURL. This is the URL your application will need to direct the end-user to submit payment.

    2. After the end-user is directed to the Hosted eDDR Page and complete the page by submitting payment details they will be directed back to the returnURL your application intially supplied in the payload. Once the end-user is bounced to the returnURL this indicates the payment page was completed and your application can call the next API to retrieve the result.

  3. GET Token Lookup

Sample API flow:

  1. POST Login

    1. Request

      1. CODE 
        {{url-auth}}/login
      2. JSON 
        {
  "Username": "{{Api-Username}}",
  "Password": "{{Api-UserKey}}"
}

    2. Response

      1. JSON 
        {
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM4NkM3N.....gs6yufdyfdiukgjfdsDD"
    "expires_in": 3600,
    "token_type": "Bearer"
}

  2. POST Generate eDDR Token

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/services/tokens/eddr/
      2. JSON 
        {
    "ReturnUrl": "https://platforms.worldpay.com/en/",
    "Template": "Basic-eDDR",
    "CardAuthorizationType": "RECURRING",
    "Payer": {
      "UniqueReference": "EDDR-TOKEN-PAYER-U-1",
      "GroupReference": "EDDR-TOKEN-PAYER-GRP-1",
      "FamilyOrBusinessName": "Surname",
      "GivenName": "FirstName",
      "Email": "support@example.com",
      "Phone": "0733332222",
      "Mobile": "0411228833",
      "Address": {
        "Line1": "1 Test St",
        "Line2": null,
        "Suburb": "Testville",
        "State": "QLD",
        "PostCode": "4001",
        "Country": null
      },
      "OverrideExisting": false
    },
    "Schedule": null,
    "Audit": {
      "Username": "EddrTokenTests",
      "UserIP": "444.888.000"
    }
  }

    2. Response

      1. JSON 
        {
    "token": "5b9ab3d4-5647-4e2b-9586-e3deeb4d2e71",
    "redirectToUrl": "https://sandbox.hosted.paymentsapi.io/ui/eddr/api/5b9ab3d4-5647-4e2b-9586-e3deeb4d2e71"
}

  3. GET Token Lookup

    1. Request

      1. CODE 
        {{url}}/businesses/{{business-id}}/services/tokens/{{token}}

    2. Response

      1. JSON 
        {
    "token": "5b9ab3d4-5647-4e2b-9586-e3deeb4d2e71",
    "type": "EDDR",
    "time": "2026-02-18T04:08:00+00:00",
    "status": "PROCESSED_SUCCESSFUL",
    "statusDescription": "PROCESSED_SUCCESSFUL",
    "returnUrl": "https://platforms.worldpay.com/en/",
    "redirectToUrl": "https://sandbox.hosted.paymentsapi.io/ui/eddr/api/5b9ab3d4-5647-4e2b-9586-e3deeb4d2e71",
    "template": "794c6bc8-e7c7-427c-bab6-a15d053ca532",
    "templateName": "Basic-eDDR",
    "transaction": null,
    "payer": {
        "business": {
            "businessId": "90129",
            "businessName": "AUS - Worldpay for Platforms TEST -- Joseph"
        },
        "payerId": "638200",
        "status": "ACTIVE",
        "statusCode": "A",
        "statusDescription": "Active",
        "statusChangeDate": null,
        "createdTime": "2026-02-18T04:07:47.553+00:00",
        "schedule": null,
        "uniqueReference": "EDDR-TOKEN-PAYER-U-1",
        "groupReference": "EDDR-TOKEN-PAYER-GRP-1",
        "familyOrBusinessName": "Surname",
        "givenName": "FirstName",
        "email": "supoprt@example.com",
        "phone": "0733332222",
        "mobile": "0411228833",
        "address": {
            "line1": "1 Test St",
            "line2": "",
            "suburb": "Testville",
            "state": "QLD",
            "postCode": "4001",
            "country": "AUS"
        },
        "dateOfBirth": null,
        "extraInfo": {
            "xeroAutoDebitEnabled": false,
            "salesforceAutoDebitEnabled": false
        }
    },
    "schedule": null,
    "requestEddr": {
        "returnUrl": "https://platforms.worldpay.com/en/",
        "template": "Basic-eDDR",
        "payer": {
            "uniqueReference": "EDDR-TOKEN-PAYER-U-1",
            "familyOrBusinessName": "Surname",
            "overrideExisting": false,
            "retainSchedule": null,
            "groupReference": "EDDR-TOKEN-PAYER-GRP-1",
            "givenName": "FirstName",
            "email": "supoprt@example.com",
            "phone": "0733332222",
            "mobile": "0411228833",
            "address": {
                "line1": "1 Test St",
                "line2": null,
                "suburb": "Testville",
                "state": "QLD",
                "postCode": "4001",
                "country": null
            },
            "dateOfBirth": null,
            "extraInfo": null
        },
        "schedule": null,
        "cardAuthorizationType": "RECURRING",
        "audit": {
            "username": "EddrTokenTests",
            "userIP": "444.888.000"
        }
    },
    "events": [
        {
            "event": "WAITING",
            "time": "2026-02-18T04:08:00+00:00",
            "description": null,
            "username": "API:  [EddrTokenTests]",
            "ip": ""
        },
        {
            "event": "VALIDATED",
            "time": "2026-02-18T04:08:00+00:00",
            "description": null,
            "username": null,
            "ip": ""
        },
        {
            "event": "PROCESSED_SUCCESSFUL",
            "time": "2026-02-18T04:08:00+00:00",
            "description": null,
            "username": null,
            "ip": ""
        }
    ]
}

Should you wish and have the development appetite to fully convert your existing integration from SOAP to REST, there is a table below which maps the SOAP Functions to the equivalent REST Function as REST offers you advanced documentation, support and functionality.

SOAP

REST

PayerSave

POST Add a new Payer

PayerSavePaymentMethod

PUT Add or update a Payers bank account details
POST Make a live tokenized card transaction
DELETE Remove a Payers payment methods

PayerChangeStatus

PUT Change a Payers status

PayerSearch / PayerSearchXml

GET Look up a specific Payers details
GET Search for multiple Payers
GET Look up a Payers payment options

ScheduleSinglePayment

POST Schedule a single payment

ScheduleTransactionWithAutoCreatePayer

Not Available

ScheduleGenerate

POST Schedule multiple future payments

ScheduleGenerate

DELETE Delete All Payments

ScheduleRemoveSinglePayment

DELETE Delete Single Payment

ScheduleChangeAmounts

PATCH Change Payment Amounts

ScheduleSearch / ScheduleSearchXml

GET Look up a scheduled payment
GET Find a Payers scheduled payments
GET Search all scheduled payments

GETNewStatusUpdates / GetNewStatusUpdatesXml

GET Search for transaction status changes

GETNewStatusUpdatesByStatus / GetNewStatusUpdatesByStatusXml

GET Search for transaction status changes

SetNewStatusUpdateAsReceived

POST Acknowledge transaction status change

TransactionStatus

GET Transaction Lookup
GET Search live card transactions
GET Look up single live card transaction

TransactionSearch / TransactionSearchXml

GET Transaction Search

CreditCardTransaction

Superseded - ImmediateCreditCardTransaction

Superseded - ImmediateCreditCardTransactionFullPayerInfo

Superseded - ImmediateCreditCardTransactionFullReg

POST Make a live tokenized card transaction

CreditCardTransactionUpdate

POST Process a pre authorised card transaction

StoredCreditCardTransaction

Superseded - ChargeStoredCard

POST Process a transaction using saved card details

CheckService

GET Check your business details

RefundTransaction

POST Refund a live card transaction

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close