MXConnect API Authentication Instructions
Guidelines to show the process for proper Authentication while using MXConnect APIs
Authentication
MX™ Connect uses a JSON Web Token to authorize calls made to the APIs. To receive a JWT, you will need to call the Security API with your MXC username and password, receive the JWT in the response and use this JWT to make further calls to the MXC APIs.
What is a JWT?
JSON Web Tokens are an open, industry-standard RFC 7519 method for representing claims securely between two parties. Click here to learn more about JWTs
Secure your API_Key
Using your MX™ Connect user, sign in to the application and click on your username in the top right. Select My Account > API Keys > +Add API Key. Enter a name that you wish to use to identify your user's API Key and press Generate Key. Copy the value that appears in the modal as it will only be available in this modal once. Use this API_XXXXX value in the body of the following API Call.
- This API_Key is a static value and is to be reused as you authorize against the Security API.
Get a JWT from Security API
POST your API_Key to the Security API endpoint indicated below. Use your base64-encoded MX™ Connect username and password as the Basic Authorization header for this API call:
https://api.mxconnect.com/security/v1/apiKey/authenticate
{
"value": "API_key-value"
}
{
"token": "a-long-string.in-multiple-parts.separated-by-periods"
}
JWT Expiration
The JWTs delivered through the Security API have a ten-minute lifespan after they are created. As the JWT expires, you will need to repeat the call above and get a new JWT.
Using a JWT with MXC APIs
Use the JWT from the Security API to transact further requests against MX™ Connect API resources. The JWT will need to be included as the Bearer Token Authorization header.
As an example:
You may recall Authorizations from the processor on your accounts with the following call:
GET to https://api.mxconnect.com/report/v1/tsys/authorization?size=10&from=0&dr_quick=weekToDate&accountNumbers=["XMID_value01","XMID_value02"]
{
"aggregations": {
"totalAmount": {
"value": 11.11
}
},
"totalRecords": 1,
"recordCount": 1,
"records": [
{
"accessMethod": "MX",
"accessMethodDescription": "Internet - VirtualNet SSL",
"accountFundingSourceDescription": "N/A",
"accountId": "accountId_value",
"accountNumber": "xmid_value",
"acl": [
"xmid:xmid_value",
"domain:domain_value",
"domain:00000000-0000-0000-0000-000000000001",
"domain:00000000-0000-0000-0000-000000000002",
"domain:domain_value_2"
],
"acquirerBin": "6_digit_card_bin_value",
"acquirerCountryCode": "840",
"additionalDataPrivateRequest": "!010",
"additionalDataPrivateResponse": "!010",
"additionalPosInformationText": "760000000001",
"agent": "000000",
"approvalCode": "NNNNNN",
"asciiBillCode": "L",
"authorizationResponse": "00",
"authorizationResponseDescription": "Approved or completed successfully",
"authorizationResponseStatus": "Approved",
"authorizedAmount": 11.11,
"businessType": "Retail",
"cardAcceptorCity": "City",
"cardAcceptorCountryCode": "US",
"cardAcceptorId": "000000000000",
"cardAcceptorState": "State",
"cardAuthenticationResultDescription": "Card authentication was not performed",
"cardExpirationDate": "1111",
"cardNumber": {
"data": "hash_value",
"hash": "hash_value",
"mask": "last_four"
},
"cardType": "Card_Brand",
"cardholderBillingAmount": 11.11,
"cardholderBillingConversionRate": "000000000",
"cardholderBillingCurrencyCode": "840",
"cashBackAmount": 0,
"cavvResultDescription": "CAVV not present or not validated",
"chain": "000000",
"created": "2019-11-07T09:33:32.559-05:00",
"cvvResultDescription": "CVV was not verified",
"dialPayAuthorizationCallTypeDescription": "Not a Dial-Pay Authorization",
"domain": {
"id": "00000000000",
"name": "DBA_Name",
"chain": [
"00000000000",
"00000000-0000-0000-0000-000000000001",
"00000000-0000-0000-0000-000000000002"
]
},
"econnectionMerchantNumber": "000000000000000",
"endpointCode": "M",
"endpointDescription": "Card_Brand",
"entityId": "0000000000",
"ex02AuthorizationIndicator": "F",
"ex02TransactionIntegrityClass": "B1",
"ex02TransactionIntegrityClassDescription": "EMV/Chip Equivalent",
"ex03CardholderVericationMethodResults": "1E0300",
"ex03TerminalVerificationResults": "8000008800",
"extBin": "00000",
"extEndpointPOSData": "00000000003",
"extEndpointPOSMastercardCardCaptureCapabilities": "0",
"extEndpointPOSMastercardCardCaptureCapabilitiesDescription": "Terminal/operator has no card capture capability",
"extEndpointPOSMastercardCardDataTerminalInputCapability": "3",
"extEndpointPOSMastercardCardDataTerminalInputCapabilityDescription": "Contactless M/Chip (Proximity Chip). Terminal supports contactless M/Chip and contactless magnetic stripe transactions. The terminal also may support other card input types, including contact transactions",
"extEndpointPOSMastercardCardPresence": "0",
"extEndpointPOSMastercardCardPresenceDescription": "Card present",
"extEndpointPOSMastercardCardholderActivatedTerminalLevel": "0",
"extEndpointPOSMastercardCardholderActivatedTerminalLevelDescription": "Not a CAT transaction",
"extEndpointPOSMastercardCardholderPresence": "0",
"extEndpointPOSMastercardCardholderPresenceDescription": "Cardholder present",
"extEndpointPOSMastercardTerminalAttendance": "0",
"extEndpointPOSMastercardTerminalAttendanceDescription": "Attended Terminal",
"extEndpointPOSMastercardTerminalLocation": "0",
"extEndpointPOSMastercardTerminalLocationDescription": "On premises of card acceptor facility",
"extEndpointPOSMastercardTransactionSecurity": "0",
"extEndpointPOSMastercardTransactionSecurityDescription": "No security concern",
"extEndpointPOSMastercardTransactionStatus": "0",
"extEndpointPOSMastercardTransactionStatusDescription": "Normal request (original presentment)",
"extExpandedBillingClass": "L0",
"extIssuerCountryCode": "USA",
"extServiceCode": "201",
"fallbackIndicatorDescription": "No Fallback",
"fileId": "0000-00000",
"filePath": "/frame/processor/archive/year/file.type.date.detail",
"fileType": "processor.type",
"id": "00000000-0000-0000-0000-000000000000",
"industry": "Industry",
"isoSourceStationID": "000000",
"issuingBinLookup": "N",
"issuingInstitutionStationID": "000000",
"julianDay": "311",
"labels": [
"domain:00000000000",
"domain:00000000-0000-0000-0000-000000000001",
"domain:00000000-0000-0000-0000-000000000002",
"label:label4",
"label:label5",
"product:3",
"label:label7",
"label:sales_rep",
"label:label_guid",
"label:processing",
"label:special_services",
"label:label12"
],
"localTransactionDate": "1107",
"localTransactionTime": "055548",
"locationAddressCity": "City",
"locationAddressCountry": "United States",
"locationAddressPostalCode": "00000",
"locationAddressState": "State",
"locationId": "location_id",
"mccCode": "5462",
"merchantName": "DBA Name",
"messageType": "0100",
"messageTypeDescription": "Authorization requests / balance inquiries",
"name": "DBA Name",
"nationalPosGeographicData": "0000000000",
"posCardDataInputCapability": "M",
"posCardDataInputCapabilityDescription": "PAN auto-entry via contactless chip",
"posCardDataInputMode": "C",
"posCardDataInputModeDescription": "Online Chip",
"posCardDataOutputCapability": "3",
"posCardDataOutputCapabilityDescription": "ICC",
"posCardHolderAuthCapability": "1",
"posCardHolderAuthCapabilityDescription": "PIN entry capability",
"posCardHolderAuthEntity": "4",
"posCardHolderAuthEntityDescription": "Merchant/card acceptor - signature",
"posCardHolderAuthMethod": "5",
"posCardHolderAuthMethodDescription": "Manual signature verification",
"posCardHolderPresentData": "0",
"posCardHolderPresentDataDescription": "Cardholder present",
"posCardPresentData": "1",
"posCardPresentDataDescription": "Card present",
"posConditionCode": "00",
"posConditionCodeDescription": "Normal transaction of this type",
"posEntryMode1": "05",
"posEntryMode1Description": "Integrated circuit card read; CVV data reliable.",
"posEntryMode2": "10",
"posPinCaptureCapability": "C",
"posPinCaptureCapabilityDescription": "PIN capture capability 12 characters maximum",
"posTerminalCardCaptureCapability": "0",
"posTerminalCardCaptureCapabilityDescription": "No capture capability",
"posTerminalDataOutputCapability": "4",
"posTerminalDataOutputCapabilityDescription": "Printing and display capability",
"posTerminalOpEnvironment": "1",
"posTerminalOpEnvironmentDescription": "On card acceptor premises; attended terminal",
"processingCode": "000000",
"responseReasonDescription": "Issuer Generated Response (Visa only)",
"retrievalReferenceNumber": "reference_number",
"runId": "00000000-0000-0000-0000-000000000000",
"sector": "Retail Trade",
"settlementDate": "1107",
"sic": "5462",
"storeNumber": "0000",
"systemsTraceAuditNumber": "000000",
"terminalNumber": "0000",
"transactionCurrencyCode": "840",
"transactionData": "NN00NN00",
"transactionDate": "2019-11-06T19:00:00.000-05:00",
"transactionDateAndTime": "2019-11-07T07:55:49.000-05:00",
"transactionIdentifier": "Identifier",
"transactionSourceFlag": "002",
"transactionTime": "12:55:49",
"tsysTokenIndicator": "N",
"uar": {
"account": {
"id": "accountId_value",
"platform": "crm",
"number": "xmid_value",
"entityId": "0000000000",
"origin": "crm",
"sponsor": {
"application": "Processor",
"bin": "card_bin_value",
"fullName": "sponsor bank",
"ica": "0000",
"id": "0",
"name": "sponsor bank"
},
"associations": {
"headOffice": {
"accountNumber": "0.00000",
"name": "head_office name"
},
"portfolio": {
"accountNumber": "0.00000",
"name": "partner Name"
},
"salesRep": {
"accountNumber": "sales_rep",
"name": "sales_rep_name"
}
},
"processor": {
"bankNumber": "0000",
"id": "0",
"name": "processor",
"platform": "processor"
},
"status": "Approved",
"active": true,
"businessType": "Retail",
"events": {
"approved": {
"date": "2017-07-26T10:33:00.000-04:00"
},
"draft": {
"date": "2017-07-26T10:33:00.000-04:00"
},
"received": {
"date": "2017-07-26T10:33:00.000-04:00"
}
},
"product": {
"name": "processor",
"id": "p_id"
},
"labels": [
"domain:00000000000",
"domain:00000000-0000-0000-0000-000000000001",
"domain:00000000-0000-0000-0000-000000000002",
"label:label4",
"label:label5",
"product:3",
"label:label7",
"label:sales_rep",
"label:label_guid",
"label:processing",
"label:special_services",
"label:label12"
],
"research": {
"risk": {}
}
},
"entity": {
"id": "0000000000",
"address": {
"street1": "1111 Main St",
"city": "City",
"state": "State",
"country": "United States"
},
"jurisdiction": {
"id": "1",
"country": "United States",
"established": "2017-07-25T20:00:00.000-04:00",
"kind": "Business_Type",
"name": "Partner",
"type": "General"
},
"taxId": {
"number": {
"hash": "hash_value"
}
}
},
"location": {
"id": "location_id",
"address": {
"street1": "1111 Main St",
"city": "City",
"state": "State",
"country": "United States"
},
"sic": "5462",
"industry": "Industry",
"sector": "Retail Trade",
"name": "DBA Name"
}
},
"user": "Transaction_Initiator",
"varTrackID": "000000000",
"vendorID": "00000"
}
]
}
Updated over 3 years ago