Split shipments using our API

Split shipments provide you with greater control over when reserved funds are settled. Instead of performing a single settlement within 7 days, as is the case with a standard authorisation, with split shipments you can perform multiple partial settlements.

Before proceeding, you may find it useful to re-familiarise yourself with our standard settlement process. Click here for further information.

Split shipments are designed for scenarios where a customer has placed a single order for multiple items, which may be dispatched at different times. This allows you to ensure the customer has the required funds by reserving the full amount of the order and then settling the funds required for each item as they are dispatched.

(We refer to an individual split shipment as a “split”)

Benefits

Split shipments help you avoid the potential inconveniences associated with performing multiple transactions for a single order. For instance:

Insufficient funds for the later payments.
Failed Fraud checks (if enabled) on later payments.
Card expires before last payment.
Card declines before last payment.

3-D Secure

An additional benefit for merchants is that all split shipments are covered by the liability shift from the initial authorisation when it has been authenticated by 3-D Secure.

Contact your acquirer for further details before going live with a split shipment solution using 3-D Secure.

Types of split shipments

There are two methods of processing split shipments that we support:

Regular – Your system submits a request to lower the settle amount of the initial request, waits for the funds to be settled (usually takes less than 24 hours from authorisation) and only then can you start processing split shipments.
Same-day – Your system submits a request to lower the settle amount of the initial request, and then you can start processing split shipments as soon as you’re ready (even prior to settlement).

Requirements

Split shipments are only supported with Mastercard and Visa branded cards.
Please contact our Support Team to check if your acquiring bank supports split shipments, and whether or not they support same-day split shipments.

For MAESTRO, MASTERCARD & MASTERCARDDEBIT

A transaction (with authmethod “PRE“) must be settled for a partial amount within 30 days of authorisation.
e.g. £50 authorised, £10 settled (£40 still reserved).
Split shipments can be processed to settle the remaining reserved funds over a period of 30 days.
All split shipments, once initiated, must be settled within 30 days of the initial authorisation.

For DELTA, ELECTRON, PURCHASING, VISA & VPAY

A transaction (with authmethod “PRE“) must be settled for a partial amount within 31 days of authorisation.
e.g. £50 authorised, £10 settled (£40 still reserved).
Split shipments can be processed to settle the remaining reserved funds over a period of 31 days.
All split shipments, once initiated, must be settled within 31 days of the initial authorisation.

Process overview

Submit AUTH request
When the customer clicks “Pay” on your checkout, an AUTH request is submitted to Trust Payments.
You must ensure the JWT includes the authmethod and splitfinalnumber fields (more info below).
Submit TRANSACTIONUPDATE request
Submit a TRANSACTIONUPDATE request using our Webservices API to lower the settlebaseamount of the initial AUTH request.
The final settle amount of this AUTH will be the cost of the first item(s) dispatched.
Submit split shipment
Submit subsequent requests to perform split shipments each time new items are dispatched.

Walkthrough

The following is an example of split shipments in action.

Before continuing, you will need to have a basic understanding of the splitfinalnumber field.

The splitfinalnumber is used to define how many split shipments are going to be performed for a transaction (this includes the initial AUTH). This is typically the number of items to be dispatched. The splitfinalnumber field is required in the JWT used when processing the initial AUTH request.

The JavaScript Library / Mobile SDK processes an AUTH request for £100, with the JWT including splitfinalnumber = 4.
In practice, this means you can perform 3 splits, in addition to the initial AUTH:
1 Parent Auth + 3 possible split requests = splitfinalnumber of 4

You can perform an update using our Webservices API to allow an amount of £50 from the initial AUTH request to be settled. Once the initial AUTH has been updated, this leaves £50 reserved on the customer’s bank account that has not been settled.

If you are processing regular split shipments, you will need to wait for the initial AUTH request to be settled before proceeding (this typically takes up to 24 hours after the initial AUTH was processed).
If your acquiring bank supports same-day split shipments, you can process split shipment requests as soon as you need to (see below).

If you are not sure which method of split shipments your acquiring bank supports, please contact our Support Team for assistance.

Following the above, there are £50 of funds that can be settled via split shipments submitted through our Webservices API. You process the following split shipment requests:

Process 1st split for £20 (£50 – £20 = £30 remaining to be settled).
Process 2nd split for £10 (£30 – £10 = £20 remaining to be settled).
Process 3rd split for £20 (£20 – £20 = £0 remaining to be settled).

Following the splits described above, it is now not possible to process subsequent splits. This is because:

The maximum number of splits (defined in the splitfinalnumber field) has been reached.
All funds reserved in the authorisation have been settled.

Splits cannot be processed if either of the above conditions are met.

If there are remaining funds that have not been settled within the timeframe outlined in the Requirements section found at the top of this page, these funds will be released back to the customer’s bank account.

splitfinalnumber specification

This field is subject to additional requirements on its use:

In the initial AUTH, the splitfinalnumber must be submitted with a value greater than or equal to ‘2’
- This value defaults to ‘1‘ when not submitted.
- If the value is ‘1’, split shipments cannot be performed.
It is not permitted to submit a greater number of split shipments than allowed in the splitfinalnumber.
We recommend that you process the same number of splits specified in the splitfinalnumber
splitfinalnumber cannot be greater than 20.
You can lower the splitfinalnumber after the initial AUTH Request by submitting a lower splitfinalnumber in a subsequent split request. This number can never be lower than the number of splits already processed nor can it ever be increased.

1. Submit AUTH request

Requirements

The initial request submitted must meet the following requirements/criteria:

The payment must be processed using a Visa or Mastercard-branded card.
The accounttypedescription must either be “ECOM” or “MOTO”.
The authmethod must be “PRE”, to indicate pre-authorisation.
The number of partial settlements must be submitted in a required field called splitfinalnumber.

Update the JWT

You will need to update the payload within the JWT to meet the requirements specified above, in order to allow split shipments to be performed on this payment at a future time.

(Example:)

{
  "payload":{
    "accounttypedescription":"ECOM",
    "authmethod":"PRE",
    "baseamount":"10000",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "splitfinalnumber":"4"
  },
  "iat":1567701632,
  "iss":"jwt.user"
}

{
  "payload":{
    "accounttypedescription":"ECOM",
    "authmethod":"PRE",
    "baseamount":"10000",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "termurl":"https://payments.securetrading.net/process/payments/mobilesdklistener",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "splitfinalnumber":"4"
  },
  "iat":1567701632,
  "iss":"jwt.user"
}

Field specification

Field	Format	Description
accounttypedescription	Alpha (20)	The source of the transaction. For split shipments, this can only ever be submitted as “ECOM” or “MOTO“.
authmethod	Alpha (11)	For the initial AUTH, this must be submitted in the request as “PRE“.
baseamount	Numeric (13)	The full transaction amount (the total of the entire order, including all shipments). Must be in base units, with no commas or decimal points, so £10 would be 1000. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
currencyiso3a	Alpha (3)	The currency that the transaction will be processed in. Click here for a full list of available currencies.
requesttypedescriptions	List	The request types to be processed. To process a 3-D Secure authenticated payment, submit [“THREEDQUERY”,”AUTH”].
sitereference	Alphanumeric & underscore (50)	The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support Team.
splitfinalnumber	Numeric (2)	Total number of splits permitted. (including the initial AUTH request) Must be 2 or higher.
termurl	URL (1024)	Required when processing 3-D Secure authentication with Android/iOS SDK. This URL is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS. You must submit the following URL in this field when performing 3-D Secure: https://payments.securetrading.net/ process/payments/mobilesdklistener

Response

You will need to decode the JWT returned. This will generally have the same structure as a JWT returned following a standard payment, but it will also contain the splitfinalnumber submitted included in the payload.

2. Submit TRANSACTIONUPDATE

You will need to submit a standard TRANSACTIONUPDATE request using our Webservices API, which specifies a lower settlebaseamount, as shown in this example:

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
  },
  "updates":{"settlebaseamount":"5000"}
}

strequest = securetrading.Request()
strequest.update(update)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
  'filter' => array(
    'sitereference' => array(array('value' => 'test_site12345')),
    'transactionreference' => array(array('value' => '1-2-3'))
  ),
  'updates' => array('settlebaseamount' => '5000')
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "requesttypedescriptions": ["TRANSACTIONUPDATE"],
    "filter":{
      "sitereference": [{"value":"test_site12345"}],
      "transactionreference": [{"value":"1-2-3"}]
    },
    "updates":{"settlebaseamount":"5000"}
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["TRANSACTIONUPDATE"],
    "filter":{"sitereference":[{"value":"test_site12345"}],
    "transactionreference":[{"value":"1-2-3"}]},
    "updates":{"settlebaseamount":"5000"}
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>1-2-3</transactionreference>
    </filter>
    <updates>
      <settlement>
        <settlebaseamount>5000</settlebaseamount>
      </settlement>
    </updates>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

The settlebaseamount submitted in this update will be settled first. The remaining funds remain authorised, and can be settled at a later date by submitting split shipment requests, as described below.

3. Submit split shipment

Split shipments are processed by submitting additional AUTH requests using our Webservices API.

When processing a split shipment, we will inherit billing and customer details from the initial authorisation. You can use updated values for the delivery details, by resubmitting these fields in the split shipment AUTH request using our Webservices API.

Requirements

The split payment request must meet the following requirements/criteria:

Must reference a parent “PRE” AUTH.
The requesttypedescription must be “AUTH”.
The authmethod must be “SPLIT”.
The accounttypedescription of the split (e.g. “ECOM”) must match that of the parent authorisation.
The baseamount must be less than or equal to the remaining reserved funds.
If performing a regular split shipment (not same day), the settlestatus of the initial parent must be “100”, indicating that the payment has been settled.

Request

The following request example submits a split. This follows the same structure as a standard AUTH request, except the authmethod field must be submitted with the value “SPLIT”.

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "baseamount": "2000",
  "orderreference": "My_Order_123",
  "accounttypedescription":"ECOM",
  "authmethod": "SPLIT",
  "parenttransactionreference": "1-2-345678"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'baseamount' => '2000',
  'orderreference' => 'My_Order_123',
  'accounttypedescription' => 'ECOM',
  'authmethod' => 'SPLIT',
  'parenttransactionreference' => '1-2-345678'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias":"webservices@example.com",
  "version": "1.00",
  "request": [{
    "sitereference": "test_site12345",
    "requesttypedescriptions": ["AUTH"],
    "baseamount": "2000",
    "orderreference": "My_Order_123",
    "accounttypedescription": "ECOM",
    "authmethod": "SPLIT",
    "parenttransactionreference": "1-2-345678"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "sitereference":"test_site12345",
    "requesttypedescriptions":["AUTH"],
    "baseamount":"2000",
    "orderreference":"My_Order_123",
    "accounttypedescription":"ECOM",
    "authmethod":"SPLIT",
    "parenttransactionreference":"1-2-345678"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount>2000</amount>
    </billing>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription> 
      <authmethod>SPLIT</authmethod>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	Must match the value submitted in the initial AUTH request (either “ECOM” or “MOTO“).
authmethod XPath: /operation/authmethod	Alpha (11)	For the split shipment, this must be set to “SPLIT”.
baseamount XPath: /billing/amount	Numeric (13)	The amount associated with the split shipment request. Must be equal to or lower than the remaining reserved funds. Must be in base units, with no commas or decimal points, so £10 would be 1000. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (25) Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.	Your unique order reference that can be stored on the Trust Payments system.
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	Submit the transactionreference returned in the initial AUTH response. This is required to inherit the payment credentials from this previous request.
requesttypedescriptions XPath: /@type	Alpha (20)	You must submit “AUTH”, as shown in the request example.
sitereference XPath: /operation/sitereference	Alphanumeric & underscore (50)	Identifies your site on the Trust Payments system.
splitfinalnumber XPath: /operation/splitfinalnumber	Numeric (2)	Optional: You can update the split final number value by passing through a new value in the split shipment request. This number can never be lower than the number of splits already processed nor can it ever be increased.

Response

This follows the same specification as a standard AUTH response, except the splitfinalnumber submitted in the request is also returned. Additional notes:

As when handling a standard AUTH response, you will need to perform the checks outlined on this page.
Be aware of two error codes specific to split shipments: “20010” for split amount too great, and “20024” for invalid split transaction.

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	Must match the value submitted in the initial AUTH request (either “ECOM” or “MOTO“).
authmethod XPath: /operation/authmethod	Alpha (11)	For the split shipment, this must be set to “SPLIT”.
baseamount XPath: /billing/amount	Numeric (13)	The amount associated with the split shipment request. Must be equal to or lower than the remaining reserved funds. Must be in base units, with no commas or decimal points, so £10 would be 1000. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
errorcode XPath: /error/code	Numeric (1-5)	The error code should be used to determine if the request was successful or not. Common values: “0” – Successful “20010” – Split amount too great “20024” – Invalid split transaction If you are returned errorcode “20024” in the response, we recommend checking your implementation meets the requirements listed on this page. Specifically, ensure the authmethod and splitfinalnumber fields are being submitted with valid values, and that the baseamount submitted doesn’t exceed the total amount authorised in the initial AUTH request. Click here for a full list of errorcode and message values.
splitfinalnumber XPath: /operation/splitfinalnumber	Numeric (2)	Total number of splits permitted.

Settlement

When your system submits a valid split shipment request, the settle status of the transaction will be ‘0’ (‘Pending settlement’) for up to 24 hours before settling (status ‘100’). During this time, split shipments can be cancelled (or suspended) by updating the settle status of the split shipment:

You can process a TRANSACTIONUPDATE request using our Webservices API to update the settle status of a split to “2” for suspended or “3” for cancelled.
Alternatively, sign in to MyST, search for the unique transactionreference and click “Update”. Then modify the settlestatus of the transaction to “2” or “3”, as required.

Split shipments can be suspended, but must be settled within the timeframe outlined in the Requirements section found at the top of this page.

Refunds

It is possible to perform refunds on any split payment that has been settled. When considering refunds, it is best to think of each split as an independent transaction, because splits are refunded independently to one another.

E.g. To fully refund a single authorisation that has been divided into 4 parts (1 Parent Auth + 3 split requests), you need to perform at least 4 refunds.

Each split is identified using their unique transactionreference.

As with standard payments, you can only refund splits when they have been settled (settle status “100”). If a split has not been settled, you can update the settle status to defer or cancel settlement.

Refunding a single split does not affect the settlement of other splits from the same initial AUTH.

Performing a refund does not prevent future splits from being processed, provided all requirements above have still been met.

Performing refunds in this manner does not make previously-reserved funds available for future splits from the same parent.

If you have reached your maximum number of splits (splitfinalnumber), refunding a split payment will not allow you to perform an additional split request.

Your system will need to submit a standard REFUND request using our Webservices API for each split you would like to be refunded.

Additional notes

Fraud checks cannot be performed on splits.
Duplicate checks are performed on splits (if enabled on your account).
Split shipments do not support DCC.

Further reading on this topic