Token Generation

Description

Generates a token that authorize the usage of Reporting API. It is the intention that some tokens are made to be shared and public, while some are made to be secret. Tokens that have larger access (tokens that can read data for any child of a merchant) should only be used from a gateway to our API. These tokens are tokens that would be generated by using a parent login that has access to child merchants. Tokens that have specific security set to only read for one merchant can be shared and placed into iframes on portals and these would be created by providing the MID for the child merchant and either the child password or parent password (which has access to children).

Secure Tokens with Overrides to run Reports

When generating a token to run a report it is possible to use overrides for parameters or settings for the intended report(s). Anything that is included within an override is encoded in the token and essentially locks this value when trying to use the token to run a report. If a parameter or setting is not provided in an override it is possible for a user to alter the query string and retrieve different reports results by providing different values for parameters or settings.

Override Types

Overrides can be of two types: report settings or parameters. Report settings overrides Possible options are: Action, ReportPermDesc, OutputType, ReportXSLTPermDesc, Tags, DecodeCSS. To include overrides of this type, use the format of OVERRIDE_SettingName= settingvalue Example using action: &OVERRIDE_Action=Report Parameter overrides This type of override is any parameter for the given report and can be found in the report definition. To include overrides of this type, use the format OVERRIDE_Param_ParamName = ParamValue Example using parameter override: &OVERRIDE_Param_MID=999011

If a token is generated using the parent MID and parent password and the child MID is not set as an override, then the token would have access to any of the child merchants and a malicious user could change the query string and retrieve results for any of the children merchants.

Best Practices

When generating tokens for reports it is highly recommended to get the token using the child MID and child password or aggregator password and to also provide an override for the child MID and an override for action equal to Report at a minimum. Minimum suggested overrides: &OVERRIDE_Action=Report&OVERRIDE_Param_MID=ChildMID

When a token is created it has an expiration date of 72 hours.

Endpoints

URL

Type

/EpnAPI/Security.aspx

CGI

Query Parameters

Name

Required

Values

Username

Yes

Provided by CheckCommerce

Password

Yes

Provided by CheckCommerce

Action

Yes

Token

OutputType

No

XML or JSON. If not provided the default is XML

Response Properties

Parameter

Values

Method

Token

Version

1.4.2.24, the version of the API that you are using.

Severity

0 Is Success, any other value is a failure

Success

Boolean True or False

Message

“Success”, or a message indicating the error

Token

The Token response, if the call was successful

Request Samples

JSON

Request

/EpnAPI/Security.aspx?&UserName={MerchantNumber}&Password={MerchantPassword}&Action=Token&OutputType=JSON

Response

{
  "Method": "Token",
  "Version": "1.4.2.24",
  "Severity": "0",
  "Success": "True",
  "Message": "Success",
  "Token":
  "f84LLM4Q/gvVr7PEpMp+iWzIjVgLtXLx0cRnX15MafcGlwvUM2dzF1CU3qA0Khep9dnOA7CrSulRUNNz9
  2eJZrthMN9IcDx/+1adVoRO5BaUkO7SpCUZfYiNha0/jaqWzUW7Gi2iH+KG8pG9BqbYt14/OO68OqozFyH
  av4aGnAbDWy5vg0Seo4vS0TAXcPKSodV56HJkGIW9+MY/e/IoCVxhPuYuZnmeZjLylsTVwDYfu1tGSWPqj
  CdlW6gj6YQP"
}

XML

Request

/EpnAPI/Security.aspx?&UserName={MerchantNumber}&Password={MerchantPassword}&Action=Token&OutputType=XML

Response

<Response Method="Token" Version="1.4.2.24" Severity="0" Success="True">
	<Message>Success</Message>
	<Token>
      1YN4tpfMWWxA7P/hzNYgXxec1mBcT5l0PuwIzNye767ShuNnRMGYYPjSYP1ot3PqfL+koF5mvx8//3Rgop
      uDp2jXDYlakofNZZCbsnwaECR6IlVAUdI2xT977y5PTDeCNGGFvv3Pfkzcss2x39r4CWrlNIcAKwB7cUJB
      o8h4v6QfA2yPneGn0/wtQVgmsjrd1+ga6V4whvBYf+rvkUET+TGBvs1qp5PhsJFR9Fcpagk=
    </Token>
</Response>

Headers

The output will be directly streamed out. Included with that will be encoded HTTP Headers containing the message status information.

Message:Success
Method:Token
Severity:0
Success:True
Token:qXDzh0e/vwIZ8mgA=
Version:1.4.2.24

SDK Example

using CheckCommerce.SDK.ActiveReports;

string token = Token.GetToken("{MerchantNumber}", "{MerchantPassword}");

Search