Payouts with Webservices API

  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.
If you are unsure, please contact our Support Team for assistance.

 

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 customer’s account typically being credited within 30 minutes.

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.

  For merchants with MCC 7995, Mastercard mandates that all payout requests processed with Mastercard-branded cards must include billing first name and last name fields, as described in our specification below.

 

Payout request

Using parent transaction

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

Python PHP cURL Raw JSON Raw XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

payout= {
"requesttypedescriptions": ["REFUND"],
"sitereference": "test_site12345",
"accounttypedescription": "CFT",
"parenttransactionreference": "1-2-345678",
"billingfirstname": "Joe",
"billinglastname": "Bloggs"
}

strequest = securetrading.Request()
strequest.update(payout)
stresponse = st.process(strequest) #stresponse contains the transaction response

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Without parent

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 customer’s payment details in the payout request. Please see the following example:

Python PHP cURL Raw JSON Raw XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

payout= {
"requesttypedescriptions": ["REFUND"],
"sitereference": "test_site12345",
"accounttypedescription": "CFT",
"baseamount": "1050",
"currencyiso3a": "GBP",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123",
"billingfirstname": "Joe",
"billinglastname": "Bloggs"
}

strequest = securetrading.Request()
strequest.update(payout)
stresponse = st.process(strequest) #stresponse contains the transaction response

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

  When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.

  Field Format Description
table-required.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Must be “CFT”.
table-conditional.png 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).

table-conditional.png billingfirstname
XPath: /billing/name/first
Alphanumeric including
symbols (127)

The customer’s billing first name.

Required for payments processed with Mastercard-branded cards by merchants with MCC 7995.

table-conditional.png billinglastname
XPath: /billing/name/last
Alphanumeric including
symbols (127)

The customer’s billing last name.

Required for payments processed with Mastercard-branded cards by merchants with MCC 7995.

table-conditional.png 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).

table-conditional.png 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.

table-optional.png 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.

table-conditional.png pan
XPath: /billing/payment/pan
Numeric (12-19)

This is the long number printed on the front of the customer’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.

table-conditional.png 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.

table-required.png requesttypedescriptions
XPath: /@type
Alphanumeric
& hyphens (25)
The request type required is “REFUND”.
table-optional.png 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.

table-required.png 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 that the accounttypedescription returned is “CFT”:

Python PHP Raw JSON Raw XML
{
u 'requestreference': u 'Agv3epv31',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2016-12-07 15:44:33',
u 'parenttransactionreference': u '1-2-345678',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'tid': u '27880001',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '1-2-345679',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1050',
u 'accounttypedescription': u 'CFT',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'REFUND',
u 'securityresponsesecuritycode': u '0',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST REFUND ACCEPTED',
u 'errormessage': u 'Ok',
u 'operatorname': u 'webservices@example.com',
u 'securityresponsepostcode': u '0',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request