Payouts with Webservices API

Michael Buckley

September 20, 2023 14:52

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

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.

Payouts to Mastercard-branded cards are processed via the MoneySend protocol.
Click here to learn more.

Payouts to Visa-branded cards are processed via the Visa Direct protocol.
Click here to learn more.

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

Payout request where card details are 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",
  "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. Click here for a full list of country codes.
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. Click here for a full list of available currencies.
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.
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.
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.
cftsourceoffunds XPath: /merchant/cftsourceoffunds	Numeric (2)	The source of funds for the Payout. Submit one of the following: "01" - Credit "02" - Debit "03" - Prepaid "04" - Cash "05" - Debit/ deposit account "07" - Mobile Money Account Required when processing Mastercard MoneySend Payments. Click here for further information.
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: "C52" General Transfer to Own Account - e.g. customer transfers funds from their trading account with the merchant to their card account. "C55" Business Disbursement - e.g. an insurance company pays out to card details used for monthly/yearly insurance premiums 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.
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 request using stored card

#!/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. Click here for a full list of country codes.
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.
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.
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.
cftsourceoffunds XPath: /merchant/cftsourceoffunds	Numeric (2)	The source of funds for the Payout. Submit one of the following: "01" - Credit "02" - Debit "03" - Prepaid "04" - Cash "05" - Debit/ deposit account "07" - Mobile Money Account Required when processing Mastercard MoneySend Payments. Click here for further information.
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: "C52" General Transfer to Own Account - e.g. customer transfers funds from their trading account with the merchant to their card account. "C55" Business Disbursement - e.g. an insurance company pays out to card details used for monthly/yearly insurance premiums 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.
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. Click here to learn more.
cryptocurrencyindicator XPath: /operation/cryptocurrencyindicator	Numeric (1)	Indicates if transaction is flagged as a purchase of cryptocurrency: 1 – Transaction is flagged as cryptocurrency purchase. 0 – Transaction is not flagged as cryptocurrency purchase.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency of the transaction. Click here for a full list of available currencies.
dccenabled XPath: /billing/dcc/@enabled	Numeric (1)	Indicates if your account is configured for DCC: 1 – Yes 0 – No
debtrepayment XPath: /merchant/debtrepayment	Numeric (1)	Indicates if transaction is flagged as debt repayment: 1 – Transaction is flagged as debt repayment. 0 – Transaction is not 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. 0 - Transaction was successful. 60044 - Recipient screening failed. 70000 - Transaction declined. Click here for a full list of errorcode and message values.
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”. Click here for a full list of errorcode and message values.
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. This will be in ISO2A format. Click here for a full list of country codes.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
maskedpan XPath: /billing/payment/pan	Alphanumeric including “#” (12-19)	If tokenisedpayment is not returned: The maskedpan field represents the customer’s card number. If tokenisedpayment is returned with value 1: The maskedpan field represents the customer’s unique token number used to perform the transaction. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
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. Click here to learn more.
securityresponsepostcode XPath: /security/postcode	Numeric (1)	The result of AVS checks. Click here to learn more.
securityresponsesecuritycode XPath: /security/securitycode	Numeric (1)	The result of Security Code Checks. Click here to learn more.
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. Click here for further info on values that can be returned.
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: 0 – No action required. 1 – New account information available. 2 – Cannot approve at this time. 4 – Do not process further recurring transactions. 8 – Payment blocked by card scheme. 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 XPath: /other/retrievalreferencenumber	Alphanumeric (255)	An ISO term. This is used to reference the source transaction. This will vary depending on your acquiring bank.
stan XPath: /other/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)	"C52" General Transfer to Own Account - e.g. customer transfers funds from their trading account with the merchant to their card account. "C55" Business Disbursement - e.g. an insurance company pays out to card details used for monthly/yearly insurance premiums 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 Payments

While the funds are typically transferred to the recipient in less than 30 minutes, MoneySend 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

Visa Direct in Canada

Click here to learn more about Visa Direct.

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

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.

Requirements

Payout request

Field specification (submitting card details)

Field specification (using stored card)

Payout response

Payout response field specification

Payout settlement

Visa Direct

Mastercard MoneySend Payments

Other

Additional notes

Politically Exposed Persons (PEP) or Sanction Screening

Visa Direct in Canada

Testing guidance

Articles in this section