TransactDirect Reporting API

Authentication

Generating an OAuth 2 Access Token

Access Token Validity

Access Tokens are typically valid for 1 hour. This can be confirmed by the expires_in response field indicating 3600 seconds.

Access Tokens should be cached and reused during this period to improve performance and reliability, and to avoid potential request throttling.

Accessing a Monek reporting API requires an OAuth 2 Access Token, which can be obtained using Client Credentials.

The client application can obtain an Access Token using the Monek OAuth endpoint:

https://oauth2.monek.com/oauth2/token

This endpoint requires a POST request. A Basic Authorization header should be present containing the client credentials base64-encoded in the format <client_id>:<secret>.

In addition, the client should include an application/x-www-form-urlencoded body specifying the grant_type and scope as follows.

Name	Value
grant_type	client_credentials
scope	As required by the report API to be requested

Sample OAuth2 Request

The complete auth request should therefore look like this:

POST https://oauth2.monek.com/oauth2/token

 Authorization: Basic <client_id>:<secret> Content-Type:
 application/x-www-form-urlencoded

 grant_type=client_credentials&scope=<reporting-service-scope>

Sample OAuth2 Response

A successful response will include an OAuth2 Access Token, valid for one hour, enabling access to the API.

{ 
    "access_token": "c2FtcGxlX2FjY2Vzc190b2tlbl9oZXJl…", 
    "expires_in": 3600, 
    "token_type": "Bearer" 
} 

TransactDirect Transaction Report

The transaction query API will allow a merchant to query their transaction history for a given date range, Cross Reference, or merchant Payment Reference.

Authentication

Accessing the transaction reporting API requires an OAuth 2 Access Token, which can be obtained using the following grant_type and scope:

Name	Value
grant_type	client_credentials
scope	transactdirect/get-transactions

The OAuth2 Access Token must be specified as a Bearer token in the Authorization header.

GET https://api.monek.com/transactdirect/v1/merchants/{monekId}/
transactions?{querystring}

Authorization: Bearer <oauth2token>

Request Fields

Path Parameters

Field Name	Description	Req'd	Size	Type
monekId	Monek issued merchant ID.	M	7	N

Query String Parameters

Field Name	Description	Req'd	Size	Type
startDateTime	Start date and time for transaction report	M	25 max.	ISO 8601
endDateTime	End date and time for transaction report	M	25 max.	ISO 8601
crossReference	Filters the transaction results by the supplied Monek Cross Reference	O*1	21 max.	A
paymentReference	Filters the transaction results by the supplied Merchant Payment Reference	O*1	50 max.	A
trackingToken	Filters the transaction results by the supplied Tracking Token	O*1	32	A
pageSize	Indicates the maximum number of transactions to be returned. Default: 1,000, minimum: 50, maximum: 5,000	O	V	N
pageNumber	Indicates the page number of the results to retrieve. Used in conjunction with pageSize	O	V	N
newestFirst	If set to True, transaction results will be ordered from newest to oldest. Defaults to False	O	5	B

Notes:

• Only one optional filter parameter should be supplied. If multiple filter parameters are present the most restrictive will be chosen with the following priority: Cross Reference, Payment Reference, Tracking Token.
• The Tracking token used for search must exist on the monekId specified in the path, results will include matching transactions across all related merchants. Tracking tokens only available to select partners.

Example:

GET
https://api.monek.com/transactdirect/v1/merchants/0000018/transactions?startDateTime=20
19-12-04T10:21:10&endDateTime=2019-12-11T10:21:12

Authorization: Bearer eyJraWQiOiJRekQzNVl4TG9tdURhQ...

Response Fields

Field Name	Description	Size	Type
merchant	Monek issued merchant ID	7	N
startDateTime	Start date and time for transaction report	25 max.	ISO 8601
endDateTime	End date and time for transaction report	25 max.	ISO 8601
message	Summary message for report e.g. - Success - Unauthorised	V	A
filterType	Confirms the type of filter used for the report, if any	V	A
filterValue	Confirms the value used to filter the report	V	A
transactionCount	Count of total transactions returned	7	N
pageSize	Page size for this result set	V	N
pageNumber	Page number for this result set	V	N
transactionDetails	Collection of Transaction Details	V	A

Transaction Detail

Field Name	Description	Size	Type
transactionDateTime	Transaction response date and time	33	ISO 8601
requestDateTime	Transaction request date and time	33	ISO 8601
source	The source of the transaction	V	A
transactionType	Transaction type	V	A
dispatch	Deferred dispatch type	5	A
isReversed	Indicates if this transaction was subsequently reversed	5	B
amount	Transaction amount in minor currency	10	N
cashbackAmount	Cashback amount in minor currency	10	N
currencyCode	Transaction currency code	3	N
countryCode	Merchant country code	3	N
idempotencyToken	Merchant supplied unique identifier for transaction	50	A
paymentReference	Merchant payment reference	50	A
paymentChannel	Merchant payment channel	50	A
paymentDetail	Merchant payment detail	1500	A
merchantData	Additional merchant data	1500	A
result	Result Details object	-	-
merchant	Merchant Details object	-	-
subMerchant	Payment Facilitator Sub Merchant Details object	-	-
device	Device Details object	-	-
cardholder	Cardholder Details object	-	-
card	Card Details object	-	-
lineItemData	Line Item Details object	-	-

Result Details

Field Name	Description	Size	Type
crossReference	A unique reference for this transaction	50	A
responseCode	TransactDirect response code	2	N
responseMessage	Transaction response message	80	A
authorisationCode	Authorisation code	2-8	N
avsCv2Code	AVS/CV2 response code	6	N
avsCv2Message	AVS/CV2 response message	30	A
threeDSecure	3-D Secure Details object	-	-
acquirerReference	Acquirer reference number	V	A
auditTrail	Information about linked transactions	V	A
cardToken	A reusable code identifying this card	50	A
trackingToken	A unique tracking token for the card used	32	A
terminalId	Terminal ID used for this transaction	8	N
messageNumber	Transaction message number	4	N

3-D Secure Details

Field Name	Description	Size	Type
enrolled	3-D Secure enrolment status code	1	A
authenticated	3-D Secure authenticated status code	1	A
eci	E-commerce indicator	2	A
cavv	Cardholder authentication value	32	A
transactionId	3-D Secure transaction ID	20	N

Merchant Details

Field Name	Description	Size	Type
monekId	Monek merchant ID	7	N
merchantNumber	Bank issuer merchant number	15	N
acquirer	Acquirer name. Echo+	V	A
name	Merchant name	V	A
location	Merchant location	V	A

Sub Merchant Details

Field Name	Description	Size	Type
subMerchantId	Sub merchant number	15	A
name	Sub merchant name	22	A
address	Sub merchant address	48	A
city	Sub merchant city	13	A
postcode	Sub merchant postcode	10	A
state	Sub merchant state	3	A
countryCode	Sub merchant country code	3	N

Device Details

Field Name	Description	Size	Type
deviceDateTime	Transaction date and time on payment device	V	8601
terminalId	Payment device terminal ID	8	N
messageNumber	Payment device message number	4	N

Cardholder Details

Field Name	Description	Size	Type
name	Cardholder name	30	A
address	Cardholder address	100	A
postcode	Cardholder postal code	10	A
phoneNumber	Cardholder phone number	30	A
emailAddress	Cardholder email address	50	A
iPv4Address	Cardholder ipv4 address	15	A

Card Details

Field Name	Description	Size	Type
maskedCard	Masked PAN	21	A
startDate	Card start date in form YYMM	4	N
expiryDate	Card expiry date in form YYMM	4	N
cardType	Monek card type code	2	A
cardDescription	Card type description	V	A
issuerCountryCode	Card issuing country code where available	3	N

Line Item Details

Field Name	Description	Size	Type
description	Line item data product summary. From QAProducts.	168	A
taxDiscountDescription	Description of tax or discount applied	20	A
discountAmount	Value of discount change to total value	9	N
taxAmount	Value of tax change to total value	9	N
lineItems	Collection of line items	-	-

Line Item

Field Name	Description	Size	Type
description	Description of line item	15	A
grossValue	Gross value of item in minor currency	10	N
quantity	Quantity of item	3	N

Successful Response Example

{ 
    "merchant": "9876543", 
    "startDateTime": "2020-01-01T00:00:00+00:00", 
    "endDateTime": "2020-02-01T00:00:00+00:00", 
    "message": "Success", 
    "filterType": "CrossReference", 
    "filterValue": "200101135257222244XYX", 
    "transactionCount": 1, 
    "pageSize": 1000, 
    "pageNumber": 1, 
    "transactionDetails": [ 
        { 
            "transactionDateTime": "2020-01-01T13:52:57.3698135+00:00", 
            "requestDateTime": "2020-01-01T13:52:56.1946514+00:00", 
            "source": "INTERNET", 
            "transactionType": "ESALE_KEYED", 
            "dispatch": "NOW", 
            "isReversed": false, 
            "amount": "499", 
            "currencyCode": "826", 
            "countryCode": "826", 
            "idempotencyToken": "e04128ad-66ab-4a6c-ae40-bbf4fc91b5ee", 
            "paymentReference": "PayRef23908", 
            "paymentDetail": "UGF5bWVudERldGFpbA==", 
            "merchantData": "QWxzb01lcmNoYW50RGF0YQ==", 
            "result": { 
                "crossReference": "200101135257222244XYX", 
                "responseCode": "00", 
                "responseMessage": "AUTH CODE:222244", 
                "authorisationCode": "222244", 
                "avsCv2Code": "222800", 
                "avsCv2Message": "ALL MATCH", 
                "trackingToken": "c37e041d129a43e58b330f8a71bb7f87", 
                "terminalId": "22080001", 
                "messageNumber": "0858" 
            }, 
            "merchant": { 
                "monekId": "9876543", 
                "merchantNumber": "0123456789", 
                "acquirer": "Monek", 
                "name": "Test Merchant", 
                "location": "Lichfield" 
            }, 
            "cardholder": { 
                "name": "Mr Smith", 
                "address": "12 High Street", 
                "postcode": "B1 2BC" 
            }, 
            "card": { 
                "maskedCard": "453979******0106", 
                "expiryDate": "2212", 
                "cardType": "VD", 
                "cardDescription": "Visa Debit", 
                "issuerCountryCode": "826" 
            }, 
            "lineItemData": { 
                "lineItems": [ 
                    { 
                        "description": "Goods", 
                        "grossValue": "499", 
                        "quantity": "1" 
                    } 
                ] 
            } 
        } 
    ] 
} 

Unauthorised Example

{ 
    "message": "Unauthorized" 
}