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

 

Testing

 

Use the credentials provided on this page to test your solution.

When you sign up, you will be provided with a “live” account and a “test” account (the latter is prefixed with “test_”).
When testing, ensure requests submitted to Trust Payments reference your test sitereference.

Warning
It is important to thoroughly test your integration using your test sitereference before processing live payments.

Info

Before you begin testing…

Please be aware of the following notes:

 

  • Most fields submitted to our test system will be accepted. Any data breaching its defined specification will return an error message.
  • Any test data that generates a successful response when submitted while a merchant is in test mode, will produce a declined response when a merchant is switched into live mode. In some cases, the test data may return an error response.
  • Our test system attempts to simulate responses in a similar fashion to the live system. However, depending on your acquirer you may find some responses differ slightly from those given by the test system.
  • In the interest of security, we recommend against using real payment details when using your test account.
  • We recommend specifying the main amount “10.50” when testing. Other amounts can be used but may return unexpected responses.
  • For those using Payment Pages, if you’re unsure where to start with your testing, you may find this resource helpful.

 


 

Test card details

The table below lists test card numbers and customer information that can be submitted to our test bank, along with the responses that should be expected in return.

Warning
Do not use these credentials when processing transactions on your live site reference.
Info
While testing, all card types are supported, but when using your live account, you will receive an error if you do not have a valid merchant number for the payment type submitted.

 

 

3-D Secure v2

The following payment credentials can be used for testing 3-D Secure v2 (a form of SCA):

 

Visa-branded cards

Visa
Credit Debit V Pay
Success frictionless 4000000000001026 4006260000000030 4087000000000040
Success step-up 4000000000001091 4006260000000501 4087000000000701
Failed frictionless 4000000000001018 4006260000000303 4087000000000404
Failed step-up 4000000000001109 4006260000000204 4087000000000305

 

Mastercard-branded cards

Test case Mastercard
Credit Debit Maestro
Success frictionless 5200000000001005 5167300000000010 6759000000000067
Success step-up 5200000000001096 5167300000000101 6759000000000083
Failed frictionless 5200000000001013 5167300000000903 6759000000000026
Failed step-up 5200000000001104 5167300000000804 6759000000000018

 

American Express-branded cards

Test case American Express
Success frictionless 340000000001007
Success step-up 340000000001098
Failed frictionless 340000000001015
Failed step-up 340000000001106
Declined 300000000000512

 

3-D Secure v1

The following payment credentials can be used for testing 3-D Secure v1 (a form of SCA):

Visa-branded cards

Visa
Credit Debit V Pay Electron Purchasing
Enrolled (Y) 4111110000000211 4006260000002473 4370000000000111 4245190000000311 4484000000000411
Not enrolled (N) 4111110000000021 4006260000002481 4370000000000921 4245190000000121 4484000000000221
Unknown enrollment (U) 4111110000000401 4006260000002408 4370000000002307 4245190000000501 4484000000000601

Mastercard-branded cards

Test case Mastercard
Credit Debit Maestro (Intl.) Maestro (UK)
Enrolled (Y) 5100000000000511

2221000000000611

5124990000000911 5000000000000611 6759000000000711
Not enrolled (N) 5100000000000321

2221000000000991

5124990000000721 5000000000000421 6759000000000521
Unknown enrollment (U) 5100000000000701

2221000000000801

5124990000000101 5000000000000801 6759000000000901

 

3-D Secure status testing

To test for different 3-D Secure status values, follow the instructions displayed in the authentication prompt shown on the page (an example is shown below). In the textbox provided, you can enter different PIN values to test for different cases.

URL
Displaying the test ACS page

 

For Payment Pages:

With 3-D Secure enabled on your site reference, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions.

 

For JavaScript library implementations:

After your payment form has been updated to reference our JavaScript library, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions.

 

For Mobile SDK implementations:

After your Android or iOS app has been updated to utilise our Mobile SDK, process a payment using one of the card numbers listed above and your app will display an authentication prompt with instructions.

 

The authentication prompt will only be displayed for non-frictionless test card details.

Frictionless cards will bypass authentication. In this case, the payment will be processed immediately (without being prompted by the browser for information).

 


 

Follow the instructions displayed within the authentication prompt to complete the payment:

 

 

 

Non 3-D Secure

The following card types are not currently processed using 3-D Secure (a form of SCA):

 

Card type Authorisation Decline Expiry date Security code
DINERS 3000000000000111 3000000000000012 12/2030 123
DISCOVER 6011000000000301 6011000000000202 12/2030 123
JCB 3528000000000411 3528000000000312 12/2030 123

 

After the payment has been processed, the error code and status values stored with the processed AUTH are used to convey the final outcome.

Info
When the status is “N”, indicating the customer failed authentication, the errorcode “60022” will be returned.

 


 

Testing AVS and security code checks

If you haven’t already, please read our AVS and Security code documentation before testing:
Link to Payment Pages docs / Link to API docs

The following tables list test details that can be submitted to obtain different responses from the AVS and Security Code Checks. These details can be used with most major payment types.

Info
Only the billing premise, billing postcode and security code field values dictate the outcome of the AVS and security code checks performed. As such, entering any details into the other address fields will not affect the outcome of these checks.

 

Premise

Billing premise Security response Security response caption
No 789 2 Matched
No 123 4 Not Matched
No 333 1 Not Checked
Leave blank 0 Not Given

 

Postcode / ZIP code

Billing postcode Security response Security response caption
UK US
TE45 6ST 55555 2 Matched
TE12 3ST 12345 4 Not Matched
TE33 3ST 33333 1 Not Checked
Leave blank Leave blank 0 Not Given

 

Security code

Security code AMEX security code Security response Security response
123 1234 2 Matched
214 2144 4 Not Matched
333 3333 1 Not Checked
Leave blank Leave blank 0 Not Given

 

 


 

Testing non-card payment methods

URL
The procedure to follow when testing non-card payment methods will vary. For the most relevant testing information, please refer to the documentation provided for the specific payment method:
Link to Payment Pages docs / Link to Webservices API docs

 


 

Testing recurring payments

Testing for the acquirer advice code

When processing recurring payments, some acquirers may return an acquirer advice code in the response. The acquirer advice code is a numeric value used to indicate if further recurring payments can be processed for the given card.

Code Description Action
0 N/A No action required
1 New account information available (Mastercard only) Query customer for updated payment details
2 Cannot approve at this time Try again later. If you are continuing to have difficulties, please contact your acquiring bank
4 Do not try again Do not process further recurring transactions
8 Payment blocked by card scheme

 

Where to find the acquirer advice code

 

How to test for different acquirer advice codes

You can test that your system responds appropriately to different acquirer advice codes by processing transactions with the following attributes:

Visa
Acquirer advice code returned Card number Base amount
0 4111111111111111 1050
2 4000000000000671 1002
4 4000000000000671 1004
8 4000000000000671 1008

 

PAYMENT MASTERCARD
Acquirer advice code ‘1’ can only be returned for recurring Mastercard transactions.
Mastercard
Acquirer advice code returned Card number Base amount
0 5100000000000511 1050
1 5100000000000271 1001
2 5100000000000271 1002
4 5100000000000271 1004
8 5100000000000271 1008

 


 

Testing Protect Plus

If you haven’t already, please read our Protect Plus document before testing:
Link to Payment Pages docs / Link to JavaScript Library docs / Link to iOS SDK docs

Use the following baseamount values in RISKDEC requests to simulate the different possible responses from the Protect Plus checks:

baseamount Possible fraudcontrolresponsecode returned fraudcontrolshieldstatuscode returned
1011, 2011, 3011 0100, 0150 “ACCEPT”
1033, 2033, 3033 0300, 0330, 0500 “CHALLENGE”
1044, 2044, 3044 0250, 0400, 0600, 0700, 0800, 1300 “DENY”

 

Info
The fraudcontrolshieldstatuscode and fraudcontrolresponsecode values returned in RISKDEC responses may vary when not using the baseamount values listed in the table, above.

 


 

Testing DCC

If you haven’t already, please read our DCC document before testing:
Link to Payment Pages docs / Link to JavaScript Library docs

The card numbers listed in this test section are associated with specific local currencies. During your integration, you can use the following international test card details in order to test your system for successful and declined DCC transactions.

Successful authorisations

Country code Currency code Visa Credit Mastercard Credit
DE EUR 4500000000000007 5500000000000004
GB GBP 4300000000002211 5311110000001511
JP JPY 4900400000000005 5590410000000006
US USD 4900460000000009 5590470000000018

Declined authorisations

Country code Currency code Visa Credit Mastercard Credit
DE EUR 4500000000002482 5500000000002422
GB GBP 4300000000002492 5311110000002402
JP JPY 4900400000002472 5590410000002432
US USD 4900460000002492 5590470000002402

 

Info
You can also use an amount of 70000 in the final currency to generate a decline response.

 

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