Package com.blockchyp.client

Class BlockChypClient

java.lang.Object
com.blockchyp.client.BlockChypClient
public class BlockChypClient extends Object
This is the main class Java developers will interact with. You can instantiate this class directly or use it with a dependency injection framework like Spring or Guice. Most developers will only need to inject credentials, but you may also want to override default endpoints if you're targeting non production BlockChyp systems (which is unlikely). You can inject settings via the constructors or via setters depending on your preferences. You'll also notice that we're not using generics or any features from Java 1.7 or later. This is just to maintain as much backward compatibility as possible with older systems (1.6 or later). The underlying REST API's are invoked using commons-httpclient 3.1 and we use Jackson for JSON serialization. Most internal methods are scoped as protected in order to give developers the ability to override things if they need special behavior or have weird classpath issues.

  • Field Details

  • Constructor Details

    • BlockChypClient

      public BlockChypClient()
      Default constructor.

    • BlockChypClient

      public BlockChypClient(String gatewayHost)
      Provided as a convenience to support constructor based dependency injection.
      Parameters:
      gatewayHost - alternate gateway endpoint.

    • BlockChypClient

      public BlockChypClient(APICredentials defaultCredentials)
      Provided as a convenience to support constructor based dependency injection.
      Parameters:
      defaultCredentials - APICredentials

    • BlockChypClient

      public BlockChypClient(String gatewayHost, APICredentials defaultCredentials)
      Provided as a convenience to support constructor based dependency injection.
      Parameters:
      gatewayHost - alternate gateway endpoint.
      defaultCredentials - APICredentials

    • BlockChypClient

      public BlockChypClient(String gatewayHost, String testGatewayHost, APICredentials defaultCredentials)
      Provided as a convenience to support constructor based dependency injection.
      Parameters:
      gatewayHost - alternate gateway endpoint.
      testGatewayHost - alternate gateway endpoint.
      defaultCredentials - APICredentials

    • BlockChypClient

      public BlockChypClient(String dashboardHost, String gatewayHost, String testGatewayHost, APICredentials defaultCredentials)
      Provided as a convenience to support constructor based dependency injection.
      Parameters:
      dashboardHost - alternate dashboard endpoint.
      gatewayHost - alternate gateway endpoint.
      testGatewayHost - alternate gateway endpoint.
      defaultCredentials - APICredentials

  • Method Details

    • setGatewayHost

      public void setGatewayHost(String gatewayHost)
      Used to override the live gateway host. Unless you work at BlockChyp, you probably won't ever need to do this.
      Parameters:
      gatewayHost - alternate gateway endpoint.

    • setDashboardHost

      public void setDashboardHost(String dashboardHost)
      Used to override the dashboard host. Unless you work at BlockChyp, you probably won't ever need to do this.
      Parameters:
      dashboardHost - alternate dashboard endpoint.

    • setTestGatewayHost

      public void setTestGatewayHost(String testGatewayHost)
      Used to override the test gateway host. Unless you work at BlockChyp, you probably won't ever need to do this.
      Parameters:
      testGatewayHost - alternate gateway endpoint.

    • setDefaultCredentials

      public void setDefaultCredentials(APICredentials defaultCredentials)
      Sets the default root API credentials for the client.
      Parameters:
      defaultCredentials - APICredentials

    • setOfflineRouteCacheEnabled

      public void setOfflineRouteCacheEnabled(boolean offlineRouteCacheEnabled)
      Enables or disables offline terminal route caching. Offline route caching is really meant as a defense for situations where developers are creating new BlockChypClient instances over and over for each request and therefore making the in memory cache useless. The BlockChypClient is thread safe so we encourage you to only create one instance and share it for all requests. If you're doing this, you can safely disable offline route caching and we recommend it. Defaults to enabled.
      Parameters:
      offlineRouteCacheEnabled - true if offline route caching is enabled.

    • setPaymentLogger

      public void setPaymentLogger(PaymentLogger paymentLogger)
      Sets the payment logger. Can be used to override that default System.out based logging.
      Parameters:
      paymentLogger - an implementation of PaymentLogger

    • initObjectMapper

      protected void initObjectMapper()
      Initializes the JSON encoder and parser.

    • heartbeat

      public HeartbeatResponse heartbeat(boolean test) throws Exception
      Tests communication with the Gateway. If authentication is successful, a merchantPk value is returned.
      Parameters:
      test - whether or not to route the the transaction to the test gateway.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • locate

      public LocateResponse locate(LocateRequest request) throws Exception
      Returns routing and location data for a payment terminal.
      Parameters:
      request - the request parameters.
      Returns:
      LocateResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • capture

      public CaptureResponse capture(CaptureRequest request) throws Exception
      Captures a preauthorization.
      Parameters:
      request - the request parameters.
      Returns:
      CaptureResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • voidTx

      public VoidResponse voidTx(VoidRequest request) throws Exception
      Discards a previous transaction.
      Parameters:
      request - the request parameters.
      Returns:
      VoidResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • reverse

      public AuthorizationResponse reverse(AuthorizationRequest request) throws Exception
      Executes a manual time out reversal. We love time out reversals. Don't be afraid to use them whenever a request to a BlockChyp terminal times out. You have up to two minutes to reverse any transaction. The only caveat is that you must assign transactionRef values when you build the original request. Otherwise, we have no real way of knowing which transaction you're trying to reverse because we may not have assigned it an id yet. And if we did assign it an id, you wouldn't know what it is because your request to the terminal timed out before you got a response.
      Parameters:
      request - the request parameters.
      Returns:
      AuthorizationResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • closeBatch

      public CloseBatchResponse closeBatch(CloseBatchRequest request) throws Exception
      Closes the current credit card batch.
      Parameters:
      request - the request parameters.
      Returns:
      CloseBatchResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • sendPaymentLink

      public PaymentLinkResponse sendPaymentLink(PaymentLinkRequest request) throws Exception
      Creates and send a payment link to a customer.
      Parameters:
      request - the request parameters.
      Returns:
      PaymentLinkResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • resendPaymentLink

      public ResendPaymentLinkResponse resendPaymentLink(ResendPaymentLinkRequest request) throws Exception
      Resends payment link.
      Parameters:
      request - the request parameters.
      Returns:
      ResendPaymentLinkResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • cancelPaymentLink

      public CancelPaymentLinkResponse cancelPaymentLink(CancelPaymentLinkRequest request) throws Exception
      Cancels a payment link.
      Parameters:
      request - the request parameters.
      Returns:
      CancelPaymentLinkResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • paymentLinkStatus

      public PaymentLinkStatusResponse paymentLinkStatus(PaymentLinkStatusRequest request) throws Exception
      Retrieves the status of a payment link.
      Parameters:
      request - the request parameters.
      Returns:
      PaymentLinkStatusResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • transactionStatus

      public AuthorizationResponse transactionStatus(TransactionStatusRequest request) throws Exception
      Retrieves the current status of a transaction.
      Parameters:
      request - the request parameters.
      Returns:
      AuthorizationResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • updateCustomer

      public CustomerResponse updateCustomer(UpdateCustomerRequest request) throws Exception
      Updates or creates a customer record.
      Parameters:
      request - the request parameters.
      Returns:
      CustomerResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • customer

      public CustomerResponse customer(CustomerRequest request) throws Exception
      Retrieves a customer by id.
      Parameters:
      request - the request parameters.
      Returns:
      CustomerResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • customerSearch

      public CustomerSearchResponse customerSearch(CustomerSearchRequest request) throws Exception
      Searches the customer database.
      Parameters:
      request - the request parameters.
      Returns:
      CustomerSearchResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • cashDiscount

      public CashDiscountResponse cashDiscount(CashDiscountRequest request) throws Exception
      Calculates the discount for actual cash transactions.
      Parameters:
      request - the request parameters.
      Returns:
      CashDiscountResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • batchHistory

      public BatchHistoryResponse batchHistory(BatchHistoryRequest request) throws Exception
      Returns the batch history for a merchant.
      Parameters:
      request - the request parameters.
      Returns:
      BatchHistoryResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • batchDetails

      public BatchDetailsResponse batchDetails(BatchDetailsRequest request) throws Exception
      Returns the batch details for a single batch.
      Parameters:
      request - the request parameters.
      Returns:
      BatchDetailsResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • transactionHistory

      public TransactionHistoryResponse transactionHistory(TransactionHistoryRequest request) throws Exception
      Returns the transaction history for a merchant.
      Parameters:
      request - the request parameters.
      Returns:
      TransactionHistoryResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • pricingPolicy

      public PricingPolicyResponse pricingPolicy(PricingPolicyRequest request) throws Exception
      Returns pricing policy for a merchant.
      Parameters:
      request - the request parameters.
      Returns:
      PricingPolicyResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • partnerStatements

      public PartnerStatementListResponse partnerStatements(PartnerStatementListRequest request) throws Exception
      Returns a list of partner statements.
      Parameters:
      request - the request parameters.
      Returns:
      PartnerStatementListResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • partnerStatementDetail

      public PartnerStatementDetailResponse partnerStatementDetail(PartnerStatementDetailRequest request) throws Exception
      Returns detail for a single partner statement.
      Parameters:
      request - the request parameters.
      Returns:
      PartnerStatementDetailResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • merchantInvoices

      public MerchantInvoiceListResponse merchantInvoices(MerchantInvoiceListRequest request) throws Exception
      Returns a list of merchant invoices.
      Parameters:
      request - the request parameters.
      Returns:
      MerchantInvoiceListResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • merchantInvoiceDetail

      public MerchantInvoiceDetailResponse merchantInvoiceDetail(MerchantInvoiceDetailRequest request) throws Exception
      Returns detail for a single merchant-invoice statement.
      Parameters:
      request - the request parameters.
      Returns:
      MerchantInvoiceDetailResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • partnerCommissionBreakdown

      public PartnerCommissionBreakdownResponse partnerCommissionBreakdown(PartnerCommissionBreakdownRequest request) throws Exception
      Returns low level details for how partner commissions were calculated for a specific merchant statement.
      Parameters:
      request - the request parameters.
      Returns:
      PartnerCommissionBreakdownResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • merchantProfile

      public MerchantProfileResponse merchantProfile(MerchantProfileRequest request) throws Exception
      Returns profile information for a merchant.
      Parameters:
      request - the request parameters.
      Returns:
      MerchantProfileResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteCustomer

      public DeleteCustomerResponse deleteCustomer(DeleteCustomerRequest request) throws Exception
      Deletes a customer record.
      Parameters:
      request - the request parameters.
      Returns:
      DeleteCustomerResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • tokenMetadata

      public TokenMetadataResponse tokenMetadata(TokenMetadataRequest request) throws Exception
      Retrieves payment token metadata.
      Parameters:
      request - the request parameters.
      Returns:
      TokenMetadataResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • linkToken

      public Acknowledgement linkToken(LinkTokenRequest request) throws Exception
      Links a token to a customer record.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • unlinkToken

      public Acknowledgement unlinkToken(UnlinkTokenRequest request) throws Exception
      Removes a link between a customer and a token.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteToken

      public DeleteTokenResponse deleteToken(DeleteTokenRequest request) throws Exception
      Deletes a payment token.
      Parameters:
      request - the request parameters.
      Returns:
      DeleteTokenResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • getMerchants

      public GetMerchantsResponse getMerchants(GetMerchantsRequest request) throws Exception
      Adds a test merchant account.
      Parameters:
      request - the request parameters.
      Returns:
      GetMerchantsResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • updateMerchant

      public MerchantProfileResponse updateMerchant(MerchantProfile request) throws Exception
      Adds or updates a merchant account. Can be used to create or update test merchants. Only gateway partners may create new live merchants.
      Parameters:
      request - the request parameters.
      Returns:
      MerchantProfileResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • merchantUsers

      public MerchantUsersResponse merchantUsers(MerchantProfileRequest request) throws Exception
      List all active users and pending invites for a merchant account.
      Parameters:
      request - the request parameters.
      Returns:
      MerchantUsersResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • inviteMerchantUser

      public Acknowledgement inviteMerchantUser(InviteMerchantUserRequest request) throws Exception
      Invites a user to join a merchant account.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • addTestMerchant

      public MerchantProfileResponse addTestMerchant(AddTestMerchantRequest request) throws Exception
      Adds a test merchant account.
      Parameters:
      request - the request parameters.
      Returns:
      MerchantProfileResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteTestMerchant

      public Acknowledgement deleteTestMerchant(MerchantProfileRequest request) throws Exception
      Deletes a test merchant account. Supports partner scoped API credentials only. Live merchant accounts cannot be deleted.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • merchantPlatforms

      public MerchantPlatformsResponse merchantPlatforms(MerchantProfileRequest request) throws Exception
      List all merchant platforms configured for a gateway merchant.
      Parameters:
      request - the request parameters.
      Returns:
      MerchantPlatformsResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • updateMerchantPlatforms

      public Acknowledgement updateMerchantPlatforms(MerchantPlatform request) throws Exception
      List all merchant platforms configured for a gateway merchant.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteMerchantPlatforms

      public Acknowledgement deleteMerchantPlatforms(MerchantPlatformRequest request) throws Exception
      Deletes a boarding platform configuration.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • terminals

      public TerminalProfileResponse terminals(TerminalProfileRequest request) throws Exception
      Returns all terminals associated with the merchant account.
      Parameters:
      request - the request parameters.
      Returns:
      TerminalProfileResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deactivateTerminal

      public Acknowledgement deactivateTerminal(TerminalDeactivationRequest request) throws Exception
      Deactivates a terminal.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • activateTerminal

      public Acknowledgement activateTerminal(TerminalActivationRequest request) throws Exception
      Activates a terminal.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • tcTemplates

      public TermsAndConditionsTemplateResponse tcTemplates(TermsAndConditionsTemplateRequest request) throws Exception
      Returns a list of terms and conditions templates associated with a merchant account.
      Parameters:
      request - the request parameters.
      Returns:
      TermsAndConditionsTemplateResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • tcTemplate

      public TermsAndConditionsTemplate tcTemplate(TermsAndConditionsTemplateRequest request) throws Exception
      Returns a single terms and conditions template.
      Parameters:
      request - the request parameters.
      Returns:
      TermsAndConditionsTemplate
      Throws:
      Exception - exception if any errors occurred processing the request.

    • tcUpdateTemplate

      public TermsAndConditionsTemplate tcUpdateTemplate(TermsAndConditionsTemplate request) throws Exception
      Updates or creates a terms and conditions template.
      Parameters:
      request - the request parameters.
      Returns:
      TermsAndConditionsTemplate
      Throws:
      Exception - exception if any errors occurred processing the request.

    • tcDeleteTemplate

      public Acknowledgement tcDeleteTemplate(TermsAndConditionsTemplateRequest request) throws Exception
      Deletes a single terms and conditions template.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • tcLog

      public TermsAndConditionsLogResponse tcLog(TermsAndConditionsLogRequest request) throws Exception
      Returns up to 250 entries from the Terms and Conditions log.
      Parameters:
      request - the request parameters.
      Returns:
      TermsAndConditionsLogResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • tcEntry

      public TermsAndConditionsLogEntry tcEntry(TermsAndConditionsLogRequest request) throws Exception
      Returns a single detailed Terms and Conditions entry.
      Parameters:
      request - the request parameters.
      Returns:
      TermsAndConditionsLogEntry
      Throws:
      Exception - exception if any errors occurred processing the request.

    • surveyQuestions

      public SurveyQuestionResponse surveyQuestions(SurveyQuestionRequest request) throws Exception
      Returns all survey questions for a given merchant.
      Parameters:
      request - the request parameters.
      Returns:
      SurveyQuestionResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • surveyQuestion

      public SurveyQuestion surveyQuestion(SurveyQuestionRequest request) throws Exception
      Returns a single survey question with response data.
      Parameters:
      request - the request parameters.
      Returns:
      SurveyQuestion
      Throws:
      Exception - exception if any errors occurred processing the request.

    • updateSurveyQuestion

      public SurveyQuestion updateSurveyQuestion(SurveyQuestion request) throws Exception
      Updates or creates a survey question.
      Parameters:
      request - the request parameters.
      Returns:
      SurveyQuestion
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteSurveyQuestion

      public Acknowledgement deleteSurveyQuestion(SurveyQuestionRequest request) throws Exception
      Deletes a survey question.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • surveyResults

      public SurveyQuestion surveyResults(SurveyResultsRequest request) throws Exception
      Returns results for a single survey question.
      Parameters:
      request - the request parameters.
      Returns:
      SurveyQuestion
      Throws:
      Exception - exception if any errors occurred processing the request.

    • media

      public MediaLibraryResponse media(MediaRequest request) throws Exception
      Returns the media library for a given partner, merchant, or organization.
      Parameters:
      request - the request parameters.
      Returns:
      MediaLibraryResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • uploadMedia

      public MediaMetadata uploadMedia(UploadMetadata request, InputStream inStream) throws Exception
      Uploads a media asset to the media library.
      Parameters:
      request - the request parameters.
      Returns:
      MediaMetadata
      Throws:
      Exception - exception if any errors occurred processing the request.

    • uploadStatus

      public UploadStatus uploadStatus(UploadStatusRequest request) throws Exception
      Retrieves the current status of a file upload.
      Parameters:
      request - the request parameters.
      Returns:
      UploadStatus
      Throws:
      Exception - exception if any errors occurred processing the request.

    • mediaAsset

      public MediaMetadata mediaAsset(MediaRequest request) throws Exception
      Returns the media details for a single media asset.
      Parameters:
      request - the request parameters.
      Returns:
      MediaMetadata
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteMediaAsset

      public Acknowledgement deleteMediaAsset(MediaRequest request) throws Exception
      Deletes a media asset.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • slideShows

      public SlideShowResponse slideShows(SlideShowRequest request) throws Exception
      Returns a collection of slide shows.
      Parameters:
      request - the request parameters.
      Returns:
      SlideShowResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • slideShow

      public SlideShow slideShow(SlideShowRequest request) throws Exception
      Returns a single slide show with slides.
      Parameters:
      request - the request parameters.
      Returns:
      SlideShow
      Throws:
      Exception - exception if any errors occurred processing the request.

    • updateSlideShow

      public SlideShow updateSlideShow(SlideShow request) throws Exception
      Updates or creates a slide show.
      Parameters:
      request - the request parameters.
      Returns:
      SlideShow
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteSlideShow

      public Acknowledgement deleteSlideShow(SlideShowRequest request) throws Exception
      Deletes a single slide show.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • terminalBranding

      public BrandingAssetResponse terminalBranding(BrandingAssetRequest request) throws Exception
      Returns the terminal branding stack for a given set of API credentials.
      Parameters:
      request - the request parameters.
      Returns:
      BrandingAssetResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • updateBrandingAsset

      public BrandingAsset updateBrandingAsset(BrandingAsset request) throws Exception
      Updates a branding asset.
      Parameters:
      request - the request parameters.
      Returns:
      BrandingAsset
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteBrandingAsset

      public Acknowledgement deleteBrandingAsset(BrandingAssetRequest request) throws Exception
      Deletes a branding asset.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • ping

      public PingResponse ping(PingRequest request) throws Exception
      Tests connectivity with a payment terminal.
      Parameters:
      request - the request parameters.
      Returns:
      PingResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • charge

      public AuthorizationResponse charge(AuthorizationRequest request) throws Exception
      Executes a standard direct preauth and capture.
      Parameters:
      request - the request parameters.
      Returns:
      AuthorizationResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • preauth

      public AuthorizationResponse preauth(AuthorizationRequest request) throws Exception
      Executes a preauthorization intended to be captured later.
      Parameters:
      request - the request parameters.
      Returns:
      AuthorizationResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • refund

      public AuthorizationResponse refund(RefundRequest request) throws Exception
      Executes a refund.
      Parameters:
      request - the request parameters.
      Returns:
      AuthorizationResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • enroll

      public EnrollResponse enroll(EnrollRequest request) throws Exception
      Adds a new payment method to the token vault.
      Parameters:
      request - the request parameters.
      Returns:
      EnrollResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • giftActivate

      public GiftActivateResponse giftActivate(GiftActivateRequest request) throws Exception
      Activates or recharges a gift card.
      Parameters:
      request - the request parameters.
      Returns:
      GiftActivateResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • balance

      public BalanceResponse balance(BalanceRequest request) throws Exception
      Checks the remaining balance on a payment method.
      Parameters:
      request - the request parameters.
      Returns:
      BalanceResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • clear

      public Acknowledgement clear(ClearTerminalRequest request) throws Exception
      Clears the line item display and any in progress transaction.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • terminalStatus

      public TerminalStatusResponse terminalStatus(TerminalStatusRequest request) throws Exception
      Returns the current status of a terminal.
      Parameters:
      request - the request parameters.
      Returns:
      TerminalStatusResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • termsAndConditions

      public TermsAndConditionsResponse termsAndConditions(TermsAndConditionsRequest request) throws Exception
      Prompts the user to accept terms and conditions.
      Parameters:
      request - the request parameters.
      Returns:
      TermsAndConditionsResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • captureSignature

      public CaptureSignatureResponse captureSignature(CaptureSignatureRequest request) throws Exception
      Captures and returns a signature.
      Parameters:
      request - the request parameters.
      Returns:
      CaptureSignatureResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • newTransactionDisplay

      public Acknowledgement newTransactionDisplay(TransactionDisplayRequest request) throws Exception
      Displays a new transaction on the terminal.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • updateTransactionDisplay

      public Acknowledgement updateTransactionDisplay(TransactionDisplayRequest request) throws Exception
      Appends items to an existing transaction display. Subtotal, Tax, and Total are overwritten by the request. Items with the same description are combined into groups.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • message

      public Acknowledgement message(MessageRequest request) throws Exception
      Displays a short message on the terminal.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • booleanPrompt

      public BooleanPromptResponse booleanPrompt(BooleanPromptRequest request) throws Exception
      Asks the consumer a yes/no question.
      Parameters:
      request - the request parameters.
      Returns:
      BooleanPromptResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • textPrompt

      public TextPromptResponse textPrompt(TextPromptRequest request) throws Exception
      Asks the consumer a text based question.
      Parameters:
      request - the request parameters.
      Returns:
      TextPromptResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • listQueuedTransactions

      public ListQueuedTransactionsResponse listQueuedTransactions(ListQueuedTransactionsRequest request) throws Exception
      Returns a list of queued transactions on a terminal.
      Parameters:
      request - the request parameters.
      Returns:
      ListQueuedTransactionsResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteQueuedTransaction

      public DeleteQueuedTransactionResponse deleteQueuedTransaction(DeleteQueuedTransactionRequest request) throws Exception
      Deletes a queued transaction from the terminal.
      Parameters:
      request - the request parameters.
      Returns:
      DeleteQueuedTransactionResponse
      Throws:
      Exception - exception if any errors occurred processing the request.

    • reboot

      public Acknowledgement reboot(PingRequest request) throws Exception
      Reboot a payment terminal.
      Parameters:
      request - the request parameters.
      Returns:
      Acknowledgement
      Throws:
      Exception - exception if any errors occurred processing the request.

    • decrypt

      protected APICredentials decrypt(APICredentials creds)
      Decrypts API credentials using the offline cache key.
      Parameters:
      creds - blockchyp API credentials.
      Returns:
      a decrypted copy of the original credentials.

    • encrypt

      protected APICredentials encrypt(APICredentials creds)
      Encrypts API credentials using the offline cache key.
      Parameters:
      creds - blockchyp API credentials.
      Returns:
      an encrypted copy of the original credentials.

    • deriveOfflineKey

      protected byte[] deriveOfflineKey()
      Generates the encryption key used for offline cache records.
      Returns:
      the key in bytes.

    • routeCacheGet

      protected TerminalRouteResponse routeCacheGet(String terminalName)
      Looks up a terminal route from the cache.
      Parameters:
      terminalName - terminal name assigned at activation.
      Returns:
      the terminal route record.

    • routeCachePut

      protected void routeCachePut(TerminalRouteResponse route)
      Puts a terminal route in the cache (both caches).
      Parameters:
      route - the terminal route record.

    • toTerminalRouteKey

      protected String toTerminalRouteKey(String terminalName)
      Creates a cache key for terminal routes.
      Parameters:
      terminalName - terminal name.
      Returns:
      terminal cache key.

    • dumpSignatureFile

      protected void dumpSignatureFile(Object request, Object response)
      Writes the signature to a file if a signature is present and the caller has requested it. Notice this does not throw exceptions in order to prevent the calling application from losing track of the authorization.
      Parameters:
      request - ISignatureRequest
      response - ISignatureResponse

    • resolveTerminalRoute

      protected TerminalRouteResponse resolveTerminalRoute(String terminalName)
      Finds the terminal route record for the given terminal name. First the local in memory cache is checked, then the offline cache (if enabled). If the first two cache lookups come up empty or the cache is over an hour old, the gateway route API is invoked. If we have a stale cache entry and the gateway route lookup fails or times out, we fall back to the stale cache entry.
      Parameters:
      terminalName - name of the terminal assigned at activation.
      Returns:
      the terminal route record.

    • getGatewayClient

      protected org.apache.commons.httpclient.HttpClient getGatewayClient()
      Returns the gateway client singleton.
      Returns:
      HttpClient configured for gateway requests.

    • getTerminalClient

      protected org.apache.commons.httpclient.HttpClient getTerminalClient()
      Returns the terminal client singleton.
      Returns:
      HttpClient configured for terminal requests.

    • resolveTerminalHost

      protected String resolveTerminalHost(TerminalRouteResponse route)
      Assembles the scheme, ip address, and port number bits of a terminal URL.
      Parameters:
      route - the terminal route record.
      Returns:
      scheme, ip addres, and port number.

    • toFullyQualifiedTerminalPath

      protected String toFullyQualifiedTerminalPath(TerminalRouteResponse route, String path)
      Assembles a full path to the terminal for an API call.
      Parameters:
      route - the terminal route record.
      path - API path relative to the root (e.g. "/api/charge")
      Returns:
      the fully qualified URI.

    • isTerminalRouted

      protected boolean isTerminalRouted(ITerminalReference terminalName)
      Returns true if transaction for the given terminal reference should be routed over the local subnet.
      Parameters:
      terminalName - reference to the terminal.
      Returns:
      true, if terminal (local subnet) routed.

    • finishTerminalRequest

      protected Object finishTerminalRequest(TerminalRouteResponse route, Object request, org.apache.commons.httpclient.HttpMethod method, Class responseType) throws Exception
      This handles all the common logic associated with processing terminal http requests.
      Parameters:
      route - the terminal route record
      request - the request payload, if put or post
      method - the HttpMethod prepopulated
      responseType - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • putTerminal

      protected Object putTerminal(String path, Object request, Class responseType) throws Exception
      Executes a put http request against the terminal API.
      Parameters:
      path - api path relative to the root (e.g. "/api/charge")
      request - the request payload object.
      responseType - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • newTerminalRequestForRoute

      protected TerminalRequest newTerminalRequestForRoute(TerminalRouteResponse route)
      Assembles a new terminal request and populates the credentials, using transient credentials if available.
      Parameters:
      route - the terminal route record.
      Returns:
      TerminalRequest

    • postTerminal

      protected Object postTerminal(String path, Object request, Class responseType) throws Exception
      Posts an http request to the terminal API.
      Parameters:
      path - api path relative to the root (e.g. "/api/charge")
      request - the request payload object.
      responseType - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • getGateway

      protected Object getGateway(String path, boolean test, Class responseType) throws Exception
      Executes an http get request against the gateway with a timeout override.
      Parameters:
      path - api path relative to the root (e.g. "/api/heartbeat")
      test - whether or not this request should go to the test gateway
      responseType - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • getGateway

      protected Object getGateway(String path, boolean test, Class responseType, int requestTimeout) throws Exception
      Executes an http get request against the gateway with a timeout override.
      Parameters:
      path - API path relative to the root (e.g. "/api/heartbeat")
      test - whether or not this request should go to the test gateway
      responseType - expected response type.
      requestTimeout - timeout for the request in milliseconds
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • getDashboard

      protected Object getDashboard(String path, ITimeoutRequest request, Class responseType) throws Exception
      Executes an http get request against the gateway with a timeout override.
      Parameters:
      path - API path relative to the root (e.g. "/api/heartbeat")
      request - the request object.
      responseType - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • finishGatewayRequest

      protected Object finishGatewayRequest(org.apache.commons.httpclient.HttpMethod method, Class responseType) throws Exception
      Executes a previously assembled HttpMethod against the gateway. Aggregates common logic associated with hitting the gateway.
      Parameters:
      method - the HttpMethod to execute.
      responseType - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • postUpload

      protected Object postUpload(String path, UploadMetadata request, InputStream inStream, Class responseClass) throws Exception
      Executes a post HTTP request against the dashboard.
      Parameters:
      path - API path from root (e.g. "/api/charge")
      request - the request object.
      inStream - is the upload input stream
      responseClass - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • postDashboard

      protected Object postDashboard(String path, ITimeoutRequest request, Class responseClass) throws Exception
      Executes a post HTTP request against the dashboard.
      Parameters:
      path - API path from root (e.g. "/api/charge")
      request - the request object.
      responseClass - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • postGateway

      protected Object postGateway(String path, ITimeoutRequest request, Class responseClass) throws Exception
      Executes a post HTTP request against the gateway.
      Parameters:
      path - API path from root (e.g. "/api/charge")
      request - the request object.
      responseClass - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • putGateway

      protected Object putGateway(String path, ITimeoutRequest request, Class responseClass) throws Exception
      Executes a put HTTP request against the gateway.
      Parameters:
      path - API path from root (e.g. "/api/charge")
      request - the request object.
      responseClass - expected response type.
      Returns:
      a reponse of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteGateway

      protected Object deleteGateway(String path, ITimeoutRequest request, Class responseClass) throws Exception
      Executes a delete HTTP request against the gateway.
      Parameters:
      path - API path from root (e.g. "/api/charge")
      request - the request object.
      responseClass - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • deleteDashboard

      protected Object deleteDashboard(String path, ITimeoutRequest request, Class responseClass) throws Exception
      Executes a delete HTTP request against the gateway.
      Parameters:
      path - API path from root (e.g. "/api/charge")
      request - the request object.
      responseClass - expected response type.
      Returns:
      a response of type specified by responseClass
      Throws:
      Exception - exception if any errors occurred processing the request.

    • resolveOfflineRouteCacheLocation

      protected String resolveOfflineRouteCacheLocation(String terminalName)
      Returns the offline cache location. This will be the value of offlineRouteCacheLocation if specified and the operation system default tmp folder otherwise.
      Parameters:
      terminalName - the target terminal name.
      Returns:
      local path.

    • getOfflineCache

      public TerminalRouteResponse getOfflineCache(String terminalName)
      Returns the route stored in the offline cache for the given terminal.
      Parameters:
      terminalName - the target terminal name.
      Returns:
      terminal route, null if not found.

    • getOfflineRouteCacheLocation

      public String getOfflineRouteCacheLocation()
      Returns the offline route cache location.
      Returns:
      offline route cache location.

    • setOfflineRouteCacheLocation

      public void setOfflineRouteCacheLocation(String offlineRouteCacheLocation)
      Sets the offline route cache location if you want to override the default. Defaults to your operation system's tmp file location.
      Parameters:
      offlineRouteCacheLocation - offline route cache location.

    • toFullyQualifiedGatewayPath

      protected String toFullyQualifiedGatewayPath(String path, boolean test)
      Converts path to the fully qualified URL for a gateway API call.
      Parameters:
      path - path relative to the root (e.g. "/api/charge")
      test - whether or not this should route to the test transaction.
      Returns:
      fully qualified URI.

    • toFullyQualifiedDashboardPath

      protected String toFullyQualifiedDashboardPath(String path)
      Converts path to the fully qualified URL for a dashboard API call.
      Parameters:
      path - path relative to the root (e.g. "/api/charge")
      Returns:
      fully qualified URI.

    • isTerminalHttps

      public boolean isTerminalHttps()
      Gets the terminal https flag. The Java SDK defaults to using http for terminal communication because installing custom root certificate authorities in Java is quite tricky and cannot be done programmatically. We strongly recommend that all developers install our root CA in your local keystores and then turn https on in production. Our terminal root CA can be found here: https://docs.blockchyp.com/rest-api/terminal/index.html#ssl-tls
      Returns:
      https flag.

    • setTerminalHttps

      public void setTerminalHttps(boolean terminalHttps)
      Sets the terminal https flag. The Java SDK defaults to using http for terminal communication because installing custom root certificate authorities in Java is quite tricky and cannot be done programmatically. We strongly recommend that all developers install our root CA in your local keystores and then turn https on in production. Our terminal root CA can be found here: https://docs.blockchyp.com/rest-api/terminal/index.html#ssl-tls
      Parameters:
      terminalHttps - https flag.