Authenticating Terminals
At Poynt we think of a merchant as an entity that can have multiple stores (or locations) with multiple payment terminal at each location. Therefore when we onboard a new merchant we create a BUSINESS object contains one or more STORE objects which in turn can contain 0 or more STOREDEVICE objects (another name for terminal):
With this in mind we wanted to give developer flexibility on setting pricing for their apps based on a per terminal, per store or per business basis.
If your application has it’s own authentication mechanism (e.g. username and password) and multiple pricing tiers at some point you may need to ensure that the Poynt terminal your application runs has an active billing agreement for the right service tier.
To do that you would have to perform the following steps
- Make a getSubscriptions call on the terminal
- Compare the businessId that you received in the getSubscriptions response to the businessId of the current terminal. (Pease note that if your subscription is at the store level or terminal level you would also have to make sure storeIds and deviceIds match)
There are a couple of ways your application can find out terminal’s storeId and businessId:
Using IPoyntBusinesService
You can call IPoyntBusinessService.getBusiness() to get a Business object. The business object will contain an array of Store objects with only one element - the current store. The Store object will contain an array of StoreDevice objects again with only one element - the current terminal.
{
"mcc" : "5812",
"sic" : "5812",
"legalName" : "Dennis's Biz",
"businessUrl" : "",
"doingBusinessAs" : "the poynt shop",
"timezone" : "America/Los_Angeles",
"acquirer" : "CHASE_PAYMENTECH",
"attributes" : {
"tipScreenTimeoutInMilliSecs" : "4000",
"automaticSettlementTime" : "2330",
"validatePANForManualEntry" : "0",
"merchantContactLastName" : "Smith",
"customScreenBrightness" : "0",
"purchaseAction" : "AUTHORIZE",
"tipType2" : "P",
"lodgingPromptTotalStayAmount" : "1",
"maxOfflineTotal" : "10000",
"receiptScreenTimeoutInMilliSecs" : "3000",
"enableHqAdjustments" : "1",
"signoutAfterTransaction" : "0",
"closingTime" : "",
"defaultScreenBrightness" : "-1",
"enableAdvancedCatalog" : "0",
"showCustomTipByDefault" : "0",
"enableBalanceInquiry" : "0",
"skipSignatureAmount" : "2500",
"reportingContactEmail" : "dennis+joesfoodtruck2@poynt.co",
"defaultScreenOffTimeoutInSecs" : "-1",
"lodgingEnableFolio" : "0",
"merchantBackgroundImageUrl" : "",
"enableIosTransactionVolumeYDay" : "1",
"disableOrderAutoClose" : "0",
"disableDebit" : "0",
"stopAfterCardReadRecords" : "0",
"enableNotTransactedEmails" : "1",
"tipPercent1" : "15",
"enablePoyntStoreApp" : "0",
"enableAlphanumericZip" : "0",
"enableDiscover" : "0",
"enableManualEntryNRR" : "0",
"disableEMVCT" : "0",
"hideCustomerWelcomeMessage" : "0",
"hideCustomerPaymentIcons" : "0",
"verifySignature" : "0",
"disablePaperReceipt" : "0",
"autoCapture" : "0",
"enableInsertCardAPI" : "0",
"disableEMVCLDebit" : "0",
"automaticReportsTypes" : "TRANSACTIONS,ITEMS",
"merchantContactFirstName" : "Dennis",
"enableEBT" : "0",
"tipType3" : "P",
"enableQuickbooks" : "1",
"enableHqVirtualTerminal" : "0",
"disableEMVCL" : "0",
"settlementMode" : "HOST",
"operatingHours" : "",
"tipBeforeCardRead" : "0",
"tipType1" : "P",
"tipAmount1" : "100",
"disableSMSReceipt" : "0",
"enablePoyntLodgingApp" : "0",
"supportContactEmail" : "",
"enableIosTransactionNotification" : "0",
"enableWeeklyInsightsEmails" : "1",
"viewScope" : "TERMINAL",
"useVTForManualEntry" : "1",
"paymentProcessor" : "co.poynt.services",
"enableLoyalty" : "0",
"enableDiners" : "0",
"distributorId" : "",
"receiptService" : "co.poynt.samples.samplereceiptprintingservice",
"autoForwardReceiptScreen" : "0",
"customerWelcomeMessage" : "",
"customFooterText" : "",
"autoSelectCommonDebitAID" : "0",
"forceEnableVT" : "0",
"enableMastercard" : "1",
"supportContactPhone" : "",
"localeCountry" : "US",
"disableEmailReceipt" : "0",
"signoutAfterSuspend" : "0",
"enablePoyntTerminalApp" : "1",
"productsDisabled" : "0",
"tipAmount2" : "200",
"enablePoyntRegisterApp" : "1",
"enableCashback" : "1",
"customScreenOffTimeoutInSecs" : "0",
"autoInventoryUpdate" : "0",
"enableCampaignCreation" : "0",
"maxOfflineTransactions" : "5",
"enableDCC" : "0",
"lodgingTaxRate" : "0",
"transactionListLimitSize" : "1000",
"enableAutomaticSettlement" : "1",
"disableWaitForCardRemoval" : "0",
"enableBaseAmountAdjust" : "0",
"secondScreenLanguages" : "",
"enableIosReportNotification" : "1",
"tipAfterCardRead" : "0",
"enableOffline" : "0",
"socialFacebook" : "",
"enableReportEmails" : "1",
"disableOrderInbox" : "0",
"enableAmex" : "0",
"autoForwardTipScreen" : "0",
"tipPercent3" : "20",
"cashbackAmountLimit" : "30000",
"webOnboarded" : "0",
"socialYelp" : "",
"enableVoiceAuth" : "1",
"supportedCustomFunding" : "",
"enableAutomaticReports" : "0",
"enableNotSettledEmails" : "1",
"parentMid" : "",
"enableEmployeeSettlementView" : "0",
"enableVisa" : "1",
"enableSecondScreenLanguagePref" : "0",
"enableGratuity" : "1",
"maxOfflineTransactionValue" : "2500",
"distributorName" : "",
"enableADA" : "0",
"enableHqSettlement" : "0",
"disableEMVCTDebit" : "0",
"tipAmount3" : "300",
"automaticReportsTime" : "0000",
"tipPercent2" : "18",
"customerBackgroundImageUrl" : "",
"enableJcb" : "0",
"socialTwitter" : "",
"enableHqMarketplace" : "0",
"socialWebsite" : "",
"enableActivationEmails" : "1"
},
"externalMerchantId" : "dennis's933a",
"address" : {
"territoryType" : "STATE",
"line1" : "15685 Business Drive",
"status" : "ADDED",
"countryCode" : "USA",
"territory" : "California",
"id" : 946,
"postalCode" : "94301",
"line2" : "Suite 302",
"city" : "Palo Alto"
},
"activeSince" : {
"year" : 2015,
"dayOfMonth" : 20,
"month" : 6,
"minute" : 14,
"hourOfDay" : 16,
"second" : 35
},
"id" : "469e957c-57a7-4d54-a72a-9e8f3296adad",
"emailAddress" : "dennis@domain.com",
"phone" : {
"ituCountryCode" : "1",
"areaCode" : "999",
"id" : 946,
"type" : "BUSINESS",
"status" : "ADDED",
"localPhoneNumber" : "1550011",
"extensionNumber" : "7398"
},
"industryType" : "Cafe",
"description" : "Just another test merchant",
"status" : "ACTIVATED",
"type" : "TEST_MERCHANT",
"stores" : [
{
"attributes" : {
"enableQuickbooks" : "1",
"enableDiscover" : "0",
"disablePaperReceipt" : "0",
"autoCapture" : "0",
"supportContactEmail" : "",
"enableIosTransactionNotification" : "0",
"disableEMVCL" : "0",
"tipBeforeCardRead" : "1",
"operatingHours" : "",
"enableHostSettlement" : "0",
"enableHqAdjustments" : "1",
"lodgingPromptTotalStayAmount" : "1",
"hostSettlementTime" : "0000",
"closingTime" : "",
"tipScreenTimeoutInMilliSecs" : "4000",
"validatePANForManualEntry" : "0",
"purchaseAction" : "SALE",
"stopAfterCardReadRecords" : "0",
"disableDebit" : "0",
"disableOrderAutoClose" : "0",
"enableIosTransactionVolumeYDay" : "1",
"enablePoyntStoreApp" : "1",
"enableAdvancedCatalog" : "0",
"showCustomTipByDefault" : "1",
"defaultScreenOffTimeoutInSecs" : "72000",
"reportingContactEmail" : "dennis@domain.com",
"socialYelp" : "",
"enableVisa" : "1",
"parentMid" : "",
"enableEmployeeSettlementView" : "0",
"enableVoiceAuth" : "1",
"tipAfterCardRead" : "0",
"enableIosReportNotification" : "1",
"enableAmex" : "0",
"enableReportEmails" : "1",
"socialFacebook" : "",
"disableOrderInbox" : "0",
"enableJcb" : "0",
"customerBackgroundImageUrl" : "https://domain.com/background.jpg",
"enableActivationEmails" : "1",
"socialWebsite" : "",
"disableEMVCTDebit" : "0",
"tipAmount3" : "300",
"distributorName" : "",
"localeCountry" : "US",
"disableEmailReceipt" : "0",
"enableMastercard" : "1",
"forceEnableVT" : "0",
"customFooterText" : "",
"enableDiners" : "0",
"viewScope" : "TERMINAL",
"customerWelcomeMessage" : "",
"distributorId" : "",
"customScreenOffTimeoutInSecs" : "1",
"enablePoyntTerminalApp" : "1",
"enableCashback" : "1",
"tipAmount2" : "200",
"productsDisabled" : "0",
"enableEBT" : "0",
"tipType3" : "P",
"automaticReportsTypes" : "TRANSACTIONS,ITEMS",
"disableEMVCLDebit" : "0",
"merchantContactFirstName" : "Dennis",
"disableEMVCT" : "0",
"hideCustomerWelcomeMessage" : "0",
"hideCustomerPaymentIcons" : "0",
"enableManualEntryNRR" : "0",
"enableAlphanumericZip" : "0",
"enableInsertCardAPI" : "0",
"verifySignature" : "0",
"enablePoyntLodgingApp" : "0",
"disableSMSReceipt" : "0",
"tipAmount1" : "100",
"enableWeeklyInsightsEmails" : "1",
"enableHqVirtualTerminal" : "0",
"tipType1" : "P",
"settlementMode" : "TERMINAL",
"signoutAfterTransaction" : "0",
"receiptScreenTimeoutInMilliSecs" : "3000",
"tipType2" : "P",
"maxOfflineTotal" : "10000",
"defaultScreenBrightness" : "-1",
"merchantContactLastName" : "Smith",
"automaticSettlementTime" : "2330",
"customScreenBrightness" : "0",
"enableNotTransactedEmails" : "1",
"merchantBackgroundImageUrl" : "",
"tipPercent1" : "15",
"enableBalanceInquiry" : "0",
"lodgingEnableFolio" : "0",
"skipSignatureAmount" : "100",
"tipPercent3" : "20",
"cashbackAmountLimit" : "30000",
"webOnboarded" : "0",
"autoForwardTipScreen" : "0",
"enableNotSettledEmails" : "1",
"supportedCustomFunding" : "",
"enableAutomaticReports" : "0",
"enableOffline" : "0",
"socialTwitter" : "",
"enableCardInsertAPI" : "0",
"enableHqMarketplace" : "0",
"enableADA" : "1",
"enableHqSettlement" : "0",
"maxOfflineTransactionValue" : "2500",
"enableGratuity" : "1",
"enableSecondScreenLanguagePref" : "0",
"tipPercent2" : "18",
"automaticReportsTime" : "0000",
"supportContactPhone" : "",
"autoSelectCommonDebitAID" : "0",
"signoutAfterSuspend" : "0",
"enableLoyalty" : "0",
"paymentProcessor" : "co.poynt.services",
"useVTForManualEntry" : "0",
"receiptService" : "co.poynt.services",
"autoForwardReceiptScreen" : "0",
"enableAutomaticSettlement" : "0",
"transactionListLimitSize" : "1000",
"enableDCC" : "0",
"lodgingTaxRate" : "0",
"enableCampaignCreation" : "0",
"maxOfflineTransactions" : "5",
"autoInventoryUpdate" : "0",
"secondScreenLanguages" : "",
"enableBaseAmountAdjust" : "0",
"disableWaitForCardRemoval" : "0",
"enablePoyntRegisterApp" : "1"
},
"currency" : "USD",
"longitude" : -132.162,
"acquirer" : "CHASE_PAYMENTECH",
"fixedLocation" : true,
"externalStoreId" : "dennis's71f3",
"id" : "d1f94f81-6257-41ce-83a8-54bf233fc78d",
"address" : {
"territory" : "California",
"countryCode" : "USA",
"status" : "ADDED",
"line1" : "15685 Business Drive",
"territoryType" : "STATE",
"line2" : "Suite 302",
"postalCode" : "94301",
"city" : "Palo Alto",
"id" : 947
},
"displayName" : "Store 2",
"latitude" : 37.4457,
"phone" : {
"localPhoneNumber" : "1550011",
"status" : "ADDED",
"type" : "BUSINESS",
"id" : 947,
"areaCode" : "180",
"ituCountryCode" : "1",
"extensionNumber" : "7398"
},
"storeDevices" : [
{
"name" : "counter 1",
"externalTerminalId" : "941a",
"catalogId" : "d657f867-aebd-4e90-997e-b04839fc027f",
"status" : "ACTIVATED",
"deviceId" : "urn:tid:d23eaeca-675f-3766-9c51-f6a0707e2587"
}
],
"timezone" : "America/Los_Angeles",
"processor" : "CREDITCALL"
}
],
"processor" : "CREDITCALL"
}
To see this API in action please refer to the sample app.
Using IPoyntTokenService
A second option is to use IPoyntTokenService.grantToken API which returns an access token with a set of custom claims which will include poynt.biz (or businessId), poynt.str (or storeId) and poynt.did (deviceId).
To see the usage of this API please refer to the sample app.