API Reference
WebsiteHelp

Refunds

Description

This function is used to process Refund transactions on the payment app via the Companion App


Refunds Request

Parameters

ParameterDescription
launchType Must be “REFUND”
Used for launching the Ecentric Payment app to process a refund.
applicationKey The 3rd party API key that will be issued by Ecentric specific for every 3rd party application
authenticationKey The authentication token that was generated by the server on a successful login to the Ecentric Payment app
merchantUsername The specific user name that with the appropriate role to transact via a Companion app with the Ecentric Payment app
merchantName The name of the merchant that requested the transaction as stored at the bank
originalTransactionUuid Supplying the original sale UUID will initiate a matched refund. If the original sale was tokenized, the refund will be processed via the previously tokenized card holder details.
customerNameThe name of the customer that will be making payment using the Ecentric Payment app
The amount in cents to be refunded (long)
transactionDescription Reference number for the merchant’s records
cellNumberToSMSReceipt 0-digit cell phone number for receipt SMS destination. Can be blank.

NOTE: If isReceiptRequired is true then this is a mandatory field.
emailAddressToSendReceipt Valid email address for receipt email destination. Can be blank.

NOTE: If isReceiptRequired is true then this is a mandatory field.
isReceiptRequired If set to true, at least one of the receipt parameters above needs to be set.
If set to false the user will not be prompted to send a receipt after payment using the Ecentric Payment app.

NOTE: According to VISA and MasterCard requirements, this must always be set to true unless the app developer is providing an alternative means to send a receipt.
alwaysShowTransactionStatusScreen Once the Ecentric Payment app has processed a transaction there is a status screen that shows the success/failure of processing.

Set this flag to true if you would like this displayed otherwise false to hide it. Default is false.
externalSTAN An optional systems trace number generated by some 3rd party ERP systems
externalTransactionGUID An optional GUID that identifies a specific transaction generated by 3rd party ERP systems
externalInvoiceGUID An optional GUID that identifies a particular invoice that may appear on more than one transaction
externalTransactionDateTime An optional date and time the transaction was generated on the 3rd party ERP systems.
Has the format of “yyyy-MM-dd'T'HH:mm:ss”
externalTerminalId An optional terminal identifier for device configured on the 3rd party ERP system
latitude An optional geolocation identifier indicating the latitude position of the device
longitude An optional geolocation identifier indicating the longitude position of the device
accuracy An optional accuracy indicator of the geolocation
transactionUuid Unique ID provided from 3rd party integrators.
Format: UUID version 4

Note: If the field was not populated by the 3rd party integrator a system generated transaction UUID will be assign for every new transaction.

Sample code

private String appURL = "payment.thumbzup.com";
private String appClass = "payment.thumbzup.com.IntentActivity";

Intent intent = new Intent();
intent.setClassName(appURL, appClass);

Bundle dataBundle = new Bundle();
dataBundle.putString("launchType", "REFUND");
dataBundle.putString("applicationKey", "2fdca02f-3cbe-4e8c-82ad-86a1a16b72e7");
dataBundle.putString("merchantID", "910100000000001");
dataBundle.putString("merchantUsername", "default");
dataBundle.putString("authenticationKey", "c282cdd3-59d2-42ff-8c96-826725a27e6e");
dataBundle.putString("originalTransactionUuid", "x282cdd3-59d2-42ff-8c96-826725a27e6z");
dataBundle.putLong("transactionAmount", 10000);

intent.putExtra("thumbzupBundle", dataBundle);
startActivityForResult(intent, 0);

Refunds Response

Parameters

Parameter Description
launchType Echo of the launchType used to launch the Ecentric Payment app.
isApproved Represents the processing result from a card perspective of the transaction. This will indicate whether the refund will occur or not. Valid values are:
● true – card payment will be made by the issuer
● false – card payment failed due to for example invalid PIN
● error – card payment failed due to an unknown error
resultCode Represents the result status of the intent call to the Ecentric Payment app (NOTE: to determine if payment will occur then please use the isApproved field as a definitive answer):
● 01 – transaction successful
● 02 – transaction declined
● 03 – transaction aborted
● 04 – error

This is not a result code from the acquiring bank and should not be made available to the customer at any time. For the Issuer/Acquirer response code, see field RC in the receiptBundle (see 3.6 Additional Server Fields).
resultDescription A user readable representation of the above resultCode
i.e. Approved for 01 resultCode

If the acquiring bank approves or declines the transaction, the response description is included in this field.
merchantName The name of the merchant that requested the transaction as stored at the bank
originalTransactionUuid Echo of the originalTransactionUuid used to launch the Ecentric Payment app
customerName Echo of the customerName used to launch the Ecentric Payment app
applicationKey The 3rd party API key that will be issued by Ecentric specific for every 3rd party application
authenticationKey The authentication token that was generated by the server on a successful login to the Ecentric Payment app
transactionAmount Echo of the transactionAmount used to launch the Ecentric Payment app.
transactionDescription Echo of the transactionDescription used to launch the Ecentric Payment app
transactionUuid Unique ID provided from 3rd party integrators.
Format: UUID version 4

Note: If the field was not populated by the 3rd party integrator a system generated transaction UUID will be assign for every new transaction.
cellNumberToSMSReceipt Masked out value of the cell number used to send the receipt to
i.e. ***657
emailAddressToSendReceipt Masked out value of the email address used to send the receipt to
i.e. **@Ecentric.com
isReceiptRequired Echo of the isReceiptRequired used to launch the Ecentric Payment app
isReceiptDataAvailable A boolean indicating whether a receiptBundle parameter is available. Will always be there for accepted or declined transactions
receiptBundle Consists of a sub-bundle of server parameters that can be used by the partner application. For a full list of these parameters see the Additional Server Fields section
pebbleFirmwareVersion The software version currently running on the Payment Pebble®
pebbleSerialNumber The serial number of the Payment Pebble®
appVersion The software version currently running on the Ecentric Payment app
deviceIMEI The IMEI number of the Payment Blade
externalSTAN Echo of the systems trace number generated by some 3rd party ERP systems
externalRRN Echo of the RRN generated by some 3rd party ERP systems
externalTransactionGUID Echo of the GUID that identifies a specific transaction generated by 3rd party ERP systems
externalInvoiceGUID Echo of the GUID that identifies a particular invoice that may appear on more than one transaction
externalTransactionDateTime Echo of the date and time the transaction was generated on the 3rd party ERP systems. Has the format of “yyyy-MM-dd'T'HH:mm:ss”
externalTerminalId Echo of the terminal identifier for device configured on the 3rd party ERP system
terminalId This is an automatically system-assigned terminalID of the payment terminal’s identity number, which can be used to assist with settlement information and is returned in BASE36 format
latitude Echo of geolocation identifier indicating the latitude position of the device
longitudeEcho of geolocation identifier indicating the longitude position of the device
accuracy Echo of accuracy indicator of the geolocation

Sample code

@Override
protected void onActivityResult(int requestCode, int resCode, Intent data) { 
    String result = "";
    Bundle b = new Bundle(data.getBundleExtra("thumbzupApplicationResponse"));
    
    if(resCode == Activity.RESULT_OK) {
        // handle ok result 
        String launchType = b.getString("launchType");
        String isApproved = b.getString("isApproved");
        String resultCode = b.getString("resultCode");
        String authenticationKey = b.getString("authenticationKey");
        String applicationKey = b.getString("applicationKey");
        String resultDescription = b.getString("resultDescription");
        String merchantName = b.getString("merchantName");
        String originalTransactionUuid = b.getString("originalTransactionUuid");
        String customerName = b.getString("customerName");
        Long transactionAmount = b.getLong("transactionAmount");
        String transactionDescription = b.getString("transactionDescription");
        String transactionUuid = b.getString("transactionUuid");
        String cellNumberToSMSReceipt = b.getString("cellNumberToSMSReceipt");
        String emailAddressToSendReceipt = b.getString("emailAddressToSendReceipt");
        boolean isReceiptRequired = b.getBoolean("isReceiptRequired");
        boolean isReceiptDataAvailable = b.getBoolean("isReceiptDataAvailable");
        String externalSTAN = b.getInt("externalSTAN");
        String externalRRN = b.getString("externalRRN");
        String externalTransactionGUID = b.getString("externalTransactionGUID");
        String externalInvoiceGUID = b.getString("externalInvoiceGUID");
        String externalTransactionDateTime = b.getString("externalTransactionDateTime");
        String externalTerminalId = b.getString("externalTerminalId");
        String latitude = b.getString("latitude");
        String longitude = b.getString("longitude");
        String accuracy = b.getString("accuracy");
        
        if (isReceiptDataAvailable) {
        // this represents extra data from card processing backend 
        Bundle receiptBundle = b.getBundle("receiptBundle");
        Iterator it = receiptBundle.keySet().iterator();
        
        while (it.hasNext()) {
            // go through extra data 
            Object key = it.next(); 
            Object val = receiptBundle.get(key.toString()); }
        }
    }
}