Transaction Reporting API

This API endpoint allows clients to inform Empello of the transaction outcome after the token has been validated. This may be because a client wishes to see subscription statistics per FraudStop service/merchant or perhaps it is mandated by the operator instigating the FraudStop programme.

Implementing the transaction API

Implementing the API is very straightforward. Whenever a transaction or subscription is completed (successful or unsuccessful) then send the following fields to this URL https://antifraud.empello.net/api/v2/transaction-report/:

Field	Description	Example(s)	Required
api_key	API Key given to you by your account manager	WNvzp9tVtPsvQi	Required
token	The token code of the transaction being reported	ukewxhz...mnjznqa	Required
msisdn	The MSISDN associated with the transaction. Ideally encrypted.	56931111111 or abcPL4wSLQFwQ==	Not required
activation_successful	Was the service activated successfully? (previously called consumer_billed)	True, False	Required
failure_reason	If the consumer was not billed, what is the reason for not billing? This must be a string from the provided list of failure reasons (see below)	no_credit, child_bar, blacklisted_msisdn	Not required
price_point	Use price point strings provided by your account manager	10.00GBP	Optional
billing_frequency	Use billing frequency strings provided by your account manager	Weekly, Daily	Optional
shortcode	The shortcode used to bill this transaction	111111	Optional
external_user_id	Use this to store the user ID from your side against this transaction (128 character max)	550e8400-e29b-41d4-a716-446655440000	Optional
external_product_id	Use this to store the product ID from your side against this transaction (128 character max)	myservice-127320	Optional

Here is an example cURL request:

curl --location -X POST https://antifraud.empello.net/api/v2/transaction-report/ \
--form api_key="myuniqueapikey" \
--form consumer_billed="true" \
--form token="ukgxydsxrogqgioblcrkolllrbgbmkhphykypupahkclhzztnhzygqrotxlrjwrz" \
--form price_point="5.00" \
--form billing_frequency="weekly" \
--form shortcode="1111" \
--form msisdn="10000000001"\
--form external_user_id="550e8400-e29b-41d4-a716-446655440000"
--form external_product_id="myservice-127320"

The API will respond with:

Field	Value	Required
status	HTTP status eg 200 for a success	Required
success	Boolean value, if 0 then an error has occurred	Required
message	Success or error message output	Required

It is possible to send updates about a token, for example if a transaction is retried an hour later and is successful. Once a successful transaction has been reported against a token it will always be reported as a successful transaction. Tokens can only be updated for up to one week after they have been created.

Failure Reasons

In the failure_reason field, please use the strings in the reason column to describe the failure.

Reason	Description
no_credit	Transaction could not be performed due to low credit
vas_bar	This MSISDN is barred from accessing VAS services
blacklisted_msisdn	This MSISDN has been blacklisted by the merchant, aggregator or network
child_bar	This is an adult service and cannot be purchased by this MSISDN
technical_fault	A technical error means the transaction was not completed
billing_frequency	This MSISDN has had too many attempted or successful transactions
service_suspended	This service has been suspended and is not currently allowed to bill consumers