Package: blockchyp
BlockChyp Python SDKThe official library for accessing theBlockChypTerminal and Gateway APIs
from Python.InstallationBlockChyp can be simply installed by running:pipinstallblockchypAdditional DocumentationComplete documentation can be found on ourDeveloper Documentation Portal.Getting a Developer KitIn order to test your integration with real terminals, you'll need a BlockChyp
Developer Kit. Our kits include a fully functioning payment terminal with
test pin encryption keys. Every kit includes a comprehensive set of test
cards with test cards for every major card brand and entry method, including
Contactless and Contact EMV and mag stripe cards. Each kit also includes
test gift cards for our blockchain gift card system.Access to BlockChyp's developer program is currently invite only, but you
can request an invitation by contacting our engineering team atnerds@blockchyp.com.You can also view a number of long form demos and learn more about us on ourYouTube Channel.Transaction Code ExamplesYou don't want to read words. You want examples. Here's a quick rundown of the
stuff you can do with the BlockChyp Python SDK and a few basic examples.Payment EndpointsThese are the core payment APIs used to execute and work with payment transactions in BlockChyp.ChargeAPI Credential Types:MerchantRequired Role:Payment API AccessOur most popular transaction executes a standard authorization and capture.
This is the most basic of
basic payment transactions, typically used in conventional retail.Charge transactions can use a payment terminal to capture a payment or
use a previously enrolled payment token.Terminal TransactionsFor terminal transactions, make sure you pass in the terminal name using theterminalNameproperty.Token TransactionsIf you have a payment token, omit theterminalNameproperty and pass in the token with thetokenproperty instead.Card Numbers and Mag StripesYou can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will
put you in PCI scope and the most common vector for POS breaches is keylogging.
If you use terminals for manual card entry, you'll bypass any keyloggers that
might be maliciously running on the point-of-sale system.Common VariationsGift Card Redemption:  There's no special API for gift card redemption in BlockChyp. Simply execute a plain charge transaction and if the customer swipes a gift card, our terminals will identify the gift card and run a gift card redemption. Also note that if for some reason the gift card's original purchase transaction is associated with fraud or a chargeback, the transaction will be rejected.EBT: Set thecard_typefield toblockchyp.CardType.EBTto process an EBT SNAP transaction. Note that test EBT transactions always assume a balance of $100.00, so test EBT transactions over that amount may be declined.Cash Back: To enable cash back for debit transactions, set thecash_backfield. If the card presented isn't a debit card, thecash_backfield will be ignored.Manual Card Entry: Set themanual_entryfield to enable manual card entry. Good as a backup when chips and MSR's don't work or for more secure phone orders. You can even combine themanual_entryfield with thecard_typefield set toblockchyp.CardType.EBTfor manual EBT card entry.Inline Tokenization: You can enroll the payment method in the token vault inline with a charge transaction by setting theenrollfield. You'll get a token back in the response. You can even bind the token to a customer record if you also pass in customer data.Prompting for Tips: Set theprompt_for_tipfield if you'd like to prompt the customer for a tip before authorization. Good for pay-at-the-table and other service related scenarios.Cash Discounting and Surcharging:  Thesurchargeandcash_discountfields can be used together to support cash discounting or surcharge problems. Consult the Cash Discount documentation for more details.CryptocurrencyThecryptocurrencyfield can be used to switch the standard present card screen to a cryptocurrency screen.  The field value can beANYto enable any supported cryptocurrency or a single currency code such asBTCfor Bitcoin.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","amount":"55.00",}# run the transaction.response=client.charge(request)print("Response:%r"%response)PreauthorizationAPI Credential Types:MerchantRequired Role:Payment API AccessA preauthorization puts a hold on funds and must be captured later.  This is used
in scenarios where the final transaction amount might change.  A common example is
fine dining, where a tip adjustment is required before final settlement.Another use case for preauthorization is e-commerce.  Typically, an online order
is preauthorized at the time of the order and then captured when the order ships.Preauthorizations can use a payment terminal to capture a payment or
use a previously enrolled payment token.Terminal TransactionsFor terminal transactions, make sure you pass in the terminal name using theterminalNameproperty.Token TransactionsIf you have a payment token, omit theterminalNameproperty and pass in the token with thetokenproperty instead.Card Numbers and Mag StripesYou can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will
put you in PCI scope and the most common vector for POS breaches is key logging.
If you use terminals for manual card entry, you'll bypass any key loggers that
might be maliciously running on the point-of-sale system.CryptocurrencyNote that preauths are not supported for cryptocurrency.Common VariationsManual Card Entry: Set themanual_entryfield to enable manual card entry. Good as a backup when chips and MSR's don't work or for more secure phone orders. You can even combine themanual_entryfield withcard_typeset toblockchyp.CardType.EBTfor manual EBT card entry.Inline Tokenization: You can enroll the payment method in the token vault in line with a charge transaction by setting theenrollfield. You'll get a token back in the response. You can even bind the token to a customer record if you also pass in customer data.Prompting for Tips: Set theprompt_for_tipfield if you'd like to prompt the customer for a tip before authorization. You can prompt for tips as part of a preauthorization, although it's not a very common approach.Cash Discounting and Surcharging: Thesurchargeandcash_discountfields can be used together to support cash discounting or surcharge problems. Consult the Cash Discount documentation for more details.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","amount":"27.00",}# run the transaction.response=client.preauth(request)print("Response:%r"%response)Capture PreauthorizationAPI Credential Types:MerchantRequired Role:Payment API AccessThis API allows you to capture a previously approved preauthorization.You'll need to make sure you pass in the Transaction ID returned by the original preauth transaction
so we know which transaction we're capturing.  If you want to capture the transaction for the
exact amount of the preauth, the Transaction ID is all you need to pass in.You can adjust the total if you need to by passing in a newamount.  We
also recommend you pass in updated amounts fortaxandtipas it can
sometimes reduce your interchange fees. (Level II Processing, for example.)importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"transactionId":"<ORIGINAL TRANSACTION ID>","amount":"32.00",}# run the transaction.response=client.capture(request)print("Response:%r"%response)RefundAPI Credential Types:MerchantRequired Role:Payment API AccessIt's not ideal, but sometimes customers want their money back.Our refund API allows you to confront this unpleasant reality by executing refunds in a few different scenarios.The most fraud resistent method is to execute refunds in the context of a previous transaction.  You should always keep track of the Transaction ID
returned in a BlockChyp response.  To refund the full amount of the previous transaction, just pass in the original Transaction ID with the refund requests.Partial RefundsFor a partial refund, just pass in an amount along with the Transaction ID.
The only rule is that the amount must be equal to or less than the original
transaction.  You can execute multiple partial refunds against the same
original transaction as long as the total refunded amount doesn't exceed the original amount.Tokenized RefundsYou can also use a token to execute a refund.  Pass in a token instead
of the Transaction ID and the desired refund amount.Free Range RefundsWhen you execute a refund without referencing a previous transaction, we
call this afree range refund.We don't recommend this type of refund, but it is permitted.  If you absolutely insist on
doing it, pass in a Terminal Name and an amount.You can execute a manual or keyed refund by passing themanual_entryfield
to a free range refund request.Gift Card RefundsGift card refunds are allowed in the context of a previous transaction, but
free range gift card refunds are not allowed.  Use the gift card activation
API if you need to add more funds to a gift card.Store and Forward SupportRefunds are not permitted when a terminal falls back to store and forward mode.Auto VoidsIf a refund referencing a previous transaction is executed for the full amount
before the original transaction's batch is closed, the refund is automatically
converted to a void.  This saves the merchant a little bit of money.CryptocurrencyNote that refunds are not supported for cryptocurrency.  You must refund crypto transactions
manually from your cryptocurrency wallet.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"transactionId":"<PREVIOUS TRANSACTION ID>",# Optional amount for partial refunds."amount":"5.00",}# run the transaction.response=client.refund(request)print("Response:%r"%response)VoidAPI Credential Types:MerchantRequired Role:Payment API AccessMistakes happen.  If a transaction is made by mistake, you can void it
with this API.  All that's needed is to pass in a Transaction ID and execute
the void before the original transaction's batch closes.Voids work with EBT and gift card transactions with no additional parameters.CryptocurrencyNote that voids are not supported for cryptocurrency.  You must refund crypto transactions
manually from your cryptocurrency wallet.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"transactionId":"<PREVIOUS TRANSACTION ID>",}# run the transaction.response=client.void(request)print("Response:%r"%response)Time Out ReversalAPI Credential Types:MerchantRequired Role:Payment API AccessPayment transactions require a stable network to function correctly and
no network is stable all the time.  Time out reversals are a great line
of defense against accidentally double charging consumers when payments
are retried during shaky network conditions.We highly recommend developers use this API whenever a charge, preauth, or refund transaction times out.  If you don't receive a definitive response
from BlockChyp, you can't be certain about whether or not the transaction went through.The best practice in this situation is to send a time out reversal request.  Time out reversals check for a transaction and void it if it exists.The only caveat is that developers must use thetransactionRefproperty (txReffor the CLI) when executing charge, preauth, and refund transactions.The reason for this requirement is that if a system never receives a definitive
response for a transaction, the system would never have received the BlockChyp
generated Transaction ID.  We have to fall back to Transaction Ref to identify
a transaction.CryptocurrencyNote that refunds are not supported for cryptocurrency.  You must refund crypto transactions
manually from your cryptocurrency wallet.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"transactionRef":"<LAST TRANSACTION REF>",}# run the transaction.response=client.reverse(request)print("Response:%r"%response)Gift Card ActivationAPI Credential Types:MerchantRequired Role:Payment API AccessThis API activates or adds value to BlockChyp gift cards.
Just pass in the terminal name and the amount to add to the card.
Once the customer swipes their card, the terminal will use keys
on the mag stripe to add value to the card.You don't need to handle a new gift card activation or a gift card recharge any
differently.  The terminal firmware will figure out what to do on its
own while also returning the new balance for the gift card.This is the part of the system where BlockChyp's blockchain DNA comes
closest to the surface.  The BlockChyp gift card system doesn't really
use gift card numbers.  This means they can't be stolen.BlockChyp identifies cards with an elliptic curve public key instead.
Gift card transactions are actually blocks signed with those keys.
This means there are no shared secrets sent over the network.
To keep track of a BlockChyp gift card, hang on to thepublic keyreturned
during gift card activation.  That's the gift card's elliptic curve public key.We sometimes print numbers on our gift cards, but these are actually
decimal encoded hashes of a portion of the public key to make our gift
cards seemnormaltonormies.  They can be used
for balance checks and play a lookup role in online gift card
authorization, but are of little use beyond that.Voids and ReversalsGift card activations can be voided and reversed just like any other
BlockChyp transaction.  Use the Transaction ID or Transaction Ref
to identify the gift activation transaction as you normally would for
voiding or reversing a conventional payment transaction.Importing Gift CardsBlockChyp does have the ability to import gift card liability from
conventional gift card platforms.  Unfortunately, BlockChyp does not
support activating cards on third party systems.  However, you can import
your outstanding gift cards and customers can swipe them on the
terminals like BlockChyp's standard gift cards.No special coding is required to access this feature.  The gateway and
terminal firmware handle everything for you.Third Party Gift Card NetworksBlockChyp does not currently provide any native support for other gift card
platforms beyond importing gift card liability.  We do have a white listing system
that can be used to support your own custom gift card implementations.  We have a security review
process before we can allow a BIN range to be white listed, so contactsupport@blockchyp.comif you need to white list a BIN range.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","amount":"50.00",}# run the transaction.response=client.gift_activate(request)print("Response:%r"%response)BalanceAPI Credential Types:MerchantRequired Role:Payment API AccessThis API checks a gift or EBT card balance.Gift Card Balance ChecksFor gift cards, pass in a terminal name and the customer will be prompted
to swipe a card on that terminal.  The remaining balance will be displayed
briefly on the terminal screen and the API response will include the gift card's public key and the remaining balance.EBT Balance ChecksAll EBT transactions require a PIN, so to check an EBT card balance,
you need to pass in theebtflag just like you would for a normal EBT
charge transaction.  The customer will be prompted to swipe their card and
enter a PIN code.  If everything checks out, the remaining balance on the
card will be displayed on the terminal for the customer and returned with the API response.Testing Gift Card Balance ChecksTest gift card balance checks work no differently than live gift cards.  You
must activate a test gift card first to test balance checks.  Test
gift cards are real blockchain cards that live on our parallel test blockchain.Testing EBT Gift Card Balance ChecksAll test EBT transactions assume a starting balance of $100.00.  As a result,
test EBT balance checks always return a balance of $100.00.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","cardType":blockchyp.CardType.EBT,}# run the transaction.response=client.balance(request)print("Response:%r"%response)Close BatchAPI Credential Types:MerchantRequired Role:Payment API AccessThis API will close the merchant's batch if it's currently open.By default, merchant batches will close automatically at 3 AM in their
local time zone.  The automatic batch closure time can be changed
in the Merchant Profile or disabled completely.If automatic batch closure is disabled, you'll need to use this API to
close the batch manually.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,}# run the transaction.response=client.close_batch(request)print("Response:%r"%response)Send Payment LinkAPI Credential Types:MerchantRequired Role:Payment API AccessThis API allows you to send an invoice to a customer and capture payment
via a BlockChyp hosted payment page.If you set theautoSendflag, BlockChyp will send a basic invoice email
to the customer for you that includes the payment link.  If you'd rather have
more control over the look of the email message, you can omit theautoSendflag and send the customer email yourself.There are a lot of optional parameters for this API, but at a minimum
you'll need to pass in a total, customer name, and email address. (Unless
you use thecashierflag.)Customer InfoUnless you're using thecashierflag, you must specify a customer; either by
creating a new customer record inline or passing in an existing Customer ID or Customer Ref.Line Item Level DataIt's not strictly required, but we strongly recommend sending line item level
detail with every request.  It will make the invoice look more complete
and the data format for line item level data is the exact same format used
for terminal line item display, so the same code can be used to support both areas.DescriptionsYou can also provide a free form description or message to display near
the bottom of the invoice.  Usually this is some kind of thank you note
or instruction.Terms and ConditionsYou can include long form contract language with a request and capture
terms and conditions accepted at the same time payment is captured.The interface is identical to that used for the terminal based Terms and
Conditions API in that you can pass in content directly viatcContentor via
a preconfigured template viatcAlias.  The Terms and Conditions log will also be updated when
agreement acceptance is incorporated into a send link request.Auto SendBlockChyp does not send the email notification automatically.   This safeguard prevents real
emails from going out when you may not expect them If you want BlockChyp to send the email
for you, just add theautoSendflag with all requests.CryptocurrencyIf the merchant is configured to support cryptocurrency transactions, the payment page will
display additional UI widgets that allowing customers to switch to a crypto payment method.TokenizationAdd theenrollflag to a send link request to enroll the payment method
in the token vault.Add theenrollOnlyflag to enroll the payment method in the token vault without any immediate payment taking place. The payment link will ask the user for their payment information and inform them that they will not be charged immediately, but that their payment may be used for future transactions.Cashier Facing Card EntryBlockChyp can be used to generate internal/cashier facing card entry pages as well.  This is
designed for situations where you might need to take a phone order and don't
have an available terminal.If you pass in thecashierflag, no email will be sent and you'll be able to
load the link in a browser or iframe for payment entry.  When thecashierflag
is used, theautoSendflag will be ignored.Note that cryptocurrency is not supported for cashier facing payment entry.Payment NotificationsWhen a customer successfully submits payment, the merchant will receive an email
notifying them that the payment was received.Real Time Callback NotificationsEmail notifications are fine, but you may want your system to be informed
immediately whenever a payment event occurs.  By using the optionalcallbackUrlrequest
property, you can specify a URL to which the Authorization Response will be posted
every time the user submits a payment, whether approved or otherwise.The response will be sent as a JSON encoded POST request and will be the exact
same format as all BlockChyp charge and preauth transaction responses.Status PollingIf real time callbacks aren't practical or necessary in your environment, you can
always use the Payment Link Status API described futher on.A common use case for the send link API with status polling is curbside pickup.
You could have your system check the Payment Link Status when a customer arrives to
ensure it's been paid without necessarily needing to create background threads
to constantly poll for status updates.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"transactionRef":"<TX REF>","amount":"199.99","description":"Widget","subject":"Widget invoice","transaction":{"subtotal":"195.00","tax":"4.99","total":"199.99","items":[{"description":"Widget","price":"195.00","quantity":1,},],},"autoSend":True,"customer":{"customerRef":"Customer reference string","firstName":"FirstName","lastName":"LastName","companyName":"Company Name","emailAddress":"notifications@blockchypteam.m8r.co","smsNumber":"(123) 123-1231",},}# run the transaction.response=client.send_payment_link(request)print("Response:%r"%response)Resend Payment LinkAPI Credential Types:MerchantRequired Role:Payment API AccessThis API will resend a previously created payment link.  An error is returned if the payment link is expired, has been
cancelled, or has already been paid.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"linkCode":"<PAYMENT LINK CODE>",}# run the transaction.response=client.resend_payment_link(request)print("Response:%r"%response)Cancel Payment LinkAPI Credential Types:MerchantRequired Role:Payment API AccessThis API cancels a payment link.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"linkCode":"<PAYMENT LINK CODE>",}# run the transaction.response=client.cancel_payment_link(request)print("Response:%r"%response)Payment Link StatusAPI Credential Types:MerchantRequired Role:Payment API AccessThis API allows you to check on the status of a payment link, including transaction data
and the full history of attempted transactions.This API is the preferred source of truth and best practice when you want to check on the
status of a payment link (as opposed to Transaction Status). The Transaction Status API is not
ideal because of ambiguity when there are multiple transactions associated with a single
payment link.You must pass thelinkCodevalue associated with the payment link. It is included in the response from BlockChyp when the payment link is originally created.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"linkCode":"<PAYMENT LINK CODE>",}# run the transaction.response=client.payment_link_status(request)print("Response:%r"%response)Transaction StatusAPI Credential Types:MerchantRequired Role:Payment API AccessThis API returns the current status for any transaction.  You can lookup a transaction
by its BlockChyp assigned Transaction ID or your own Transaction Ref.You should always use globally unique Transaction Ref values, but in the event
that you duplicate Transaction Refs, the most recent transaction matching your
Transaction Ref is returned.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"transactionId":"<TRANSACTION ID>",}# run the transaction.response=client.transaction_status(request)print("Response:%r"%response)Cash DiscountAPI Credential Types:MerchantRequired Role:Payment API AccessThis API calculates the surcharge, cash discount, and total amounts for cash transactions.If you're using BlockChyp's cash discounting features, you can use this endpoint
to ensure the numbers and receipts for true cash transactions are consistent
with transactions processed by BlockChyp.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"amount":"100.00","cashDiscount":True,"surcharge":True,}# run the transaction.response=client.cash_discount(request)print("Response:%r"%response)Batch HistoryAPI Credential Types:MerchantRequired Role:Payment API AccessThis endpoint allows developers to query the gateway for the merchant's batch history.
The data will be returned in descending order of open date with the most recent
batch returned first.  The results will include basic information about the batch.
Consider using the Batch Details API for more detail about a specific batch.Limiting ResultsThis API will return a maximum of 250 results.  Use themaxResultsproperty to
limit maximum results even further and use thestartIndexproperty to
page through results that span multiple queries.For example, if you want the ten most recent batches, pass in a value of10formaxResults.  Also note thatstartIndexis zero based. Use a value of0to
get the first batch in the dataset.Filtering by Date RangeYou can also filter results by date.  Use thestartDateandendDateproperties to return only those batches opened between those dates.
You can use eitherstartDateandendDateand you can use date filters
in conjunction withmaxResultsandstartIndeximportosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"maxResults":250,"startIndex":0,}# run the transaction.response=client.batch_history(request)print("Response:%r"%response)Batch DetailsAPI Credential Types:MerchantRequired Role:Payment API AccessThis API allows developers to pull down details for a specific batch,
including captured volume, gift card activity, expected deposit, and
captured volume broken down by terminal.The only required request parameter isbatchId.  Batch IDs are returned
with every transaction response and can be discovered using the Batch
History API.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"batchId":"<BATCH ID>",}# run the transaction.response=client.batch_details(request)print("Response:%r"%response)Transaction HistoryAPI Credential Types:MerchantRequired Role:Payment API AccessThis endpoint provides several different methods to sift through
transaction history.By default with no filtering properties, this endpoint will return the 250
most recent transactions.Limiting ResultsThis API will return a maximum of 50 results in a single query.  Use themaxResultsproperty
to limit maximum results even further and use thestartIndexproperty to
page through results that span multiple queries.For example, if you want the ten most recent batches, pass in a value of10formaxResults.  Also note thatstartIndexis zero based. Use a value of0to
get the first transaction in the dataset.Filtering By Date RangeYou can also filter results by date.  Use thestartDateandendDateproperties to return only transactions run between those dates.
You can use eitherstartDateorendDateand you can use date filters
in conjunction withmaxResultsandstartIndexFiltering By BatchTo restrict results to a single batch, pass in thebatchIdparameter.Filtering By TerminalTo restrict results to those executed on a single terminal, pass in the terminal name.Combining FiltersNone of the above filters are mutually exclusive.  You can combine any of the
above properties in a single request to restrict transaction results to a
narrower set of results.Searching Transaction HistoryYou can search transaction history by passing in search criteria with thequeryoption.  The search system will match the amount (requested and authorized),
last four of the card number, cardholder name, and the auth code.Note that when search queries are used, terminalName or
batch id filters are not supported.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"maxResults":10,"batchId":"<BATCH ID>",}# run the transaction.response=client.transaction_history(request)print("Response:%r"%response)List Queued TransactionsAPI Credential Types:MerchantRequired Role:Payment API AccessReturns a list of transaction refs of transactions queued on a terminal.
Details about the transactions can be retrieved using the Transaction Status
API.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal",}# run the transaction.response=client.list_queued_transactions(request)print("Response:%r"%response)Delete Queued TransactionAPI Credential Types:MerchantRequired Role:Payment API AccessDeletes one or all queued transactions from a terminal. If*is passed as
a transaction ref, then the entire terminal queue will be cleared. An error is
returned if the passed transaction ref is not queued on the terminal.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal","transactionRef":"*",}# run the transaction.response=client.delete_queued_transaction(request)print("Response:%r"%response)Terminal Management EndpointsThese APIs support terminal management functions and additional terminal
features such as line item display, messages, and interactive prompts.These features can be used to extend a point of sale system's functionality.Terminal PingAPI Credential Types:MerchantRequired Role:Payment API AccessThis simple test transaction helps ensure good communication with a payment terminal
and is usually the first test you'll run in development.It tests communication with the terminal and returns a positive response if everything
is okay.  It works the same way in local or cloud relay mode.If you get a positive response, you've successfully verified all of the following:The terminal is online.There is a valid route to the terminal.The API Credentials are valid.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal",}# run the transaction.response=client.ping(request)print("Response:%r"%response)Terminal LocateAPI Credential Types:MerchantRequired Role:Payment API AccessThis endpoint returns a terminal's routing and location information.The result will indicate whether or not the terminal is in cloud relay mode and will
return the local IP address if the terminal is in local mode.The terminal will also return the public key for the terminal.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal",}# run the transaction.response=client.locate(request)print("Response:%r"%response)Terminal ClearAPI Credential Types:MerchantRequired Role:Payment API AccessThis API interrupts whatever a terminal may be doing and returns it to the
idle state.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal",}# run the transaction.response=client.clear(request)print("Response:%r"%response)Terminal StatusAPI Credential Types:MerchantRequired Role:Payment API AccessThis API returns the current status of a payment terminal.  This is typically used
as a way to determine if the terminal is busy before sending a new transaction.If the terminal is busy,idlewill be false and thestatusfield will return
a short string that indicates the transaction type currently in progress.  The system
will also return the timestamp of the last status change in thesincefield.ThecardInSlotfield in the response will indicates whether or not a card is currently in the card reader slot.If the system is running a payment transaction and you wisely passed in a
Transaction Ref, this API will also return the Transaction Ref of the in progress
transaction.The table below lists all possible status responses.Status CodeDescriptionidleThe terminal is idle and ready for transactions.  The default branding is being displayed.activateThe terminal is in the process of activating and pairing with the merchant account.balanceA balance check (EBT or Gift Card) is pending on the terminal.boolean-promptA boolean prompt (yes/no) operation is pending on the terminal.signatureA signature capture is pending.cryptoA cryptocurrency transaction is pending.enrollA token vault enrollment operation is pending.gift-activateA gift card activation operation is in progress.messageThe terminal is displaying a custom message.chargeThe terminal is executing a charge transaction.preauthThe terminal is executing a preauth transaction.refundThe terminal is executing a refund transaction.surveyThe terminal is displaying post transaction survey questions.terms-and-conditionsThe terminal is pending terms and conditions acceptance and signature.text-promptThe terminal is awaiting response to a text input prompt.txdisplayThe terminal is displaying transaction and/or line item level details.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal",}# run the transaction.response=client.terminal_status(request)print("Response:%r"%response)Capture SignatureAPI Credential Types:MerchantRequired Role:Payment API AccessThis endpoint captures a written signature from the terminal and returns the
image.Unlike the Terms & Conditions API, this endpoint performs basic signature
capture with no agreement display or signature archival.Under the hood, signatures are captured in a proprietary vector format and
must be converted to a common raster format in order to be useful to most
applications.  At a minimum, you must specify an image format using thesigFormatparameter.  Currently, JPG and PNG are supported.By default, images are returned in the JSON response as hex encoded binary.
You can redirect the binary image output to a file using thesigFileparameter.You can also scale the output image to your preferred width by
passing in asigWidthparameter.  The image will be scaled to that
width, preserving the aspect ratio of the original image.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal",# File format for the signature image."sigFormat":blockchyp.SignatureFormat.PNG,# Width of the signature image in pixels."sigWidth":200,}# run the transaction.response=client.capture_signature(request)print("Response:%r"%response)New Transaction DisplayAPI Credential Types:MerchantRequired Role:Payment API AccessThis API sends totals and line item level data to the terminal.At a minimum, you should send total information as part of a display request,
includingtotal,tax, andsubtotal.You can also send line item level data and each line item can have adescription,qty,price, andextendedprice.If you fail to send an extended price, BlockChyp will multiply theqtyby theprice.  However, we strongly recommend you precalculate all the fields yourself
to ensure consistency.  For example, your treatment of floating-point multiplication
and rounding may differ slightly from BlockChyp's.DiscountsYou have the option to show discounts on the display as individual line items
with negative values or you can associate discounts with a specific line item.
You can apply any number of discounts to an individual line item with a description
and amount.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","transaction":{"subtotal":"60.00","tax":"5.00","total":"65.00","items":[{"description":"Leki Trekking Poles","price":"35.00","quantity":2,"extended":"70.00","discounts":[{"description":"memberDiscount","amount":"10.00",},],},],},}# run the transaction.response=client.new_transaction_display(request)print("Response:%r"%response)Update Transaction DisplayAPI Credential Types:MerchantRequired Role:Payment API AccessSimilar toNew Transaction Display, this variant allows developers to update
line item level data currently being displayed on the terminal.This feature is designed for situations where you want to update the terminal display as
items are scanned.  You'll only have to send information to the
terminal that's changed, which usually means the new line item and updated totals.If the terminal is not in line item display mode and you invoke this endpoint,
the first invocation will behave like aNew Transaction Displaycall.At a minimum, you should send total information as part of a display request,
includingtotal,tax, andsubtotal.You can also send line item level data and each line item can have adescription,qty,price, andextendedprice.If you fail to send an extended price, BlockChyp will multiply theqtyby theprice.  However, we strongly recommend you precalculate all the fields yourself
to ensure consistency.  For example, your treatment of floating-point multiplication and rounding
may differ slightly from BlockChyp's.DiscountsYou have the option to show discounts on the display as individual line items
with negative values or you can associate discounts with a specific line item.
You can apply any number of discounts to an individual line item with a description
and amount.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","transaction":{"subtotal":"60.00","tax":"5.00","total":"65.00","items":[{"description":"Leki Trekking Poles","price":"35.00","quantity":2,"extended":"70.00","discounts":[{"description":"memberDiscount","amount":"10.00",},],},],},}# run the transaction.response=client.update_transaction_display(request)print("Response:%r"%response)Display MessageAPI Credential Types:MerchantRequired Role:Payment API AccessThis API displays a message on the payment terminal.Just specify the target terminal and the message using themessageparameter.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","message":"Thank you for your business.",}# run the transaction.response=client.message(request)print("Response:%r"%response)Boolean PromptAPI Credential Types:MerchantRequired Role:Payment API AccessThis API prompts the customer to answer a yes or no question.You can specify the question or prompt with thepromptparameter and
the response is returned in theresponsefield.This can be used for a number of use cases including starting a loyalty enrollment
workflow or customer facing suggestive selling prompts.Custom CaptionsYou can optionally override the "YES" and "NO" button captions by
using theyesCaptionandnoCaptionrequest parameters.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal","prompt":"Would you like to become a member?","yesCaption":"Yes","noCaption":"No",}# run the transaction.response=client.boolean_prompt(request)print("Response:%r"%response)Text PromptAPI Credential Types:MerchantRequired Role:Payment API AccessThis API prompts the customer to enter numeric or alphanumeric data.Due to PCI rules, free-form prompts are not permitted when the response
could be any valid string.  The reason for this is that a malicious
developer (not you, of course) could use text prompts to ask the customer to
input a card number or PIN code.This means that instead of providing a prompt, you provide apromptTypeinstead.The prompt types currently supported are listed below:phone: Captures a phone number.email: Captures an email address.first-name: Captures a first name.last-name: Captures a last name.customer-number: Captures a customer number.rewards-number: Captures a rewards number.You can specify the prompt with thepromptTypeparameter and
the response is returned in theresponsefield.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal",# Type of prompt. Can be 'email', 'phone', 'customer-number', or# 'rewards-number'."promptType":blockchyp.PromptType.EMAIL,}# run the transaction.response=client.text_prompt(request)print("Response:%r"%response)List TerminalsAPI Credential Types:Merchant & PartnerRequired Role:Terminal ManagementThis API returns details about terminals associated with a merchant account.Status and resource information is returned for all terminals along with a preview of the
current branding image displayed on the terminalimportosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.terminals(request)print("Response:%r"%response)Deactivate TerminalAPI Credential Types:Merchant & PartnerRequired Role:Terminal ManagementThis API deactivates a payment terminal.If the terminal exists and is currently online, it will be removed from the merchant's
terminal inventory.  The terminal will be remotely cleared and factory reset.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalId":"<TERMINAL ID>",}# run the transaction.response=client.deactivate_terminal(request)print("Response:%r"%response)Activate TerminalAPI Credential Types:Merchant & PartnerRequired Role:Terminal ManagementThis API activates a payment terminal.If successful, the payment terminal will restart, generate new encryption keys, and download any active
branding assets for the merchant account it's been added to.Activation requests require an activation code and a unique terminal name.  All terminal names must be unique across
a merchant account.Optional ParametersmerchantId:For partner scoped API credentials, a merchant ID is required.  For merchant scoped API credentials, the merchant ID is implicit and cannot be overridden.cloudRelay:Activates the terminal in cloud relay mode.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal","activationCode":"<ACTIVATION CODE>",}# run the transaction.response=client.activate_terminal(request)print("Response:%r"%response)Reboot TerminalAPI Credential Types:MerchantRequired Role:Payment API AccessThis API reboots the terminal.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"terminalName":"Test Terminal",}# run the transaction.response=client.reboot(request)print("Response:%r"%response)Terms & Conditions EndpointsDevelopers can use BlockChyp to display and capture acceptance of contracts or agreements related to transactions.
These agreements can be any long-form contract ranging from rental agreements to HIPPA disclosures.There are two basic approaches to terms and conditions capture.  Merchants can store contract templates in
BlockChyp or they can send the full agreement text as part of every API call.  The right approach will largely
depend on whether or not the system being integrated with BlockChyp already has a mechanism for organizing
and managing agreements.  For systems that already have this feature built in, it's probably not necessary
to use Terms and Conditions.When agreements are displayed on a terminal, the consumer can scroll through and read the entire agreement,
and provide a signature.  Results are returned as part of the API response, but BlockChyp also stores a
record of the agreement including the signature image, timestamp, and the full text of the agreement that was
agreed to.The Terms and Conditions Log APIs can be used to search and retrieve acceptance records.  Those records
can also be linked to a transaction if a transaction id is provided with the original API request.Terms & Conditions CaptureAPI Credential Types:MerchantRequired Role:Terms & Conditions ManagementThis API allows you to prompt a customer to accept a legal agreement on the terminal
and (usually) capture their signature.Content for the agreement can be specified in two ways.  You can reference a
previously configured T&C template or pass in the full agreement text with every request.Using TemplatesIf your application doesn't keep track of agreements you can leverage BlockChyp's
template system.  You can create any number of T&C Templates in the merchant dashboard
and pass in thetcAliasflag to specify which one should display.Raw ContentIf your system keeps track of the agreement language or executes complicated merging
and rendering logic, you can bypass our template system and pass in the full text with
every transaction.  UsetcNameto pass in the agreement name andtcContentto
pass in the contract text.  Note that only plain text is supported.Bypassing SignaturesSignature images are captured by default.  If for some reason this doesn't fit your
use case and you'd like to capture acceptance without actually capturing a signature image, set
thedisableSignatureflag in the request.Terms & Conditions LogEvery time a user accepts an agreement on the terminal, the signature image (if captured),
will be uploaded to the gateway.  The image will also be added to the log along with the full text of the
agreement.  This preserves the historical record in the event that standard agreements
or templates change over time.Associating Agreements with TransactionsTo associate a Terms & Conditions log entry with a transaction, just pass in the
Transaction ID or Transaction Ref for the associated transaction.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal",# Alias for a Terms and Conditions template configured in the BlockChyp# dashboard."tcAlias":"hippa",# Name of the contract or document if not using an alias."tcName":"HIPPA Disclosure",# Full text of the contract or disclosure if not using an alias."tcContent":"Full contract text",# File format for the signature image."sigFormat":blockchyp.SignatureFormat.PNG,# Width of the signature image in pixels."sigWidth":200,# Whether or not a signature is required. Defaults to true."sigRequired":True,}# run the transaction.response=client.terms_and_conditions(request)print("Response:%r"%response)List TemplatesAPI Credential Types:MerchantRequired Role:Terms & Conditions ManagementThis API returns all terms and conditions templates associated with a merchant account.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.tc_templates(request)print("Response:%r"%response)Get TemplateAPI Credential Types:MerchantRequired Role:Terms & Conditions ManagementThis API returns as single terms and conditions template.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"templateId":"<TEMPLATE ID>",}# run the transaction.response=client.tc_template(request)print("Response:%r"%response)Update TemplateAPI Credential Types:MerchantRequired Role:Terms & Conditions ManagementThis API updates or creates a terms and conditions template.Terms and conditions templates are fairly simple and essentially consist of a name, content, and alias.The name is the caption that will be displayed at the top of the screen.  The alias is a code or short
description that will be used in subsequence API calls to refer to the template.Content is the full text of the contract or agreement.  Currently, no special formatting or
merge behavior is supported.  Only plain text is supported.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"alias":"HIPPA","name":"HIPPA Disclosure","content":"Lorem ipsum dolor sit amet.",}# run the transaction.response=client.tc_update_template(request)print("Response:%r"%response)Delete TemplateAPI Credential Types:MerchantRequired Role:Terms & Conditions ManagementThis API deletes a terms and conditions template.If a template is deleted, its alias can be reused and any previous Terms & Conditions log entry
derived from the template being deleted is fully preserved since log entries always include
a complete independent copy of the agreement text.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"templateId":"<TEMPLATE ID>",}# run the transaction.response=client.tc_delete_template(request)print("Response:%r"%response)Terms & Conditions LogAPI Credential Types:MerchantRequired Role:Terms & Conditions ManagementThis API allows developers to search and sort through terms and conditions log entries.The default API call with no parameters will return the last 250 log entries in descending order.Optional parameters can be used to filter and query the data set.transactionId:If provided, returns only those log entries associated with a specific transactions.  Paging and date filters are ignored if this parameter is used.maxResults:The max number of results to return in a single page.  Defaults to 250 and 250 is the maximum value.startIndexThe zero based start index of results within the full result set to return.  Used to advance pages.  For example, if the page size is 10 and you wish to return the second page of results, send a startIndex of 10.startDate: An optional start date for results provided as an ISO 8601 timestamp. (e.g. 2022-05-24T13:51:38+00:00)endDate: An optional end date for results provided as an ISO 8601 timestamp. (e.g. 2022-05-24T13:51:38+00:00)importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"logEntryId":"<LOG ENTRY ID>",}# run the transaction.response=client.tc_log(request)print("Response:%r"%response)Terms & Conditions DetailsAPI Credential Types:MerchantRequired Role:Terms & Conditions ManagementThis API returns details for a single terms and conditions log entry.  ThelogEntryIdof the record to be returned is the only required parameter.The signature image is returned as Base 64 encoded binary in the image format specified by thesigFormatfield.
The default format is PNG.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"logEntryId":"<ENTRY ID>",}# run the transaction.response=client.tc_entry(request)print("Response:%r"%response)Token ManagementBlockChyp supports saved payments and recurring payments through the use of tokens.  Tokens can be created
via the Enroll API or the web tokenizer.  Once created, these tokens can be used for subsequent payments
or associated with customer records as saved payment methods.Tokens are limited to a single merchant by default, but can be shared across an organization for multi-location
merchants by special arrangement with BlockChyp.  Contact your BlockChyp rep to setup token sharing.EnrollAPI Credential Types:MerchantRequired Role:Payment API AccessThis API allows you to tokenize and enroll a payment method in the token
vault.  You can also pass in customer information and associate the
payment method with a customer record.A token is returned in the response that can be used in subsequent charge,
preauth, and refund transactions.Gift Cards and EBTGift Cards and EBT cards cannot be tokenized.E-Commerce TokensThe tokens returned by the enroll API and the e-commerce web tokenizer
are the same tokens and can be used interchangeably.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,"terminalName":"Test Terminal",}# run the transaction.response=client.enroll(request)print("Response:%r"%response)Token MetadataAPI Credential Types:MerchantRequired Role:Payment API AccessThis API retrieves status and metadata information about a token,
including any links to customer records.This will also return any customer records related to the card
behind the token.  If the underlying card has been tokenized
multiple times, all customers related to the card will be returned,
even if those customer associations are related to other tokens.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"token":"<TOKEN>",}# run the transaction.response=client.token_metadata(request)print("Response:%r"%response)Link TokenAPI Credential Types:MerchantRequired Role:Payment API AccessThis API links a payment token with a customer record.  Usually this would only be needed
to reverse a previous unlink operation.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"token":"<TOKEN>","customerId":"<CUSTOMER ID>",}# run the transaction.response=client.link_token(request)print("Response:%r"%response)Unlink TokenAPI Credential Types:MerchantRequired Role:Payment API AccessThis API removes a payment token link from a customer record.This will remove links between the customer record and all tokens
for the same underlying card.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"token":"<TOKEN>","customerId":"<CUSTOMER ID>",}# run the transaction.response=client.unlink_token(request)print("Response:%r"%response)Delete TokenAPI Credential Types:MerchantRequired Role:Payment API AccessThis API deletes a payment token from the gateway.  Tokens are automatically deleted if they have not been used
for a year.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"token":"<TOKEN>",}# run the transaction.response=client.delete_token(request)print("Response:%r"%response)Customer EndpointsThese APIs allow developers to create and manage customer records in BlockChyp.  Developers who wish to use
BlockChyp for tokenized recurring payments can use tokens directly if they have their own customer management
system.  However, BlockChyp provides additional tools for managing customers and keeping track of a customer's saved
payment tokens.In addition, if customer features are used, BlockChyp can detect a payment method associated with an existing
customer, and return customer data with payment transactions.  This can be used as a passive method to detect
repeat customers.Update CustomerAPI Credential Types:MerchantRequired Role:Payment API AccessThis API adds or updates a customer record.If you pass in customer information includingfirstName,lastName,email,
orsmswithout any Customer ID or Customer Ref, a new record will
be created.If you pass incustomerRefandcustomerId, the customer record will be updated
if it exists.Customer RefThecustomerReffield is optional, but highly recommended as this allows you
to use your own customer identifiers instead of storing BlockChyp's Customer IDs
in your systems.Creating Customer Records With Payment TransactionsIf you have customer information available at the time a payment transaction is
executed, you can pass all the same customer information directly into a payment transaction.  BlockChyp
will create a customer record at the same time payment is captured.  The advantage of this approach is
that the customer's payment card is automatically associated with the customer record in a single step.
If the customer uses the payment card in the future, the customer data will automatically
be returned.  You won't need to ask the customer to provide any additional information.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"customer":{"id":"<CUSTOMER ID>","customerRef":"Customer reference string","firstName":"FirstName","lastName":"LastName","companyName":"Company Name","emailAddress":"notifications@blockchypteam.m8r.co","smsNumber":"(123) 123-1231",},}# run the transaction.response=client.update_customer(request)print("Response:%r"%response)Retrieve CustomerAPI Credential Types:MerchantRequired Role:Payment API AccessWith this API, you can retrieve detailed information about a customer record, including saved payment
methods if available.Customers can be looked up bycustomerIdorcustomerRef.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"customerId":"<CUSTOMER ID>",}# run the transaction.response=client.customer(request)print("Response:%r"%response)Search CustomerAPI Credential Types:MerchantRequired Role:Payment API AccessThis API searches the customer database and returns matching results.Usequeryto pass in a search string and the system will return all results whose
first or last names contain the query string.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"query":"(123) 123-1234",}# run the transaction.response=client.customer_search(request)print("Response:%r"%response)Delete CustomerAPI Credential Types:MerchantRequired Role:Payment API AccessThis API deletes a customer record.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"customerId":"<CUSTOMER ID>",}# run the transaction.response=client.delete_customer(request)print("Response:%r"%response)Survey ReferenceThese APIs are used to work with post-transaction surveys and survey data.Merchants can optionally configure scaled (1-5) or yes/no questions that can be presented to consumers
after every approved Charge and Preauth transaction.  Surveys do not require any custom programming and
merchants can simply configure them without the point-of-sale system needing any additional customization.However, these APIs allow point-of-sale or third-party system developers to integrate survey question configuration
or result visualization into their own systems.List QuestionsAPI Credential Types:MerchantRequired Role:Survey ManagementThis API returns all survey questions in the order in which they would be presented on the terminal.All questions are returned, whether enabled or disabled.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.survey_questions(request)print("Response:%r"%response)Question DetailsAPI Credential Types:MerchantRequired Role:Survey ManagementThis API returns a single survey question with response data.questionIdis required.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"questionId":"<QUESTION ID>",}# run the transaction.response=client.survey_question(request)print("Response:%r"%response)Update QuestionAPI Credential Types:MerchantRequired Role:Survey ManagementThis API updates or creates survey questions.questionTextandquestionTypeare required
fields.  The following values are valid forquestionType.yes_no:Use for simple yes or no questions.scaled:Displays the question with buttons that allow the customer to respond with values from 1 through 5.Questions are disabled by default.  Pass inenabledto enable a question.Theordinalfield is used to control the sequence of questions when multiple questions are enabled.  We recommend keeping
the number of questions minimal.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"id":"<QUESTION ID>","ordinal":1,"questionText":"Would you shop here again?","questionType":"yes_no","enabled":True,}# run the transaction.response=client.update_survey_question(request)print("Response:%r"%response)Delete QuestionAPI Credential Types:MerchantRequired Role:Survey ManagementThis API deletes a survey question.questionIdis a required parameter.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"questionId":"<QUESTION ID>",}# run the transaction.response=client.delete_survey_question(request)print("Response:%r"%response)Survey ResultsAPI Credential Types:MerchantRequired Role:Survey ManagementThis API returns survey results for a single question.The results returned include the response rate, which is the percentage of transactions after which
the consumer provided an answer.Theresponsesarray breaks down the results by answer, providing the total number of responses,
the answer's percentage of the total, and the average transaction amount associated with a specific
answer.By default, all results based on all responses are returned.  However, developers may optionally providestartDateandendDateparameters to return only responses provided between certain dates.startDateandendDatecan be provided in MM/DD/YYYY or YYYY-MM-DD format.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"questionId":"<QUESTION ID>",}# run the transaction.response=client.survey_results(request)print("Response:%r"%response)Media and Branding ControlBlockChyp has a sophisticated terminal media and branding control platform.  Terminals can be configured to
display logos, images, videos, and slide shows when a terminal is idle.  Branding assets can be configured
at the partner, organization, and merchant level with fine-grained hour-by-hour schedules, if desired.Conceptually, all branding and media start with the media library.  Merchants, Partners, and Organizations can
upload images or video and build branding assets from uploaded media.Slide shows can combine images from the media library into a timed loop of repeating images.Branding Assets can then be used to combine media or slide shows with priority and timing rules to create what
we call the Terminal Branding Stack.We call a group of branding assets theTerminal Branding Stackbecause there are implicit rules about which
branding assets take priority. For example, a merchant with no branding assets configured will inherit the
branding rules from any organization to which the merchant may belong.  If the merchant doesn't belong to an organization
or the organization has no branding rules configured, then the system will defer to branding defaults established
by the point-of-sale or software partner that owns the merchant.This feature enables partners and organizations (multi-store operators and large national chains) to configure branding
for potentially thousands of terminals from a single interface.Terminal Branding can also be configured at the individual terminal level and a merchant's terminal fleet
can be broken into groups and branding configured at the group level.  Branding configured at the terminal
level will always override branding from any higher level group.The order of priority for the Terminal Branding Stack is given below.TerminalTerminal GroupMerchantOrganization (Region, Chain, etc)PartnerBlockChyp Default LogoMedia LibraryAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API returns the entire media library associated with the API Credentials (Merchant, Partner, or Organization).  The media library results will include the ID used
to reference a media asset in slide shows and branding assets along with the full file url and thumbnail.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.media(request)print("Response:%r"%response)Upload MediaAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API supports media library uploads.  The operation of this API works slightly differently depending
on the SDK platform.  In all cases, the intent is to allow the file's binary to be passed into the SDK using
the lowest level I/O primitive possible in order to support situations where developers aren't working
with literal files.  It might be (and usually is) more convenient to work with buffers, raw bytes, or streams.For example, the Go implementation accepts anio.Readerand the Java implementation accepts ajava.io.InputStream.  The CLI does accept a literal File URL via the-filecommand line parameter.The following file formats are accepted as valid uploads:.png.jpg.jpeg.gif.mov.mpg.mp4.mpegThe UploadMetadata object allows developers to pass additional metadata about the upload includingfileName,fileSize, anduploadId.None of these values are required, but providing them can unlock some additional functionality relating to
media uploads.fileNamewill be used to record the original file name in the media library.fileSizeanduploadIdare used to support upload status tracking, which is especially useful for large video file
uploads.ThefileSizeshould be the file's full size in bytes.TheuploadIdvalue can be any random string.  This is the value you'll use to check the status of an upload
via the Upload Status API.  This API will return information needed to drive progress feedback on uploads and
return video transcoding information.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"fileName":"aviato.png","fileSize":18843,"uploadId":"<RANDOM ID>",}# run the transaction.f=open("aviato.png","rb")content=f.read()response=client.upload_media(request,content)f.close()print("Response:%r"%response)Upload StatusAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API returns status and progress information about in progress or recently completed uploads.Before calling this API, developers must first start a file upload withfileSizeanduploadIdparameters.The data structure returned will include the file size, number of bytes uploaded, a narrative status
and flags indicating whether or not the upload is complete or post upload processing is in progress.If the upload is completed, the ID assigned to the media asset and a link to the thumbnail image will
also be returned.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"uploadId":"<UPLOAD ID>",}# run the transaction.response=client.upload_status(request)print("Response:%r"%response)Get Media AssetAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API returns a detailed media asset.  The data returned includes the exact same media information returned
by the full media library endpoint, including fully qualified URLs pointing to the original media file
and the thumbnail.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"mediaId":"<MEDIA ASSET ID>",}# run the transaction.response=client.media_asset(request)print("Response:%r"%response)Delete Media AssetAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API deletes a media asset.  Note that a media asset cannot be deleted if it is in use in a slide
show or in the terminal branding stack.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"mediaId":"<MEDIA ASSET ID>",}# run the transaction.response=client.delete_media_asset(request)print("Response:%r"%response)List Slide ShowsAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API returns all slide shows.Note that slide level data is not returned with this API.   Use the Get Slide Show API to get slide level detail.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.slide_shows(request)print("Response:%r"%response)Get Slide ShowAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API returns a single slide show.  Slide level detail is returned with the fully qualified thumbnail URL
for each slide.slideShowIdis the only required parameter.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"slideShowId":"<SLIDE SHOW ID>",}# run the transaction.response=client.slide_show(request)print("Response:%r"%response)Update Slide ShowAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API updates or creates a slide show.name,delayandslidesare required.The slides property is an array of slides.  The Slide data structure has ordinal and thumbnail URL fields,
but these are not required when updating or creating a slide show.  Only themediaIdfield is required
when updating or creating a slide show.When using the CLI, slides can be specified by sending a comma-separated list of media ids via the-mediaIdparameter.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"name":"Test Slide Show","delay":5,"slides":[{"mediaId":"<MEDIA ID>",},],}# run the transaction.response=client.update_slide_show(request)print("Response:%r"%response)Delete Slide ShowAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API deletes a slide showslideShowIdis the only required parameter.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"slideShowId":"<SLIDE SHOW ID>",}# run the transaction.response=client.delete_slide_show(request)print("Response:%r"%response)Terminal BrandingAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API returns the full branding stack for a given API scope in the order of priority.Consumers of this API should pay special attention to theeditablefield.  This field indicates whether or
not a branding asset is read-only from the perspective of a particular API Credential scope.ThethumbnailandpreviewImageattributes can be used to support building user interfaces for
managing the branding stack.previewImagediffers fromthumbnailin that the preview image is
intended to show how an asset would actually look when displayed on the terminal.activeAssetreturns the asset that is currently visible on the terminal.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.terminal_branding(request)print("Response:%r"%response)Update Branding AssetAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API updates or creates a single Branding Asset.Branding Assets represent a single element of the terminal branding stack.  A Branding Asset can be a video or image,
in which case amediaIdreferencing an asset from the media library must be provided.  A Branding Asset can also
be a slide show, in which caseslideShowIdmust be provided.  Branding Assets must have a validmediaIdor a validslideShowId.  The optionalnotesfield can be used to provide short notes and descriptions for a Branding asset.Visibility FlagsIn order for a Branding Asset to be visible on a terminal, theenabledflag must be set to true and thepreviewmust be turned off.previewis intended to show how a proposed Branding Asset will behave
without pushing it to live terminals.  The Publish button in the BlockChyp merchant portal effectively turns
thepreviewsetting off.Order and SequencingTheordinalfield is used to specify priority for a Branding Asset.  Assets with a higher value forordinalwill be prioritized first.Padding ImagesFor plain images, it's sometimes helpful to add margins to images.  This is especially helpful with logos
or any image file rendered without any white space or margins between the image content and edge of the image file.
Set thepaddedflag to true if you'd like BlockChyp to auto apply margins when displaying an image on
the terminal.SchedulingBy default, a Branding Asset placed on top of the Branding Stack, if it'senabledand not inpreviewmode, will immediately be displayed on the terminal round the clock.Branding Assets can be scheduled with effective start and stop dates for seasonal campaigns.  These assets can
also be scheduled for specific times of day and specific days of the week.startDate:Optional date after which the Branding Asset is eligible for display.  Can be provided in MM/DD/YYYY or YYYY-MM-DD format.endDate:Optional date before which the Branding Asset is eligible for display.  Can be provided in MM/DD/YYYY or YYYY-MM-DD format.startTimeOptional time of day after which the branding asset is eligible for display.  Must be provided in 24 hour time: HH:MM.endTimeOptional time of day before which the branding asset is eligible for display.  Must be provided in 24 hour time format: HH:MMdaysOfWeekFor branding assets that should only be displayed on certain days of the week, this field is an array of day of the week constants. (Constants vary by SDK platform.)Read Only FieldsThe Branding Asset data structure has a number of read only fields that are returned when Branding Assets are
retrieved.  But these fields are ignored when you try to send them as part of an update.  These are derived
or calculated fields and are helpful for displaying branding assets in a management user interface, but
cannot be changed via an API call.These fields are:ownerIdmerchantIdorganizationIdpartnerIduserIduserNamethumbnaillastModifiededitableassetTypeownerTypeownerTypeCaptionpreviewImagenarrativeEffectiveDatesnarrativeDisplayPeriodimportosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"mediaId":"<MEDIA ID>","padded":True,"ordinal":10,"startDate":"01/06/2021","startTime":"14:00","endDate":"11/05/2024","endTime":"16:00","notes":"Test Branding Asset","preview":False,"enabled":True,}# run the transaction.response=client.update_branding_asset(request)print("Response:%r"%response)Delete Branding AssetAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Media ManagementThis API deletes a Branding Asset from the branding stack.Note that deleting a Branding Asset does not delete the underlying media from the media library or slide
show from the slide show library.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"assetId":"<BRANDING ASSET ID>",}# run the transaction.response=client.delete_branding_asset(request)print("Response:%r"%response)Merchant ManagementThese APIs allow partners to manage and configure their merchant portfolios.Use of these APIs (other than the Merchant Profile API) requires partner scoped API credentials
with special roles and permissions that may require a special arrangement with BlockChyp.For example, Partners usually can't board merchants directly, but must board merchants using
the standard underwriting process via offer codes and invitations.Merchant ProfileAPI Credential Types:MerchantRequired Role:Payment API AccessThe API returns detailed metadata about the merchant's configuration, including
basic identity information, terminal settings, store and forward settings,
and bank account information for merchants that support split settlement.Some of these fields can be updated via the Update Merchant API, but many of these
fields are controlled by underwriting and cannot be altered outside of the
underwriting and risk processes.Merchant Descriptive FieldsThe following fields are basic descriptive fields that can be used to describe and identify merchants.companyName:The merchant's official corporate entity name.dbaName:The business's DBA (doing business as) name.contactName:Name of the merchant's primary control contact.contactNumber:Primary control contact's phone number.locationName:Optional location name for multi-location operators.storeNumber:Optional store number for multi-location operators.partnerRef:Optional reference number partners can add to a merchant record.  Usually the partner's own identifier for the merchant.timeZone:Unix style local time zone for the merchant. Example: America/New_York.publicKey:Read only field.  The merchant's blockchain public key.  Generated and assigned when a merchant account is first created.billingAddress:Address for billing and written correspondence.shippingAddress:Physical shipping address. Usually the actual street address of the business.status:Current status of the merchant account.tcDisabled:Disables all terms and conditions features in the merchant dashboard.  Used to hide the feature if a partner has not chosen to support it.gatewayOnly:Indicates that a merchant has been boarded in gateway only mode.  Not common.Batch and Terminal SettingsThe following fields are used to control batch closure and high level terminal configuration.batchCloseTime:Time in 24 hour HH:MM format when batches will automatically close in the merchant's local time.  Defaults to 3 AM.autoBatchClose:Flag the determines whether or not batches will automatically close.  Defaults to true.disableBatchEmails:Flag that optionally turns off automatic batch closure notification emails.cooldownTimeout:The amount of time in seconds after a transactions for which the transaction response is displayed on the terminal.  After the cooldown period elapses, the terminal will revert to the idle state and display the currently active terminal branding.surveyTimeout:The amount of time in seconds a survey question should be displayed on a terminal before reverting to the idle screen.pinEnabled:Enables pin code entry for debit cards, EBT cards, and EMV cards with pin CVMs.  Will be ignored if terminals are not injected with the proper encryption keys.pinBypassEnabled:Enable pin bypass for debit transactions.cashBackEnabled:Enables cash back for debit transactions.cashbackPresets:An array of four default values for cashback amounts when cashback is enabled.storeAndForwardEnabled:Enables automatic store and forward during network outages.  Store and Forward does not support cash back, refunds, EBT, or gift card transactions.storeAndForwardFloorLimit:Maximum dollar value of a store and forward transaction.ebtEnabled:Enables EBT (SNAP) on BlockChyp terminals.tipEnabled:Enables tips entry on the terminal.promptForTip:If true, the terminal will always prompt for a tip, even if the API call does not request a tip prompt.tipDefaults:An array of exactly three percentages that will be used to calculate default tip amounts.giftCardsDisabled:Disables BlockChyp gift cards.  Normally only used if the merchant is using an alternate gift card system.digitalSignaturesEnabled:Enables electronic signature capture for mag stripe cards and EMV cards with Signature CVMs.digitalSignatureReversal:Will cause a transaction to auto-reverse if the consumer refuses to provide a signature.manualEntryEnabled:Enables manual card entry.manualEntryPromptZip:Requires zip code based address verification for manual card entry.manualEntryPromptStreetNumber:Requires street/address based verification for manual card entry.Card Brand and Transaction SettingsfreeRangeRefundsEnabled:Enables direct refunds that do not reference a previous transaction.partialAuthEnabled:Indicates that partial authorizations (usually for gift card support) are enabled.splitBankAccountsEnabled:Used for law firm merchants only.contactlessEmv:Enables contactless/tap transactions on a terminal.  Defaults to true.visa:Enables Visa transactions.masterCard:Enables MasterCard transactions.amex:Enables American Express transactions.discover:Enables Discover transactions.jcb:Enables JCB (Japan Card Bureau) transactions.unionPay:Enables China UnionPay transactions.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.merchant_profile(request)print("Response:%r"%response)Get MerchantsAPI Credential Types:Partner & OrganizationRequired Role:Merchant ManagementThis is a partner or organization level API that can be used to return the merchant portfolio.Live merchants are returned by default.  Use thetestflag to return only test merchants.  The
results returned include detailed settings including underwriting controlled flags.A maximum of 250 merchants are returned by default.  For large merchant portfolios, themaxResultsandstartIndexfield can be used to reduce the page size and page through multiple pages of results.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"test":True,}# run the transaction.response=client.get_merchants(request)print("Response:%r"%response)Update MerchantAPI Credential Types:Merchant, Partner, & OrganizationRequired Role:Merchant ManagementThis API can be used to update or create merchant accounts.Merchant scoped API credentials can be used to update merchant account settings.Partner scoped API credentials can be used to update merchants, create new test
merchants or board new gateway merchants.Merchant Descriptive FieldsThe following fields are basic descriptive fields that can be used to describe and identify merchants.companyName:The merchant's official corporate entity name.dbaName:The businesses DBA (doing business as) name.contactName:Name of the merchant's primary control contact.contactNumber:Primary control contact's phone number.locationName:Optional location name for multi location operators.storeNumber:Optional store number for multi location operators.partnerRef:Optional reference number partners can add to a merchant record.  Usually the partner's own identifier for the merchant.timeZone:Unix style local time zone for the merchant. Example: America/New_York.publicKey:Read only field.  The merchant's blockchain public key.  Generated and assigned when a merchant account is first created.billingAddress:Address for billing and written correspondence.shippingAddress:Physical shipping address. Usually the actual street address of the business.status:Current status of the merchant account.tcDisabled:Disables all terms and conditions features in the merchant dashboard.  Used to hide the feature if a partner has not chosen to support it.gatewayOnly:Indicates that a merchant has been boarded in gateway only mode.  Not common.Batch and Terminal SettingsThe following fields are used to control batch closure and high level terminal configuration.batchCloseTime:Time in 24 hour HH:MM format when batches will automatically close in the merchant's local time.  Defaults to 3 AM.autoBatchClose:Flag the determines whether or not batches will automatically close.  Defaults to true.disableBatchEmails:Flag that optionally turns off automatic batch closure notification emails.cooldownTimeout:The amount of time in seconds after a transactions for which the transaction response is displayed on the terminal.  After the cooldown period elapses, the terminal will revert to the idle state and display the currently active terminal branding.surveyTimeout:The amount of time in seconds a survey question should be displayed on a terminal before reverting to the idle screen.pinEnabled:Enables pin code entry for debit cards, EBT cards, and EMV cards with pin CVMs.  Will be ignored if terminals are not injected with the proper encryption keys.pinBypassEnabled:Enable pin bypass for debit transactions.cashBackEnabled:Enables cash back for debit transactions.cashbackPresets:An array of four default values for cashback amounts when cashback is enabled.storeAndForwardEnabled:Enables automatic store and forward during network outages.  Store and Forward does not support cash back, refunds, EBT, or gift card transactions.storeAndForwardFloorLimit:Maximum dollar value of a store and forward transaction.ebtEnabled:Enables EBT (SNAP) on BlockChyp terminals.tipEnabled:Enables tips entry on the terminal.promptForTip:If true, the terminal will always prompt for a tip, even if the API call does not request a tip prompt.tipDefaults:An array of exactly three percentages that will be used to calculate default tip amounts.giftCardsDisabled:Disables BlockChyp gift cards.  Normally only used if the merchant is using an alternate gift card system.digitalSignaturesEnabled:Enables electronic signature capture for mag stripe cards and EMV cards with Signature CVMs.digitalSignatureReversal:Will cause a transaction to auto-reverse if the consumer refuses to provide a signature.manualEntryEnabled:Enables manual card entry.manualEntryPromptZip:Requires zip code based address verification for manual card entry.manualEntryPromptStreetNumber:Requires street/address based verification for manual card entry.Card Brand and Transaction SettingsfreeRangeRefundsEnabled:Enables direct refunds that do not reference a previous transaction.partialAuthEnabled:Indicates that partial authorizations (usually for gift card support) are enabled.splitBankAccountsEnabled:Used for law firm merchants only.contactlessEmv:Enables contactless/tap transactions on a terminal.  Defaults to true.visa:Enables Visa transactions.masterCard:Enables MasterCard transactions.amex:Enables American Express transactions.discover:Enables Discover transactions.jcb:Enables JCB (Japan Card Bureau) transactions.unionPay:Enables China UnionPay transactions.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"merchantId":"<MERCHANT ID>","test":True,"dbaName":"Test Merchant","companyName":"Test Merchant","billingAddress":{"address1":"1060 West Addison","city":"Chicago","stateOrProvince":"IL","postalCode":"60613",},}# run the transaction.response=client.update_merchant(request)print("Response:%r"%response)Merchant UsersAPI Credential Types:Partner & OrganizationRequired Role:Merchant ManagementThis API returns all users and pending invites associated with a merchant account including any assigned role codes.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"merchantId":"<MERCHANT ID>",}# run the transaction.response=client.merchant_users(request)print("Response:%r"%response)Invite Merchant UserAPI Credential Types:Partner & OrganizationRequired Role:Merchant ManagementInvites a new user to join a merchant account.email,firstName, andlastNameare required.The user will be sent an invite email with steps for creating a BlockChyp account and linking it to
a merchant account.  If the user already has a BlockChyp user account, the new user signup wil be skipped
and the existing user account will be linked to the merchant account.Developers can optionally restrict the user's access level by sending one or more role codes.
Otherwise, the user will be given the default merchant user role. (STDMERCHANT)importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"email":"Email address for the invite",}# run the transaction.response=client.invite_merchant_user(request)print("Response:%r"%response)Add Test MerchantAPI Credential Types:PartnerRequired Role:Merchant ManagementThis is a partner level API that can be used to create test merchant accounts.  This creates
a basic test merchant with default settings.Settings can be changed by using the Update Merchant API.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"dbaName":"DBA Name","companyName":"Corporate Entity Name",}# run the transaction.response=client.add_test_merchant(request)print("Response:%r"%response)Delete Test MerchantAPI Credential Types:PartnerRequired Role:Merchant ManagementThis partner API can be used to delete unused test merchant accounts.merchantIdis a required parameter.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={"merchantId":"<MERCHANT ID>",}# run the transaction.response=client.delete_test_merchant(request)print("Response:%r"%response)Partner UtilitiesThese partner only APIs give ISV partners advanced reporting and tools for managing their portfolio.Most of the APIs below are for portfolio reporting and range from basic partner commission statements
to individual statements with all underlying card brand data.We also provide a pricing policy API that enables partners to pull down the current pricing rules
in force for any merchant in their portfolio.Currency DataAll partner APIs return currency and percentage values in two formats: floating point and formatted strings.It's recommended that all developers use the formatted string as this will ensure the most precise values.
Floating point numbers are usually not appropriate for currency or fixed point decimal numbers as
the underlying binary encoding can lead to errors in precision.  We provide floating point values
only as a convenience for developers want to save development time and can live with approximated
values in their use case.Retrieve Pricing PolicyAPI Credential Types:PartnerRequired Role:Partner API AccessThe API returns the current pricing policy for a merchant.  This API is valid for partner scoped API credentials
andmerchantIdis a required parameter.  By default this API returns the currently in-force pricing policy for a merchant,
but other inactive policies can be returned by providing theidparameter.Buy rates for interchange plus and fixed rate pricing are always returned, but only the pricing related to the
pricing model type (flat rate or interchange plus) are actually used in fee calculation.Each pricing level returns three values:buyRate,current, andlimit.  The actual price the merchant will pay is
given in thecurrentfield.  The other values reflect the contract minimum (buyRate) and maximum (limit) range
the partner can use when changing prices.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.pricing_policy(request)print("Response:%r"%response)Partner StatementsAPI Credential Types:PartnerRequired Role:Partner API AccessThe API returns a list of partner residual statements.  By default, all statements are returned with the most recent
statements listed first.  Optional date parameters (startDateandendDate) can filter statements to a specific date range.The list of statements returns basic information about statements like volume, transaction count, and commissions earned.Use theidreturned with each statement summary with thePartner Statement DetailAPI to pull down full details.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.partner_statements(request)print("Response:%r"%response)Partner Statement DetailAPI Credential Types:PartnerRequired Role:Partner API AccessThe API returns detailed information about a specific partner statement.  Aggregate data is returned along with
line item level data for each underlying merchant statement.Use the merchant invoice id with theMerchant Statement DetailAPI and thePartner Commission BreakdownAPI
to get the merchant statement and the card brand fee cost breakdown respectively.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.partner_statement_detail(request)print("Response:%r"%response)Merchant InvoicesAPI Credential Types:Partner or MerchantRequired Role:Partner API Access or Merchant APIThe API returns a list of merchant statements and invoices.  By default, all invoices are returned with the most recent
statements listed first.  Optional date parameters (startDateandendDate) can be used to filter statements by date
range.TheinvoiceTypeparameter can also be used to filter invoices by type.  Invoices could be conventional invoices, such
as those generated when ordering terminals or gift cards, or invoices could be merchant statements.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.merchant_invoices(request)print("Response:%r"%response)Merchant Invoice DetailAPI Credential Types:PartnerRequired Role:Partner API AccessThe API returns detailed information about a specific merchant statement or invoice.All line items are returned a topographically sorted tree modeling the nested line item structure of the
invoice.  Details about any payments posted against the invoice are returned.It the invoice is a merchant statement, details about every merchant deposit that occurred during the statement period
are also returned.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.merchant_invoice_detail(request)print("Response:%r"%response)Partner Commission BreakdownAPI Credential Types:PartnerRequired Role:Partner API AccessThis API allows partners to pull down the low level data used to compute a partner commission for a specific merchant statement.ThestatementIdis required and must be the id of a valid merchant invoice of typestatement.importosimportblockchyp# initialize a client.client=blockchyp.Client(api_key=os.environ["BC_API_KEY"],bearer_token=os.environ["BC_BEARER_TOKEN"],signing_key=os.environ["BC_SIGNING_KEY"],)# populate request parameters.request={}# run the transaction.response=client.partner_commission_breakdown(request)print("Response:%r"%response)Running Integration TestsIf you'd like to run the integration tests, create a new file on your system
calledsdk-itest-config.jsonwith the API credentials you'll be using as
shown in the example below.{
 "gatewayHost": "https://api.blockchyp.com",
 "testGatewayHost": "https://test.blockchyp.com",
 "apiKey": "PZZNEFK7HFULCB3HTLA7HRQDJU",
 "bearerToken": "QUJCHIKNXOMSPGQ4QLT2UJX5DI",
 "signingKey": "f88a72d8bc0965f193abc7006bbffa240663c10e4d1dc3ba2f81e0ca10d359f5"
}This file can be located in a few different places, but is usually located
at<USER_HOME>/.config/blockchyp/sdk-itest-config.json. All BlockChyp SDKs
use the same configuration file.To run the integration test suite viamake, type the following command:make integrationContributionsBlockChyp welcomes contributions from the open source community, but bear in mind
that this repository has been generated by our internal SDK Generator tool. If
we choose to accept a PR or contribution, your code will be moved into our SDK
Generator project, which is a private repository.LicenseCopyright BlockChyp, Inc., 2019Distributed under the terms of theMITlicense, blockchyp-python is free and open source software.Other SDKsBlockChyp has officially supported SDKs for eight different development platforms and counting.
Here's the full list with links to their GitHub repositories.Go SDKNode.js/JavaScript SDKJava SDK.net/C# SDKRuby SDKPHP SDKPython SDKiOS (Objective-C/Swift) SDK