Contents

Split shipments

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.

Info
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”)

 

Status good
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.
Padlock
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.

You must only process split shipments with Mastercard and Visa branded cards.

 

Process overview

1
Submit AUTH request

Submit an AUTH request, including authmethod and splitfinalnumber fields.

2
Submit TRANSACTIONUPDATE

Submit a TRANSACTIONUPDATE request to lower the settlebaseamount of the initial AUTH request. This new amount will be the cost of the first item(s) dispatched.

3
Submit split shipment

Following Settlement of the first AUTH, submit subsequent requests to perform split shipments each time new items are dispatched.

 

Requirements

PAYMENT MASTERCARD
For MAESTRO, MASTERCARD & MASTERCARDDEBIT

  • A transaction must be settled for a partial amount within 7 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 7 days of being processed AND within 30 days of the initial authorisation.

PAYMENT Visa
For DELTA, ELECTRON, PURCHASING, VISA & VPAY

  • A transaction must be settled for a partial amount within 7 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 7 days.
  • All split shipments, once initiated, must be settled within 7 days of the initial authorisation.

 

Walkthrough

Field specification
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 initial AUTH Request.

 

The following is an example of split shipments in action:

Your system processes an AUTH request for £100, 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 to allow an amount of £50 of the initial AUTH request to be settled. Once the initial AUTH has been updated and settled, this leaves £50 reserved on the customer’s bank account that has not been settled.

 

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

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

Info
If there are remaining funds that have not been settled within the timeframe outlined in section, these funds will be released back to the customer’s bank account.

 

 

splitfinalnumber full specification

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 submitted in the initial AUTH Request.

This field is subject to requirements on its use:

 


 

1. Submit AUTH request

 

Requirements

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

 

Request

The following request example submits a pre-authorisation, including the number of splits expected within the splitfinalnumber field. Other than this, it follows the same structure as a standard AUTH request.


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "10000",
  "orderreference": "My_Order_123",
  "authmethod": "PRE",
  "splitfinalnumber": "4",
  "cachetoken": "token_posted_by_st.js"
}

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' => '[email protected]',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '10000',
  'orderreference' => 'My_Order_123',
  'authmethod' => 'PRE',
  'splitfinalnumber' => '4',
  'cachetoken' => 'token_posted_by_st.js'
);

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "baseamount": "10000",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "authmethod": "PRE",
  "splitfinalnumber": "4",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

Response

This follows the same specification as a standard AUTH response, except the splitfinalnumber submitted in the request is also returned. In addition to the below, please read our best practices page and follow the recommendations there.

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20 The source of the transaction.

For split shipments, this can only ever be submitted as “ECOM” or “MOTO“.

authmethod Alpha 5 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)
splitfinalnumber Numeric 2 Total number of splits permitted. (including the initial AUTH request)

Must be 2 or higher.

 


 

2. Submit TRANSACTIONUPDATE

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


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
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' => '[email protected]',
  '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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlebaseamount":"5000"}
}]}'

 

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.

Info
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.

 

Requirements

Before you can process a split payment request, the initial AUTH must have been successfully authorised and settled for a partial amount (as explained above).

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

 

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 = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

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

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' => '[email protected]',
  'password' => 'Password1^',
);

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

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]le.com",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "baseamount": "2000",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "authmethod": "SPLIT",
  "parenttransactionreference": "1-2-345678",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

Response

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

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20 Must match the value submitted in the initial AUTH request (either “ECOM” or “MOTO“).
authmethod Alpha 5 For the split shipment, this must be set to “SPLIT”.
baseamount 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 Numeric 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 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.

 

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:

Info
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. If a single authorisation was divided into 4 parts (1 Parent Auth + 3 split requests), you can perform up to 4 refunds.

Each split is identified using their unique transactionreference.

Info
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 for each split you would like to be refunded (you can only refund one split per request).

 

Additional notes