The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.
Read this article to learn more.
Payouts are used to credit funds to another bank account. Common use cases of this include:
- Allowing customers to withdraw funds from their account with you.
- Paying out an insurance claim to a customer.
Payouts are also known as Credit Fund Transfers (CFT) or Original Credit Transfers (OCT).
Payouts to Visa-branded cards are processed via the Visa Direct protocol.
Click here to learn more.
Gaming Payouts to Mastercard-branded cards are processed via the Mastercard Gaming and Gambling Payments Program.
Click here to learn more.
Non-Gaming Payouts to Mastercard-branded cards are processed via the Mastercard MoneySend Program.
Click here to learn more.
Requirements
You will need to have a CFT Merchant Number associated with your Trust Payments account. If you are unsure if your merchant number supports this, we recommend contacting your bank for clarification. Additionally, please ensure you are following any guidelines outlined by your bank before proceeding.
Payout request
To process a Payout, you will need to submit a Payout request using our Webservices API. Please refer to the below for code examples.
To process a Payout successfully, it is imperative that your request includes the following:
- accounttypedescription=CFT
- requesttypedescriptions=REFUND
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
payout= {
"accounttypedescription": "CFT",
"baseamount": "1050",
"billingcountryiso2a": "GB",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"cftsourceoffunds": "05",
"currencyiso3a": "GBP",
"customeraccountnumber": "12345678",
"customeraccountnumbertype": "ACCOUNT",
"customercountryiso2a": "GB",
"customerfirstname": "Jane",
"customerlastname": "Public",
"customerstreet": "Caernarfon Road",
"customertown": "Bangor",
"expirydate": "12/2030",
"orderreference": "My_Order_123",
"pan": "5124990000000911",
"requesttypedescriptions": ["REFUND"],
"sitereference": "site12346",
"transactiontypeindicator": "C52"
}
strequest = securetrading.Request()
strequest.update(payout)
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(
'accounttypedescription' => 'CFT',
'baseamount' => '1050',
'billingcountryiso2a' => 'GB',
'billingdob' => '1991-05-28',
'billingfirstname' => 'Joe',
'billinglastname' => 'Bloggs',
'cftsourceoffunds' => '05',
'currencyiso3a' => 'GBP',
'customeraccountnumber' => '12345678',
'customeraccountnumbertype' => 'ACCOUNT',
'customercountryiso2a' => 'GB',
'customerfirstname' => 'Jane',
'customerlastname' => 'Public',
'customerstreet' => 'Caernarfon Road',
'customertown' => 'Bangor',
'expirydate' => '12/2030',
'orderreference' => 'My_Order_123',
'pan' => '5124990000000911',
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'site12346',
'transactiontypeindicator' => 'C52'
);
$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": [{
"accounttypedescription": "CFT",
"baseamount": "1050",
"billingcountryiso2a": "GB",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"cftsourceoffunds": "05",
"currencyiso3a": "GBP",
"customeraccountnumber": "12345678",
"customeraccountnumbertype": "ACCOUNT",
"customercountryiso2a": "GB",
"customerfirstname": "Jane",
"customerlastname": "Public",
"customerstreet": "Caernarfon Road",
"customertown": "Bangor",
"expirydate": "12/2030",
"orderreference": "My_Order_123",
"pan": "5124990000000911",
"requesttypedescriptions": ["REFUND"],
"sitereference": "site12346",
"transactiontypeindicator": "C52"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"CFT",
"baseamount":"1050",
"billingcountryiso2a":"GB",
"billingdob":"1991-05-28",
"billingfirstname":"Joe",
"billinglastname":"Bloggs",
"cftsourceoffunds":"05",
"currencyiso3a":"GBP",
"customeraccountnumber":"12345678",
"customeraccountnumbertype":"ACCOUNT",
"customercountryiso2a":"GB",
"customerfirstname":"Jane",
"customerlastname":"Public",
"customerstreet":"Caernarfon Road",
"customertown":"Bangor",
"expirydate":"12/2030",
"orderreference":"My_Order_123",
"pan":"5124990000000911",
"requesttypedescriptions":["REFUND"],
"sitereference":"site12346",
"transactiontypeindicator":"C52"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<billing>
<amount currencycode="GBP">1050</amount>
<country>GB</country>
<dob>1991-05-28</dob>
<name>
<first>Joe</first>
<last>Bloggs</last>
</name>
<payment>
<expirydate>12/2030</expirydate>
<pan>5124990000000911</pan>
</payment>
</billing>
<customer>
<accountnumber type="ACCOUNT">12345678</accountnumber>
<country>GB</country>
<name>
<first>Jane</first>
<last>Public</last>
</name>
<street>Caernarfon Road</street>
<town>Bangor</town>
</customer>
<merchant>
<orderreference>My_Order_123</orderreference>
<transactiontypeindicator>C52</transactiontypeindicator>
</merchant>
<operation>
<accounttypedescription>CFT</accounttypedescription>
<sitereference>site12346</sitereference>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification (submitting card details)
| Field | Format | Description | |
| accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Must be “CFT”. | |
| baseamount XPath: /billing/amount |
Numeric (13) |
The refund amount in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”. |
|
| billingcountryiso2a XPath: /billing/country |
Alpha (2) |
The country for the recipient's billing address. This will need to be in ISO2A format. |
|
| billingdob XPath: /billing/dob |
Date YYYY-MM-DD |
The recipient's date of birth. Conditions apply when processing Payouts where Trust Payments performs PEP or sanction screening on the recipient. Click here for info. |
|
| billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The recipient's billing first name. |
|
| billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The recipient's billing last name. |
|
| currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The currency that the transaction will be processed in. |
|
| expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY |
The card expiry date. |
|
| pan XPath: /billing/payment/pan |
Numeric (12-19) |
The customer's card number. |
|
| requesttypedescriptions XPath: /@type |
Alphanumeric & hyphens (25) |
The request type required is “REFUND”. | |
| sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
A unique reference that identifies your account. You receive this when you first sign up with us. | |
| billingcounty XPath: /billing/county |
Alphanumeric including symbols (127) |
The county for the recipient's billing address. For Canadian addresses, submit the two-character province code, e.g. for British Columbia, submit “BC”. Required for Visa Direct payments processed with cards issued in Canada. Click here for info. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingpostcode XPath: /billing/postcode |
Alphanumeric (25) |
The recipient's billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingstreet XPath: /billing/street |
Alphanumeric including symbols (127) |
The street entered for the recipient's billing address. Required for Visa Direct payments processed with cards issued in Canada. Click here for info. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingtelephone XPath: /billing/telephone |
Alphanumeric including symbols (20) |
The customer’s telephone number. Valid characters:
Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingtown XPath: /billing/town |
Alphanumeric including symbols (127) |
The town entered for the recipient's billing address. Required for Visa Direct payments processed with cards issued in Canada. Click here for info. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| cftsourceoffunds XPath: /merchant/cftsourceoffunds |
Numeric (2) |
The source of funds for the Payout. Submit one of the following:
|
|
| customeraccountnumber XPath: /customer/accountnumber |
Numeric (20) |
If account number type is “ACCOUNT”, the account number of the sender. If account number type is “CARD”, the card number of the sender. The returned value in the response is in a masked format, e.g. “411111#######1111”. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customeraccountnumbertype XPath: /customer/accountnumber/@type |
Alpha (7) |
Either “CARD” or “ACCOUNT”. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customercountryiso2a XPath: /customer/country |
Alpha (2) |
The sender's country. This will need to be in ISO2A format. Click here for a full list of country codes. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customerfirstname XPath: /customer/name/first |
Alphanumeric including symbols (127) |
The sender's first name. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customerlastname XPath: /customer/name/last |
Alphanumeric including symbols (127) |
The sender's last name. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customerstreet XPath: /customer/street |
Alphanumeric including symbols (127) |
The sender's street name. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customertown XPath: /customer/town |
Alphanumeric including symbols (127) |
The sender's town. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| transactiontypeindicator XPath: /merchant/transactiontypeindicator |
Alphanumeric (3) |
Facilitates Mastercard MoneySend Payments. Submit one of the following:
Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingpremise XPath: /billing/premise |
Alphanumeric including symbols (25) |
The house number or first line of the recipient's billing address. |
|
| orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25) |
We strongly recommend submitting a unique reference to identify each request submitted. |
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
payout= {
"accounttypedescription": "CFT",
"baseamount": "1050",
"billingcountryiso2a": "GB",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"cftsourceoffunds": "05",
"customeraccountnumber": "12345678",
"customeraccountnumbertype": "ACCOUNT",
"customercountryiso2a": "GB",
"customerfirstname": "Jane",
"customerlastname": "Public",
"customerstreet": "Caernarfon Road",
"customertown": "Bangor",
"orderreference": "My_Order_123",
"parenttransactionreference": "1-2-345",
"requesttypedescriptions": ["REFUND"],
"sitereference": "site12346",
"transactiontypeindicator": "C52"
}
strequest = securetrading.Request()
strequest.update(payout)
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(
'accounttypedescription' => 'CFT',
'baseamount' => '1050',
'billingcountryiso2a' => 'GB',
'billingdob' => '1991-05-28',
'billingfirstname' => 'Joe',
'billinglastname' => 'Bloggs',
'cftsourceoffunds' => '05',
'customeraccountnumber' => '12345678',
'customeraccountnumbertype' => 'ACCOUNT',
'customercountryiso2a' => 'GB',
'customerfirstname' => 'Jane',
'customerlastname' => 'Public',
'customerstreet' => 'Caernarfon Road',
'customertown' => 'Bangor',
'orderreference' => 'My_Order_123',
'parenttransactionreference' => '1-2-345',
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'site12346',
'transactiontypeindicator' => 'C52'
);
$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": [{
"accounttypedescription": "CFT",
"baseamount": "1050",
"billingcountryiso2a": "GB",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"cftsourceoffunds": "05",
"customeraccountnumber": "12345678",
"customeraccountnumbertype": "ACCOUNT",
"customercountryiso2a": "GB",
"customerfirstname": "Jane",
"customerlastname": "Public",
"customerstreet": "Caernarfon Road",
"customertown": "Bangor",
"orderreference": "My_Order_123",
"parenttransactionreference": "1-2-345",
"requesttypedescriptions": ["REFUND"],
"sitereference": "site12346",
"transactiontypeindicator": "C52"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"CFT",
"baseamount":"1050",
"billingcountryiso2a":"GB",
"billingdob":"1991-05-28",
"billingfirstname":"Joe",
"billinglastname":"Bloggs",
"cftsourceoffunds":"05",
"customeraccountnumber":"12345678",
"customeraccountnumbertype":"ACCOUNT",
"customercountryiso2a":"GB",
"customerfirstname":"Jane",
"customerlastname":"Public",
"customerstreet":"Caernarfon Road",
"customertown":"Bangor",
"orderreference":"My_Order_123",
"parenttransactionreference":"1-2-345",
"requesttypedescriptions":["REFUND"],
"sitereference":"site12346",
"transactiontypeindicator":"C52"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<billing>
<amount>1050</amount>
<country>GB</country>
<dob>1991-05-28</dob>
<name>
<first>Joe</first>
<last>Bloggs</last>
</name>
</billing>
<customer>
<accountnumber type="ACCOUNT">12345678</accountnumber>
<country>GB</country>
<name>
<first>Jane</first>
<last>Public</last>
</name>
<street>Caernarfon Road</street>
<town>Bangor</town>
</customer>
<merchant>
<orderreference>My_Order_123</orderreference>
<transactiontypeindicator>C52</transactiontypeindicator>
</merchant>
<operation>
<accounttypedescription>CFT</accounttypedescription>
<parenttransactionreference>1-2-345</parenttransactionreference>
<sitereference>site12346</sitereference>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification (using stored card)
| Field | Format | Description | |
| accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Must be “CFT”. | |
| baseamount XPath: /billing/amount |
Numeric (13) |
The refund amount in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”. |
|
| billingcountryiso2a XPath: /billing/country |
Alpha (2) |
The country for the recipient's billing address. This will need to be in ISO2A format. |
|
| billingdob XPath: /billing/dob |
Date YYYY-MM-DD |
The recipient's date of birth. Conditions apply when processing Payouts where Trust Payments performs PEP or sanction screening on the recipient. Click here for info. |
|
| billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The recipient's billing first name. |
|
| billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The recipient's billing last name. |
|
| parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
Submit the transaction reference of a previous AUTH, ACCOUNTCHECK or Payout (CFT REFUND) request and we will retrieve the customer's card stored in our records and credit the funds to said card. All fields that start with "billing-" and "customer-" will also be inherited from the parent request, if available. Inherited fields do not need to be included in this new Payout request (even if denoted as required in this specification), but you do still have the option to submit new billing and customer fields and this will override any inherited data. |
|
| requesttypedescriptions XPath: /@type |
Alphanumeric & hyphens (25) |
The request type required is “REFUND”. | |
| sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
A unique reference that identifies your account. You receive this when you first sign up with us. | |
| billingcounty XPath: /billing/county |
Alphanumeric including symbols (127) |
The county for the recipient's billing address. For Canadian addresses, submit the two-character province code, e.g. for British Columbia, submit “BC”. Required for Visa Direct payments processed with cards issued in Canada. Click here for info. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingpostcode XPath: /billing/postcode |
Alphanumeric (25) |
The recipient's billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingstreet XPath: /billing/street |
Alphanumeric including symbols (127) |
The street entered for the recipient's billing address. Required for Visa Direct payments processed with cards issued in Canada. Click here for info. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingtelephone XPath: /billing/telephone |
Alphanumeric including symbols (20) |
The customer’s telephone number. Valid characters:
Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingtown XPath: /billing/town |
Alphanumeric including symbols (127) |
The town entered for the recipient's billing address. Required for Visa Direct payments processed with cards issued in Canada. Click here for info. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| cftsourceoffunds XPath: /merchant/cftsourceoffunds |
Numeric (2) |
The source of funds for the Payout. Submit one of the following:
|
|
| customeraccountnumber XPath: /customer/accountnumber |
Numeric (20) |
If account number type is “ACCOUNT”, the account number of the sender. If account number type is “CARD”, the card number of the sender. The returned value in the response is in a masked format, e.g. “411111#######1111”. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customeraccountnumbertype XPath: /customer/accountnumber/@type |
Alpha (7) |
Either “CARD” or “ACCOUNT”. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customercountryiso2a XPath: /customer/country |
Alpha (2) |
The sender's country. This will need to be in ISO2A format. Click here for a full list of country codes. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customerfirstname XPath: /customer/name/first |
Alphanumeric including symbols (127) |
The sender's first name. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customerlastname XPath: /customer/name/last |
Alphanumeric including symbols (127) |
The sender's last name. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customerstreet XPath: /customer/street |
Alphanumeric including symbols (127) |
The sender's street name. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| customertown XPath: /customer/town |
Alphanumeric including symbols (127) |
The sender's town. Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| transactiontypeindicator XPath: /merchant/transactiontypeindicator |
Alphanumeric (3) |
Facilitates Mastercard MoneySend Payments. Submit one of the following:
Required when processing Mastercard MoneySend Payments. Click here for further information. |
|
| billingpremise XPath: /billing/premise |
Alphanumeric including symbols (25) |
The house number or first line of the recipient's billing address. |
|
| orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25) |
We strongly recommend submitting a unique reference to identify each request submitted. |
Payout response
The following is an example of a typical Payout response:
{
u 'requestreference': u 'Agv3epv31',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'CFT',
u 'acquirerresponsecode': u '00',
u 'acquirerresponsemessage': u 'Approved or completed Successfully',
u 'authcode': u '000005',
u 'baseamount': u '1050',
u 'chargedescription': u 'Charge description',
u 'cryptocurrencyindicator': u '0',
u 'currencyiso3a': u 'GBP',
u 'customeraccountnumbertype': u 'ACCOUNT',
u 'dccenabled': u '0',
u 'debtrepayment': u '0',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'issuer': u 'ISSUER NAME',
u 'issuercountryiso2a': u 'GB',
u 'livestatus': u '1',
u 'maskedcustomeraccountnumber': u '12345678',
u 'maskedpan': u '512499######0911',
u 'merchantcategorycode': u '6537',
u 'merchantcity': u 'Bangor',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Merchant Shop',
u 'merchantnumber': u '000123456789012',
u 'merchantzipcode': u 'LL57 4BL',
u 'operatorname': u 'webservices@merchant.com',
u 'orderreference': u 'My_Order_123',
u 'parenttransactionreference': u '1-2-345678',
u 'paymenttypedescription': u 'MASTERCARDDEBIT',
u 'requesttypedescription': u 'REFUND',
u 'retrievalreferencenumber': u '323313210011',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '0',
u 'settleduedate': u '2023-08-21',
u 'settlestatus': u '10',
u 'stan': u '210011',
u 'transactionreference': u '21-70-11',
u 'transactionstartedtimestamp': u '2023-08-21 13:23:08',
u 'transactiontypeindicator': u 'C52'
}]
}
array(3) {
["requestreference"] => string(9) "A19beknpr"
["responses"] => array(1) {
[0] => array(39) {
["accounttypedescription"] => string(3) "CFT"
["acquirerresponsecode"] => string(2) "00"
["acquirerresponsemessage"] => string(34) "Approved or completed Successfully"
["authcode"] => string(6) "000005"
["baseamount"] => string(4) "1050"
["chargedescription"] => string(18) "Charge description"
["cryptocurrencyindicator"] => string(1) "0"
["currencyiso3a"] => string(3) "GBP"
["customeraccountnumbertype"] => string(7) "ACCOUNT"
["dccenabled"] => string(1) "0"
["debtrepayment"] => string(1) "0"
["errorcode"] => string(1) "0"
["errormessage"] => string(2) "Ok"
["issuer"] => string(11) "ISSUER NAME"
["issuercountryiso2a"] => string(2) "GB"
["livestatus"] => string(1) "1"
["maskedcustomeraccountnumber"] => string(8) "12345678"
["maskedpan"] => string(16) "512499######0911"
["merchantcategorycode"] => string(4) "6537"
["merchantcity"] => string(6) "Bangor"
["merchantcountryiso2a"] => string(2) "GB"
["merchantname"] => string(13) "Merchant Shop"
["merchantnumber"] => string(15) "000123456789012"
["merchantzipcode"] => string(8) "LL57 4BL"
["operatorname"] => string(24) "webservices@merchant.com"
["orderreference"] => string(12) "My_Order_123"
["parenttransactionreference"] => string(10) "1-2-345678"
["paymenttypedescription"] => string(15) "MASTERCARDDEBIT"
["requesttypedescription"] => string(6) "REFUND"
["retrievalreferencenumber"] => string(12) "323313210011"
["securityresponseaddress"] => string(1) "0"
["securityresponsepostcode"] => string(1) "0"
["securityresponsesecuritycode"] => string(1) "0"
["settleduedate"] => string(10) "2023-08-21"
["settlestatus"] => string(2) "10"
["stan"] => string(6) "210011"
["transactionreference"] => string(8) "21-70-11"
["transactionstartedtimestamp"] => string(19) "2023-08-21 13:23:08"
["transactiontypeindicator"] => string(3) "C52"
}
}
["version"] => string(4) "1.00"
}
{
"requestreference":"W23-qc7t4h8a",
"version":"1.00",
"response":[{
"accounttypedescription": "CFT",
"acquirerresponsecode": "00",
"acquirerresponsemessage": "Approved or completed Successfully",
"authcode": "000005",
"baseamount": "1050",
"chargedescription": "Charge description",
"cryptocurrencyindicator": "0",
"currencyiso3a": "GBP",
"customeraccountnumbertype": "ACCOUNT",
"dccenabled": "0",
"debtrepayment": "0",
"errorcode": "0",
"errormessage": "Ok",
"issuer": "ISSUER NAME",
"issuercountryiso2a": "GB",
"livestatus": "1",
"maskedcustomeraccountnumber": "12345678",
"maskedpan": "512499######0911",
"merchantcategorycode": "6537",
"merchantcity": "Bangor",
"merchantcountryiso2a": "GB",
"merchantname": "Merchant Shop",
"merchantnumber": "000123456789012",
"merchantzipcode": "LL57 4BL",
"operatorname": "webservices@merchant.com",
"orderreference": "My_Order_123",
"parenttransactionreference":"1-2-345678",
"paymenttypedescription": "MASTERCARDDEBIT",
"requesttypedescription": "REFUND",
"retrievalreferencenumber": "323313210011",
"securityresponseaddress": "0",
"securityresponsepostcode": "0",
"securityresponsesecuritycode": "0",
"settleduedate": "2023-08-21",
"settlestatus": "10",
"stan": "210011",
"transactionreference": "21-70-11",
"transactionstartedtimestamp": "2023-08-21 13:23:08",
"transactiontypeindicator": "C52"
}],
"secrand":"0V2j6j0kl2R1UU"
}
<responseblock version="3.67">
<requestreference>X1u3u92dg</requestreference>
<response type="REFUND">
<acquirerresponsecode>00</acquirerresponsecode>
<acquirerresponsemessage>Approved or completed Successfully</acquirerresponsemessage>
<authcode>000005</authcode>
<billing>
<amount currencycode="GBP">1050</amount>
<dcc enabled="0"/>
<payment type="MASTERCARDDEBIT">
<issuer>ISSUER NAME</issuer>
<issuercountry>GB</issuercountry>
<pan>512499######0911</pan>
</payment>
</billing>
<customer>
<accountnumber type="ACCOUNT">12345678</accountnumber>
</customer>
<error>
<code>0</code>
<message>Ok</message>
</error>
<live>1</live>
<merchant>
<chargedescription>Charge description</chargedescription>
<debtrepayment>0</debtrepayment>
<merchantcategorycode>6537</merchantcategorycode>
<merchantcity>Bangor</merchantcity>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Merchant Shop</merchantname>
<merchantnumber>000123456789012</merchantnumber>
<merchantzipcode>LL57 4BL</merchantzipcode>
<operatorname>webservices@merchant.com</operatorname>
<orderreference>My_Order_123</orderreference>
<transactiontypeindicator>C52</transactiontypeindicator>
</merchant>
<operation>
<accounttypedescription>CFT</accounttypedescription>
<cryptocurrencyindicator>0</cryptocurrencyindicator>
<parenttransactionreference>1-2-345678</parenttransactionreference>
</operation>
<other>
<retrievalreferencenumber>323313210011</retrievalreferencenumber>
<stan>210011</stan>
</other>
<security>
<address>0</address>
<postcode>0</postcode>
<securitycode>0</securitycode>
</security>
<settlement>
<settleduedate>2023-08-21</settleduedate>
<settlestatus>10</settlestatus>
</settlement>
<timestamp>2023-08-21 13:23:08</timestamp>
<transactionreference>21-70-11</transactionreference>
</response>
<secrand>V1utOQ5A</secrand>
</responseblock>
Payout response field specification
| Field | Format | Description | |
| accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) |
“CFT” is returned in the response. |
|
| baseamount XPath: /billing/amount |
Numeric (13) | The refund amount in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”. | |
| chargedescription XPath: /merchant/chargedescription |
Alphanumeric including spaces and special characters (25) |
The charge description is a field that we provide to the acquiring bank during a transaction. It is a basic description of the transaction that is shown on the customer’s bank statement. |
|
| cryptocurrencyindicator XPath: /operation/cryptocurrencyindicator |
Numeric (1) |
Indicates if transaction is flagged as a purchase of cryptocurrency:
|
|
| currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The currency of the transaction. |
|
| dccenabled XPath: /billing/dcc/@enabled |
Numeric (1) |
Indicates if your account is configured for DCC:
|
|
| debtrepayment XPath: /merchant/debtrepayment |
Numeric (1) |
Indicates if transaction is flagged as debt repayment:
|
|
| errorcode XPath: /error/code |
Numeric (1-5) |
The error code should be used to determine if the request was successful or not.
|
|
| errormessage XPath: /error/message |
Alphanumeric (255) |
This provides a brief explanation as to the cause of the error.
For successful transactions, this is returned as “Ok”. |
|
| issuer XPath: /billing/payment/issuer |
Alphanumeric (255) | The customer’s card issuer. | |
| issuercountryiso2a XPath: /billing/payment/issuercountry |
Alpha (2) |
The country for the customer’s card issuer. |
|
| livestatus XPath: /live |
Numeric (1) |
|
|
| maskedpan XPath: /billing/payment/pan |
Alphanumeric including “#” (12-19) |
If tokenisedpayment is not returned: If tokenisedpayment is returned with value 1: |
|
| merchantnumber XPath: /merchant/merchantnumber |
Alphanumeric (32) |
The merchant number that was used to process the transaction. Provided by the acquiring bank. |
|
| operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. | |
| paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | Payment method (e.g. “VISA” or “MASTERCARD”). | |
| requesttypedescription XPath: /@type |
Alpha (20) |
“REFUND” is returned in the response. |
|
| securityresponseaddress XPath: /security/address |
Numeric (1) |
The result of AVS checks. |
|
| securityresponsepostcode XPath: /security/postcode |
Numeric (1) |
The result of AVS checks. |
|
| securityresponsesecuritycode XPath: /security/securitycode |
Numeric (1) |
The result of Security Code Checks. |
|
| settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. | |
| settlestatus XPath: /settlement/settlestatus |
Numeric (3) |
A numeric value used to indicate the progress of settlement regarding this transaction. |
|
| transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction. | |
| transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the transaction was processed. | |
| acquireradvicecode XPath: /acquireradvicecode |
Numeric (1) |
A numeric value returned following a repeat payment request, indicating if further payments can be processed.
Mapping:
This will vary depending on your acquiring bank. Please contact your bank for further information. |
|
| acquirerresponsecode XPath: /acquirerresponsecode |
Alphanumeric (255) |
Used by your acquirer to indicate the outcome of the request. This will vary depending on your acquiring bank. Please contact your bank for further information. |
|
| acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric (255) |
Used by your acquirer to indicate the outcome of the request. This will vary depending on your acquiring bank. Please contact your bank for further information. |
|
| authcode XPath: /authcode |
Alphanumeric (255) |
The authorisation code provided by the issuing bank. This will differ depending on which bank you use. Only returned if the transaction is authorised. |
|
| customeraccountnumbertype XPath: /customer/accountnumber/@type |
Alpha (7) |
Either “CARD” or “ACCOUNT”. Returned if submitted in the request. |
|
| errordata XPath: /error/data |
Alphanumeric (255) |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
| maskedcustomeraccountnumber XPath: /customer/accountnumber |
Numeric (20) |
If account number type is “ACCOUNT”, the account number of the sender. If account number type is “CARD”, the card number of the sender. The returned value in the response is in a masked format, e.g. “411111#######1111”. Returned if submitted in the request. |
|
| merchantcategorycode XPath: /merchant/merchantcategorycode |
Alphanumeric (255) |
These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration. |
|
| merchantcity XPath: /merchant/merchantcity |
Alphanumeric (127) |
These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration. |
|
| merchantcountryiso2a XPath: /merchant/merchantcountryiso2a |
Alpha (2) |
These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration. |
|
| merchantname XPath: /merchant/merchantname |
Alphanumeric (255) |
These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration. |
|
| merchantstatecode XPath: /merchant/merchantstatecode |
Alphanumeric (127) |
These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration. |
|
| merchantzipcode XPath: /merchant/merchantzipcode |
Alphanumeric (10) |
These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration. |
|
| orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25) |
Your unique order reference that can be stored on the Trust Payments system. This field is returned if submitted in the request or inherited from a parent. |
|
| parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
The transactionreference of a previous request, from which key details have been inherited. This field is returned if submitted in the request. |
|
|
retrievalreferencenumber |
Alphanumeric (255) |
An ISO term. This is used to reference the source transaction. This will vary depending on your acquiring bank. |
|
|
stan |
ISO 8583 |
The STAN (System Trace Audit Number) associated with the transaction. This follows the ISO 8583 standard. This field is returned if available. |
|
| tokenisedpayment XPath: /billing/payment/pan/@tokenised |
Numeric (1) |
If this field is returned with value 1, this indicates the transaction was processed using a token. This field is returned if payment was performed using a token. |
|
| tokentype XPath: /billing/payment/pan/@tokentype |
Alphanumeric (50) |
Used to identify the type of token used for this payment (e.g. “VISATOKEN”). This field is returned if payment was performed using a token. |
|
| transactiontypeindicator XPath: /merchant/transactiontypeindicator |
Alphanumeric (3) |
Returned if submitted in the request. |
|
| walletdisplayname XPath: /billing/payment/wallet/displayname |
Alphanumeric (255) |
This normally contains the last four digits of the customer’s card number (e.g. “1111”). This field is returned if payment was performed using a wallet. |
|
| walletsource XPath: /billing/payment/wallet/source |
Alphanumeric (20) |
Used to identify the type of wallet used for this payment (e.g. “APPLEPAY”). This field is returned if payment was performed using a wallet. |
Payout settlement
The settlement flow depends on the protocol being used to perform the Payout.
Visa Direct
Transfers processed via Visa Direct are typically transferred to the recipient in less than 30 minutes. The settlestatus of the transfer is immediately set to 100.
Mastercard MoneySend & Gaming Payments
While the funds are typically transferred to the recipient in less than 30 minutes, MoneySend & Gaming Payments will initially have settlestatus=10. A batch process runs on a daily basis, updating the settlestatus of successful transfers to 100.
Other
Payouts that are not processed via Visa Direct or Mastercard MoneySend will follow the same settlement flow as a standard e-commerce AUTH or REFUND request:
- If the Payout request is successful, settlestatus=0
- Settlement is performed in batches on a daily basis, after which Payouts are updated to settlestatus=100 to indicate successful settlement.
- The transfer will normally complete within 24 hours.
Additional notes
Politically Exposed Persons (PEP) or Sanction Screening
Requests to process Payouts where Trust Payments performs PEP or sanction screening on the recipient are subject to strict requirements. The following fields must be submitted in the Payout request:
Failure to submit may result in returning of 60044 "Recipient screening failed" error.
- billingcountryiso2a
- billingdob
- billingfirstname
- billinglastname
Testing guidance
When testing, you can use the following test card details:
- Visa card "4111 1111 1111 1111" or Mastercard "5100 0000 0000 0511".
- Set expiry date to any valid date in the future.
- Use security code “123”.
You can also send different baseamount values to affect the outcome of the request:
- baseamount 70000 returns a declined response from the test bank.
- baseamount 60010 returns a bank system error from the test bank.
- baseamount 1050 returns an authorised response from the test bank.
Please generate and submit your own dummy/example sender/recipient name, address, date of birth and/or account number etc. when testing.