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 similar to standard refunds, except they can be performed independently of other transactions. The benefits of performing payouts include:
- The refund amount can be greater than the original payment, if required.
- The refund can be processed before the original payment has been settled into your bank account.
Payouts are also known as Credit Fund Transfers (CFT) or Original Credit Transfers (OCT).
Payouts processed with Visa Direct are processed online, with the recipient's account typically being credited within 30 minutes. Click here to learn more.
Please contact your account manager to check if you are eligible to enable Visa Direct on your account.
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
Using a parent request
- Payouts are performed by processing a REFUND request.
- Like a standard REFUND request, the requesttypedescriptions needs to be “REFUND”.
- The accounttypedescription submitted needs to be “CFT”.
- In this example, the parenttransactionreference is included, which references the original AUTH. This will inherit the payment, billing and customer details from the parent, so your system does not need to submit them again.
The following is an example of such a request:
Ensure the submitted accounttypedescription is “CFT”, otherwise a regular REFUND will be processed instead of a payout.
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
payout= {
"accounttypedescription": "CFT",
"billingcountryiso2a": "GB",
"billingcounty": "Gwynedd",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs"
"billingpostcode": "TR45 6ST",
"billingpremise": "123",
"billingstreet": "Test Street",
"billingtown": "Bangor",
"orderreference": "MyOrder123",
"parenttransactionreference": "1-2-345678",
"requesttypedescriptions": ["REFUND"],
"sitereference": "test_site12345"
}
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',
'billingcountryiso2a' => 'GB',
'billingcounty' => 'Gwynedd',
'billingdob' => '1991-05-28',
'billingfirstname' => 'Joe',
'billinglastname' => 'Bloggs',
'billingpostcode' => 'TR45 6ST',
'billingpremise' => '123',
'billingstreet' => 'Test Street',
'billingtown' => 'Bangor',
'orderreference' => 'MyOrder123',
'parenttransactionreference' => '1-2-345678',
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'test_site12345'
);
$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",
"billingcountryiso2a": "GB",
"billingcounty": "Gwynedd",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"billingpostcode": "TR45 6ST",
"billingpremise": "123",
"billingstreet": "Test Street",
"billingtown": "Bangor",
"orderreference": "MyOrder123",
"parenttransactionreference": "1-2-345678",
"requesttypedescriptions": ["REFUND"],
"sitereference": "test_site12345"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"CFT",
"billingcountryiso2a": "GB",
"billingcounty": "Gwynedd",
"billingdob": "1991-05-28",
"billingfirstname":"Joe",
"billinglastname":"Bloggs",
"billingpostcode": "TR45 6ST",
"billingpremise": "123",
"billingstreet": "Test Street",
"billingtown": "Bangor",
"orderreference": "MyOrder123",
"parenttransactionreference":"1-2-345678",
"requesttypedescriptions":["REFUND"],
"sitereference":"test_site12345"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<billing>
<country>GB</country>
<county>Gwynedd</county>
<dob>1991-05-28</dob>
<name>
<first>Joe</first>
<last>Bloggs</last>
</name>
<postcode>TR45 6ST</postcode>
<premise>123</premise>
<street>Test Street</street>
<town>Bangor</town>
</billing>
<merchant>
<orderreference>MyOrder123</orderreference>
</merchant>
<operation>
<accounttypedescription>CFT</accounttypedescription>
<parenttransactionreference>1-2-345678</parenttransactionreference>
<sitereference>test_site12345</sitereference>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Without a parent request
As an alternative to the above, you can also submit a payout request without reference to a parent transaction. In this scenario, you will instead need to submit the recipient's payment details in the payout request. Please see the following example:
#!/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",
"billingcounty": "Gwynedd",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"billingpostcode": "TR45 6ST",
"billingpremise": "123",
"billingstreet": "Test Street",
"billingtown": "Bangor",
"currencyiso3a": "GBP",
"expirydate": "12/2020",
"orderreference": "MyOrder123",
"pan": "4111111111111111",
"requesttypedescriptions": ["REFUND"],
"securitycode": "123",
"sitereference": "test_site12345"
}
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',
'billingcounty' => 'Gwynedd',
'billingdob' => '1991-05-28',
'billingfirstname' => 'Joe',
'billinglastname' => 'Bloggs',
'billingpostcode' => 'TR45 6ST',
'billingpremise' => '123',
'billingstreet' => 'Test Street',
'billingtown' => 'Bangor',
'currencyiso3a' => 'GBP',
'expirydate' => '12/2020',
'orderreference": "MyOrder123',
'pan' => '4111111111111111',
'requesttypedescriptions' => array('REFUND'),
'securitycode' => '123',
'sitereference' => 'test_site12345'
);
$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",
"billingcounty": "Gwynedd",
"billingdob": "1991-05-28",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"billingpostcode": "TR45 6ST",
"billingpremise": "123",
"billingstreet": "Test Street",
"billingtown": "Bangor",
"currencyiso3a": "GBP",
"expirydate": "12/2020",
"orderreference": "MyOrder123",
"pan": "4111111111111111",
"requesttypedescriptions": ["REFUND"],
"securitycode": "123",
"sitereference": "test_site12345"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"CFT",
"baseamount":"1050",
"billingcountryiso2a": "GB",
"billingcounty": "Gwynedd",
"billingdob": "1991-05-28",
"billingfirstname":"Joe",
"billinglastname":"Bloggs",
"billingpostcode": "TR45 6ST",
"billingpremise": "123",
"billingstreet": "Test Street",
"billingtown": "Bangor",
"currencyiso3a":"GBP",
"expirydate":"12/2020",
"orderreference": "MyOrder123",
"pan":"4111111111111111",
"requesttypedescriptions":["REFUND"],
"securitycode":"123",
"sitereference":"test_site12345"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<billing>
<amount currencycode="GBP">1050</amount>
<country>GB</country>
<county>Gwynedd</county>
<dob>1991-05-28</dob>
<name>
<first>Joe</first>
<last>Bloggs</last>
</name>
<payment>
<expirydate>12/2020</expirydate>
<pan>4111111111111111</pan>
<securitycode>123</securitycode>
</payment>
<postcode>TR45 6ST</postcode>
<premise>123</premise>
<street>Test Street</street>
<town>Bangor</town>
</billing>
<merchant>
<orderreference>MyOrder123</orderreference>
</merchant>
<operation>
<accounttypedescription>CFT</accounttypedescription>
<sitereference>test_site12345</sitereference>
</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 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”. (Max length of amount may vary depending on your acquiring bank – Contact your bank for further info) Required if not passing through a parenttransactionreference (if a parent has been provided, the amount can instead be inherited). |
|
billingcountryiso2a XPath: /billing/country |
Alpha (2) |
The country for the recipient's billing address. This will need to be in ISO2A format. |
|
billingcounty XPath: /billing/county |
Alphanumeric including symbols (127) |
The county for the recipient's billing address. For US addresses, the state would be entered in this field. Valid formats:
Conditions apply for Visa Direct payments processed with cards issued in Canada. Click here for info. |
|
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. |
 |
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. |
|
billingpremise XPath: /billing/premise |
Alphanumeric including symbols (25) |
The house number or first line of the recipient's billing address. |
|
billingstreet XPath: /billing/street |
Alphanumeric including symbols (127) |
The street entered for the recipient's billing address. Conditions apply for Visa Direct payments processed with cards issued in Canada. Click here for info. |
|
billingtown XPath: /billing/town |
Alphanumeric including symbols (127) |
The town entered for the recipient's billing address. Conditions apply for Visa Direct payments processed with cards issued in Canada. Click here for info. |
|
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The currency that the transaction will be processed in. Click here for a full list of available currencies. Required if not passing through a parenttransactionreference (if a parent has been provided, the currency is inherited). |
|
expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY |
If you would like to process a refund with an updated expiry date, the new value is submitted in this field. Required if not passing through a parenttransactionreference. |
|
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25)
Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction. |
Your unique order reference that can be stored on Trust Payments’s system. If this is not submitted, it is inherited from the parent AUTH request, provided a parenttransactionreference has been included. |
|
pan XPath: /billing/payment/pan |
Numeric (12-19) |
This is the long number printed on the front of the recipient's card. We return a masked version of this PAN in the response, in the field maskedpan. e.g. “411111######1111” Required if not passing through a parenttransactionreference. |
|
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
You can submit the transaction reference of the AUTH request that you would like to refund. You can omit this field and submit the pan, expirydate and securitycode instead. |
|
requesttypedescriptions XPath: /@type |
Alphanumeric & hyphens (25) |
The request type required is “REFUND”. |
|
securitycode XPath: /security/securitycode |
Numeric (3-4) |
This is the three digit security code printed on the back of the card. (For AMEX cards, this is a 4 digit code found on the front of the card) We strongly recommend submitting this value for the processing of security code checks. Additionally, some banks may decline the payment if the security code is not present. |
|
sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
A unique reference that identifies your account. You receive this when you first sign up with us. |
Payout response
The response returned has the same structure as a standard REFUND, except for the following considerations:
- accounttypedescription returned is “CFT”.
- For Payouts using Visa Direct, settlestatus returned is "100", otherwise the settlestatus returned is "0".
{
u 'requestreference': u 'Agv3epv31',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'CFT',
u 'acquirerresponsecode': u '00',
u 'authcode': u 'TEST REFUND ACCEPTED',
u 'baseamount': u '1050',
u 'currencyiso3a': u 'GBP',
u 'dccenabled': u '0',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'issuercountryiso2a': u 'US',
u 'livestatus': u '0',
u 'maskedpan': u '411111######1111',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'merchantnumber': u '00000000',
u 'operatorname': u 'webservices@example.com',
u 'orderreference': u 'My_Order_123',
u 'parenttransactionreference': u '1-2-345678',
u 'paymenttypedescription': u 'VISA',
u 'requesttypedescription': u 'REFUND',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '0',
u 'settleduedate': u '2016-12-07',
u 'settlestatus': u '0',
u 'tid': u '27880001',
u 'transactionreference': u '1-2-345679',
u 'transactionstartedtimestamp': u '2016-12-07 15:44:33'
}]
}
array(3) {
["requestreference"] => string(9) "A19beknpr"
["responses"] => array(1) {
[0] => array(28) {
["accounttypedescription"] => string(3) "CFT"
["acquirerresponsecode"] => string(2) "00"
["authcode"] => string(20) "TEST REFUND ACCEPTED"
["baseamount"] => string(4) "1050"
["currencyiso3a"] => string(3) "GBP"
["dccenabled"] => string(1) "0"
["errorcode"] => string(1) "0"
["errormessage"] => string(2) "Ok"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["issuercountryiso2a"] => string(2) "US"
["livestatus"] => string(1) "0"
["maskedpan"] => string(16) "411111######1111"
["merchantcountryiso2a"] => string(2) "GB"
["merchantname"] => string(13) "Test Merchant"
["merchantnumber"] => string(8) "00000000"
["operatorname"] => string(23) "webservices@example.com"
["orderreference"] => string(12) "My_Order_123"
["parenttransactionreference"] => string(10) "1-2-345678"
["paymenttypedescription"] => string(4) "VISA"
["requesttypedescription"] => string(6) "REFUND"
["securityresponseaddress"] => string(1) "0"
["securityresponsepostcode"] => string(1) "0"
["securityresponsesecuritycode"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["settlestatus"] => string(1) "0"
["tid"] => string(8) "27880001"
["transactionreference"] => string(10) "1-2-345679"
["transactionstartedtimestamp"] => string(19) "2016-12-09 10:21:13"
}
}
["version"] => string(4) "1.00"
}
{
"requestreference":"W23-qc7t4h8a",
"version":"1.00",
"response":[{
"accounttypedescription":"CFT",
"acquirerresponsecode":"00",
"authcode":"TEST REFUND ACCEPTED",
"baseamount":"1050",
"currencyiso3a":"GBP",
"dccenabled":"0",
"errorcode":"0",
"errormessage":"Ok",
"issuer":"SecureTrading Test Issuer1",
"issuercountryiso2a":"US",
"livestatus":"0",
"maskedpan":"411111######1111",
"merchantcountryiso2a":"GB",
"merchantname":"Test Merchant",
"merchantnumber":"00000000",
"operatorname":"webservices@example.com",
"orderreference":"My_Order_123",
"parenttransactionreference":"1-2-345678",
"paymenttypedescription":"VISA",
"requesttypedescription":"REFUND",
"securityresponseaddress":"0",
"securityresponsepostcode":"0",
"securityresponsesecuritycode":"0",
"settleduedate":"2016-12-07",
"settlestatus":"0",
"tid":"27880001",
"transactionreference":"1-2-345679",
"transactionstartedtimestamp":"2016-12-07 15:50:37"
}],
"secrand":"0V2j6j0kl2R1UU"
}
<responseblock version="3.67">
<requestreference>X1u3u92dg</requestreference>
<response type="REFUND">
<acquirerresponsecode>00</acquirerresponsecode>
<authcode>TEST REFUND ACCEPTED</authcode>
<billing>
<amount currencycode="GBP">1050</amount>
<dcc enabled="0"/>
<payment type="VISA">
<issuer>SecureTrading Test Issuer1</issuer>
<issuercountry>US</issuercountry>
<pan>411111######1111</pan>
</payment>
</billing>
<error>
<code>0</code>
<message>Ok</message>
</error>
<live>0</live>
<merchant>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<merchantnumber>00000000</merchantnumber>
<operatorname>webservices@example.com</operatorname>
<orderreference>My_Order_123</orderreference>
<tid>27880001</tid>
</merchant>
<operation>
<accounttypedescription>CFT</accounttypedescription>
<parenttransactionreference>1-2-345678</parenttransactionreference>
</operation>
<security>
<address>0</address>
<postcode>0</postcode>
<securitycode>0</securitycode>
</security>
<settlement>
<settleduedate>2019-12-17</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<timestamp>2019-12-17 11:16:05</timestamp>
<transactionreference>1-2-345679</transactionreference>
</response>
<secrand>V1utOQ5A</secrand>
</responseblock>
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 additional 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
Visa Direct in Canada
When Visa Direct is enabled on your account, requests to process Payouts with Visa-branded cards issued in Canada are subject to additional requirements. The following fields must be submitted in the Payout request:
- billingcountryiso2a
- billingcounty
- billingfirstname
- billinglastname
- billingstreet
- billingtown