blockchyp 2.9.3 → 2.9.6

Sign up to get free protection for your applications and to get access to all the features.
Files changed (92) hide show
  1. checksums.yaml +4 -4
  2. data/Makefile +8 -1
  3. data/README.md +2605 -477
  4. data/lib/blockchyp/version.rb +1 -1
  5. data/lib/blockchyp.rb +242 -3
  6. data/lib/blockchyp_client.rb +80 -0
  7. data/test/activate_terminal_test.rb +45 -0
  8. data/test/add_test_merchant_test.rb +56 -0
  9. data/test/batch_history_test.rb +10 -6
  10. data/test/boolean_prompt_test.rb +12 -6
  11. data/test/cancel_payment_link_test.rb +72 -0
  12. data/test/capture_signature_test.rb +12 -6
  13. data/test/deactivate_terminal_test.rb +42 -0
  14. data/test/delete_branding_asset_test.rb +50 -0
  15. data/test/delete_customer_test.rb +55 -0
  16. data/test/delete_media_asset_test.rb +53 -0
  17. data/test/delete_queued_transaction_test.rb +56 -0
  18. data/test/delete_slide_show_test.rb +50 -0
  19. data/test/delete_survey_question_test.rb +51 -0
  20. data/test/delete_test_merchant_test.rb +59 -0
  21. data/test/delete_token_test.rb +55 -0
  22. data/test/empty_branding_asset_test.rb +44 -0
  23. data/test/empty_slide_show_test.rb +45 -0
  24. data/test/gateway_timeout_test.rb +11 -4
  25. data/test/get_customer_test.rb +10 -6
  26. data/test/get_merchants_test.rb +52 -0
  27. data/test/invite_merchant_user_test.rb +45 -0
  28. data/test/link_token_test.rb +56 -0
  29. data/test/list_queued_transactions_test.rb +55 -0
  30. data/test/list_terminals_test.rb +42 -0
  31. data/test/media_asset_test.rb +57 -0
  32. data/test/media_test.rb +42 -0
  33. data/test/media_upload_test.rb +52 -0
  34. data/test/merchant_platforms_test.rb +59 -0
  35. data/test/merchant_profile_test.rb +10 -5
  36. data/test/merchant_users_test.rb +42 -0
  37. data/test/new_transaction_display_test.rb +12 -6
  38. data/test/pan_charge_test.rb +11 -5
  39. data/test/pan_enroll_test.rb +17 -6
  40. data/test/pan_preauth_test.rb +11 -5
  41. data/test/partial_refund_test.rb +11 -6
  42. data/test/search_customer_test.rb +10 -6
  43. data/test/send_payment_link_test.rb +11 -6
  44. data/test/simple_batch_close_test.rb +10 -6
  45. data/test/simple_capture_test.rb +10 -6
  46. data/test/simple_gift_activate_test.rb +12 -6
  47. data/test/simple_locate_test.rb +44 -0
  48. data/test/simple_message_test.rb +12 -6
  49. data/test/simple_ping_test.rb +12 -6
  50. data/test/simple_refund_test.rb +11 -6
  51. data/test/simple_reversal_test.rb +10 -6
  52. data/test/simple_void_test.rb +10 -6
  53. data/test/slide_show_test.rb +51 -0
  54. data/test/slide_shows_test.rb +49 -0
  55. data/test/survey_question_test.rb +48 -0
  56. data/test/survey_questions_test.rb +50 -0
  57. data/test/survey_results_test.rb +48 -0
  58. data/test/tc_delete_template_test.rb +51 -0
  59. data/test/tc_entry_test.rb +56 -0
  60. data/test/tc_log_test.rb +42 -0
  61. data/test/tc_template_test.rb +53 -0
  62. data/test/tc_template_update_test.rb +48 -0
  63. data/test/tc_templates_test.rb +42 -0
  64. data/test/terminal_branding_test.rb +42 -0
  65. data/test/terminal_charge_test.rb +12 -6
  66. data/test/terminal_clear_test.rb +12 -6
  67. data/test/terminal_ebt_balance_test.rb +12 -6
  68. data/test/terminal_ebt_charge_test.rb +12 -6
  69. data/test/terminal_enroll_test.rb +12 -6
  70. data/test/terminal_gift_card_balance_test.rb +12 -6
  71. data/test/terminal_keyed_charge_test.rb +12 -6
  72. data/test/terminal_manual_ebt_charge_test.rb +12 -6
  73. data/test/terminal_preauth_test.rb +12 -6
  74. data/test/terminal_queued_transaction_test.rb +51 -0
  75. data/test/terminal_status_test.rb +12 -6
  76. data/test/terminal_timeout_test.rb +12 -5
  77. data/test/terms_and_conditions_test.rb +12 -6
  78. data/test/test_helper.rb +2 -4
  79. data/test/testdata/aviato.png +0 -0
  80. data/test/text_prompt_test.rb +12 -6
  81. data/test/token_metadata_test.rb +55 -0
  82. data/test/transaction_history_test.rb +10 -6
  83. data/test/unlink_token_test.rb +56 -0
  84. data/test/update_branding_asset_test.rb +62 -0
  85. data/test/update_customer_test.rb +10 -5
  86. data/test/update_merchant_platforms_test.rb +61 -0
  87. data/test/update_merchant_test.rb +60 -0
  88. data/test/update_slide_show_test.rb +60 -0
  89. data/test/update_survey_question_test.rb +47 -0
  90. data/test/update_transaction_display_test.rb +12 -6
  91. data/test/upload_status_test.rb +53 -0
  92. metadata +49 -2
data/README.md CHANGED
@@ -74,48 +74,19 @@ You can also view a number of long form demos and learn more about us on our [Yo
74
74
  You don't want to read words. You want examples. Here's a quick rundown of the
75
75
  stuff you can do with the BlockChyp Ruby SDK and a few basic examples.
76
76
 
77
- #### Terminal Ping
78
-
79
-
80
- This simple test transaction helps ensure you have good communication with a payment terminal and is usually the first one you'll run in development.
81
-
82
- It tests communication with the terminal and returns a positive response if everything
83
- is okay. It works the same way in local or cloud relay mode.
84
-
85
- If you get a positive response, you've successfully verified all of the following:
86
-
87
- * The terminal is online.
88
- * There is a valid route to the terminal.
89
- * The API Credentials are valid.
90
-
91
-
92
-
93
-
94
- ```ruby
95
- # frozen_string_literal: true
96
-
97
- require 'blockchyp'
77
+ ### Payment Endpoints
98
78
 
99
- blockchyp = BlockChyp::BlockChyp.new(
100
- ENV['BC_API_KEY'],
101
- ENV['BC_BEARER_TOKEN'],
102
- ENV['BC_SIGNING_KEY']
103
- )
104
79
 
105
- # Set request parameters
106
- request = {
107
- terminalName: 'Test Terminal'
108
- }
80
+ These are the core payment APIs used to execute and work with payment transactions in BlockChyp.
109
81
 
110
- response = blockchyp.ping(request)
111
82
 
112
- puts "Response: #{response.inspect}"
113
83
 
84
+ #### Charge
114
85
 
115
- ```
116
86
 
117
- #### Charge
118
87
 
88
+ * **API Credential Types:** Merchant
89
+ * **Required Role:** Payment API Access
119
90
 
120
91
  Our most popular transaction executes a standard authorization and capture.
121
92
  This is the most basic of
@@ -135,21 +106,21 @@ property instead.
135
106
 
136
107
  **Card Numbers and Mag Stripes**
137
108
 
138
- You can also pass in PANs and Mag Stripes, but you probably shouldn't. This will
139
- put you in PCI scope and the most common vector for POS breaches is key logging.
140
- If you use terminals for manual card entry, you'll bypass any key loggers that
109
+ You can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will
110
+ put you in PCI scope and the most common vector for POS breaches is keylogging.
111
+ If you use terminals for manual card entry, you'll bypass any keyloggers that
141
112
  might be maliciously running on the point-of-sale system.
142
113
 
143
114
  **Common Variations**
144
115
 
145
- * **Gift Card Redemption**: There's no special API for gift card redemption in BlockChyp. Just execute a plain charge transaction and if the customer happens to swipe 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.
116
+ * **Gift 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.
146
117
  * **EBT**: Set the `CardType` field to `CardType::EBT` to 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.
147
118
  * **Cash Back**: To enable cash back for debit transactions, set the `CashBack` field. If the card presented isn't a debit card, the `CashBack` field will be ignored.
148
119
  * **Manual Card Entry**: Set the `ManualEntry` field 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 the `ManualEntry` field with the `CardType` field set to `CardType::EBT` for manual EBT card entry.
149
120
  * **Inline Tokenization**: You can enroll the payment method in the token vault inline with a charge transaction by setting the `Enroll` field. 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.
150
121
  * **Prompting for Tips**: Set the `PromptForTip` field if you'd like to prompt the customer for a tip before authorization. Good for pay-at-the-table and other service related scenarios.
151
122
  * **Cash Discounting and Surcharging**: The `Surcharge` and `CashDiscount` fields can be used together to support cash discounting or surcharge problems. Consult the Cash Discount documentation for more details.
152
-
123
+ * **Cryptocurrency** The `Cryptocurrency` field can be used to switch the standard present card screen to a cryptocurrency screen. The field value can be `ANY` to enable any supported cryptocurrency or a single currency code such as `BTC` for Bitcoin.
153
124
 
154
125
 
155
126
 
@@ -181,9 +152,13 @@ puts "Response: #{response.inspect}"
181
152
  #### Preauthorization
182
153
 
183
154
 
155
+
156
+ * **API Credential Types:** Merchant
157
+ * **Required Role:** Payment API Access
158
+
184
159
  A preauthorization puts a hold on funds and must be captured later. This is used
185
- in scenarios where the final transaction amount might change. A common examples would
186
- be fine dining where a tip adjustment is required prior to final settlement.
160
+ in scenarios where the final transaction amount might change. A common example is
161
+ fine dining, where a tip adjustment is required before final settlement.
187
162
 
188
163
  Another use case for preauthorization is e-commerce. Typically, an online order
189
164
  is preauthorized at the time of the order and then captured when the order ships.
@@ -202,11 +177,15 @@ property instead.
202
177
 
203
178
  **Card Numbers and Mag Stripes**
204
179
 
205
- You can also pass in PANs and Mag Stripes, but you probably shouldn't. This will
180
+ You can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will
206
181
  put you in PCI scope and the most common vector for POS breaches is key logging.
207
182
  If you use terminals for manual card entry, you'll bypass any key loggers that
208
183
  might be maliciously running on the point-of-sale system.
209
184
 
185
+ **Cryptocurrency**
186
+
187
+ Note that preauths are not supported for cryptocurrency.
188
+
210
189
  **Common Variations**
211
190
 
212
191
  * **Manual Card Entry**: Set the `ManualEntry` field 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 the `ManualEntry` field with `CardType` set to `CardType::EBT` for manual EBT card entry.
@@ -245,14 +224,19 @@ puts "Response: #{response.inspect}"
245
224
  #### Capture Preauthorization
246
225
 
247
226
 
227
+
228
+ * **API Credential Types:** Merchant
229
+ * **Required Role:** Payment API Access
230
+
248
231
  This API allows you to capture a previously approved preauthorization.
249
232
 
250
- 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
233
+ You'll need to make sure you pass in the Transaction ID returned by the original preauth transaction
234
+ so we know which transaction we're capturing. If you want to capture the transaction for the
251
235
  exact amount of the preauth, the Transaction ID is all you need to pass in.
252
236
 
253
237
  You can adjust the total if you need to by passing in a new `amount`. We
254
238
  also recommend you pass in updated amounts for `tax` and `tip` as it can
255
- reduce your interchange fees in some cases. (Level II Processing, for example.)
239
+ sometimes reduce your interchange fees. (Level II Processing, for example.)
256
240
 
257
241
 
258
242
 
@@ -271,7 +255,8 @@ blockchyp = BlockChyp::BlockChyp.new(
271
255
  # Set request parameters
272
256
  request = {
273
257
  test: true,
274
- transactionId: '<PREAUTH TRANSACTION ID>'
258
+ transactionId: '<ORIGINAL TRANSACTION ID>',
259
+ amount: '32.00'
275
260
  }
276
261
 
277
262
  response = blockchyp.capture(request)
@@ -284,6 +269,10 @@ puts "Response: #{response.inspect}"
284
269
  #### Refund
285
270
 
286
271
 
272
+
273
+ * **API Credential Types:** Merchant
274
+ * **Required Role:** Payment API Access
275
+
287
276
  It's not ideal, but sometimes customers want their money back.
288
277
 
289
278
  Our refund API allows you to confront this unpleasant reality by executing refunds in a few different scenarios.
@@ -294,21 +283,21 @@ returned in a BlockChyp response. To refund the full amount of the previous tra
294
283
  **Partial Refunds**
295
284
 
296
285
  For a partial refund, just pass in an amount along with the Transaction ID.
297
- The only rule is that the amount has to be equal to or less than the original
286
+ The only rule is that the amount must be equal to or less than the original
298
287
  transaction. You can execute multiple partial refunds against the same
299
288
  original transaction as long as the total refunded amount doesn't exceed the original amount.
300
289
 
301
290
  **Tokenized Refunds**
302
291
 
303
292
  You can also use a token to execute a refund. Pass in a token instead
304
- of the Transaction ID along with the desired refund amount.
293
+ of the Transaction ID and the desired refund amount.
305
294
 
306
295
  **Free Range Refunds**
307
296
 
308
297
  When you execute a refund without referencing a previous transaction, we
309
298
  call this a *free range refund*.
310
299
 
311
- We don't recommend it, but it is permitted. If you absolutely insist on
300
+ We don't recommend this type of refund, but it is permitted. If you absolutely insist on
312
301
  doing it, pass in a Terminal Name and an amount.
313
302
 
314
303
  You can execute a manual or keyed refund by passing the `ManualEntry` field
@@ -330,6 +319,11 @@ If a refund referencing a previous transaction is executed for the full amount
330
319
  before the original transaction's batch is closed, the refund is automatically
331
320
  converted to a void. This saves the merchant a little bit of money.
332
321
 
322
+ **Cryptocurrency**
323
+
324
+ Note that refunds are not supported for cryptocurrency. You must refund crypto transactions
325
+ manually from your cryptocurrency wallet.
326
+
333
327
 
334
328
 
335
329
 
@@ -357,64 +351,26 @@ response = blockchyp.refund(request)
357
351
  puts "Response: #{response.inspect}"
358
352
 
359
353
 
360
- ```
361
-
362
- #### Enroll
363
-
364
-
365
- This API allows you to tokenize and enroll a payment method in the token
366
- vault. You can also pass in customer information and associate the
367
- payment method with a customer record.
368
-
369
- A token is returned in the response that can be used in subsequent charge,
370
- preauth, and refund transactions.
371
-
372
- **Gift Cards and EBT**
373
-
374
- Gift Cards and EBT cards cannot be tokenized.
375
-
376
- **E-Commerce Tokens**
377
-
378
- The tokens returned by the enroll API and the e-commerce web tokenizer
379
- are the same tokens and can be used interchangeably.
380
-
381
-
382
-
383
-
384
- ```ruby
385
- # frozen_string_literal: true
386
-
387
- require 'blockchyp'
388
-
389
- blockchyp = BlockChyp::BlockChyp.new(
390
- ENV['BC_API_KEY'],
391
- ENV['BC_BEARER_TOKEN'],
392
- ENV['BC_SIGNING_KEY']
393
- )
394
-
395
- # Set request parameters
396
- request = {
397
- test: true,
398
- terminalName: 'Test Terminal'
399
- }
400
-
401
- response = blockchyp.enroll(request)
402
-
403
- puts "Response: #{response.inspect}"
404
-
405
-
406
354
  ```
407
355
 
408
356
  #### Void
409
357
 
410
358
 
411
359
 
360
+ * **API Credential Types:** Merchant
361
+ * **Required Role:** Payment API Access
362
+
412
363
  Mistakes happen. If a transaction is made by mistake, you can void it
413
364
  with this API. All that's needed is to pass in a Transaction ID and execute
414
365
  the void before the original transaction's batch closes.
415
366
 
416
367
  Voids work with EBT and gift card transactions with no additional parameters.
417
368
 
369
+ **Cryptocurrency**
370
+
371
+ Note that voids are not supported for cryptocurrency. You must refund crypto transactions
372
+ manually from your cryptocurrency wallet.
373
+
418
374
 
419
375
 
420
376
 
@@ -446,6 +402,9 @@ puts "Response: #{response.inspect}"
446
402
 
447
403
 
448
404
 
405
+ * **API Credential Types:** Merchant
406
+ * **Required Role:** Payment API Access
407
+
449
408
  Payment transactions require a stable network to function correctly and
450
409
  no network is stable all the time. Time out reversals are a great line
451
410
  of defense against accidentally double charging consumers when payments
@@ -460,9 +419,14 @@ The only caveat is that developers must use the `transactionRef` property (`txRe
460
419
 
461
420
  The reason for this requirement is that if a system never receives a definitive
462
421
  response for a transaction, the system would never have received the BlockChyp
463
- generated Transaction ID. We have to fallback to Transaction Ref to identify
422
+ generated Transaction ID. We have to fall back to Transaction Ref to identify
464
423
  a transaction.
465
424
 
425
+ **Cryptocurrency**
426
+
427
+ Note that refunds are not supported for cryptocurrency. You must refund crypto transactions
428
+ manually from your cryptocurrency wallet.
429
+
466
430
 
467
431
 
468
432
 
@@ -492,14 +456,18 @@ puts "Response: #{response.inspect}"
492
456
  #### Gift Card Activation
493
457
 
494
458
 
495
- This API can be used to activate or add value to BlockChyp gift cards.
459
+
460
+ * **API Credential Types:** Merchant
461
+ * **Required Role:** Payment API Access
462
+
463
+ This API activates or adds value to BlockChyp gift cards.
496
464
  Just pass in the terminal name and the amount to add to the card.
497
465
  Once the customer swipes their card, the terminal will use keys
498
466
  on the mag stripe to add value to the card.
499
467
 
500
468
  You don't need to handle a new gift card activation or a gift card recharge any
501
469
  differently. The terminal firmware will figure out what to do on its
502
- own and also returns the new balance for the gift card.
470
+ own while also returning the new balance for the gift card.
503
471
 
504
472
  This is the part of the system where BlockChyp's blockchain DNA comes
505
473
  closest to the surface. The BlockChyp gift card system doesn't really
@@ -528,9 +496,9 @@ voiding or reversing a conventional payment transaction.
528
496
 
529
497
  BlockChyp does have the ability to import gift card liability from
530
498
  conventional gift card platforms. Unfortunately, BlockChyp does not
531
- support activating cards on third party systems, but you can import
499
+ support activating cards on third party systems. However, you can import
532
500
  your outstanding gift cards and customers can swipe them on the
533
- terminals just like BlockChyp's standard gift cards.
501
+ terminals like BlockChyp's standard gift cards.
534
502
 
535
503
  No special coding is required to access this feature. The gateway and
536
504
  terminal firmware handle everything for you.
@@ -540,7 +508,7 @@ terminal firmware handle everything for you.
540
508
  BlockChyp does not currently provide any native support for other gift card
541
509
  platforms beyond importing gift card liability. We do have a white listing system
542
510
  that can be used to support your own custom gift card implementations. We have a security review
543
- process before we allow a BIN range to be white listed, so contact
511
+ process before we can allow a BIN range to be white listed, so contact
544
512
  support@blockchyp.com if you need to white list a BIN range.
545
513
 
546
514
 
@@ -575,25 +543,29 @@ puts "Response: #{response.inspect}"
575
543
 
576
544
 
577
545
 
578
- Checks a gift or EBT card balance.
546
+ * **API Credential Types:** Merchant
547
+ * **Required Role:** Payment API Access
548
+
549
+ This API checks a gift or EBT card balance.
579
550
 
580
551
  **Gift Card Balance Checks**
581
552
 
582
- For gift cards, just pass in a terminal name and the customer will be prompted
553
+ For gift cards, pass in a terminal name and the customer will be prompted
583
554
  to swipe a card on that terminal. The remaining balance will be displayed
584
555
  briefly on the terminal screen and the API response will include the gift card's public key and the remaining balance.
585
556
 
586
557
  **EBT Balance Checks**
587
558
 
588
- All EBT transactions require a PIN, so in order to check an EBT card balance,
559
+ All EBT transactions require a PIN, so to check an EBT card balance,
589
560
  you need to pass in the `ebt` flag just like you would for a normal EBT
590
561
  charge transaction. The customer will be prompted to swipe their card and
591
- 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 in the API.
562
+ enter a PIN code. If everything checks out, the remaining balance on the
563
+ card will be displayed on the terminal for the customer and returned with the API response.
592
564
 
593
565
  **Testing Gift Card Balance Checks**
594
566
 
595
567
  Test gift card balance checks work no differently than live gift cards. You
596
- must activate a test gift card first in order to test balance checks. Test
568
+ must activate a test gift card first to test balance checks. Test
597
569
  gift cards are real blockchain cards that live on our parallel test blockchain.
598
570
 
599
571
  **Testing EBT Gift Card Balance Checks**
@@ -632,6 +604,10 @@ puts "Response: #{response.inspect}"
632
604
  #### Close Batch
633
605
 
634
606
 
607
+
608
+ * **API Credential Types:** Merchant
609
+ * **Required Role:** Payment API Access
610
+
635
611
  This API will close the merchant's batch if it's currently open.
636
612
 
637
613
  By default, merchant batches will close automatically at 3 AM in their
@@ -670,6 +646,9 @@ puts "Response: #{response.inspect}"
670
646
 
671
647
 
672
648
 
649
+ * **API Credential Types:** Merchant
650
+ * **Required Role:** Payment API Access
651
+
673
652
  This API allows you to send an invoice to a customer and capture payment
674
653
  via a BlockChyp hosted payment page.
675
654
 
@@ -684,26 +663,26 @@ you use the `cashier` flag.)
684
663
 
685
664
  **Customer Info**
686
665
 
687
- Unless you're using the `cashier` flag, you must specify a customer, either by
688
- creating a new customer record inline or by passing in an existing Customer ID or Customer Ref.
666
+ Unless you're using the `cashier` flag, you must specify a customer; either by
667
+ creating a new customer record inline or passing in an existing Customer ID or Customer Ref.
689
668
 
690
669
  **Line Item Level Data**
691
670
 
692
671
  It's not strictly required, but we strongly recommend sending line item level
693
- detail with every request. It will make the invoice look a little more complete
672
+ detail with every request. It will make the invoice look more complete
694
673
  and the data format for line item level data is the exact same format used
695
674
  for terminal line item display, so the same code can be used to support both areas.
696
675
 
697
676
  **Descriptions**
698
677
 
699
- You can also provide a free form description or message that's displayed near
678
+ You can also provide a free form description or message to display near
700
679
  the bottom of the invoice. Usually this is some kind of thank you note
701
680
  or instruction.
702
681
 
703
682
  **Terms and Conditions**
704
683
 
705
684
  You can include long form contract language with a request and capture
706
- terms and conditions acceptance at the same time payment is captured.
685
+ terms and conditions accepted at the same time payment is captured.
707
686
 
708
687
  The interface is identical to that used for the terminal based Terms and
709
688
  Conditions API in that you can pass in content directly via `tcContent` or via
@@ -712,10 +691,14 @@ agreement acceptance is incorporated into a send link request.
712
691
 
713
692
  **Auto Send**
714
693
 
715
- BlockChyp does not send the email notification automatically. This is
716
- a safeguard to prevent real emails from going out when you may not expect it.
717
- If you want BlockChyp to send the email for you, just add the `autoSend` flag with
718
- all requests.
694
+ BlockChyp does not send the email notification automatically. This safeguard prevents real
695
+ emails from going out when you may not expect them If you want BlockChyp to send the email
696
+ for you, just add the `autoSend` flag with all requests.
697
+
698
+ **Cryptocurrency**
699
+
700
+ If the merchant is configured to support cryptocurrency transactions, the payment page will
701
+ display additional UI widgets that allowing customers to switch to a crypto payment method.
719
702
 
720
703
  **Tokenization**
721
704
 
@@ -725,13 +708,15 @@ in the token vault.
725
708
  **Cashier Facing Card Entry**
726
709
 
727
710
  BlockChyp can be used to generate internal/cashier facing card entry pages as well. This is
728
- designed for situations where you might need to take a phone order and you don't
729
- have a terminal.
711
+ designed for situations where you might need to take a phone order and don't
712
+ have an available terminal.
730
713
 
731
- If you pass in the `cashier` flag, no email will be sent and you'll be be able to
714
+ If you pass in the `cashier` flag, no email will be sent and you'll be able to
732
715
  load the link in a browser or iframe for payment entry. When the `cashier` flag
733
716
  is used, the `autoSend` flag will be ignored.
734
717
 
718
+ Note that cryptocurrency is not supported for cashier facing payment entry.
719
+
735
720
  **Payment Notifications**
736
721
 
737
722
  When a customer successfully submits payment, the merchant will receive an email
@@ -773,6 +758,7 @@ blockchyp = BlockChyp::BlockChyp.new(
773
758
 
774
759
  # Set request parameters
775
760
  request = {
761
+ transactionRef: '<TX REF>',
776
762
  amount: '199.99',
777
763
  description: 'Widget',
778
764
  subject: 'Widget invoice',
@@ -794,7 +780,7 @@ request = {
794
780
  firstName: 'FirstName',
795
781
  lastName: 'LastName',
796
782
  companyName: 'Company Name',
797
- emailAddress: 'support@blockchyp.com',
783
+ emailAddress: 'notifications@blockchypteam.m8r.co',
798
784
  smsNumber: '(123) 123-1231'
799
785
  }
800
786
  }
@@ -806,16 +792,14 @@ puts "Response: #{response.inspect}"
806
792
 
807
793
  ```
808
794
 
809
- #### Transaction Status
795
+ #### Cancel Payment Link
810
796
 
811
797
 
812
798
 
813
- Returns the current status for any transaction. You can lookup a transaction
814
- by its BlockChyp assigned Transaction ID or your own Transaction Ref.
799
+ * **API Credential Types:** Merchant
800
+ * **Required Role:** Payment API Access
815
801
 
816
- You should alway use globally unique Transaction Ref values, but in the event
817
- that you duplicate Transaction Refs, the most recent transaction matching your
818
- Transaction Ref is returned.
802
+ This API cancels a payment link.
819
803
 
820
804
 
821
805
 
@@ -833,23 +817,29 @@ blockchyp = BlockChyp::BlockChyp.new(
833
817
 
834
818
  # Set request parameters
835
819
  request = {
836
- transactionId: 'ID of transaction to retrieve'
820
+ linkCode: '<PAYMENT LINK CODE>'
837
821
  }
838
822
 
839
- response = blockchyp.transactionStatus(request)
823
+ response = blockchyp.cancelPaymentLink(request)
840
824
 
841
825
  puts "Response: #{response.inspect}"
842
826
 
843
827
 
844
828
  ```
845
829
 
846
- #### Terminal Clear
830
+ #### Transaction Status
847
831
 
848
832
 
849
833
 
850
- This API interrupts whatever a terminal may be doing and returns it to the
851
- idle state.
834
+ * **API Credential Types:** Merchant
835
+ * **Required Role:** Payment API Access
836
+
837
+ This API returns the current status for any transaction. You can lookup a transaction
838
+ by its BlockChyp assigned Transaction ID or your own Transaction Ref.
852
839
 
840
+ You should alway use globally unique Transaction Ref values, but in the event
841
+ that you duplicate Transaction Refs, the most recent transaction matching your
842
+ Transaction Ref is returned.
853
843
 
854
844
 
855
845
 
@@ -867,31 +857,28 @@ blockchyp = BlockChyp::BlockChyp.new(
867
857
 
868
858
  # Set request parameters
869
859
  request = {
870
- test: true,
871
- terminalName: 'Test Terminal'
860
+ transactionId: '<TRANSACTION ID>'
872
861
  }
873
862
 
874
- response = blockchyp.clear(request)
863
+ response = blockchyp.transactionStatus(request)
875
864
 
876
865
  puts "Response: #{response.inspect}"
877
866
 
878
867
 
879
868
  ```
880
869
 
881
- #### Terminal Status
870
+ #### Cash Discount
882
871
 
883
872
 
884
873
 
885
- Returns the current status of a payment terminal. This is typically used
886
- as a way to determine if the terminal is busy before sending a new transaction.
874
+ * **API Credential Types:** Merchant
875
+ * **Required Role:** Payment API Access
887
876
 
888
- If the terminal is busy, `idle` will be false and the `status` field will return
889
- a short string indicating the transaction type currently in progress. The system
890
- will also return the timestamp of the last status change in the `since` field.
877
+ This API calculates the surcharge, cash discount, and total amounts for cash transactions.
891
878
 
892
- If the system is running a payment transaction and you wisely passed in a
893
- Transaction Ref, this API will also return the Transaction Ref of the in progress
894
- transaction.
879
+ If you're using BlockChyp's cash discounting features, you can use this endpoint
880
+ to ensure the numbers and receipts for true cash transactions are consistent
881
+ with transactions processed by BlockChyp.
895
882
 
896
883
 
897
884
 
@@ -909,57 +896,46 @@ blockchyp = BlockChyp::BlockChyp.new(
909
896
 
910
897
  # Set request parameters
911
898
  request = {
912
- terminalName: 'Test Terminal'
899
+ amount: '100.00',
900
+ cashDiscount: true,
901
+ surcharge: true
913
902
  }
914
903
 
915
- response = blockchyp.terminalStatus(request)
904
+ response = blockchyp.cashDiscount(request)
916
905
 
917
906
  puts "Response: #{response.inspect}"
918
907
 
919
908
 
920
909
  ```
921
910
 
922
- #### Terms & Conditions Capture
923
-
924
-
925
-
926
- This API allows you to prompt a customer to accept a legal agreement on the terminal
927
- and (usually) capture their signature.
928
-
929
- Content for the agreement can be specified in two ways. You can reference a
930
- previously configured T&C template or pass in the full agreement text with every request.
931
-
932
- **Using Templates**
933
-
934
- If your application doesn't keep track of agreements you can leverage BlockChyp's
935
- template system. You can create any number of T&C Templates in the merchant dashboard
936
- and pass in the `tcAlias` flag to specify which one to display.
911
+ #### Batch History
937
912
 
938
- **Raw Content**
939
913
 
940
- If your system keeps track of the agreement language or executes complicated merging
941
- and rendering logic, you can bypass our template system and pass in the full text with
942
- every transaction. Use the `tcName` to pass in the agreement name and `tcContent` to
943
- pass in the contract text. Note that only plain text is supported.
944
914
 
945
- **Bypassing Signatures**
915
+ * **API Credential Types:** Merchant
916
+ * **Required Role:** Payment API Access
946
917
 
947
- Signature images are captured by default. If for some reason this doesn't fit your
948
- use case and you'd like to capture acceptance without actually capturing a signature image, set
949
- the `disableSignature` flag in the request.
918
+ This endpoint allows developers to query the gateway for the merchant's batch history.
919
+ The data will be returned in descending order of open date with the most recent
920
+ batch returned first. The results will include basic information about the batch.
921
+ Consider using the Batch Details API for more detail about a specific batch.
950
922
 
951
- **Terms & Conditions Log**
923
+ **Limiting Results**
952
924
 
953
- Every time a user accepts an agreement on the terminal, the signature image (if captured),
954
- will be uploaded to the gateway and added to the log along with the full text of the
955
- agreement. This preserves the historical record in the event that standard agreements
956
- or templates change over time.
925
+ This API will return a maximum of 250 results. Use the `maxResults` property to
926
+ limit maximum results even further and use the `startIndex` property to
927
+ page through results that span multiple queries.
957
928
 
958
- **Associating Agreements with Transactions**
929
+ For example, if you want the ten most recent batches, pass in a value of
930
+ `10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
931
+ get the first batch in the dataset.
959
932
 
960
- To associate a Terms & Conditions log entry with a transaction, just pass in the
961
- Transaction ID or Transaction Ref for the associated transaction.
933
+ **Filtering by Date Range**
962
934
 
935
+ You can also filter results by date. Use the `startDate` and `endDate`
936
+ properties to return only those batches opened between those dates.
937
+ You can use either `startDate` and `endDate` and you can use date filters
938
+ in conjunction with `maxResults` and `startIndex`
963
939
 
964
940
 
965
941
 
@@ -977,58 +953,31 @@ blockchyp = BlockChyp::BlockChyp.new(
977
953
 
978
954
  # Set request parameters
979
955
  request = {
980
- test: true,
981
- terminalName: 'Test Terminal',
982
-
983
- # Alias for a Terms and Conditions template configured in the BlockChyp
984
- # dashboard.
985
- tcAlias: 'hippa',
986
-
987
- # Name of the contract or document if not using an alias.
988
- tcName: 'HIPPA Disclosure',
989
-
990
- # Full text of the contract or disclosure if not using an alias.
991
- tcContent: 'Full contract text',
992
-
993
- # File format for the signature image.
994
- sigFormat: SignatureFormat::PNG,
995
-
996
- # Width of the signature image in pixels.
997
- sigWidth: 200,
998
-
999
- # Whether or not a signature is required. Defaults to true.
1000
- sigRequired: true
956
+ maxResults: 250,
957
+ startIndex: 0
1001
958
  }
1002
959
 
1003
- response = blockchyp.termsAndConditions(request)
960
+ response = blockchyp.batchHistory(request)
1004
961
 
1005
962
  puts "Response: #{response.inspect}"
1006
963
 
1007
964
 
1008
965
  ```
1009
966
 
1010
- #### Capture Signature
1011
-
1012
-
967
+ #### Batch Details
1013
968
 
1014
- This endpoint captures a written signature from the terminal and returns the
1015
- image.
1016
969
 
1017
- Unlike the Terms & Conditions API, this endpoint performs basic signature
1018
- capture with no agreement display or signature archival.
1019
970
 
1020
- Under the hood, signatures are captured in a proprietary vector format and
1021
- must be converted to a common raster format in order to be useful to most
1022
- applications. At a minimum, you must specify an image format using the
1023
- `sigFormat` parameter. As of this writing JPG and PNG are supported.
971
+ * **API Credential Types:** Merchant
972
+ * **Required Role:** Payment API Access
1024
973
 
1025
- By default, images are returned in the JSON response as hex encoded binary.
1026
- You can redirect the binary image output to a file using the `sigFile`
1027
- parameter.
974
+ This API allows developers to pull down details for a specific batch,
975
+ including captured volume, gift card activity, expected deposit, and
976
+ captured volume broken down by terminal.
1028
977
 
1029
- You can also scale the output image to your preferred width by
1030
- passing in a `sigWidth` parameter. The image will be scaled to that
1031
- width, preserving the aspect ratio of the original image.
978
+ The only required request parameter is `batchId`. Batch IDs are returned
979
+ with every transaction response and can be discovered using the Batch
980
+ History API.
1032
981
 
1033
982
 
1034
983
 
@@ -1046,42 +995,509 @@ blockchyp = BlockChyp::BlockChyp.new(
1046
995
 
1047
996
  # Set request parameters
1048
997
  request = {
1049
- terminalName: 'Test Terminal',
1050
-
1051
- # File format for the signature image.
1052
- sigFormat: SignatureFormat::PNG,
1053
-
1054
- # Width of the signature image in pixels.
1055
- sigWidth: 200
998
+ batchId: '<BATCH ID>'
1056
999
  }
1057
1000
 
1058
- response = blockchyp.captureSignature(request)
1001
+ response = blockchyp.batchDetails(request)
1059
1002
 
1060
1003
  puts "Response: #{response.inspect}"
1061
1004
 
1062
1005
 
1063
1006
  ```
1064
1007
 
1065
- #### New Transaction Display
1008
+ #### Transaction History
1066
1009
 
1067
1010
 
1068
1011
 
1069
- Sends totals and line item level data to the terminal.
1012
+ * **API Credential Types:** Merchant
1013
+ * **Required Role:** Payment API Access
1070
1014
 
1071
- At a minimum, you should send total information as part of a display request,
1072
- including `total`, `tax`, and `subtotal`.
1015
+ This endpoint provides several different methods to sift through
1016
+ transaction history.
1073
1017
 
1074
- You can also send line item level data and each line item can have a `description`,
1075
- `qty`, `price`, and `extended` price.
1018
+ By default with no filtering properties, this endpoint will return the 250
1019
+ most recent transactions.
1076
1020
 
1077
- If you fail to send an extended price, BlockChyp will multiply the `qty` by the
1078
- `price`, but we strongly recommend you precalculate all the fields yourself
1079
- to ensure consistency. Your treatment of floating-point multiplication and rounding
1080
- may differ slightly from BlockChyp's, for example.
1021
+ **Limiting Results**
1081
1022
 
1082
- **Discounts**
1023
+ This API will return a maximum of 50 results in a single query. Use the `maxResults` property
1024
+ to limit maximum results even further and use the `startIndex` property to
1025
+ page through results that span multiple queries.
1083
1026
 
1084
- You have the option to show discounts on the display as individual line items
1027
+ For example, if you want the ten most recent batches, pass in a value of
1028
+ `10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
1029
+ get the first transaction in the dataset.
1030
+
1031
+ **Filtering By Date Range**
1032
+
1033
+ You can also filter results by date. Use the `startDate` and `endDate`
1034
+ properties to return only transactions run between those dates.
1035
+ You can use either `startDate` or `endDate` and you can use date filters
1036
+ in conjunction with `maxResults` and `startIndex`
1037
+
1038
+ **Filtering By Batch**
1039
+
1040
+ To restrict results to a single batch, pass in the `batchId` parameter.
1041
+
1042
+ **Filtering By Terminal**
1043
+
1044
+ To restrict results to those executed on a single terminal, pass in the terminal name.
1045
+
1046
+ **Combining Filters**
1047
+
1048
+ None of the above filters are mutually exclusive. You can combine any of the
1049
+ above properties in a single request to restrict transaction results to a
1050
+ narrower set of results.
1051
+
1052
+ **Searching Transaction History**
1053
+
1054
+ You can search transaction history by passing in search criteria with the
1055
+ `query` option. The search system will match the amount (requested and authorized),
1056
+ last four of the card number, cardholder name, and the auth code.
1057
+
1058
+ Note that when search queries are used, terminalName or
1059
+ batch id filters are not supported.
1060
+
1061
+
1062
+
1063
+
1064
+ ```ruby
1065
+ # frozen_string_literal: true
1066
+
1067
+ require 'blockchyp'
1068
+
1069
+ blockchyp = BlockChyp::BlockChyp.new(
1070
+ ENV['BC_API_KEY'],
1071
+ ENV['BC_BEARER_TOKEN'],
1072
+ ENV['BC_SIGNING_KEY']
1073
+ )
1074
+
1075
+ # Set request parameters
1076
+ request = {
1077
+ maxResults: 10,
1078
+ batchId: '<BATCH ID>'
1079
+ }
1080
+
1081
+ response = blockchyp.transactionHistory(request)
1082
+
1083
+ puts "Response: #{response.inspect}"
1084
+
1085
+
1086
+ ```
1087
+
1088
+ #### List Queued Transactions
1089
+
1090
+
1091
+
1092
+ * **API Credential Types:** Merchant
1093
+ * **Required Role:** Payment API Access
1094
+
1095
+ Returns a list of transaction refs of transactions queued on a terminal.
1096
+ Details about the transactions can be retrieved using the Transaction Status
1097
+ API.
1098
+
1099
+
1100
+
1101
+
1102
+ ```ruby
1103
+ # frozen_string_literal: true
1104
+
1105
+ require 'blockchyp'
1106
+
1107
+ blockchyp = BlockChyp::BlockChyp.new(
1108
+ ENV['BC_API_KEY'],
1109
+ ENV['BC_BEARER_TOKEN'],
1110
+ ENV['BC_SIGNING_KEY']
1111
+ )
1112
+
1113
+ # Set request parameters
1114
+ request = {
1115
+ terminalName: 'Test Terminal'
1116
+ }
1117
+
1118
+ response = blockchyp.listQueuedTransactions(request)
1119
+
1120
+ puts "Response: #{response.inspect}"
1121
+
1122
+
1123
+ ```
1124
+
1125
+ #### Delete Queued Transaction
1126
+
1127
+
1128
+
1129
+ * **API Credential Types:** Merchant
1130
+ * **Required Role:** Payment API Access
1131
+
1132
+ Deletes one or all queued transactions from a terminal. If `*` is passed as
1133
+ a transaction ref, then the entire terminal queue will be cleared. An error is
1134
+ returned if the passed transaction ref is not queued on the terminal.
1135
+
1136
+
1137
+
1138
+
1139
+ ```ruby
1140
+ # frozen_string_literal: true
1141
+
1142
+ require 'blockchyp'
1143
+
1144
+ blockchyp = BlockChyp::BlockChyp.new(
1145
+ ENV['BC_API_KEY'],
1146
+ ENV['BC_BEARER_TOKEN'],
1147
+ ENV['BC_SIGNING_KEY']
1148
+ )
1149
+
1150
+ # Set request parameters
1151
+ request = {
1152
+ terminalName: 'Test Terminal',
1153
+ transactionRef: '*'
1154
+ }
1155
+
1156
+ response = blockchyp.deleteQueuedTransaction(request)
1157
+
1158
+ puts "Response: #{response.inspect}"
1159
+
1160
+
1161
+ ```
1162
+
1163
+ ### Terminal Management Endpoints
1164
+
1165
+
1166
+ These APIs support terminal management functions and additional terminal
1167
+ features such as line item display, messages, and interactive prompts.
1168
+ These features can be used to extend a point of sale system's functionality.
1169
+
1170
+
1171
+
1172
+ #### Terminal Ping
1173
+
1174
+
1175
+
1176
+ * **API Credential Types:** Merchant
1177
+ * **Required Role:** Payment API Access
1178
+
1179
+ This simple test transaction helps ensure good communication with a payment terminal
1180
+ and is usually the first test you'll run in development.
1181
+
1182
+ It tests communication with the terminal and returns a positive response if everything
1183
+ is okay. It works the same way in local or cloud relay mode.
1184
+
1185
+ If you get a positive response, you've successfully verified all of the following:
1186
+
1187
+ * The terminal is online.
1188
+ * There is a valid route to the terminal.
1189
+ * The API Credentials are valid.
1190
+
1191
+
1192
+
1193
+
1194
+ ```ruby
1195
+ # frozen_string_literal: true
1196
+
1197
+ require 'blockchyp'
1198
+
1199
+ blockchyp = BlockChyp::BlockChyp.new(
1200
+ ENV['BC_API_KEY'],
1201
+ ENV['BC_BEARER_TOKEN'],
1202
+ ENV['BC_SIGNING_KEY']
1203
+ )
1204
+
1205
+ # Set request parameters
1206
+ request = {
1207
+ terminalName: 'Test Terminal'
1208
+ }
1209
+
1210
+ response = blockchyp.ping(request)
1211
+
1212
+ puts "Response: #{response.inspect}"
1213
+
1214
+
1215
+ ```
1216
+
1217
+ #### Terminal Locate
1218
+
1219
+
1220
+
1221
+ * **API Credential Types:** Merchant
1222
+ * **Required Role:** Payment API Access
1223
+
1224
+ This endpoint returns a terminal's routing and location information.
1225
+
1226
+ The result will indicate whether or not the terminal is in cloud relay mode and will
1227
+ return the local IP address if the terminal is in local mode.
1228
+
1229
+ The terminal will also return the public key for the terminal.
1230
+
1231
+
1232
+
1233
+
1234
+ ```ruby
1235
+ # frozen_string_literal: true
1236
+
1237
+ require 'blockchyp'
1238
+
1239
+ blockchyp = BlockChyp::BlockChyp.new(
1240
+ ENV['BC_API_KEY'],
1241
+ ENV['BC_BEARER_TOKEN'],
1242
+ ENV['BC_SIGNING_KEY']
1243
+ )
1244
+
1245
+ # Set request parameters
1246
+ request = {
1247
+ terminalName: 'Test Terminal'
1248
+ }
1249
+
1250
+ response = blockchyp.locate(request)
1251
+
1252
+ puts "Response: #{response.inspect}"
1253
+
1254
+
1255
+ ```
1256
+
1257
+ #### Terminal Clear
1258
+
1259
+
1260
+
1261
+ * **API Credential Types:** Merchant
1262
+ * **Required Role:** Payment API Access
1263
+
1264
+ This API interrupts whatever a terminal may be doing and returns it to the
1265
+ idle state.
1266
+
1267
+
1268
+
1269
+
1270
+
1271
+ ```ruby
1272
+ # frozen_string_literal: true
1273
+
1274
+ require 'blockchyp'
1275
+
1276
+ blockchyp = BlockChyp::BlockChyp.new(
1277
+ ENV['BC_API_KEY'],
1278
+ ENV['BC_BEARER_TOKEN'],
1279
+ ENV['BC_SIGNING_KEY']
1280
+ )
1281
+
1282
+ # Set request parameters
1283
+ request = {
1284
+ test: true,
1285
+ terminalName: 'Test Terminal'
1286
+ }
1287
+
1288
+ response = blockchyp.clear(request)
1289
+
1290
+ puts "Response: #{response.inspect}"
1291
+
1292
+
1293
+ ```
1294
+
1295
+ #### Terminal Status
1296
+
1297
+
1298
+
1299
+ * **API Credential Types:** Merchant
1300
+ * **Required Role:** Payment API Access
1301
+
1302
+ This API returns the current status of a payment terminal. This is typically used
1303
+ as a way to determine if the terminal is busy before sending a new transaction.
1304
+
1305
+ If the terminal is busy, `idle` will be false and the `status` field will return
1306
+ a short string that indicates the transaction type currently in progress. The system
1307
+ will also return the timestamp of the last status change in the `since` field.
1308
+
1309
+ If the system is running a payment transaction and you wisely passed in a
1310
+ Transaction Ref, this API will also return the Transaction Ref of the in progress
1311
+ transaction.
1312
+
1313
+
1314
+
1315
+
1316
+ ```ruby
1317
+ # frozen_string_literal: true
1318
+
1319
+ require 'blockchyp'
1320
+
1321
+ blockchyp = BlockChyp::BlockChyp.new(
1322
+ ENV['BC_API_KEY'],
1323
+ ENV['BC_BEARER_TOKEN'],
1324
+ ENV['BC_SIGNING_KEY']
1325
+ )
1326
+
1327
+ # Set request parameters
1328
+ request = {
1329
+ terminalName: 'Test Terminal'
1330
+ }
1331
+
1332
+ response = blockchyp.terminalStatus(request)
1333
+
1334
+ puts "Response: #{response.inspect}"
1335
+
1336
+
1337
+ ```
1338
+
1339
+ #### Capture Signature
1340
+
1341
+
1342
+
1343
+ * **API Credential Types:** Merchant
1344
+ * **Required Role:** Payment API Access
1345
+
1346
+ This endpoint captures a written signature from the terminal and returns the
1347
+ image.
1348
+
1349
+ Unlike the Terms & Conditions API, this endpoint performs basic signature
1350
+ capture with no agreement display or signature archival.
1351
+
1352
+ Under the hood, signatures are captured in a proprietary vector format and
1353
+ must be converted to a common raster format in order to be useful to most
1354
+ applications. At a minimum, you must specify an image format using the
1355
+ `sigFormat` parameter. Currently, JPG and PNG are supported.
1356
+
1357
+ By default, images are returned in the JSON response as hex encoded binary.
1358
+ You can redirect the binary image output to a file using the `sigFile`
1359
+ parameter.
1360
+
1361
+ You can also scale the output image to your preferred width by
1362
+ passing in a `sigWidth` parameter. The image will be scaled to that
1363
+ width, preserving the aspect ratio of the original image.
1364
+
1365
+
1366
+
1367
+
1368
+ ```ruby
1369
+ # frozen_string_literal: true
1370
+
1371
+ require 'blockchyp'
1372
+
1373
+ blockchyp = BlockChyp::BlockChyp.new(
1374
+ ENV['BC_API_KEY'],
1375
+ ENV['BC_BEARER_TOKEN'],
1376
+ ENV['BC_SIGNING_KEY']
1377
+ )
1378
+
1379
+ # Set request parameters
1380
+ request = {
1381
+ terminalName: 'Test Terminal',
1382
+
1383
+ # File format for the signature image.
1384
+ sigFormat: SignatureFormat::PNG,
1385
+
1386
+ # Width of the signature image in pixels.
1387
+ sigWidth: 200
1388
+ }
1389
+
1390
+ response = blockchyp.captureSignature(request)
1391
+
1392
+ puts "Response: #{response.inspect}"
1393
+
1394
+
1395
+ ```
1396
+
1397
+ #### New Transaction Display
1398
+
1399
+
1400
+
1401
+ * **API Credential Types:** Merchant
1402
+ * **Required Role:** Payment API Access
1403
+
1404
+ This API sends totals and line item level data to the terminal.
1405
+
1406
+ At a minimum, you should send total information as part of a display request,
1407
+ including `total`, `tax`, and `subtotal`.
1408
+
1409
+ You can also send line item level data and each line item can have a `description`,
1410
+ `qty`, `price`, and `extended` price.
1411
+
1412
+ If you fail to send an extended price, BlockChyp will multiply the `qty` by the
1413
+ `price`. However, we strongly recommend you precalculate all the fields yourself
1414
+ to ensure consistency. For example, your treatment of floating-point multiplication
1415
+ and rounding may differ slightly from BlockChyp's.
1416
+
1417
+ **Discounts**
1418
+
1419
+ You have the option to show discounts on the display as individual line items
1420
+ with negative values or you can associate discounts with a specific line item.
1421
+ You can apply any number of discounts to an individual line item with a description
1422
+ and amount.
1423
+
1424
+
1425
+
1426
+
1427
+ ```ruby
1428
+ # frozen_string_literal: true
1429
+
1430
+ require 'blockchyp'
1431
+
1432
+ blockchyp = BlockChyp::BlockChyp.new(
1433
+ ENV['BC_API_KEY'],
1434
+ ENV['BC_BEARER_TOKEN'],
1435
+ ENV['BC_SIGNING_KEY']
1436
+ )
1437
+
1438
+ # Set request parameters
1439
+ request = {
1440
+ test: true,
1441
+ terminalName: 'Test Terminal',
1442
+ transaction: {
1443
+ subtotal: '60.00',
1444
+ tax: '5.00',
1445
+ total: '65.00',
1446
+ items: [
1447
+ {
1448
+ description: 'Leki Trekking Poles',
1449
+ price: '35.00',
1450
+ quantity: 2,
1451
+ extended: '70.00',
1452
+ discounts: [
1453
+ {
1454
+ description: 'memberDiscount',
1455
+ amount: '10.00'
1456
+ }
1457
+ ]
1458
+ }
1459
+ ]
1460
+ }
1461
+ }
1462
+
1463
+ response = blockchyp.newTransactionDisplay(request)
1464
+
1465
+ puts "Response: #{response.inspect}"
1466
+
1467
+
1468
+ ```
1469
+
1470
+ #### Update Transaction Display
1471
+
1472
+
1473
+
1474
+ * **API Credential Types:** Merchant
1475
+ * **Required Role:** Payment API Access
1476
+
1477
+ Similar to *New Transaction Display*, this variant allows developers to update
1478
+ line item level data currently being displayed on the terminal.
1479
+
1480
+ This feature is designed for situations where you want to update the terminal display as
1481
+ items are scanned. You'll only have to send information to the
1482
+ terminal that's changed, which usually means the new line item and updated totals.
1483
+
1484
+ If the terminal is not in line item display mode and you invoke this endpoint,
1485
+ the first invocation will behave like a *New Transaction Display* call.
1486
+
1487
+ At a minimum, you should send total information as part of a display request,
1488
+ including `total`, `tax`, and `subtotal`.
1489
+
1490
+ You can also send line item level data and each line item can have a `description`,
1491
+ `qty`, `price`, and `extended` price.
1492
+
1493
+ If you fail to send an extended price, BlockChyp will multiply the `qty` by the
1494
+ `price`. However, we strongly recommend you precalculate all the fields yourself
1495
+ to ensure consistency. For example, your treatment of floating-point multiplication and rounding
1496
+ may differ slightly from BlockChyp's.
1497
+
1498
+ **Discounts**
1499
+
1500
+ You have the option to show discounts on the display as individual line items
1085
1501
  with negative values or you can associate discounts with a specific line item.
1086
1502
  You can apply any number of discounts to an individual line item with a description
1087
1503
  and amount.
@@ -1102,67 +1518,1658 @@ blockchyp = BlockChyp::BlockChyp.new(
1102
1518
 
1103
1519
  # Set request parameters
1104
1520
  request = {
1105
- test: true,
1106
- terminalName: 'Test Terminal',
1107
- transaction: {
1108
- subtotal: '60.00',
1109
- tax: '5.00',
1110
- total: '65.00',
1111
- items: [
1112
- {
1113
- description: 'Leki Trekking Poles',
1114
- price: '35.00',
1115
- quantity: 2,
1116
- extended: '70.00',
1117
- discounts: [
1118
- {
1119
- description: 'memberDiscount',
1120
- amount: '10.00'
1121
- }
1122
- ]
1123
- }
1124
- ]
1125
- }
1521
+ test: true,
1522
+ terminalName: 'Test Terminal',
1523
+ transaction: {
1524
+ subtotal: '60.00',
1525
+ tax: '5.00',
1526
+ total: '65.00',
1527
+ items: [
1528
+ {
1529
+ description: 'Leki Trekking Poles',
1530
+ price: '35.00',
1531
+ quantity: 2,
1532
+ extended: '70.00',
1533
+ discounts: [
1534
+ {
1535
+ description: 'memberDiscount',
1536
+ amount: '10.00'
1537
+ }
1538
+ ]
1539
+ }
1540
+ ]
1541
+ }
1542
+ }
1543
+
1544
+ response = blockchyp.updateTransactionDisplay(request)
1545
+
1546
+ puts "Response: #{response.inspect}"
1547
+
1548
+
1549
+ ```
1550
+
1551
+ #### Display Message
1552
+
1553
+
1554
+
1555
+ * **API Credential Types:** Merchant
1556
+ * **Required Role:** Payment API Access
1557
+
1558
+ This API displays a message on the payment terminal.
1559
+
1560
+ Just specify the target terminal and the message using the `message` parameter.
1561
+
1562
+
1563
+
1564
+
1565
+ ```ruby
1566
+ # frozen_string_literal: true
1567
+
1568
+ require 'blockchyp'
1569
+
1570
+ blockchyp = BlockChyp::BlockChyp.new(
1571
+ ENV['BC_API_KEY'],
1572
+ ENV['BC_BEARER_TOKEN'],
1573
+ ENV['BC_SIGNING_KEY']
1574
+ )
1575
+
1576
+ # Set request parameters
1577
+ request = {
1578
+ test: true,
1579
+ terminalName: 'Test Terminal',
1580
+ message: 'Thank you for your business.'
1581
+ }
1582
+
1583
+ response = blockchyp.message(request)
1584
+
1585
+ puts "Response: #{response.inspect}"
1586
+
1587
+
1588
+ ```
1589
+
1590
+ #### Boolean Prompt
1591
+
1592
+
1593
+
1594
+ * **API Credential Types:** Merchant
1595
+ * **Required Role:** Payment API Access
1596
+
1597
+ This API Pprompts the customer to answer a yes or no question.
1598
+
1599
+ You can specify the question or prompt with the `prompt` parameter and
1600
+ the response is returned in the `response` field.
1601
+
1602
+ This can be used for a number of use cases including starting a loyalty enrollment
1603
+ workflow or customer facing suggestive selling prompts.
1604
+
1605
+ **Custom Captions**
1606
+
1607
+ You can optionally override the "YES" and "NO" button captions by
1608
+ using the `yesCaption` and `noCaption` request parameters.
1609
+
1610
+
1611
+
1612
+
1613
+ ```ruby
1614
+ # frozen_string_literal: true
1615
+
1616
+ require 'blockchyp'
1617
+
1618
+ blockchyp = BlockChyp::BlockChyp.new(
1619
+ ENV['BC_API_KEY'],
1620
+ ENV['BC_BEARER_TOKEN'],
1621
+ ENV['BC_SIGNING_KEY']
1622
+ )
1623
+
1624
+ # Set request parameters
1625
+ request = {
1626
+ test: true,
1627
+ terminalName: 'Test Terminal',
1628
+ prompt: 'Would you like to become a member?',
1629
+ yesCaption: 'Yes',
1630
+ noCaption: 'No'
1631
+ }
1632
+
1633
+ response = blockchyp.booleanPrompt(request)
1634
+
1635
+ puts "Response: #{response.inspect}"
1636
+
1637
+
1638
+ ```
1639
+
1640
+ #### Text Prompt
1641
+
1642
+
1643
+
1644
+ * **API Credential Types:** Merchant
1645
+ * **Required Role:** Payment API Access
1646
+
1647
+ This API prompts the customer to enter numeric or alphanumeric data.
1648
+
1649
+ Due to PCI rules, free-form prompts are not permitted when the response
1650
+ could be any valid string. The reason for this is that a malicious
1651
+ developer (not you, of course) could use text prompts to ask the customer to
1652
+ input a card number or PIN code.
1653
+
1654
+ This means that instead of providing a prompt, you provide a `promptType` instead.
1655
+
1656
+ The prompt types currently supported are listed below:
1657
+
1658
+ * **phone**: Captures a phone number.
1659
+ * **email**: Captures an email address.
1660
+ * **first-name**: Captures a first name.
1661
+ * **last-name**: Captures a last name.
1662
+ * **customer-number**: Captures a customer number.
1663
+ * **rewards-number**: Captures a rewards number.
1664
+
1665
+ You can specify the prompt with the `promptType` parameter and
1666
+ the response is returned in the `response` field.
1667
+
1668
+
1669
+
1670
+
1671
+
1672
+ ```ruby
1673
+ # frozen_string_literal: true
1674
+
1675
+ require 'blockchyp'
1676
+
1677
+ blockchyp = BlockChyp::BlockChyp.new(
1678
+ ENV['BC_API_KEY'],
1679
+ ENV['BC_BEARER_TOKEN'],
1680
+ ENV['BC_SIGNING_KEY']
1681
+ )
1682
+
1683
+ # Set request parameters
1684
+ request = {
1685
+ test: true,
1686
+ terminalName: 'Test Terminal',
1687
+
1688
+ # Type of prompt. Can be 'email', 'phone', 'customer-number', or
1689
+ # 'rewards-number'.
1690
+ promptType: PromptType::EMAIL
1691
+ }
1692
+
1693
+ response = blockchyp.textPrompt(request)
1694
+
1695
+ puts "Response: #{response.inspect}"
1696
+
1697
+
1698
+ ```
1699
+
1700
+ #### List Terminals
1701
+
1702
+
1703
+
1704
+ * **API Credential Types:** Merchant & Partner
1705
+ * **Required Role:** Terminal Management
1706
+
1707
+ This API returns details about terminals associated with a merchant account.
1708
+
1709
+ Status and resource information is returned for all terminals along with a preview of the
1710
+ current branding image displayed on the terminal
1711
+
1712
+
1713
+
1714
+
1715
+ ```ruby
1716
+ # frozen_string_literal: true
1717
+
1718
+ require 'blockchyp'
1719
+
1720
+ blockchyp = BlockChyp::BlockChyp.new(
1721
+ ENV['BC_API_KEY'],
1722
+ ENV['BC_BEARER_TOKEN'],
1723
+ ENV['BC_SIGNING_KEY']
1724
+ )
1725
+
1726
+ # Set request parameters
1727
+ request = {
1728
+ }
1729
+
1730
+ response = blockchyp.terminals(request)
1731
+
1732
+ puts "Response: #{response.inspect}"
1733
+
1734
+
1735
+ ```
1736
+
1737
+ #### Deactivate Terminal
1738
+
1739
+
1740
+
1741
+ * **API Credential Types:** Merchant & Partner
1742
+ * **Required Role:** Terminal Management
1743
+
1744
+ This API deactivates a payment terminal.
1745
+
1746
+ If the terminal exists and is currently online, it will be removed from the merchant's
1747
+ terminal inventory. The terminal will be remotely cleared and factory reset.
1748
+
1749
+
1750
+
1751
+
1752
+ ```ruby
1753
+ # frozen_string_literal: true
1754
+
1755
+ require 'blockchyp'
1756
+
1757
+ blockchyp = BlockChyp::BlockChyp.new(
1758
+ ENV['BC_API_KEY'],
1759
+ ENV['BC_BEARER_TOKEN'],
1760
+ ENV['BC_SIGNING_KEY']
1761
+ )
1762
+
1763
+ # Set request parameters
1764
+ request = {
1765
+ terminalId: '<TERMINAL ID>'
1766
+ }
1767
+
1768
+ response = blockchyp.deactivateTerminal(request)
1769
+
1770
+ puts "Response: #{response.inspect}"
1771
+
1772
+
1773
+ ```
1774
+
1775
+ #### Activate Terminal
1776
+
1777
+
1778
+
1779
+ * **API Credential Types:** Merchant & Partner
1780
+ * **Required Role:** Terminal Management
1781
+
1782
+ This API activates a payment terminal.
1783
+
1784
+ If successful, the payment terminal will restart, generate new encryption keys, and download any active
1785
+ branding assets for the merchant account it's been added to.
1786
+
1787
+ Activation requests require an activation code and a unique terminal name. All terminal names must be unique across
1788
+ a merchant account.
1789
+
1790
+ Optional Parameters
1791
+
1792
+ * **merchantId:** For partner scoped API credentials, a merchant ID is required. For merchant scoped API credentials, the merchant ID is implicit and cannot be overridden.
1793
+ * **cloudRelay:** Activates the terminal in cloud relay mode.
1794
+
1795
+
1796
+
1797
+ ```ruby
1798
+ # frozen_string_literal: true
1799
+
1800
+ require 'blockchyp'
1801
+
1802
+ blockchyp = BlockChyp::BlockChyp.new(
1803
+ ENV['BC_API_KEY'],
1804
+ ENV['BC_BEARER_TOKEN'],
1805
+ ENV['BC_SIGNING_KEY']
1806
+ )
1807
+
1808
+ # Set request parameters
1809
+ request = {
1810
+ terminalName: 'Test Terminal',
1811
+ activationCode: '<ACTIVATION CODE>'
1812
+ }
1813
+
1814
+ response = blockchyp.activateTerminal(request)
1815
+
1816
+ puts "Response: #{response.inspect}"
1817
+
1818
+
1819
+ ```
1820
+
1821
+ #### Reboot Terminal
1822
+
1823
+
1824
+
1825
+ * **API Credential Types:** Merchant
1826
+ * **Required Role:** Payment API Access
1827
+
1828
+ This API reboots the terminal.
1829
+
1830
+
1831
+
1832
+
1833
+ ```ruby
1834
+ # frozen_string_literal: true
1835
+
1836
+ require 'blockchyp'
1837
+
1838
+ blockchyp = BlockChyp::BlockChyp.new(
1839
+ ENV['BC_API_KEY'],
1840
+ ENV['BC_BEARER_TOKEN'],
1841
+ ENV['BC_SIGNING_KEY']
1842
+ )
1843
+
1844
+ # Set request parameters
1845
+ request = {
1846
+ terminalName: 'Test Terminal'
1847
+ }
1848
+
1849
+ response = blockchyp.reboot(request)
1850
+
1851
+ puts "Response: #{response.inspect}"
1852
+
1853
+
1854
+ ```
1855
+
1856
+ ### Terms & Conditions Endpoints
1857
+
1858
+
1859
+ Developers can use BlockChyp to display and capture acceptance of contracts or agreements related to transactions.
1860
+ These agreements can be any long-form contract ranging from rental agreements to HIPPA disclosures.
1861
+
1862
+ There are two basic approaches to terms and conditions capture. Merchants can store contract templates in
1863
+ BlockChyp or they can send the full agreement text as part of every API call. The right approach will largely
1864
+ depend on whether or not the system being integrated with BlockChyp already has a mechanism for organizing
1865
+ and managing agreements. For systems that already have this feature built in, it's probably not necessary
1866
+ to use Terms and Conditions.
1867
+
1868
+ When agreements are displayed on a terminal, the consumer can scroll through and read the entire agreement,
1869
+ and provide a signature. Results are returned as part of the API response, but BlockChyp also stores a
1870
+ record of the agreement including the signature image, timestamp, and the full text of the agreement that was
1871
+ agreed to.
1872
+
1873
+ The Terms and Conditions Log APIs can be used to search and retrieve acceptance records. Those records
1874
+ can also be linked to a transaction if a transaction id is provided with the original API request.
1875
+
1876
+
1877
+
1878
+ #### Terms & Conditions Capture
1879
+
1880
+
1881
+
1882
+ * **API Credential Types:** Merchant
1883
+ * **Required Role:** Terms & Conditions Management
1884
+
1885
+ This API allows you to prompt a customer to accept a legal agreement on the terminal
1886
+ and (usually) capture their signature.
1887
+
1888
+ Content for the agreement can be specified in two ways. You can reference a
1889
+ previously configured T&C template or pass in the full agreement text with every request.
1890
+
1891
+ **Using Templates**
1892
+
1893
+ If your application doesn't keep track of agreements you can leverage BlockChyp's
1894
+ template system. You can create any number of T&C Templates in the merchant dashboard
1895
+ and pass in the `tcAlias` flag to specify which one should display.
1896
+
1897
+ **Raw Content**
1898
+
1899
+ If your system keeps track of the agreement language or executes complicated merging
1900
+ and rendering logic, you can bypass our template system and pass in the full text with
1901
+ every transaction. Use `tcName` to pass in the agreement name and `tcContent` to
1902
+ pass in the contract text. Note that only plain text is supported.
1903
+
1904
+ **Bypassing Signatures**
1905
+
1906
+ Signature images are captured by default. If for some reason this doesn't fit your
1907
+ use case and you'd like to capture acceptance without actually capturing a signature image, set
1908
+ the `disableSignature` flag in the request.
1909
+
1910
+ **Terms & Conditions Log**
1911
+
1912
+ Every time a user accepts an agreement on the terminal, the signature image (if captured),
1913
+ will be uploaded to the gateway. The image will also be added to the log along with the full text of the
1914
+ agreement. This preserves the historical record in the event that standard agreements
1915
+ or templates change over time.
1916
+
1917
+ **Associating Agreements with Transactions**
1918
+
1919
+ To associate a Terms & Conditions log entry with a transaction, just pass in the
1920
+ Transaction ID or Transaction Ref for the associated transaction.
1921
+
1922
+
1923
+
1924
+
1925
+
1926
+ ```ruby
1927
+ # frozen_string_literal: true
1928
+
1929
+ require 'blockchyp'
1930
+
1931
+ blockchyp = BlockChyp::BlockChyp.new(
1932
+ ENV['BC_API_KEY'],
1933
+ ENV['BC_BEARER_TOKEN'],
1934
+ ENV['BC_SIGNING_KEY']
1935
+ )
1936
+
1937
+ # Set request parameters
1938
+ request = {
1939
+ test: true,
1940
+ terminalName: 'Test Terminal',
1941
+
1942
+ # Alias for a Terms and Conditions template configured in the BlockChyp
1943
+ # dashboard.
1944
+ tcAlias: 'hippa',
1945
+
1946
+ # Name of the contract or document if not using an alias.
1947
+ tcName: 'HIPPA Disclosure',
1948
+
1949
+ # Full text of the contract or disclosure if not using an alias.
1950
+ tcContent: 'Full contract text',
1951
+
1952
+ # File format for the signature image.
1953
+ sigFormat: SignatureFormat::PNG,
1954
+
1955
+ # Width of the signature image in pixels.
1956
+ sigWidth: 200,
1957
+
1958
+ # Whether or not a signature is required. Defaults to true.
1959
+ sigRequired: true
1960
+ }
1961
+
1962
+ response = blockchyp.termsAndConditions(request)
1963
+
1964
+ puts "Response: #{response.inspect}"
1965
+
1966
+
1967
+ ```
1968
+
1969
+ #### List Templates
1970
+
1971
+
1972
+
1973
+ * **API Credential Types:** Merchant
1974
+ * **Required Role:** Terms & Conditions Management
1975
+
1976
+ This API returns all terms and conditions templates associated with a merchant account.
1977
+
1978
+
1979
+
1980
+
1981
+ ```ruby
1982
+ # frozen_string_literal: true
1983
+
1984
+ require 'blockchyp'
1985
+
1986
+ blockchyp = BlockChyp::BlockChyp.new(
1987
+ ENV['BC_API_KEY'],
1988
+ ENV['BC_BEARER_TOKEN'],
1989
+ ENV['BC_SIGNING_KEY']
1990
+ )
1991
+
1992
+ # Set request parameters
1993
+ request = {
1994
+ }
1995
+
1996
+ response = blockchyp.tcTemplates(request)
1997
+
1998
+ puts "Response: #{response.inspect}"
1999
+
2000
+
2001
+ ```
2002
+
2003
+ #### Get Template
2004
+
2005
+
2006
+
2007
+ * **API Credential Types:** Merchant
2008
+ * **Required Role:** Terms & Conditions Management
2009
+
2010
+ This API returns as single terms and conditions template.
2011
+
2012
+
2013
+
2014
+
2015
+ ```ruby
2016
+ # frozen_string_literal: true
2017
+
2018
+ require 'blockchyp'
2019
+
2020
+ blockchyp = BlockChyp::BlockChyp.new(
2021
+ ENV['BC_API_KEY'],
2022
+ ENV['BC_BEARER_TOKEN'],
2023
+ ENV['BC_SIGNING_KEY']
2024
+ )
2025
+
2026
+ # Set request parameters
2027
+ request = {
2028
+ templateId: '<TEMPLATE ID>'
2029
+ }
2030
+
2031
+ response = blockchyp.tcTemplate(request)
2032
+
2033
+ puts "Response: #{response.inspect}"
2034
+
2035
+
2036
+ ```
2037
+
2038
+ #### Update Template
2039
+
2040
+
2041
+
2042
+ * **API Credential Types:** Merchant
2043
+ * **Required Role:** Terms & Conditions Management
2044
+
2045
+ This API updates or creates a terms and conditions template.
2046
+
2047
+ Terms and conditions templates are fairly simple and essentially consist of a name, content, and alias.
2048
+
2049
+ The name is the caption that will be displayed at the top of the screen. The alias is a code or short
2050
+ description that will be used in subsequence API calls to refer to the template.
2051
+
2052
+ Content is the full text of the contract or agreement. Currently, no special formatting or
2053
+ merge behavior is supported. Only plain text is supported.
2054
+
2055
+
2056
+
2057
+
2058
+ ```ruby
2059
+ # frozen_string_literal: true
2060
+
2061
+ require 'blockchyp'
2062
+
2063
+ blockchyp = BlockChyp::BlockChyp.new(
2064
+ ENV['BC_API_KEY'],
2065
+ ENV['BC_BEARER_TOKEN'],
2066
+ ENV['BC_SIGNING_KEY']
2067
+ )
2068
+
2069
+ # Set request parameters
2070
+ request = {
2071
+ alias: 'HIPPA',
2072
+ name: 'HIPPA Disclosure',
2073
+ content: 'Lorem ipsum dolor sit amet.'
2074
+ }
2075
+
2076
+ response = blockchyp.tcUpdateTemplate(request)
2077
+
2078
+ puts "Response: #{response.inspect}"
2079
+
2080
+
2081
+ ```
2082
+
2083
+ #### Delete Template
2084
+
2085
+
2086
+
2087
+ * **API Credential Types:** Merchant
2088
+ * **Required Role:** Terms & Conditions Management
2089
+
2090
+ This API deletes a terms and conditions template.
2091
+
2092
+ If a template is deleted, its alias can be reused and any previous Terms & Conditions log entry
2093
+ derived from the template being deleted is fully preserved since log entries always include
2094
+ a complete independent copy of the agreement text.
2095
+
2096
+
2097
+
2098
+
2099
+ ```ruby
2100
+ # frozen_string_literal: true
2101
+
2102
+ require 'blockchyp'
2103
+
2104
+ blockchyp = BlockChyp::BlockChyp.new(
2105
+ ENV['BC_API_KEY'],
2106
+ ENV['BC_BEARER_TOKEN'],
2107
+ ENV['BC_SIGNING_KEY']
2108
+ )
2109
+
2110
+ # Set request parameters
2111
+ request = {
2112
+ templateId: '<TEMPLATE ID>'
2113
+ }
2114
+
2115
+ response = blockchyp.tcDeleteTemplate(request)
2116
+
2117
+ puts "Response: #{response.inspect}"
2118
+
2119
+
2120
+ ```
2121
+
2122
+ #### Terms & Conditions Log
2123
+
2124
+
2125
+
2126
+ * **API Credential Types:** Merchant
2127
+ * **Required Role:** Terms & Conditions Management
2128
+
2129
+ This API allows developers to search and sort through terms and conditions log entries.
2130
+
2131
+ The default API call with no parameters will return the last 250 log entries in descending order.
2132
+
2133
+ Optional parameters can be used to filter and query the data set.
2134
+
2135
+ * **transactionId:** If provided, returns only those log entries associated with a specific transactions. Paging and date filters are ignored if this parameter is used.
2136
+ * **maxResults:** The max number of results to return in a single page. Defaults to 250 and 250 is the maximum value.
2137
+ * **startIndex** The 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.
2138
+ * **startDate**: An optional start date for results provided as an ISO 8601 timestamp. (e.g. 2022-05-24T13:51:38+00:00)
2139
+ * **endDate**: An optional end date for results provided as an ISO 8601 timestamp. (e.g. 2022-05-24T13:51:38+00:00)
2140
+
2141
+
2142
+
2143
+
2144
+ ```ruby
2145
+ # frozen_string_literal: true
2146
+
2147
+ require 'blockchyp'
2148
+
2149
+ blockchyp = BlockChyp::BlockChyp.new(
2150
+ ENV['BC_API_KEY'],
2151
+ ENV['BC_BEARER_TOKEN'],
2152
+ ENV['BC_SIGNING_KEY']
2153
+ )
2154
+
2155
+ # Set request parameters
2156
+ request = {
2157
+ logEntryId: '<LOG ENTRY ID>'
2158
+ }
2159
+
2160
+ response = blockchyp.tcLog(request)
2161
+
2162
+ puts "Response: #{response.inspect}"
2163
+
2164
+
2165
+ ```
2166
+
2167
+ #### Terms & Conditions Details
2168
+
2169
+
2170
+
2171
+ * **API Credential Types:** Merchant
2172
+ * **Required Role:** Terms & Conditions Management
2173
+
2174
+ This API returns details for a single terms and conditions log entry. The `logEntryId` of the record to be returned is the only required parameter.
2175
+
2176
+ The signature image is returned as Base 64 encoded binary in the image format specified by the `sigFormat` field.
2177
+ The default format is PNG.
2178
+
2179
+
2180
+
2181
+
2182
+ ```ruby
2183
+ # frozen_string_literal: true
2184
+
2185
+ require 'blockchyp'
2186
+
2187
+ blockchyp = BlockChyp::BlockChyp.new(
2188
+ ENV['BC_API_KEY'],
2189
+ ENV['BC_BEARER_TOKEN'],
2190
+ ENV['BC_SIGNING_KEY']
2191
+ )
2192
+
2193
+ # Set request parameters
2194
+ request = {
2195
+ logEntryId: '<ENTRY ID>'
2196
+ }
2197
+
2198
+ response = blockchyp.tcEntry(request)
2199
+
2200
+ puts "Response: #{response.inspect}"
2201
+
2202
+
2203
+ ```
2204
+
2205
+ ### Token Management
2206
+
2207
+
2208
+ BlockChyp supports saved payments and recurring payments through the use of tokens. Tokens can be created
2209
+ via the Enroll API or the web tokenizer. Once created, these tokens can be used for subsequent payments
2210
+ or associated with customer records as saved payment methods.
2211
+
2212
+ Tokens are limited to a single merchant by default, but can be shared across an organization for multi-location
2213
+ merchants by special arrangement with BlockChyp. Contact your BlockChyp rep to setup token sharing.
2214
+
2215
+
2216
+
2217
+ #### Enroll
2218
+
2219
+
2220
+
2221
+ * **API Credential Types:** Merchant
2222
+ * **Required Role:** Payment API Access
2223
+
2224
+ This API allows you to tokenize and enroll a payment method in the token
2225
+ vault. You can also pass in customer information and associate the
2226
+ payment method with a customer record.
2227
+
2228
+ A token is returned in the response that can be used in subsequent charge,
2229
+ preauth, and refund transactions.
2230
+
2231
+ **Gift Cards and EBT**
2232
+
2233
+ Gift Cards and EBT cards cannot be tokenized.
2234
+
2235
+ **E-Commerce Tokens**
2236
+
2237
+ The tokens returned by the enroll API and the e-commerce web tokenizer
2238
+ are the same tokens and can be used interchangeably.
2239
+
2240
+
2241
+
2242
+
2243
+ ```ruby
2244
+ # frozen_string_literal: true
2245
+
2246
+ require 'blockchyp'
2247
+
2248
+ blockchyp = BlockChyp::BlockChyp.new(
2249
+ ENV['BC_API_KEY'],
2250
+ ENV['BC_BEARER_TOKEN'],
2251
+ ENV['BC_SIGNING_KEY']
2252
+ )
2253
+
2254
+ # Set request parameters
2255
+ request = {
2256
+ test: true,
2257
+ terminalName: 'Test Terminal'
2258
+ }
2259
+
2260
+ response = blockchyp.enroll(request)
2261
+
2262
+ puts "Response: #{response.inspect}"
2263
+
2264
+
2265
+ ```
2266
+
2267
+ #### Token Metadata
2268
+
2269
+
2270
+
2271
+ * **API Credential Types:** Merchant
2272
+ * **Required Role:** Payment API Access
2273
+
2274
+ This API retrieves status and metadata information about a token,
2275
+ including any links to customer records.
2276
+
2277
+ This will also return any customer records related to the card
2278
+ behind the token. If the underlying card has been tokenized
2279
+ multiple times, all customers related to the card will be returned,
2280
+ even if those customer associations are related to other tokens.
2281
+
2282
+
2283
+
2284
+
2285
+ ```ruby
2286
+ # frozen_string_literal: true
2287
+
2288
+ require 'blockchyp'
2289
+
2290
+ blockchyp = BlockChyp::BlockChyp.new(
2291
+ ENV['BC_API_KEY'],
2292
+ ENV['BC_BEARER_TOKEN'],
2293
+ ENV['BC_SIGNING_KEY']
2294
+ )
2295
+
2296
+ # Set request parameters
2297
+ request = {
2298
+ token: '<TOKEN>'
2299
+ }
2300
+
2301
+ response = blockchyp.tokenMetadata(request)
2302
+
2303
+ puts "Response: #{response.inspect}"
2304
+
2305
+
2306
+ ```
2307
+
2308
+ #### Link Token
2309
+
2310
+
2311
+
2312
+ * **API Credential Types:** Merchant
2313
+ * **Required Role:** Payment API Access
2314
+
2315
+ This API links a payment token with a customer record. Usually this would only be needed
2316
+ to reverse a previous unlink operation.
2317
+
2318
+
2319
+
2320
+
2321
+ ```ruby
2322
+ # frozen_string_literal: true
2323
+
2324
+ require 'blockchyp'
2325
+
2326
+ blockchyp = BlockChyp::BlockChyp.new(
2327
+ ENV['BC_API_KEY'],
2328
+ ENV['BC_BEARER_TOKEN'],
2329
+ ENV['BC_SIGNING_KEY']
2330
+ )
2331
+
2332
+ # Set request parameters
2333
+ request = {
2334
+ token: '<TOKEN>',
2335
+ customerId: '<CUSTOMER ID>'
2336
+ }
2337
+
2338
+ response = blockchyp.linkToken(request)
2339
+
2340
+ puts "Response: #{response.inspect}"
2341
+
2342
+
2343
+ ```
2344
+
2345
+ #### Unlink Token
2346
+
2347
+
2348
+
2349
+ * **API Credential Types:** Merchant
2350
+ * **Required Role:** Payment API Access
2351
+
2352
+ This API removes a payment token link from a customer record.
2353
+
2354
+ This will remove links between the customer record and all tokens
2355
+ for the same underlying card.
2356
+
2357
+
2358
+
2359
+
2360
+ ```ruby
2361
+ # frozen_string_literal: true
2362
+
2363
+ require 'blockchyp'
2364
+
2365
+ blockchyp = BlockChyp::BlockChyp.new(
2366
+ ENV['BC_API_KEY'],
2367
+ ENV['BC_BEARER_TOKEN'],
2368
+ ENV['BC_SIGNING_KEY']
2369
+ )
2370
+
2371
+ # Set request parameters
2372
+ request = {
2373
+ token: '<TOKEN>',
2374
+ customerId: '<CUSTOMER ID>'
2375
+ }
2376
+
2377
+ response = blockchyp.unlinkToken(request)
2378
+
2379
+ puts "Response: #{response.inspect}"
2380
+
2381
+
2382
+ ```
2383
+
2384
+ #### Delete Token
2385
+
2386
+
2387
+
2388
+ * **API Credential Types:** Merchant
2389
+ * **Required Role:** Payment API Access
2390
+
2391
+ This API deletes a payment token from the gateway. Tokens are automatically deleted if they have not been used
2392
+ for a year.
2393
+
2394
+
2395
+
2396
+
2397
+ ```ruby
2398
+ # frozen_string_literal: true
2399
+
2400
+ require 'blockchyp'
2401
+
2402
+ blockchyp = BlockChyp::BlockChyp.new(
2403
+ ENV['BC_API_KEY'],
2404
+ ENV['BC_BEARER_TOKEN'],
2405
+ ENV['BC_SIGNING_KEY']
2406
+ )
2407
+
2408
+ # Set request parameters
2409
+ request = {
2410
+ token: '<TOKEN>'
2411
+ }
2412
+
2413
+ response = blockchyp.deleteToken(request)
2414
+
2415
+ puts "Response: #{response.inspect}"
2416
+
2417
+
2418
+ ```
2419
+
2420
+ ### Customer Endpoints
2421
+
2422
+
2423
+ These APIs allow developers to create and manage customer records in BlockChyp. Developers who wish to use
2424
+ BlockChyp for tokenized recurring payments can use tokens directly if they have their own customer management
2425
+ system. However, BlockChyp provides additional tools for managing customers and keeping track of a customer's saved
2426
+ payment tokens.
2427
+
2428
+ In addition, if customer features are used, BlockChyp can detect a payment method associated with an existing
2429
+ customer, and return customer data with payment transactions. This can be used as a passive method to detect
2430
+ repeat customers.
2431
+
2432
+
2433
+
2434
+ #### Update Customer
2435
+
2436
+
2437
+
2438
+ * **API Credential Types:** Merchant
2439
+ * **Required Role:** Payment API Access
2440
+
2441
+ This API adds or updates a customer record.
2442
+
2443
+ If you pass in customer information including `firstName`, `lastName`, `email`,
2444
+ or `sms` without any Customer ID or Customer Ref, a new record will
2445
+ be created.
2446
+
2447
+ If you pass in `customerRef` and `customerId`, the customer record will be updated
2448
+ if it exists.
2449
+
2450
+ **Customer Ref**
2451
+
2452
+ The `customerRef` field is optional, but highly recommended as this allows you
2453
+ to use your own customer identifiers instead of storing BlockChyp's Customer IDs
2454
+ in your systems.
2455
+
2456
+ **Creating Customer Records With Payment Transactions**
2457
+
2458
+ If you have customer information available at the time a payment transaction is
2459
+ executed, you can pass all the same customer information directly into a payment transaction. BlockChyp
2460
+ will create a customer record at the same time payment is captured. The advantage of this approach is
2461
+ that the customer's payment card is automatically associated with the customer record in a single step.
2462
+ If the customer uses the payment card in the future, the customer data will automatically
2463
+ be returned. You won't need to ask the customer to provide any additional information.
2464
+
2465
+
2466
+
2467
+
2468
+ ```ruby
2469
+ # frozen_string_literal: true
2470
+
2471
+ require 'blockchyp'
2472
+
2473
+ blockchyp = BlockChyp::BlockChyp.new(
2474
+ ENV['BC_API_KEY'],
2475
+ ENV['BC_BEARER_TOKEN'],
2476
+ ENV['BC_SIGNING_KEY']
2477
+ )
2478
+
2479
+ # Set request parameters
2480
+ request = {
2481
+ customer: {
2482
+ id: '<CUSTOMER ID>',
2483
+ customerRef: 'Customer reference string',
2484
+ firstName: 'FirstName',
2485
+ lastName: 'LastName',
2486
+ companyName: 'Company Name',
2487
+ emailAddress: 'notifications@blockchypteam.m8r.co',
2488
+ smsNumber: '(123) 123-1231'
2489
+ }
2490
+ }
2491
+
2492
+ response = blockchyp.updateCustomer(request)
2493
+
2494
+ puts "Response: #{response.inspect}"
2495
+
2496
+
2497
+ ```
2498
+
2499
+ #### Retrieve Customer
2500
+
2501
+
2502
+
2503
+ * **API Credential Types:** Merchant
2504
+ * **Required Role:** Payment API Access
2505
+
2506
+ With this API, you can retrieve detailed information about a customer record, including saved payment
2507
+ methods if available.
2508
+
2509
+ Customers can be looked up by `customerId` or `customerRef`.
2510
+
2511
+
2512
+
2513
+
2514
+ ```ruby
2515
+ # frozen_string_literal: true
2516
+
2517
+ require 'blockchyp'
2518
+
2519
+ blockchyp = BlockChyp::BlockChyp.new(
2520
+ ENV['BC_API_KEY'],
2521
+ ENV['BC_BEARER_TOKEN'],
2522
+ ENV['BC_SIGNING_KEY']
2523
+ )
2524
+
2525
+ # Set request parameters
2526
+ request = {
2527
+ customerId: '<CUSTOMER ID>'
2528
+ }
2529
+
2530
+ response = blockchyp.customer(request)
2531
+
2532
+ puts "Response: #{response.inspect}"
2533
+
2534
+
2535
+ ```
2536
+
2537
+ #### Search Customer
2538
+
2539
+
2540
+
2541
+ * **API Credential Types:** Merchant
2542
+ * **Required Role:** Payment API Access
2543
+
2544
+ This API searches the customer database and returns matching results.
2545
+
2546
+ Use `query` to pass in a search string and the system will return all results whose
2547
+ first or last names contain the query string.
2548
+
2549
+
2550
+
2551
+
2552
+ ```ruby
2553
+ # frozen_string_literal: true
2554
+
2555
+ require 'blockchyp'
2556
+
2557
+ blockchyp = BlockChyp::BlockChyp.new(
2558
+ ENV['BC_API_KEY'],
2559
+ ENV['BC_BEARER_TOKEN'],
2560
+ ENV['BC_SIGNING_KEY']
2561
+ )
2562
+
2563
+ # Set request parameters
2564
+ request = {
2565
+ query: '(123) 123-1234'
2566
+ }
2567
+
2568
+ response = blockchyp.customerSearch(request)
2569
+
2570
+ puts "Response: #{response.inspect}"
2571
+
2572
+
2573
+ ```
2574
+
2575
+ #### Delete Customer
2576
+
2577
+
2578
+
2579
+ * **API Credential Types:** Merchant
2580
+ * **Required Role:** Payment API Access
2581
+
2582
+ This API deletes a customer record.
2583
+
2584
+
2585
+
2586
+
2587
+ ```ruby
2588
+ # frozen_string_literal: true
2589
+
2590
+ require 'blockchyp'
2591
+
2592
+ blockchyp = BlockChyp::BlockChyp.new(
2593
+ ENV['BC_API_KEY'],
2594
+ ENV['BC_BEARER_TOKEN'],
2595
+ ENV['BC_SIGNING_KEY']
2596
+ )
2597
+
2598
+ # Set request parameters
2599
+ request = {
2600
+ customerId: '<CUSTOMER ID>'
2601
+ }
2602
+
2603
+ response = blockchyp.deleteCustomer(request)
2604
+
2605
+ puts "Response: #{response.inspect}"
2606
+
2607
+
2608
+ ```
2609
+
2610
+ ### Survey Reference
2611
+
2612
+
2613
+ These APIs are used to work with post-transaction surveys and survey data.
2614
+
2615
+ Merchants can optionally configure scaled (1-5) or yes/no questions that can be presented to consumers
2616
+ after every approved Charge and Preauth transaction. Surveys do not require any custom programming and
2617
+ merchants can simply configure them without the point-of-sale system needing any additional customization.
2618
+
2619
+ However, these APIs allow point-of-sale or third-party system developers to integrate survey question configuration
2620
+ or result visualization into their own systems.
2621
+
2622
+
2623
+
2624
+ #### List Questions
2625
+
2626
+
2627
+
2628
+ * **API Credential Types:** Merchant
2629
+ * **Required Role:** Survey Management
2630
+
2631
+ This API returns all survey questions in the order in which they would be presented on the terminal.
2632
+
2633
+ All questions are returned, whether enabled or disabled.
2634
+
2635
+
2636
+
2637
+
2638
+ ```ruby
2639
+ # frozen_string_literal: true
2640
+
2641
+ require 'blockchyp'
2642
+
2643
+ blockchyp = BlockChyp::BlockChyp.new(
2644
+ ENV['BC_API_KEY'],
2645
+ ENV['BC_BEARER_TOKEN'],
2646
+ ENV['BC_SIGNING_KEY']
2647
+ )
2648
+
2649
+ # Set request parameters
2650
+ request = {
2651
+ }
2652
+
2653
+ response = blockchyp.surveyQuestions(request)
2654
+
2655
+ puts "Response: #{response.inspect}"
2656
+
2657
+
2658
+ ```
2659
+
2660
+ #### Question Details
2661
+
2662
+
2663
+
2664
+ * **API Credential Types:** Merchant
2665
+ * **Required Role:** Survey Management
2666
+
2667
+ This API returns a single survey question with response data. `questionId` is required.
2668
+
2669
+
2670
+
2671
+
2672
+ ```ruby
2673
+ # frozen_string_literal: true
2674
+
2675
+ require 'blockchyp'
2676
+
2677
+ blockchyp = BlockChyp::BlockChyp.new(
2678
+ ENV['BC_API_KEY'],
2679
+ ENV['BC_BEARER_TOKEN'],
2680
+ ENV['BC_SIGNING_KEY']
2681
+ )
2682
+
2683
+ # Set request parameters
2684
+ request = {
2685
+ questionId: '<QUESTION ID>'
2686
+ }
2687
+
2688
+ response = blockchyp.surveyQuestion(request)
2689
+
2690
+ puts "Response: #{response.inspect}"
2691
+
2692
+
2693
+ ```
2694
+
2695
+ #### Update Question
2696
+
2697
+
2698
+
2699
+ * **API Credential Types:** Merchant
2700
+ * **Required Role:** Survey Management
2701
+
2702
+ This API updates or creates survey questions. `questionText` and `questionType` are required
2703
+ fields. The following values are valid for `questionType`.
2704
+
2705
+ * **yes_no:** Use for simple yes or no questions.
2706
+ * **scaled:** Displays the question with buttons that allow the customer to respond with values from 1 through 5.
2707
+
2708
+ Questions are disabled by default. Pass in `enabled` to enable a question.
2709
+
2710
+ The `ordinal` field is used to control the sequence of questions when multiple questions are enabled. We recommend keeping
2711
+ the number of questions minimal.
2712
+
2713
+
2714
+
2715
+
2716
+ ```ruby
2717
+ # frozen_string_literal: true
2718
+
2719
+ require 'blockchyp'
2720
+
2721
+ blockchyp = BlockChyp::BlockChyp.new(
2722
+ ENV['BC_API_KEY'],
2723
+ ENV['BC_BEARER_TOKEN'],
2724
+ ENV['BC_SIGNING_KEY']
2725
+ )
2726
+
2727
+ # Set request parameters
2728
+ request = {
2729
+ id: '<QUESTION ID>',
2730
+ ordinal: 1,
2731
+ questionText: 'Would you shop here again?',
2732
+ questionType: 'yes_no',
2733
+ enabled: true
2734
+ }
2735
+
2736
+ response = blockchyp.updateSurveyQuestion(request)
2737
+
2738
+ puts "Response: #{response.inspect}"
2739
+
2740
+
2741
+ ```
2742
+
2743
+ #### Delete Question
2744
+
2745
+
2746
+
2747
+ * **API Credential Types:** Merchant
2748
+ * **Required Role:** Survey Management
2749
+
2750
+ This API deletes a survey question. `questionId` is a required parameter.
2751
+
2752
+
2753
+
2754
+
2755
+ ```ruby
2756
+ # frozen_string_literal: true
2757
+
2758
+ require 'blockchyp'
2759
+
2760
+ blockchyp = BlockChyp::BlockChyp.new(
2761
+ ENV['BC_API_KEY'],
2762
+ ENV['BC_BEARER_TOKEN'],
2763
+ ENV['BC_SIGNING_KEY']
2764
+ )
2765
+
2766
+ # Set request parameters
2767
+ request = {
2768
+ questionId: '<QUESTION ID>'
2769
+ }
2770
+
2771
+ response = blockchyp.deleteSurveyQuestion(request)
2772
+
2773
+ puts "Response: #{response.inspect}"
2774
+
2775
+
2776
+ ```
2777
+
2778
+ #### Survey Results
2779
+
2780
+
2781
+
2782
+ * **API Credential Types:** Merchant
2783
+ * **Required Role:** Survey Management
2784
+
2785
+ This API returns survey results for a single question.
2786
+
2787
+ The results returned include the response rate, which is the percentage of transactions after which
2788
+ the consumer provided an answer.
2789
+
2790
+ The `responses` array breaks down the results by answer, providing the total number of responses,
2791
+ the answer's percentage of the total, and the average transaction amount associated with a specific
2792
+ answer.
2793
+
2794
+ By default, all results based on all responses are returned. However, developers may optionally provide
2795
+ `startDate` and `endDate` parameters to return only responses provided between certain dates.
2796
+
2797
+ `startDate` and `endDate` can be provided in MM/DD/YYYY or YYYY-MM-DD format.
2798
+
2799
+
2800
+
2801
+
2802
+ ```ruby
2803
+ # frozen_string_literal: true
2804
+
2805
+ require 'blockchyp'
2806
+
2807
+ blockchyp = BlockChyp::BlockChyp.new(
2808
+ ENV['BC_API_KEY'],
2809
+ ENV['BC_BEARER_TOKEN'],
2810
+ ENV['BC_SIGNING_KEY']
2811
+ )
2812
+
2813
+ # Set request parameters
2814
+ request = {
2815
+ questionId: '<QUESTION ID>'
2816
+ }
2817
+
2818
+ response = blockchyp.surveyResults(request)
2819
+
2820
+ puts "Response: #{response.inspect}"
2821
+
2822
+
2823
+ ```
2824
+
2825
+ ### Media and Branding Control
2826
+
2827
+
2828
+ BlockChyp has a sophisticated terminal media and branding control platform. Terminals can be configured to
2829
+ display logos, images, videos, and slide shows when a terminal is idle. Branding assets can be configured
2830
+ at the partner, organization, and merchant level with fine-grained hour-by-hour schedules, if desired.
2831
+
2832
+ Conceptually, all branding and media start with the media library. Merchants, Partners, and Organizations can
2833
+ upload images or video and build branding assets from uploaded media.
2834
+
2835
+ Slide shows can combine images from the media library into a timed loop of repeating images.
2836
+
2837
+ Branding Assets can then be used to combine media or slide shows with priority and timing rules to create what
2838
+ we call the Terminal Branding Stack.
2839
+
2840
+ We call a group of branding assets the *Terminal Branding Stack* because there are implicit rules about which
2841
+ branding assets take priority. For example, a merchant with no branding assets configured will inherit the
2842
+ branding rules from any organization to which the merchant may belong. If the merchant doesn't belong to an organization
2843
+ or the organization has no branding rules configured, then the system will defer to branding defaults established
2844
+ by the point-of-sale or software partner that owns the merchant.
2845
+
2846
+ This feature enables partners and organizations (multi-store operators and large national chains) to configure branding
2847
+ for potentially thousands of terminals from a single interface.
2848
+
2849
+ Terminal Branding can also be configured at the individual terminal level and a merchant's terminal fleet
2850
+ can be broken into groups and branding configured at the group level. Branding configured at the terminal
2851
+ level will always override branding from any higher level group.
2852
+
2853
+ The order of priority for the Terminal Branding Stack is given below.
2854
+
2855
+ * Terminal
2856
+ * Terminal Group
2857
+ * Merchant
2858
+ * Organization (Region, Chain, etc)
2859
+ * Partner
2860
+ * BlockChyp Default Logo
2861
+
2862
+
2863
+
2864
+ #### Media Library
2865
+
2866
+
2867
+
2868
+ * **API Credential Types:** Merchant, Partner, & Organization
2869
+ * **Required Role:** Media Management
2870
+
2871
+ This API returns the entire media library associated with the API Credentials (Merchant, Partner, or Organization). The media library results will include the ID used
2872
+ to reference a media asset in slide shows and branding assets along with the full file url and thumbnail.
2873
+
2874
+
2875
+
2876
+
2877
+ ```ruby
2878
+ # frozen_string_literal: true
2879
+
2880
+ require 'blockchyp'
2881
+
2882
+ blockchyp = BlockChyp::BlockChyp.new(
2883
+ ENV['BC_API_KEY'],
2884
+ ENV['BC_BEARER_TOKEN'],
2885
+ ENV['BC_SIGNING_KEY']
2886
+ )
2887
+
2888
+ # Set request parameters
2889
+ request = {
2890
+ }
2891
+
2892
+ response = blockchyp.media(request)
2893
+
2894
+ puts "Response: #{response.inspect}"
2895
+
2896
+
2897
+ ```
2898
+
2899
+ #### Upload Media
2900
+
2901
+
2902
+
2903
+ * **API Credential Types:** Merchant, Partner, & Organization
2904
+ * **Required Role:** Media Management
2905
+
2906
+ This API supports media library uploads. The operation of this API works slightly differently depending
2907
+ on the SDK platform. In all cases, the intent is to allow the file's binary to be passed into the SDK using
2908
+ the lowest level I/O primitive possible in order to support situations where developers aren't working
2909
+ with literal files. It might be (and usually is) more convenient to work with buffers, raw bytes, or streams.
2910
+
2911
+ For example, the Go implementation accepts an `io.Reader` and the Java implementation accepts a
2912
+ `java.io.InputStream`. The CLI does accept a literal File URL via the `-file` command line parameter.
2913
+
2914
+ The following file formats are accepted as valid uploads:
2915
+
2916
+ * .png
2917
+ * .jpg
2918
+ * .jpeg
2919
+ * .gif
2920
+ * .mov
2921
+ * .mpg
2922
+ * .mp4
2923
+ * .mpeg
2924
+
2925
+ The UploadMetadata object allows developers to pass additional metadata about the upload including
2926
+ `fileName`, `fileSize`, and `uploadId`.
2927
+
2928
+ None of these values are required, but providing them can unlock some additional functionality relating to
2929
+ media uploads. `fileName` will be used to record the original file name in the media library. `fileSize`
2930
+ and `uploadId` are used to support upload status tracking, which is especially useful for large video file
2931
+ uploads.
2932
+
2933
+ The `fileSize` should be the file's full size in bytes.
2934
+
2935
+ The `uploadId` value can be any random string. This is the value you'll use to check the status of an upload
2936
+ via the Upload Status API. This API will return information needed to drive progress feedback on uploads and
2937
+ return video transcoding information.
2938
+
2939
+
2940
+
2941
+
2942
+ ```ruby
2943
+ # frozen_string_literal: true
2944
+
2945
+ require 'blockchyp'
2946
+
2947
+ blockchyp = BlockChyp::BlockChyp.new(
2948
+ ENV['BC_API_KEY'],
2949
+ ENV['BC_BEARER_TOKEN'],
2950
+ ENV['BC_SIGNING_KEY']
2951
+ )
2952
+
2953
+ # Set request parameters
2954
+ request = {
2955
+ fileName: 'aviato.png',
2956
+ fileSize: 18843,
2957
+ uploadId: '<RANDOM ID>'
2958
+ }
2959
+
2960
+ file = File.open("aviato.png")
2961
+ content = file.read
2962
+ response = blockchyp.uploadMedia(request, content)
2963
+
2964
+ puts "Response: #{response.inspect}"
2965
+
2966
+
2967
+ ```
2968
+
2969
+ #### Upload Status
2970
+
2971
+
2972
+
2973
+ * **API Credential Types:** Merchant, Partner, & Organization
2974
+ * **Required Role:** Media Management
2975
+
2976
+ This API returns status and progress information about in progress or recently completed uploads.
2977
+
2978
+ Before calling this API, developers must first start a file upload with `fileSize` and `uploadId` parameters.
2979
+
2980
+ The data structure returned will include the file size, number of bytes uploaded, a narrative status
2981
+ and flags indicating whether or not the upload is complete or post upload processing is in progress.
2982
+ If the upload is completed, the ID assigned to the media asset and a link to the thumbnail image will
2983
+ also be returned.
2984
+
2985
+
2986
+
2987
+
2988
+ ```ruby
2989
+ # frozen_string_literal: true
2990
+
2991
+ require 'blockchyp'
2992
+
2993
+ blockchyp = BlockChyp::BlockChyp.new(
2994
+ ENV['BC_API_KEY'],
2995
+ ENV['BC_BEARER_TOKEN'],
2996
+ ENV['BC_SIGNING_KEY']
2997
+ )
2998
+
2999
+ # Set request parameters
3000
+ request = {
3001
+ uploadId: '<UPLOAD ID>'
3002
+ }
3003
+
3004
+ response = blockchyp.uploadStatus(request)
3005
+
3006
+ puts "Response: #{response.inspect}"
3007
+
3008
+
3009
+ ```
3010
+
3011
+ #### Get Media Asset
3012
+
3013
+
3014
+
3015
+ * **API Credential Types:** Merchant, Partner, & Organization
3016
+ * **Required Role:** Media Management
3017
+
3018
+ This API returns a detailed media asset. The data returned includes the exact same media information returned
3019
+ by the full media library endpoint, including fully qualified URLs pointing to the original media file
3020
+ and the thumbnail.
3021
+
3022
+
3023
+
3024
+
3025
+ ```ruby
3026
+ # frozen_string_literal: true
3027
+
3028
+ require 'blockchyp'
3029
+
3030
+ blockchyp = BlockChyp::BlockChyp.new(
3031
+ ENV['BC_API_KEY'],
3032
+ ENV['BC_BEARER_TOKEN'],
3033
+ ENV['BC_SIGNING_KEY']
3034
+ )
3035
+
3036
+ # Set request parameters
3037
+ request = {
3038
+ mediaId: '<MEDIA ASSET ID>'
3039
+ }
3040
+
3041
+ response = blockchyp.mediaAsset(request)
3042
+
3043
+ puts "Response: #{response.inspect}"
3044
+
3045
+
3046
+ ```
3047
+
3048
+ #### Delete Media Asset
3049
+
3050
+
3051
+
3052
+ * **API Credential Types:** Merchant, Partner, & Organization
3053
+ * **Required Role:** Media Management
3054
+
3055
+ This API deletes a media asset. Note that a media asset cannot be deleted if it is in use in a slide
3056
+ show or in the terminal branding stack.
3057
+
3058
+
3059
+
3060
+
3061
+ ```ruby
3062
+ # frozen_string_literal: true
3063
+
3064
+ require 'blockchyp'
3065
+
3066
+ blockchyp = BlockChyp::BlockChyp.new(
3067
+ ENV['BC_API_KEY'],
3068
+ ENV['BC_BEARER_TOKEN'],
3069
+ ENV['BC_SIGNING_KEY']
3070
+ )
3071
+
3072
+ # Set request parameters
3073
+ request = {
3074
+ mediaId: '<MEDIA ASSET ID>'
3075
+ }
3076
+
3077
+ response = blockchyp.deleteMediaAsset(request)
3078
+
3079
+ puts "Response: #{response.inspect}"
3080
+
3081
+
3082
+ ```
3083
+
3084
+ #### List Slide Shows
3085
+
3086
+
3087
+
3088
+ * **API Credential Types:** Merchant, Partner, & Organization
3089
+ * **Required Role:** Media Management
3090
+
3091
+ This API returns all slide shows.
3092
+
3093
+ Note that slide level data is not returned with this API. Use the Get Slide Show API to get slide level detail.
3094
+
3095
+
3096
+
3097
+
3098
+ ```ruby
3099
+ # frozen_string_literal: true
3100
+
3101
+ require 'blockchyp'
3102
+
3103
+ blockchyp = BlockChyp::BlockChyp.new(
3104
+ ENV['BC_API_KEY'],
3105
+ ENV['BC_BEARER_TOKEN'],
3106
+ ENV['BC_SIGNING_KEY']
3107
+ )
3108
+
3109
+ # Set request parameters
3110
+ request = {
3111
+ }
3112
+
3113
+ response = blockchyp.slideShows(request)
3114
+
3115
+ puts "Response: #{response.inspect}"
3116
+
3117
+
3118
+ ```
3119
+
3120
+ #### Get Slide Show
3121
+
3122
+
3123
+
3124
+ * **API Credential Types:** Merchant, Partner, & Organization
3125
+ * **Required Role:** Media Management
3126
+
3127
+ This API returns a single slide show. Slide level detail is returned with the fully qualified thumbnail URL
3128
+ for each slide.
3129
+
3130
+ `slideShowId` is the only required parameter.
3131
+
3132
+
3133
+
3134
+
3135
+ ```ruby
3136
+ # frozen_string_literal: true
3137
+
3138
+ require 'blockchyp'
3139
+
3140
+ blockchyp = BlockChyp::BlockChyp.new(
3141
+ ENV['BC_API_KEY'],
3142
+ ENV['BC_BEARER_TOKEN'],
3143
+ ENV['BC_SIGNING_KEY']
3144
+ )
3145
+
3146
+ # Set request parameters
3147
+ request = {
3148
+ slideShowId: '<SLIDE SHOW ID>'
1126
3149
  }
1127
3150
 
1128
- response = blockchyp.newTransactionDisplay(request)
3151
+ response = blockchyp.slideShow(request)
1129
3152
 
1130
3153
  puts "Response: #{response.inspect}"
1131
3154
 
1132
3155
 
1133
3156
  ```
1134
3157
 
1135
- #### Update Transaction Display
1136
-
3158
+ #### Update Slide Show
1137
3159
 
1138
3160
 
1139
- Similar to *New Transaction Display*, this variant allows developers to update
1140
- line item level data currently being displayed on the terminal.
1141
-
1142
- This is designed for situations where you want to update the terminal display as
1143
- items are scanned. This variant means you only have to send information to the
1144
- terminal that's changed, which usually means the new line item and updated totals.
1145
-
1146
- If the terminal is not in line item display mode and you invoke this endpoint,
1147
- the first invocation will behave like a *New Transaction Display* call.
1148
-
1149
- At a minimum, you should send total information as part of a display request,
1150
- including `total`, `tax`, and `subtotal`.
1151
3161
 
1152
- You can also send line item level data and each line item can have a `description`,
1153
- `qty`, `price`, and `extended` price.
3162
+ * **API Credential Types:** Merchant, Partner, & Organization
3163
+ * **Required Role:** Media Management
1154
3164
 
1155
- If you fail to send an extended price, BlockChyp will multiply the `qty` by the
1156
- `price`, but we strongly recommend you precalculate all the fields yourself
1157
- to ensure consistency. Your treatment of floating-point multiplication and rounding
1158
- may differ slightly from BlockChyp's, for example.
3165
+ This API updates or creates a slide show. `name`, `delay` and `slides` are required.
1159
3166
 
1160
- **Discounts**
3167
+ The slides property is an array of slides. The Slide data structure has ordinal and thumbnail URL fields,
3168
+ but these are not required when updating or creating a slide show. Only the `mediaId` field is required
3169
+ when updating or creating a slide show.
1161
3170
 
1162
- You have the option to show discounts on the display as individual line items
1163
- with negative values or you can associate discounts with a specific line item.
1164
- You can apply any number of discounts to an individual line item with a description
1165
- and amount.
3171
+ When using the CLI, slides can be specified by sending a comma-separated list of media ids via the `-mediaId`
3172
+ parameter.
1166
3173
 
1167
3174
 
1168
3175
 
@@ -1180,43 +3187,30 @@ blockchyp = BlockChyp::BlockChyp.new(
1180
3187
 
1181
3188
  # Set request parameters
1182
3189
  request = {
1183
- test: true,
1184
- terminalName: 'Test Terminal',
1185
- transaction: {
1186
- subtotal: '60.00',
1187
- tax: '5.00',
1188
- total: '65.00',
1189
- items: [
1190
- {
1191
- description: 'Leki Trekking Poles',
1192
- price: '35.00',
1193
- quantity: 2,
1194
- extended: '70.00',
1195
- discounts: [
1196
- {
1197
- description: 'memberDiscount',
1198
- amount: '10.00'
1199
- }
1200
- ]
1201
- }
1202
- ]
1203
- }
3190
+ name: 'Test Slide Show',
3191
+ delay: 5,
3192
+ slides: [
3193
+ {
3194
+ mediaId: '<MEDIA ID>'
3195
+ }
3196
+ ]
1204
3197
  }
1205
3198
 
1206
- response = blockchyp.updateTransactionDisplay(request)
3199
+ response = blockchyp.updateSlideShow(request)
1207
3200
 
1208
3201
  puts "Response: #{response.inspect}"
1209
3202
 
1210
3203
 
1211
3204
  ```
1212
3205
 
1213
- #### Display Message
3206
+ #### Delete Slide Show
1214
3207
 
1215
3208
 
1216
3209
 
1217
- Displays a message on the payment terminal.
3210
+ * **API Credential Types:** Merchant, Partner, & Organization
3211
+ * **Required Role:** Media Management
1218
3212
 
1219
- Just specify the target terminal and the message using the `message` parameter.
3213
+ This API deletes a slide show `slideShowId` is the only required parameter.
1220
3214
 
1221
3215
 
1222
3216
 
@@ -1234,34 +3228,33 @@ blockchyp = BlockChyp::BlockChyp.new(
1234
3228
 
1235
3229
  # Set request parameters
1236
3230
  request = {
1237
- test: true,
1238
- terminalName: 'Test Terminal',
1239
- message: 'Thank you for your business.'
3231
+ slideShowId: '<SLIDE SHOW ID>'
1240
3232
  }
1241
3233
 
1242
- response = blockchyp.message(request)
3234
+ response = blockchyp.deleteSlideShow(request)
1243
3235
 
1244
3236
  puts "Response: #{response.inspect}"
1245
3237
 
1246
3238
 
1247
3239
  ```
1248
3240
 
1249
- #### Boolean Prompt
3241
+ #### Terminal Branding
1250
3242
 
1251
3243
 
1252
3244
 
1253
- Prompts the customer to answer a yes or no question.
3245
+ * **API Credential Types:** Merchant, Partner, & Organization
3246
+ * **Required Role:** Media Management
1254
3247
 
1255
- You can specify the question or prompt with the `prompt` parameter and
1256
- the response is returned in the `response` field.
3248
+ This API returns the full branding stack for a given API scope in the order of priority.
1257
3249
 
1258
- This can be used for a number of use cases including starting a loyalty enrollment
1259
- workflow or customer facing suggestive selling prompts.
3250
+ Consumers of this API should pay special attention to the `editable` field. This field indicates whether or
3251
+ not a branding asset is read-only from the perspective of a particular API Credential scope.
1260
3252
 
1261
- **Custom Captions**
3253
+ The `thumbnail` and `previewImage` attributes can be used to support building user interfaces for
3254
+ managing the branding stack. `previewImage` differs from `thumbnail` in that the preview image is
3255
+ intended to show how an asset would actually look when displayed on the terminal.
1262
3256
 
1263
- You can optionally override the "YES" and "NO" button captions by
1264
- using the `yesCaption` and `noCaption` request parameters.
3257
+ `activeAsset` returns the asset that is currently visible on the terminal.
1265
3258
 
1266
3259
 
1267
3260
 
@@ -1279,45 +3272,86 @@ blockchyp = BlockChyp::BlockChyp.new(
1279
3272
 
1280
3273
  # Set request parameters
1281
3274
  request = {
1282
- test: true,
1283
- terminalName: 'Test Terminal',
1284
- prompt: 'Would you like to become a member?',
1285
- yesCaption: 'Yes',
1286
- noCaption: 'No'
1287
3275
  }
1288
3276
 
1289
- response = blockchyp.booleanPrompt(request)
3277
+ response = blockchyp.terminalBranding(request)
1290
3278
 
1291
3279
  puts "Response: #{response.inspect}"
1292
3280
 
1293
3281
 
1294
3282
  ```
1295
3283
 
1296
- #### Text Prompt
3284
+ #### Update Branding Asset
1297
3285
 
1298
3286
 
1299
3287
 
1300
- Prompts the customer to enter numeric or alphanumeric data.
3288
+ * **API Credential Types:** Merchant, Partner, & Organization
3289
+ * **Required Role:** Media Management
1301
3290
 
1302
- Due to PCI rules, free form prompts are not permitted when the response
1303
- could be any valid string. The reason for this is that a malicious
1304
- developer (not you, of course) could use text prompts to ask the customer to
1305
- input a card number or PIN code.
3291
+ This API updates or creates a single Branding Asset.
1306
3292
 
1307
- This means that instead of providing a prompt, you provide a `promptType` instead.
3293
+ Branding Assets represent a single element of the terminal branding stack. A Branding Asset can be a video or image,
3294
+ in which case a `mediaId` referencing an asset from the media library must be provided. A Branding Asset can also
3295
+ be a slide show, in which case `slideShowId` must be provided. Branding Assets must have a valid `mediaId` or a valid
3296
+ `slideShowId`. The optional `notes` field can be used to provide short notes and descriptions for a Branding asset.
1308
3297
 
1309
- The prompt types currently supported are listed below:
3298
+ **Visibility Flags**
1310
3299
 
1311
- * **phone**: Captures a phone number.
1312
- * **email**: Captures an email address.
1313
- * **first-name**: Captures a first name.
1314
- * **last-name**: Captures a last name.
1315
- * **customer-number**: Captures a customer number.
1316
- * **rewards-number**: Captures a rewards number.
3300
+ In order for a Branding Asset to be visible on a terminal, the `enabled` flag must be set to true and the `preview`
3301
+ must be turned off. `preview` is intended to show how a proposed Branding Asset will behave
3302
+ without pushing it to live terminals. The Publish button in the BlockChyp merchant portal effectively turns
3303
+ the `preview` setting off.
1317
3304
 
1318
- You can specify the prompt with the `promptType` parameter and
1319
- the response is returned in the `response` field.
3305
+ **Order and Sequencing**
3306
+
3307
+ The `ordinal` field is used to specify priority for a Branding Asset. Assets with a higher value for `ordinal`
3308
+ will be prioritized first.
3309
+
3310
+ **Padding Images**
3311
+
3312
+ For plain images, it's sometimes helpful to add margins to images. This is especially helpful with logos
3313
+ or any image file rendered without any white space or margins between the image content and edge of the image file.
3314
+ Set the `padded` flag to true if you'd like BlockChyp to auto apply margins when displaying an image on
3315
+ the terminal.
3316
+
3317
+ **Scheduling**
3318
+
3319
+ By default, a Branding Asset placed on top of the Branding Stack, if it's `enabled` and not in `preview`
3320
+ mode, will immediately be displayed on the terminal round the clock.
1320
3321
 
3322
+ Branding Assets can be scheduled with effective start and stop dates for seasonal campaigns. These assets can
3323
+ also be scheduled for specific times of day and specific days of the week.
3324
+
3325
+ * **startDate:** Optional date after which the Branding Asset is eligible for display. Can be provided in MM/DD/YYYY or YYYY-MM-DD format.
3326
+ * **endDate:** Optional date before which the Branding Asset is eligible for display. Can be provided in MM/DD/YYYY or YYYY-MM-DD format.
3327
+ * **startTime** Optional time of day after which the branding asset is eligible for display. Must be provided in 24 hour time: HH:MM.
3328
+ * **endTime** Optional time of day before which the branding asset is eligible for display. Must be provided in 24 hour time format: HH:MM
3329
+ * **daysOfWeek** For 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.)
3330
+
3331
+ **Read Only Fields**
3332
+
3333
+ The Branding Asset data structure has a number of read only fields that are returned when Branding Assets are
3334
+ retrieved. But these fields are ignored when you try to send them as part of an update. These are derived
3335
+ or calculated fields and are helpful for displaying branding assets in a management user interface, but
3336
+ cannot be changed via an API call.
3337
+
3338
+ These fields are:
3339
+
3340
+ * ownerId
3341
+ * merchantId
3342
+ * organizationId
3343
+ * partnerId
3344
+ * userId
3345
+ * userName
3346
+ * thumbnail
3347
+ * lastModified
3348
+ * editable
3349
+ * assetType
3350
+ * ownerType
3351
+ * ownerTypeCaption
3352
+ * previewImage
3353
+ * narrativeEffectiveDates
3354
+ * narrativeDisplayPeriod
1321
3355
 
1322
3356
 
1323
3357
 
@@ -1335,48 +3369,36 @@ blockchyp = BlockChyp::BlockChyp.new(
1335
3369
 
1336
3370
  # Set request parameters
1337
3371
  request = {
1338
- test: true,
1339
- terminalName: 'Test Terminal',
1340
-
1341
- # Type of prompt. Can be 'email', 'phone', 'customer-number', or
1342
- # 'rewards-number'.
1343
- promptType: PromptType::EMAIL
3372
+ mediaId: '<MEDIA ID>',
3373
+ padded: true,
3374
+ ordinal: 10,
3375
+ startDate: '01/06/2021',
3376
+ startTime: '14:00',
3377
+ endDate: '11/05/2024',
3378
+ endTime: '16:00',
3379
+ notes: 'Test Branding Asset',
3380
+ preview: false,
3381
+ enabled: true
1344
3382
  }
1345
3383
 
1346
- response = blockchyp.textPrompt(request)
3384
+ response = blockchyp.updateBrandingAsset(request)
1347
3385
 
1348
3386
  puts "Response: #{response.inspect}"
1349
3387
 
1350
3388
 
1351
3389
  ```
1352
3390
 
1353
- #### Update Customer
1354
-
1355
-
1356
-
1357
- Adds or updates a customer record.
3391
+ #### Delete Branding Asset
1358
3392
 
1359
- If you pass in customer information including `firstName`, `lastName`, `email`,
1360
- or `sms` without any Customer ID or Customer Ref, a new record will
1361
- be created.
1362
-
1363
- If you pass in `customerRef` and `customerId`, the customer record will be updated
1364
- if it exists.
1365
3393
 
1366
- **Customer Ref**
1367
3394
 
1368
- The `customerRef` field is optional, but highly recommended as this allows you
1369
- to use your own customer identifiers instead of storing BlockChyp's Customer IDs
1370
- in your systems.
3395
+ * **API Credential Types:** Merchant, Partner, & Organization
3396
+ * **Required Role:** Media Management
1371
3397
 
1372
- **Creating Customer Records With Payment Transactions**
3398
+ This API deletes a Branding Asset from the branding stack.
1373
3399
 
1374
- If you have customer information available at the time a payment transaction is
1375
- executed, you can pass all the same customer information directly into a payment transaction and
1376
- create a customer record at the same time payment is captured. The advantage of this approach is
1377
- that the customer's payment card is automatically associated with the customer record in a single step.
1378
- If the customer uses the payment card in the future, the customer data will automatically
1379
- be returned without needing to ask the customer to provide any additional information.
3400
+ Note that deleting a Branding Asset does not delete the underlying media from the media library or slide
3401
+ show from the slide show library.
1380
3402
 
1381
3403
 
1382
3404
 
@@ -1394,32 +3416,101 @@ blockchyp = BlockChyp::BlockChyp.new(
1394
3416
 
1395
3417
  # Set request parameters
1396
3418
  request = {
1397
- customer: {
1398
- id: 'ID of the customer to update',
1399
- customerRef: 'Customer reference string',
1400
- firstName: 'FirstName',
1401
- lastName: 'LastName',
1402
- companyName: 'Company Name',
1403
- emailAddress: 'support@blockchyp.com',
1404
- smsNumber: '(123) 123-1231'
1405
- }
3419
+ assetId: '<BRANDING ASSET ID>'
1406
3420
  }
1407
3421
 
1408
- response = blockchyp.updateCustomer(request)
3422
+ response = blockchyp.deleteBrandingAsset(request)
1409
3423
 
1410
3424
  puts "Response: #{response.inspect}"
1411
3425
 
1412
3426
 
1413
3427
  ```
1414
3428
 
1415
- #### Retrieve Customer
3429
+ ### Merchant Management
1416
3430
 
1417
3431
 
3432
+ These APIs allow partners to manage and configure their merchant portfolios.
1418
3433
 
1419
- Retrieves detailed information about a customer record, including saved payment
1420
- methods if available.
3434
+ Use of these APIs (other than the Merchant Profile API) requires partner scoped API credentials
3435
+ with special roles and permissions that may require a special arrangement with BlockChyp.
1421
3436
 
1422
- Customers can be looked up by `customerId` or `customerRef`.
3437
+ For example, Partners usually can't board merchants directly, but must board merchants using
3438
+ the standard underwriting process via offer codes and invitations.
3439
+
3440
+
3441
+
3442
+ #### Merchant Profile
3443
+
3444
+
3445
+
3446
+ * **API Credential Types:** Merchant
3447
+ * **Required Role:** Payment API Access
3448
+
3449
+ The API returns detailed metadata about the merchant's configuration, including
3450
+ basic identity information, terminal settings, store and forward settings,
3451
+ and bank account information for merchants that support split settlement.
3452
+
3453
+ Some of these fields can be updated via the Update Merchant API, but many of these
3454
+ fields are controlled by underwriting and cannot be altered outside of the
3455
+ underwriting and risk processes.
3456
+
3457
+ **Merchant Descriptive Fields**
3458
+
3459
+ The following fields are basic descriptive fields that can be used to describe and identify merchants.
3460
+
3461
+ * **companyName:** The merchant's official corporate entity name.
3462
+ * **dbaName:** The business's DBA (doing business as) name.
3463
+ * **contactName:** Name of the merchant's primary control contact.
3464
+ * **contactNumber:** Primary control contact's phone number.
3465
+ * **locationName:** Optional location name for multi-location operators.
3466
+ * **storeNumber:** Optional store number for multi-location operators.
3467
+ * **partnerRef:** Optional reference number partners can add to a merchant record. Usually the partner's own identifier for the merchant.
3468
+ * **timeZone:** Unix style local time zone for the merchant. Example: America/New_York.
3469
+ * **publicKey:** Read only field. The merchant's blockchain public key. Generated and assigned when a merchant account is first created.
3470
+ * **billingAddress:** Address for billing and written correspondence.
3471
+ * **shippingAddress:** Physical shipping address. Usually the actual street address of the business.
3472
+ * **status:** Current status of the merchant account.
3473
+ * **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.
3474
+ * **gatewayOnly:** Indicates that a merchant has been boarded in gateway only mode. Not common.
3475
+
3476
+ **Batch and Terminal Settings**
3477
+
3478
+ The following fields are used to control batch closure and high level terminal configuration.
3479
+
3480
+ * **batchCloseTime:** Time in 24 hour HH:MM format when batches will automatically close in the merchant's local time. Defaults to 3 AM.
3481
+ * **autoBatchClose:** Flag the determines whether or not batches will automatically close. Defaults to true.
3482
+ * **disableBatchEmails:** Flag that optionally turns off automatic batch closure notification emails.
3483
+ * **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.
3484
+ * **surveyTimeout:** The amount of time in seconds a survey question should be displayed on a terminal before reverting to the idle screen.
3485
+ * **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.
3486
+ * **pinBypassEnabled:** Enable pin bypass for debit transactions.
3487
+ * **cashBackEnabled:** Enables cash back for debit transactions.
3488
+ * **cashbackPresets:** An array of four default values for cashback amounts when cashback is enabled.
3489
+ * **storeAndForwardEnabled:** Enables automatic store and forward during network outages. Store and Forward does not support cash back, refunds, EBT, or gift card transactions.
3490
+ * **storeAndForwardFloorLimit:** Maximum dollar value of a store and forward transaction.
3491
+ * **ebtEnabled:** Enables EBT (SNAP) on BlockChyp terminals.
3492
+ * **tipEnabled:** Enables tips entry on the terminal.
3493
+ * **promptForTip:** If true, the terminal will always prompt for a tip, even if the API call does not request a tip prompt.
3494
+ * **tipDefaults:** An array of exactly three percentages that will be used to calculate default tip amounts.
3495
+ * **giftCardsDisabled:** Disables BlockChyp gift cards. Normally only used if the merchant is using an alternate gift card system.
3496
+ * **digitalSignaturesEnabled:** Enables electronic signature capture for mag stripe cards and EMV cards with Signature CVMs.
3497
+ * **digitalSignatureReversal:** Will cause a transaction to auto-reverse if the consumer refuses to provide a signature.
3498
+ * **manualEntryEnabled:** Enables manual card entry.
3499
+ * **manualEntryPromptZip:** Requires zip code based address verification for manual card entry.
3500
+ * **manualEntryPromptStreetNumber:** Requires street/address based verification for manual card entry.
3501
+
3502
+ **Card Brand and Transaction Settings**
3503
+
3504
+ * **freeRangeRefundsEnabled:** Enables direct refunds that do not reference a previous transaction.
3505
+ * **partialAuthEnabled:** Indicates that partial authorizations (usually for gift card support) are enabled.
3506
+ * **splitBankAccountsEnabled:** Used for law firm merchants only.
3507
+ * **contactlessEmv:** Enables contactless/tap transactions on a terminal. Defaults to true.
3508
+ * **visa:** Enables Visa transactions.
3509
+ * **masterCard:** Enables MasterCard transactions.
3510
+ * **amex:** Enables American Express transactions.
3511
+ * **discover:** Enables Discover transactions.
3512
+ * **jcb:** Enables JCB (Japan Card Bureau) transactions.
3513
+ * **unionPay:** Enables China UnionPay transactions.
1423
3514
 
1424
3515
 
1425
3516
 
@@ -1437,24 +3528,29 @@ blockchyp = BlockChyp::BlockChyp.new(
1437
3528
 
1438
3529
  # Set request parameters
1439
3530
  request = {
1440
- customerId: 'ID of the customer to retrieve'
1441
3531
  }
1442
3532
 
1443
- response = blockchyp.customer(request)
3533
+ response = blockchyp.merchantProfile(request)
1444
3534
 
1445
3535
  puts "Response: #{response.inspect}"
1446
3536
 
1447
3537
 
1448
3538
  ```
1449
3539
 
1450
- #### Search Customer
3540
+ #### Get Merchants
1451
3541
 
1452
3542
 
1453
3543
 
1454
- Searches the customer database and returns matching results.
3544
+ * **API Credential Types:** Partner & Organization
3545
+ * **Required Role:** Merchant Management
1455
3546
 
1456
- Use `query` to pass in a search string and the system will return all results whose
1457
- first or last names contain the query string.
3547
+ This is a partner or organization level API that can be used to return the merchant portfolio.
3548
+
3549
+ Live merchants are returned by default. Use the `test` flag to return only test merchants. The
3550
+ results returned include detailed settings including underwriting controlled flags.
3551
+
3552
+ A maximum of 250 merchants are returned by default. For large merchant portfolios, the `maxResults`
3553
+ and `startIndex` field can be used to reduce the page size and page through multiple pages of results.
1458
3554
 
1459
3555
 
1460
3556
 
@@ -1472,25 +3568,87 @@ blockchyp = BlockChyp::BlockChyp.new(
1472
3568
 
1473
3569
  # Set request parameters
1474
3570
  request = {
1475
- query: '(123) 123-1234'
3571
+ test: true
1476
3572
  }
1477
3573
 
1478
- response = blockchyp.customerSearch(request)
3574
+ response = blockchyp.getMerchants(request)
1479
3575
 
1480
3576
  puts "Response: #{response.inspect}"
1481
3577
 
1482
3578
 
1483
3579
  ```
1484
3580
 
1485
- #### Cash Discount
3581
+ #### Update Merchant
1486
3582
 
1487
3583
 
1488
3584
 
1489
- Calculates the surcharge, cash discount, and total amounts for cash transactions.
3585
+ * **API Credential Types:** Merchant, Partner, & Organization
3586
+ * **Required Role:** Merchant Management
1490
3587
 
1491
- If you're using BlockChyp's cash discounting features, you can use this endpoint
1492
- to make sure the numbers and receipts for true cash transactions are consistent
1493
- with transactions processed by BlockChyp.
3588
+ This API can be used to update or create merchant accounts.
3589
+
3590
+ Merchant scoped API credentials can be used to update merchant account settings.
3591
+
3592
+ Partner scoped API credentials can be used to update merchants, create new test
3593
+ merchants or board new gateway merchants.
3594
+
3595
+ **Merchant Descriptive Fields**
3596
+
3597
+ The following fields are basic descriptive fields that can be used to describe and identify merchants.
3598
+
3599
+ * **companyName:** The merchant's official corporate entity name.
3600
+ * **dbaName:** The businesses DBA (doing business as) name.
3601
+ * **contactName:** Name of the merchant's primary control contact.
3602
+ * **contactNumber:** Primary control contact's phone number.
3603
+ * **locationName:** Optional location name for multi location operators.
3604
+ * **storeNumber:** Optional store number for multi location operators.
3605
+ * **partnerRef:** Optional reference number partners can add to a merchant record. Usually the partner's own identifier for the merchant.
3606
+ * **timeZone:** Unix style local time zone for the merchant. Example: America/New_York.
3607
+ * **publicKey:** Read only field. The merchant's blockchain public key. Generated and assigned when a merchant account is first created.
3608
+ * **billingAddress:** Address for billing and written correspondence.
3609
+ * **shippingAddress:** Physical shipping address. Usually the actual street address of the business.
3610
+ * **status:** Current status of the merchant account.
3611
+ * **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.
3612
+ * **gatewayOnly:** Indicates that a merchant has been boarded in gateway only mode. Not common.
3613
+
3614
+ **Batch and Terminal Settings**
3615
+
3616
+ The following fields are used to control batch closure and high level terminal configuration.
3617
+
3618
+ * **batchCloseTime:** Time in 24 hour HH:MM format when batches will automatically close in the merchant's local time. Defaults to 3 AM.
3619
+ * **autoBatchClose:** Flag the determines whether or not batches will automatically close. Defaults to true.
3620
+ * **disableBatchEmails:** Flag that optionally turns off automatic batch closure notification emails.
3621
+ * **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.
3622
+ * **surveyTimeout:** The amount of time in seconds a survey question should be displayed on a terminal before reverting to the idle screen.
3623
+ * **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.
3624
+ * **pinBypassEnabled:** Enable pin bypass for debit transactions.
3625
+ * **cashBackEnabled:** Enables cash back for debit transactions.
3626
+ * **cashbackPresets:** An array of four default values for cashback amounts when cashback is enabled.
3627
+ * **storeAndForwardEnabled:** Enables automatic store and forward during network outages. Store and Forward does not support cash back, refunds, EBT, or gift card transactions.
3628
+ * **storeAndForwardFloorLimit:** Maximum dollar value of a store and forward transaction.
3629
+ * **ebtEnabled:** Enables EBT (SNAP) on BlockChyp terminals.
3630
+ * **tipEnabled:** Enables tips entry on the terminal.
3631
+ * **promptForTip:** If true, the terminal will always prompt for a tip, even if the API call does not request a tip prompt.
3632
+ * **tipDefaults:** An array of exactly three percentages that will be used to calculate default tip amounts.
3633
+ * **giftCardsDisabled:** Disables BlockChyp gift cards. Normally only used if the merchant is using an alternate gift card system.
3634
+ * **digitalSignaturesEnabled:** Enables electronic signature capture for mag stripe cards and EMV cards with Signature CVMs.
3635
+ * **digitalSignatureReversal:** Will cause a transaction to auto-reverse if the consumer refuses to provide a signature.
3636
+ * **manualEntryEnabled:** Enables manual card entry.
3637
+ * **manualEntryPromptZip:** Requires zip code based address verification for manual card entry.
3638
+ * **manualEntryPromptStreetNumber:** Requires street/address based verification for manual card entry.
3639
+
3640
+ **Card Brand and Transaction Settings**
3641
+
3642
+ * **freeRangeRefundsEnabled:** Enables direct refunds that do not reference a previous transaction.
3643
+ * **partialAuthEnabled:** Indicates that partial authorizations (usually for gift card support) are enabled.
3644
+ * **splitBankAccountsEnabled:** Used for law firm merchants only.
3645
+ * **contactlessEmv:** Enables contactless/tap transactions on a terminal. Defaults to true.
3646
+ * **visa:** Enables Visa transactions.
3647
+ * **masterCard:** Enables MasterCard transactions.
3648
+ * **amex:** Enables American Express transactions.
3649
+ * **discover:** Enables Discover transactions.
3650
+ * **jcb:** Enables JCB (Japan Card Bureau) transactions.
3651
+ * **unionPay:** Enables China UnionPay transactions.
1494
3652
 
1495
3653
 
1496
3654
 
@@ -1508,43 +3666,33 @@ blockchyp = BlockChyp::BlockChyp.new(
1508
3666
 
1509
3667
  # Set request parameters
1510
3668
  request = {
1511
- amount: '100.00',
1512
- cashDiscount: true,
1513
- surcharge: true
3669
+ merchantId: '<MERCHANT ID>',
3670
+ test: true,
3671
+ dbaName: 'Test Merchant',
3672
+ companyName: 'Test Merchant',
3673
+ billingAddress: {
3674
+ address1: '1060 West Addison',
3675
+ city: 'Chicago',
3676
+ stateOrProvince: 'IL',
3677
+ postalCode: '60613'
3678
+ }
1514
3679
  }
1515
3680
 
1516
- response = blockchyp.cashDiscount(request)
3681
+ response = blockchyp.updateMerchant(request)
1517
3682
 
1518
3683
  puts "Response: #{response.inspect}"
1519
3684
 
1520
3685
 
1521
3686
  ```
1522
3687
 
1523
- #### Batch History
1524
-
1525
-
1526
-
1527
- This endpoint allows developers to query the gateway for the merchant's batch history.
1528
- The data will be returned in descending order of open date with the most recent
1529
- batch returned first. The results will include basic information about the batch.
1530
- For more detail about a specific batch, consider using the Batch Details API.
1531
-
1532
- **Limiting Results**
3688
+ #### Merchant Users
1533
3689
 
1534
- This API will return a maximum of 250 results. Use the `maxResults` property to
1535
- limit maximum results even further and use the `startIndex` property to
1536
- page through results that span multiple queries.
1537
3690
 
1538
- For example, if you want the ten most recent batches, just pass in a value of
1539
- `10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
1540
- get the first batch in the dataset.
1541
3691
 
1542
- **Filtering By Date Range**
3692
+ * **API Credential Types:** Partner & Organization
3693
+ * **Required Role:** Merchant Management
1543
3694
 
1544
- You can also filter results by date. Use the `startDate` and `endDate`
1545
- properties to return only those batches opened between those dates.
1546
- You can use either `startDate` and `endDate` and you can use date filters
1547
- in conjunction with `maxResults` and `startIndex`
3695
+ This API returns all users and pending invites associated with a merchant account including any assigned role codes.
1548
3696
 
1549
3697
 
1550
3698
 
@@ -1562,28 +3710,31 @@ blockchyp = BlockChyp::BlockChyp.new(
1562
3710
 
1563
3711
  # Set request parameters
1564
3712
  request = {
1565
- maxResults: 250,
1566
- startIndex: 1
3713
+ merchantId: '<MERCHANT ID>'
1567
3714
  }
1568
3715
 
1569
- response = blockchyp.batchHistory(request)
3716
+ response = blockchyp.merchantUsers(request)
1570
3717
 
1571
3718
  puts "Response: #{response.inspect}"
1572
3719
 
1573
3720
 
1574
3721
  ```
1575
3722
 
1576
- #### Batch Details
3723
+ #### Invite Merchant User
1577
3724
 
1578
3725
 
1579
3726
 
1580
- This endpoint allows developers to pull down details for a specific batch,
1581
- including captured volume, gift card activity, expected deposit, and
1582
- captured volume broken down by terminal.
3727
+ * **API Credential Types:** Partner & Organization
3728
+ * **Required Role:** Merchant Management
1583
3729
 
1584
- The only required request parameter is `batchId`. Batch IDs are returned
1585
- with every transaction response and can also be discovered using the Batch
1586
- History API.
3730
+ Invites a new user to join a merchant account. `email`, `firstName`, and `lastName` are required.
3731
+
3732
+ The user will be sent an invite email with steps for creating a BlockChyp account and linking it to
3733
+ a merchant account. If the user already has a BlockChyp user account, the new user signup wil be skipped
3734
+ and the existing user account will be linked to the merchant account.
3735
+
3736
+ Developers can optionally restrict the user's access level by sending one or more role codes.
3737
+ Otherwise, the user will be given the default merchant user role. (STDMERCHANT)
1587
3738
 
1588
3739
 
1589
3740
 
@@ -1601,57 +3752,27 @@ blockchyp = BlockChyp::BlockChyp.new(
1601
3752
 
1602
3753
  # Set request parameters
1603
3754
  request = {
1604
- batchId: 'BATCHID'
3755
+ email: 'Email address for the invite'
1605
3756
  }
1606
3757
 
1607
- response = blockchyp.batchDetails(request)
3758
+ response = blockchyp.inviteMerchantUser(request)
1608
3759
 
1609
3760
  puts "Response: #{response.inspect}"
1610
3761
 
1611
3762
 
1612
3763
  ```
1613
3764
 
1614
- #### Transaction History
1615
-
1616
-
1617
-
1618
- This endpoint provides a number of different methods to sift through
1619
- transaction history.
1620
-
1621
- By default with no filtering properties, this endpoint will return the 250
1622
- most recent transactions.
1623
-
1624
- **Limiting Results**
1625
-
1626
- This API will return a maximum of 50 results in a single query. Use the `maxResults` property
1627
- to limit maximum results even further and use the `startIndex` property to
1628
- page through results that span multiple queries.
1629
-
1630
- For example, if you want the ten most recent batches, just pass in a value of
1631
- `10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
1632
- get the first transaction in the dataset.
1633
-
1634
- **Filtering By Date Range**
1635
-
1636
- You can also filter results by date. Use the `startDate` and `endDate`
1637
- properties to return only transactions run between those dates.
1638
- You can use either `startDate` or `endDate` and you can use date filters
1639
- in conjunction with `maxResults` and `startIndex`
1640
-
1641
- **Filtering By Batch**
3765
+ #### Add Test Merchant
1642
3766
 
1643
- To restrict results to a single batch, pass in the `batchId` parameter.
1644
3767
 
1645
- **Filtering By Terminal**
1646
3768
 
1647
- To restrict results to those executed on a single terminal, just
1648
- pass in the terminal name.
3769
+ * **API Credential Types:** Partner
3770
+ * **Required Role:** Merchant Management
1649
3771
 
1650
- **Combining Filters**
3772
+ This is a partner level API that can be used to create test merchant accounts. This creates
3773
+ a basic test merchant with default settings.
1651
3774
 
1652
- None of the above filters are mutually exclusive. You can combine any of the
1653
- above properties in a single request to restrict transaction results to a
1654
- narrower set of results.
3775
+ Settings can be changed by using the Update Merchant API.
1655
3776
 
1656
3777
 
1657
3778
 
@@ -1669,23 +3790,25 @@ blockchyp = BlockChyp::BlockChyp.new(
1669
3790
 
1670
3791
  # Set request parameters
1671
3792
  request = {
1672
- maxResults: 10
3793
+ dbaName: 'DBA Name',
3794
+ companyName: 'Corporate Entity Name'
1673
3795
  }
1674
3796
 
1675
- response = blockchyp.transactionHistory(request)
3797
+ response = blockchyp.addTestMerchant(request)
1676
3798
 
1677
3799
  puts "Response: #{response.inspect}"
1678
3800
 
1679
3801
 
1680
3802
  ```
1681
3803
 
1682
- #### Merchant Profile
3804
+ #### Delete Test Merchant
1683
3805
 
1684
3806
 
1685
3807
 
1686
- Returns detailed metadata about the merchant's configuraton, including
1687
- basic identity information, terminal settings, store and forward settings,
1688
- and bank account information for merchants that support split settlement.
3808
+ * **API Credential Types:** Partner
3809
+ * **Required Role:** Merchant Management
3810
+
3811
+ This partner API can be used to delete unused test merchant accounts. `merchantId` is a required parameter.
1689
3812
 
1690
3813
 
1691
3814
 
@@ -1703,15 +3826,20 @@ blockchyp = BlockChyp::BlockChyp.new(
1703
3826
 
1704
3827
  # Set request parameters
1705
3828
  request = {
3829
+ merchantId: '<MERCHANT ID>'
1706
3830
  }
1707
3831
 
1708
- response = blockchyp.merchantProfile(request)
3832
+ response = blockchyp.deleteTestMerchant(request)
1709
3833
 
1710
3834
  puts "Response: #{response.inspect}"
1711
3835
 
1712
3836
 
1713
3837
  ```
1714
3838
 
3839
+
3840
+
3841
+
3842
+
1715
3843
  ## Running Integration Tests
1716
3844
 
1717
3845
  If you'd like to run the integration tests, create a new file on your system