Introduction

Webhook provides a server-to-server messaging system that facilitate communication regarding various transaction types and agreement-related changes. The service enables your systems to receive notifications about important events such as refunds or voids or agreement modifications.

You have the flexibility to choose the specific transaction types or agreement actions you want to receive messages for. Once selected, the webhook service will deliver relevant information for selected actions. These events may include transactions processed through payment processing APIs like Hosted Payment Pages or Remote, manually processed transactions through the Merchant Administration System or agreement-related changes made via the system or API or when the Payout happens.

Each message is transmitted as an HTTP POST request to a pre-configured URL.

Service configuration

To configure webhook notifications, navigate to the Merchant Administration System and select either the ‘Payment Page’ or ‘Security’ menu, and click on the ‘Transaction advice’ option.

This will display the configuration page, where you can specify the transaction types or agreement action for which you want to receive notifications You can also choose to receive messages only for transactions which have been authorised (transaction status A or H)

📘
In case "Only include authorised transactions (status 'A' or 'H')" option is not selected, then decline transaction data will also be sent along with authorised entries.

You will need to supply the URL that is to be used by the advice service. This URL must use either the HTTP or HTTPS protocol and must be on either port 80 or port 443. The connection that is made to the URL is a direct server-to-server connection, there is no browser involved in the request. The URL used must be accessible over the internet.

Message format

Transaction-Related Webhooks

Transaction-related webhooks are sent using the HTTP POST method and contain the following fields:

Field	Description
tran_store	Your store ID
tran_type	Transaction type. See the transcation type and class lists below.
tran_class	Transaction class
tran_test	Test mode (0 = Live transaction, 1 = Test)
tran_ref	Transaction reference
tran_prevref	Reference for previous transaction. For transactions which are a follow-up transaction, such as a void, this contains the transaction reference of the transaction being voided. For an initial transaction, such as a sale or auth, this will be the same as the tran_ref.
tran_firstref	Reference for the first transaction in a sequence. For example if refund is being performed on a capture transaction, this will contain the reference to the initial auth transaction.
tran_order	Order Reference. This parameter is relevant whenever the payment link is generated using the 'order.json' API. Please note this field is not sent by default. If you need the order reference in the response, please contact our support.
tran_currency	Transaction currency as 3 character ISO code
tran_amount	Transaction amount
tran_cartid	Cart ID
tran_desc	Purchase description
tran_status	Transaction status. ‘A’ or ‘H’ indicate an authorised transaction. Any other value indicates that the request could not be processed. Transactions with status H have been authorised but are on hold.
tran_authcode	Authorisation code. If the transaction was authorised, this contains the authorisation code from the acquirer. Otherwise it contains an error code. See the response codes section for more details.
tran_authmessage	Authorisation message
tran_check	Data signature check. See the section on data security below.
card_code	Card identifier two digit code
card_payment	Type of payment used
bin_number	Card Bank Identification Number (BIN) used to identify the issuing bank and card type.
card_issuer	Name of the bank issued the card.
card_country	Card country name identified by a two-letter ISO country code.
card_last4	The last four digits of the card number, often used for verification purposes.
cart_lang	Language code used for the checkout process
integration_id	Integration setup identifier. Identifier for the integration setup or type of integration used to connect with the payment gateway.
actual_payment_date	Date and time of the payment
bill_title	Title (Mr, Mrs, etc)
bill_fname	Forenames
bill_sname	Surname
bill_addr1	Street address – line 1
bill_addr2	Street address – line 2
bill_addr3	Street address – line 3
bill_city	City
bill_region	Region/State
bill_country	Country as 2 character ISO code
bill_zip	Zip/Area/Postcode
bill_phone1	Phone number
bill_email	Email address
xtra_	Extra data fields from the authorisation.

Transaction types

Type	Details
Sale	A standard online transaction. If authorised the relevant amount will be debited from the customers’ card.
Void	A method used to cancel a sale transaction. This can only be done within a short time after the sale transaction was processed. The void amount is always the same as the original sale amount.
Refund	Used to credit an amount back to the customer. The refund amount may be the same as or less than the original Sale amount.
Refund Reversal	This can be used to cancel a refund, and can only be done within a short time after the refund was processed. Not all acquirers support this transaction type.
Auth	A pre-authorisation transaction. This is similar to a sale, but the amount is not immediately debited from the customers’ card. Instead the amount is reserved on that card, and can then be debited at a later date using a capture transaction. Until the capture transaction is processed, no funds will be debited. Release used to release any funds that have previously been reserved by an auth transaction. No funds are debited from the card, and the capture option can no longer be used.
Capture	Used to debit funds that have been previously reserved using an auth transaction. This completes the transaction processing.
Capture Reversal	This can be used to cancel a capture transaction, and can only be done within a short time after the capture was processed. Not all acquirers support this transaction type.

In some situations, a transaction may be changed from a Sale to an Auth. If, for example, the original transaction request was for a Sale but the anti-fraud system has flagged the transaction for inspection then it may be converted into an Auth transaction which then requires a Capture in order to be completed.

If your system uses the Sale transaction method, then you should also allow for advice messages relating to Auth, Capture and Release transactions.

Card codes

Code	Card Type
VC	Visa Credit
VD	Visa Debit
VE	Visa Electron
VP	Visa Corporate Purchasing Card
VB	Visa Corporate
MC	Mastercard Credit
MD	Mastercard Debit
MA	Mastercard Maestro
MM	Mada
AM	American Express
AP	American Express Corporate Purchasing Card
DN	Diners Club
JC	JCB
DS	Discover
A1	Applepay Visa
A2	Applepay Mastercard
A3	Applepay Amex
A4	Applepay Discover
A5	Applepay JCB
A6	Applepay Mada
S1	Samsungpay Visa
S3	Samsungpay Amex
S2	Samsungpay Mastercard
S4	Samsungpay Discover
S5	Samsungpay JCB
S6	Samsungpay Mada
PP	Paypal
SP	STC Pay
TB	Tabby
UP	Union Pay
UR	UR Pay
JP	Jeel Pay
ED	Sadad Bill

Transaction class codes

Code	Transaction Type
ecom	E-Commerce
moto	Mail Order / Telephone Order
cont	Continuous Authority

Agreement-Related Webhooks

Agreement-related webhooks are also sent using the HTTP POST method and contain the following fields:

Field	Description
type	Agreement Type
agreement_id	Unique identifier for the agreement.
action	Action performed on the agreement
store_id	Store ID
change_by	Who is updating the action
timestamp	Timestamp of the action
cancellation_reason	Reason for cancellation
cancellation_document_received	Indicates if cancellation document is received
email_id	Customer Email ID
freeze_start_date	Start date of the freeze period
freeze_end_date	End date of the freeze period
new_store_id	Agreement transferred to which store
due_date	Next payment date
description	Description of the agreement
cart_id	Cart ID
customer_id	Customer ID
subscription	Subscription type
transaction_id	Transaction ID
phone	Customer phone number
amount	Regular amount
overdue_amount	Overdue amount

Agreement Actions

Action	Fields Required
CHANGE_DATE	due_date, email_id
CHANGE_DETAILS	description, cart_id, customer_id, subscription, transaction_id, email_id, phone, cancel_date, cancellation_reason, cancellation_document_received, amount, overdue_amount
FREEZE	freeze_start_date, freeze_end_date
STORE_TRANSFER	new_store_id, email_id
CANCEL	cancellation_reason, cancellation_document_received, email_id

📘
Other fields in the agreement-related webhooks are not included as they are common fields applicable to all actions.

Payout-Related Webhooks

Payout webhooks are sent via HTTP POST and are triggered for enabled stores when a payout occurs. Each webhook includes the following fields:

Field	Description
type	Indicates the request relates to an account-level operation (fixed value: ACCOUNT)
action	Defines the action being performed (fixed value: PAYOUT)
account_id	Used to identify the account in which the merchant is receiving the payout
store_id	Your store ID
payout_id	Unique identifier for the specific payout transaction
amount	The payout amount being settled
currency	Payout currency as 3-character ISO code
date	The date of the payout
payout_interval	Indicates the payout frequency
payout_fee	Fee charged for this payout
account_check	Data signature check for security validation. See the section on data security below.

Message delivery

The webhook will be generated as soon as the transaction processing has been completed or an agreement action is completed. If there is an error while attempting to deliver the message, then there will be a short delay and a second attempt will be made. 3 attempts in total will be made with 5 second delay between each attempt.

Your systems must indicate successful receipt of the message by using the HTTP 200 OK response code. Other response codes will be treated as a failure and the message will be repeated.

Data security

To authenticate a webhook message, a SHA1 hash check can be done using key transaction, card, billing information, agreement or account fields. The process includes these steps:

Concatenate Field Values: Combine the values of the specified fields using the secret key, separating each value with a colon (:). Make sure not to include the labels.

<secretkey>:<tran_store>:<tran_type>:<tran_class>:<tran_test>:<tran_ref>:<tran_prevref>:<tran_firstref>:<tran_currency>:<tran_amount>:<tran_cartid>:<tran_desc>:<tran_status>:<tran_authcode>:<tran_authmessage>

<secretkey>:<card_code>:<card_payment>:<bin_number>:<card_issuer>:<card_country>:<card_last4>

<secretkey>:<bill_title>:<bill_fname>:<bill_sname>:<bill_addr1>:<bill_addr2>:<bill_addr3>:<bill_city>:<bill_region>:<bill_country>:<bill_zip>:<bill_email>:<bill_phone1>

📘
'agreement_check' (Type is always AGREEMENT and action can be any of the following :CHANGE_DATE/ CHANGE_DETAILS/ FREEZE/ STORE_TRANSFER/ CANCEL)

<secretkey>:<type>:<agreement_id><action>:<due_date>:<email_id>:<store_id>:<change_by>:<timestamp>

<secretkey>:<type>:<agreement_id><action>:<description>:<cart_id>:<customer_id>:<subscription>:<transaction_id>:<email_id>:<phone>:<cancel_date>:<cancellation_reason>:<cancellation_document_received>:<amount>:<overdue_amount>:<store_id>:<change_by>:<timestamp>

<secretkey>:<type>:<agreement_id><action>:<freeze_start_date>:<freeze_end_date>:<store_id>:<change_by><timestamp>

<secretkey>:<type>:<agreement_id><action>:<new_store_id>:<email_id>:<store_id>:<change_by>:<timestamp>

<secretkey>:<type>:<agreement_id><action>:<cancellation_reason>:<cancellation_document_received>:<email_id>:<store_id>:<change_by>:<timestamp>

<secretkey>:<type>:<action>:<account_id>:<store_id>:<payout_id>:<amount>:<currency>:<date>:<payout_interval>:<payout_fee>

If any field value is missing, use an empty value in its place in the concatenated string.
Convert any percent-encoded characters (e.g., %20) to their corresponding characters.

Generate the SHA1 Hash: After concatenating the values, create the SHA1 hash of the resulting string.
Compare Hashes: Match the generated hash with the ones in the tran_check, card_check, bill_check fields respectively. This confirms the transaction’s integrity and authenticity.

📘
'tran_order' is not sent by default. If you need the order reference in the response, please send a request to support@telr.com. If 'tran_order' is enabled, then its value needs to be placed like <tran_firstref>:<tran_order>:<tran_currency>

Message authentication - PHP example

This is an example of authenticating a transaction advice message using the method described in the Data security section.

function SignData($post_data,$secretKey,$fieldList) {
  $signatureParams = explode(',', $fieldList);
  $signatureString = $secretKey;
	
  foreach ($signatureParams as $param) {

    if (array_key_exists($param, $post_data)) { 
      $signatureString .= ':' . trim($post_data[$param]);
    } else {
      $signatureString .= ':';
    } 
	}
	return sha1($signatureString); 
}

$secret_key='[Your Secret Goes Here]';

// Create a check value based on the secret key and the data received.
// To make the following more readable, the field list has been split over two lines
$check=SignData($_POST,$secret_key, 'tran_store,tran_type,tran_class,tran_test,tran_ref,tran_prevref,tran_firstref,tran_order,tran_currency,tran_amount,tran_cartid,tran_desc,tran_status,tran_authcode,tran_authmessage'

// Check that the signature in the message matches the expected value
if (strcasecmp($_POST['tran_check'],$hash_check)!=0) {
	// Hash check does not match. Data may have been tampered with. 
  die('Check mismatch');
}
                
// Hash check OK, use details supplied in POST data to determine what action to take 
// tran_status:
// A = Authorised, H = Authorised but on hold, any other character = not authorised