Contents

Split shipments (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.

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.

 


 

Types of split shipments

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

  1. 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.
  2. 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

 

 

PAYMENT MASTERCARD
For MAESTRO, MASTERCARD & MASTERCARDDEBIT

  • A transaction (with authmethodPRE“) 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.

 

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

  • A transaction (with authmethodPRE“) 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

1
Submit AUTH request

When the customer clicks “Pay” on your checkout, the JavaScript Library submits an AUTH request to Trust Payments.

You must ensure the JWT includes the authmethod and splitfinalnumber fields (more info below).

2
Submit TRANSACTIONUPDATE

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.

3
Submit split shipment

Submit subsequent requests to perform split shipments each time new items are dispatched.

 


 

 

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 JWT used when processing the initial AUTH request.

 

The following is an example of split shipments in action:

The JavaScript Library 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 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:

 

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 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 requirements on its use:

 


 

1. Submit AUTH request

 

Requirements

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

 

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","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.
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.

 

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 = "[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 = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/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"}
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-3"}]},"updates":{"settlebaseamount":"5000"}}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
  <alias>[email protected]</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.

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 using our Webservices API.

 

Requirements

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"],
  "baseamount": "2000",
  "orderreference": "My_Order_123",
  "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' => '[email protected]',
  'password' => 'Password1^',
);

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

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

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "baseamount": "2000",
  "orderreference": "My_Order_123",
  "authmethod": "SPLIT",
  "parenttransactionreference": "1-2-345678"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["AUTH"],"sitereference":"test_site12345","baseamount":"2000","orderreference":"My_Order_123","authmethod":"SPLIT","parenttransactionreference":"1-2-345678"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount>2000</amount>
    </billing>
    <operation>             
      <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)
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:

 

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:

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

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 using our Webservices API for each split you would like to be refunded.

 


 

Additional notes

 

Best practices

 

This section assumes you have already read our Getting started documentation and understand how to submit a basic request to us. If you haven’t already, we recommend reading this before you continue.

 

When receiving our response, your system will need to perform the following checks on the values returned (where applicable) to ensure the request was processed successfully.

 

Error code

The errorcode is a fundamentally important field as it displays the outcome of the submitted request. It is returned in every response from Trust Payments.

Status good

If the errorcode is “0”, this indicates the request was processed successfully.

 

It is imperative that you have a process in place to check the final status of the processed request, by looking at the values of the other fields returned. 

Status attention

If the errorcode is “30000”, this indicates a field error.

If you look at the errordata field returned, this typically contains the name of the field that was deemed invalid. You will need to retry the request, ensuring all required fields have been submitted, and that all submitted field values follow our specification.

Status attention

If the errorcode is “70000”, this indicates a payment was declined by your bank.

We recommend that you show an error message to the customer and allow them to try a different method of payment.

Status bad

If the errorcode is “60010”, “60034” or “99999”, there has been a problem processing the request and the final status is not known.

 

This can be due to a communication problem with a bank or third party. In such cases, we recommend informing the customer of the problem and to contact you to query the issue. You will need to contact our Support team, providing a copy of the entire request submitted and response returned, and we will contact the relevant parties to establish the status of the request. In the interest of security, ensure you omit or mask sensitive field values, such as card details.

If the errorcode is not listed above, please refer to our full list of errorcodes for assistance. If you need further help, please contact our Support team.

 

Settle status

It is important to check the value of the settlestatus when processing an AUTH or REFUND request, as this indicates if Settlement will be performed. Here are the basics:

Status good

If the settlestatus is “0”, “1” or “10”, you do not need to take any further actions.

The transaction is currently scheduled to settle.

Status good

If the settlestatus is “100”, the transaction has been settled.

You cannot perform any further updates to the transaction.

Status attention

If the settlestatus is “2”, the transaction has been suspended.

Funds will not be settled without your intervention. Please refer to our settlement documentation for further information.

Status bad

If the settlestatus is “3”, the transaction has been cancelled.

Funds will not be settled and you will need to investigate the problem and try again. In this scenario, it is useful to look at the accompanying errorcode as this will often inform you of the reason behind the transaction failing.

If you haven’t already, we recommend you read our settlement documentation for further detail on how settlement is performed.

 

Security response

If the AVS and Security Code Checks are performed as part of the request (as is the case for most AUTH and ACCOUNTCHECKs), you will need to check the three security response fields returned, which are defined as follows:

Status good

If the value is “2”, the customer entered the correct details.

If all values are “2”, there is no reason here to prevent the transaction from settling.

Status attention

If the value is “1”, the bank was unable to check the customer’s details.

This may be because the customer has a card issued by a foreign country, and your bank was therefore unable to check their address. You may need to consider suspending transactions that fall into this category to allow you to investigate before proceeding with the payment.

Status attention

If the value is “0”, the customer’s details were not sent to the bank.

This is because the customer didn’t enter any of the details at all, or that these details were not submitted in your request. You may need to consider suspending transactions that fall into this category to allow you to investigate before proceeding with the payment.

Status bad

If the value is “4”, the customer entered incorrect details.

By default, we will suspend transactions where the security code entered by the customer fails to match the value on their card. Depending on your preferences, you may also prefer to suspend transactions where the address details do not match (disabled by default).

You can request that Trust Payments automatically cancels transactions when the security response fields have a certain value. As mentioned above, we suspend all transactions where the security code entered by the customer fails to match the value on their card. You can specify the circumstances under which transactions are suspended to match your own preferences (you can even disable such checks entirely). This is achieved by modifying your Security Policy. To discuss changes to your account’s security policy, please contact our Support team.

 

Request type description

Each response will contain a requesttypedescription. The value of this field returned in the response should always match the value submitted in the request.

e.g. If you are sending an “AUTH” request, ensure the requesttypedescription returned is “AUTH”.

If you receive requesttypedescription with value “ERROR”, the request may not have been processed successfully and you will need to investigate.

 

Live status

Check the live status value returned is “0” while testing and “1” when processing live payments.

 

Amount & currency

When submitting an amount and currency, check that the same values are returned in the response.

 

Response site security

If you are processing transactions using our Payment Pages interface, and have configured URL notifications or redirects to be triggered upon transaction completion, you will need to re-calculate the site security hash using the fields returned and check it matches the corresponding hash returned from Trust Payments. This is to ensure the content returned hasn’t been modified by an unauthorised party. Click here to learn more.

 

Going live

After you have finished configuring your site and have tested thoroughly, follow the final steps below to begin processing live payments.

 

Warning

Before you continue…

 

Most acquiring banks mandate that 3-D Secure is performed prior to AUTH requests.
If 3-D Secure is not implemented, you could be liable for fines from the card schemes.
Ensure you have contacted your acquiring bank and have configured 3-D Secure, if required.

 

You must ensure your servers are PCI compliant before processing live payments.
For further information, we recommend contacting your acquiring bank.

 

It is crucial that you have read and understood the practices outlined in our best practices and testing documents.
You will need to ensure your system can submit requests using your test sitereference (starts with “test_”) and handle both successful and failure responses before processing live payments.

 

Rules for live site reference

When you are ready to switch your account live, you will need to consider any Rules that may have been configured on your test Site Reference, as these will need to be re-configured on your live site reference to ensure they update your system as expected. Click here for our Rule documentation.

 

Styling for Payment Pages

If you are processing payments using our Payment Pages interface and have applied custom styling to your test site reference using HTML, CSS and/or JavaScript, these changes will also need to be applied to your live site reference.

 

Get in touch

Once you have tested your system and you are ready to go live, please send an email to [email protected] with your live site reference and request to go live. You will receive a response when your live site reference is ready to begin processing payments.

 

Make changes to your requests

Your requests will need to be updated to use your live site reference. This is achieved by modifying the sitereference field submitted to Trust Payments. When your live site reference is submitted in a request, it will be processed as a live request.

Warning
If you have developed your solution using our JavaScript Library, you will need to ensure you update your payment form to submit the field “livestatus”, with value 1.

 

Click here to view an example of a form configured in this way

 


<html>
<head>
</head>
<body>
  <div id="st-notification-frame"></div>
  <form id="st-form" action="https://www.example.com" method="POST">
    <div id="st-card-number" class="st-card-number"></div>
    <div id="st-expiration-date" class="st-expiration-date"></div>
    <div id="st-security-code" class="st-security-code"></div>
    <button type="submit" id="st-form__submit" class="st-form__submit">
      Pay securely
    </button>
  </form>
 <script src=<DOMAIN>/js/v2/st.js></script>
 <script> 
  (function() {
   var st = SecureTrading({  
    jwt: 'INSERT YOUR JWT HERE',
    livestatus: 1
    });  
   st.Components(); 
  })(); 
 </script>
</body>
</html>

Warning
If you have developed your solution using our Mobile SDK, you will need to ensure your instance is configured in the production environment, rather than staging.

 

Click here to view an example of this configuration

 


TrustPayments.instance.configure(username: username_from_trustpayments,
                                 gateway: .eu,
                                 environment: .production,
                                 translationsForOverride: nil
)

 

Live testing

Once you have switched to your live site reference, we recommend that you test this by performing a transaction using a live card, to ensure it is processed successfully. You can sign in to MyST to manage your transactions. Therefore you can cancel transactions processed on live cards.

Warning
You should not use the same live card too many times, as the requests may still be authorised, and could cause the issuer to suspect fraud or the cardholder could exceed their limit.

 

Thumbs up
You’re all set!

Remember to sign in to MyST and to check your transactions regularly to ensure payments are being processed successfully.
If you need assistance, please contact our Support team.

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116