How to - Trigger Custom Disbursements for real-time transaction

For approved businesses, the “Disbursements” parameters of our real-time transaction APIs POST Make a live card transaction, POST Make a live tokenised card transaction and via Hosted Payment Page Tokens can be used to specify custom disbursements/fees on a transaction-by-transaction basis.

Custom disbursements for real-time transactions can be applicable to PREAUTH and COMPLETE transactions and is applicable to both card and wallet (ApplePay/GooglePay) payments via the 3 payment APIs:

Sample code has been provided below to support this implementation.

Make a live tokenised card transaction

ProcessType - Complete

JSON

{
    "ProcessType": "COMPLETE",
    "Reference": "REAL-TIME-DISBURSEMENTTEST-123",
    "Description": "This is an example real-time transaction",
    "Amount": 100.00,
    "CurrencyCode": "AUD",
    "CardToken": "daa013c96c354a01bdbdd54e0cb3a792",
      "Disbursements":[
          {
              "BusinessId":1003,
              "Type": "MISC_FEE",
              "Amount":2.25
          },
      ]
    },
    "ServiceDate": "2022-03-01T10:00:00+10:00",
    "Payer": {
    	"familyOrBusinessName":"Surname",
    	"givenName":"First Name",
    	"email":"test@test.com",

    },
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
  }

ProcessType - PreAuth

If you are pre-authorising a transaction, a follow up step to capture the payment must be submitted to take payment.

Request

JSON

{
    "ProcessType": "PREAUTH",
    "Reference": "PREAUTH-REAL-TIME-DISBURSEMENTTEST",
    "Description": "This is an example PREAUTH real-time transaction",
    "Amount": 10.00,
    "CurrencyCode": "AUD",
    "CardToken": "0932cd68d36446a4af528aa8b14d7d59",
      "Disbursements":[
          {
              "BusinessId":1003,
              "Type": "MISC_FEE",
              "Amount":2.25
          },
      ]
    },
    "Payer": {
    	"familyOrBusinessName":"Surname",
    	"givenName":"First Name",
    	"email":"test@test.com",

    },
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
  }

Response

JSON

{
    "transactionId": "RT1436988",
    "reference": "PREAUTH-REAL-TIME-DISBURSEMENTTEST",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": null,
    "processedAmount": 10.0,
    "cardType": "Visa",
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null,
    "bankGatewayIDCreditCardDebits": 99
}

Request -

POST {{url}}/businesses/{{business-id}}/transactions/card-payments/RT1436970/captures

JSON

{
    "Reference": "CAPTURE-PREAUTH-TXN-RT1436970",
    "Description": "This is a capture example",
    "Audit": {
        "Username": "Example-User",
         "UserIP": "1.2.3.4"
    }
}

Response

JSON

{
    "transactionId": "OPM247019",
    "reference": "CAPTURE-PREAUTH-TXN-RT1436970",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": "Successful",
    "processedAmount": 10.00,
    "cardType": null,
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null,
    "bankGatewayIDCreditCardDebits": 0
}

Hosted Payment Page - HPP

ProcessType - Complete

JSON

{
    "ReturnUrl": "https://www.worldpayforplatforms.com.au?txn=123456789",
    "Template": "Basic",
    "Transaction": {
      "ProcessType": "COMPLETE",
      "Reference": "HPP Disbursement Test2022",
      "Description": "Test HPP Disbursement API Token",
      "Amount": 10.00,
      "Disbursements":[
          {
              "BusinessId":1003,
              "Type": "MISC_FEE",
              "Amount":2.25
          },
      ]
    },
    "Payer": {
      "FamilyOrBusinessName": "Surname",
      "GivenName": "First Name",
      "Email": "customerintegration@worldpayforplatforms.com.au",
      "SavePayer": false
    },
    "Audit": {
      "Username": "Token Example",
      "UserIP": "1.2.3.4"
    }
  }

ProcessType - PreAuth

If you are pre-authorising a transaction, a follow up step to capture the payment must be submitted to take payment.

Request

JSON

{
    "ReturnUrl": "https://www.worldpayforplatforms.com.au?txn=123456789",
    "Template": "Basic",
    "Transaction": {
      "ProcessType": "COMPLETE",
      "Reference": "HPP Disbursement Test2022",
      "Description": "Test HPP Disbursement API Token",
      "Amount": 10.00,
      "Disbursements":[
          {
              "BusinessId":1003,
              "Type": "MISC_FEE",
              "Amount":2.25
          },
      ]
    },
    "Payer": {
      "FamilyOrBusinessName": "Surname",
      "GivenName": "First Name",
      "Email": "customerintegration@worldpayforplatforms.com.au",
      "SavePayer": false
    },
    "Audit": {
      "Username": "Token Example",
      "UserIP": "1.2.3.4"
    }
  }

Response to re-direct customer to make payment via HPP

JSON

{
    "token": "dc7a0a99-9718-4253-9aa2-258b178edec3",
    "redirectToUrl": "https://sandbox.hosted.paymentsapi.io/ui/hpp/api/dc7a0a99-9718-4253-9aa2-258b178edec3"
}

When payment is complete, customer will be redirected to the ReturnURL you supplied in the request. This is the trigger for your platform to call the API - GET TokenLookup

Request

{{url}}/businesses/{{business-id}}/services/tokens/{{token}}

Response

JSON

{
    "token": "dc7a0a99-9718-4253-9aa2-258b178edec3",
    "type": "HPP",
    "time": "2026-10-08T23:14:00+00:00",
    "status": "PROCESSED_SUCCESSFUL",
    "statusDescription": "PROCESSED_SUCCESSFUL",
    "returnUrl": "https://www.worldpayforplatforms.com.au?txn=123456789",
    "redirectToUrl": "https://sandbox.hosted.paymentsapi.io/ui/hpp/api/dc7a0a99-9718-4253-9aa2-258b178edec3",
    "template": "68126866-ba79-42d5-bda2-cc57d5632f05",
    "templateName": "Basic",
    "transaction": {
        "business": {
            "businessId": "90129",
            "businessName": "AUS - Worldpay for Platforms TEST - JDemo"
        },
        "time": "2026-10-08T23:17:55.53+00:00",
        "transactionId": null,
        "secondaryTransactionId": "RT1437012",
        "reference": "HPREAUTHPP Disbursement Test2022-23423451",
        "description": "Test HPP Disbursement API Token",
        "scheduleReference": null,
        "amount": 50.00,
        "amountRequested": 50.00,
        "amountRefunded": 0.00,
        "currency": "AUD",
        "type": "RT",
        "typeDescription": "Realtime Payment - Website",
        "statusCode": "PRE",
        "subStatusCode": "UR",
        "statusDescription": "Pre-Auth Waiting Capture",

As it was successful, you will be able to capture the pre-authorisation until you reverse/cancel or the pre-authorisation automatically drops.

Capture Request -

POST {{url}}/businesses/{{business-id}}/transactions/card-payments/RT1437012/captures

JSON

{
    "Reference": "CAPTURE-PREAUTH-HPP-RT1437012",
    "Description": "This is a capture example",
    "Audit": {
        "Username": "Example-User",
         "UserIP": "1.2.3.4"
    }
}

Response

JSON

{
    "transactionId": "OPM247020",
    "reference": "CAPTURE-PREAUTH-HPP-RT1437012",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": "Successful",
    "processedAmount": 50.00,
    "cardType": null,
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null,
    "bankGatewayIDCreditCardDebits": 0
}

Data Table

Field	Required	Value Type	Description
BusinessID	Yes	Integer (5)	We will provide you with a list of the IDs of the businesses associated with your account to which you are able to distribute funds.
Amount	Yes	Decimal (10,2)	The amount to be paid out. The total amount of all disbursements must not exceed the transaction amount.
ID	No	String (100)*	You have the option of including an ID from your system to identify each disbursement. Please note: We do not currently provide any reporting on this ID.
Description	No	String (100)*	You have the option of suppling a custom description for the fee/disbursement that can replace the standard type name displayed on reports such as the processing report and tax invoices that are sent to clients.
Type	No	String (100)*	The type of fee/disbursement that the payout is for. This type is displayed on reports such as the processing reports and tax invoices that are sent to clients. At present only the types below are supported. You must pass in one of the following Enums: •TXN_FEE •MISC_FEE If you don’t pass a type ID then MISC_FEE “Miscellaneous Fee” is used.
Method	No	String (100)*	Relevant only if the disbursement is for a fee, this specifies how the fees to collected from the business. The following values are supported: •“SETTLEMENT” – The fee will be collected by reducing the amount of the transaction that is settled to the client