blockchyp 2.9.6 → 2.10.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Makefile +1 -8
- data/README.md +479 -2442
- data/lib/blockchyp/version.rb +1 -1
- data/lib/blockchyp.rb +3 -217
- data/lib/blockchyp_client.rb +0 -78
- data/test/batch_history_test.rb +6 -10
- data/test/boolean_prompt_test.rb +4 -10
- data/test/cancel_payment_link_test.rb +7 -11
- data/test/capture_signature_test.rb +4 -10
- data/test/delete_customer_test.rb +6 -10
- data/test/delete_token_test.rb +7 -16
- data/test/gateway_timeout_test.rb +3 -10
- data/test/get_customer_test.rb +6 -10
- data/test/merchant_profile_test.rb +5 -10
- data/test/new_transaction_display_test.rb +4 -10
- data/test/pan_charge_test.rb +4 -10
- data/test/pan_enroll_test.rb +5 -16
- data/test/pan_preauth_test.rb +4 -10
- data/test/partial_refund_test.rb +5 -10
- data/test/search_customer_test.rb +6 -10
- data/test/send_payment_link_test.rb +6 -11
- data/test/simple_batch_close_test.rb +6 -10
- data/test/simple_capture_test.rb +6 -10
- data/test/simple_gift_activate_test.rb +4 -10
- data/test/simple_message_test.rb +4 -10
- data/test/simple_ping_test.rb +5 -11
- data/test/simple_refund_test.rb +5 -10
- data/test/simple_reversal_test.rb +6 -10
- data/test/simple_void_test.rb +6 -10
- data/test/terminal_charge_test.rb +5 -11
- data/test/terminal_clear_test.rb +4 -10
- data/test/terminal_ebt_balance_test.rb +4 -10
- data/test/terminal_ebt_charge_test.rb +4 -10
- data/test/terminal_enroll_test.rb +4 -10
- data/test/terminal_gift_card_balance_test.rb +4 -10
- data/test/terminal_keyed_charge_test.rb +4 -10
- data/test/terminal_manual_ebt_charge_test.rb +4 -10
- data/test/terminal_preauth_test.rb +4 -10
- data/test/terminal_status_test.rb +4 -10
- data/test/terminal_timeout_test.rb +3 -10
- data/test/terms_and_conditions_test.rb +4 -10
- data/test/test_helper.rb +2 -0
- data/test/text_prompt_test.rb +4 -10
- data/test/transaction_history_test.rb +6 -10
- data/test/update_customer_test.rb +5 -10
- data/test/update_transaction_display_test.rb +4 -10
- metadata +2 -46
- data/test/activate_terminal_test.rb +0 -45
- data/test/add_test_merchant_test.rb +0 -56
- data/test/deactivate_terminal_test.rb +0 -42
- data/test/delete_branding_asset_test.rb +0 -50
- data/test/delete_media_asset_test.rb +0 -53
- data/test/delete_queued_transaction_test.rb +0 -56
- data/test/delete_slide_show_test.rb +0 -50
- data/test/delete_survey_question_test.rb +0 -51
- data/test/delete_test_merchant_test.rb +0 -59
- data/test/empty_branding_asset_test.rb +0 -44
- data/test/empty_slide_show_test.rb +0 -45
- data/test/get_merchants_test.rb +0 -52
- data/test/invite_merchant_user_test.rb +0 -45
- data/test/link_token_test.rb +0 -56
- data/test/list_queued_transactions_test.rb +0 -55
- data/test/list_terminals_test.rb +0 -42
- data/test/media_asset_test.rb +0 -57
- data/test/media_test.rb +0 -42
- data/test/media_upload_test.rb +0 -52
- data/test/merchant_platforms_test.rb +0 -59
- data/test/merchant_users_test.rb +0 -42
- data/test/simple_locate_test.rb +0 -44
- data/test/slide_show_test.rb +0 -51
- data/test/slide_shows_test.rb +0 -49
- data/test/survey_question_test.rb +0 -48
- data/test/survey_questions_test.rb +0 -50
- data/test/survey_results_test.rb +0 -48
- data/test/tc_delete_template_test.rb +0 -51
- data/test/tc_entry_test.rb +0 -56
- data/test/tc_log_test.rb +0 -42
- data/test/tc_template_test.rb +0 -53
- data/test/tc_template_update_test.rb +0 -48
- data/test/tc_templates_test.rb +0 -42
- data/test/terminal_branding_test.rb +0 -42
- data/test/terminal_queued_transaction_test.rb +0 -51
- data/test/testdata/aviato.png +0 -0
- data/test/token_metadata_test.rb +0 -55
- data/test/unlink_token_test.rb +0 -56
- data/test/update_branding_asset_test.rb +0 -62
- data/test/update_merchant_platforms_test.rb +0 -61
- data/test/update_merchant_test.rb +0 -60
- data/test/update_slide_show_test.rb +0 -60
- data/test/update_survey_question_test.rb +0 -47
- data/test/upload_status_test.rb +0 -53
data/README.md
CHANGED
@@ -74,19 +74,48 @@ 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
|
-
|
77
|
+
#### Terminal Ping
|
78
78
|
|
79
79
|
|
80
|
-
|
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
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.
|
82
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'
|
98
|
+
|
99
|
+
blockchyp = BlockChyp::BlockChyp.new(
|
100
|
+
ENV['BC_API_KEY'],
|
101
|
+
ENV['BC_BEARER_TOKEN'],
|
102
|
+
ENV['BC_SIGNING_KEY']
|
103
|
+
)
|
104
|
+
|
105
|
+
# Set request parameters
|
106
|
+
request = {
|
107
|
+
terminalName: 'Test Terminal'
|
108
|
+
}
|
109
|
+
|
110
|
+
response = blockchyp.ping(request)
|
111
|
+
|
112
|
+
puts "Response: #{response.inspect}"
|
83
113
|
|
84
|
-
#### Charge
|
85
114
|
|
115
|
+
```
|
86
116
|
|
117
|
+
#### Charge
|
87
118
|
|
88
|
-
* **API Credential Types:** Merchant
|
89
|
-
* **Required Role:** Payment API Access
|
90
119
|
|
91
120
|
Our most popular transaction executes a standard authorization and capture.
|
92
121
|
This is the most basic of
|
@@ -106,21 +135,21 @@ property instead.
|
|
106
135
|
|
107
136
|
**Card Numbers and Mag Stripes**
|
108
137
|
|
109
|
-
You can also pass in PANs and Mag Stripes, but you probably shouldn't
|
110
|
-
put you in PCI scope and the most common vector for POS breaches is
|
111
|
-
If you use terminals for manual card entry, you'll bypass any
|
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
|
112
141
|
might be maliciously running on the point-of-sale system.
|
113
142
|
|
114
143
|
**Common Variations**
|
115
144
|
|
116
|
-
* **Gift Card Redemption**: There's no special API for gift card redemption in BlockChyp.
|
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.
|
117
146
|
* **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.
|
118
147
|
* **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.
|
119
148
|
* **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.
|
120
149
|
* **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.
|
121
150
|
* **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.
|
122
151
|
* **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.
|
123
|
-
|
152
|
+
|
124
153
|
|
125
154
|
|
126
155
|
|
@@ -152,13 +181,9 @@ puts "Response: #{response.inspect}"
|
|
152
181
|
#### Preauthorization
|
153
182
|
|
154
183
|
|
155
|
-
|
156
|
-
* **API Credential Types:** Merchant
|
157
|
-
* **Required Role:** Payment API Access
|
158
|
-
|
159
184
|
A preauthorization puts a hold on funds and must be captured later. This is used
|
160
|
-
in scenarios where the final transaction amount might change. A common
|
161
|
-
fine dining
|
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.
|
162
187
|
|
163
188
|
Another use case for preauthorization is e-commerce. Typically, an online order
|
164
189
|
is preauthorized at the time of the order and then captured when the order ships.
|
@@ -177,15 +202,11 @@ property instead.
|
|
177
202
|
|
178
203
|
**Card Numbers and Mag Stripes**
|
179
204
|
|
180
|
-
You can also pass in PANs and Mag Stripes, but you probably shouldn't
|
205
|
+
You can also pass in PANs and Mag Stripes, but you probably shouldn't. This will
|
181
206
|
put you in PCI scope and the most common vector for POS breaches is key logging.
|
182
207
|
If you use terminals for manual card entry, you'll bypass any key loggers that
|
183
208
|
might be maliciously running on the point-of-sale system.
|
184
209
|
|
185
|
-
**Cryptocurrency**
|
186
|
-
|
187
|
-
Note that preauths are not supported for cryptocurrency.
|
188
|
-
|
189
210
|
**Common Variations**
|
190
211
|
|
191
212
|
* **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.
|
@@ -224,19 +245,14 @@ puts "Response: #{response.inspect}"
|
|
224
245
|
#### Capture Preauthorization
|
225
246
|
|
226
247
|
|
227
|
-
|
228
|
-
* **API Credential Types:** Merchant
|
229
|
-
* **Required Role:** Payment API Access
|
230
|
-
|
231
248
|
This API allows you to capture a previously approved preauthorization.
|
232
249
|
|
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
|
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
|
235
251
|
exact amount of the preauth, the Transaction ID is all you need to pass in.
|
236
252
|
|
237
253
|
You can adjust the total if you need to by passing in a new `amount`. We
|
238
254
|
also recommend you pass in updated amounts for `tax` and `tip` as it can
|
239
|
-
|
255
|
+
reduce your interchange fees in some cases. (Level II Processing, for example.)
|
240
256
|
|
241
257
|
|
242
258
|
|
@@ -255,8 +271,7 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
255
271
|
# Set request parameters
|
256
272
|
request = {
|
257
273
|
test: true,
|
258
|
-
transactionId: '<
|
259
|
-
amount: '32.00'
|
274
|
+
transactionId: '<PREAUTH TRANSACTION ID>'
|
260
275
|
}
|
261
276
|
|
262
277
|
response = blockchyp.capture(request)
|
@@ -269,10 +284,6 @@ puts "Response: #{response.inspect}"
|
|
269
284
|
#### Refund
|
270
285
|
|
271
286
|
|
272
|
-
|
273
|
-
* **API Credential Types:** Merchant
|
274
|
-
* **Required Role:** Payment API Access
|
275
|
-
|
276
287
|
It's not ideal, but sometimes customers want their money back.
|
277
288
|
|
278
289
|
Our refund API allows you to confront this unpleasant reality by executing refunds in a few different scenarios.
|
@@ -283,21 +294,21 @@ returned in a BlockChyp response. To refund the full amount of the previous tra
|
|
283
294
|
**Partial Refunds**
|
284
295
|
|
285
296
|
For a partial refund, just pass in an amount along with the Transaction ID.
|
286
|
-
The only rule is that the amount
|
297
|
+
The only rule is that the amount has to be equal to or less than the original
|
287
298
|
transaction. You can execute multiple partial refunds against the same
|
288
299
|
original transaction as long as the total refunded amount doesn't exceed the original amount.
|
289
300
|
|
290
301
|
**Tokenized Refunds**
|
291
302
|
|
292
303
|
You can also use a token to execute a refund. Pass in a token instead
|
293
|
-
of the Transaction ID
|
304
|
+
of the Transaction ID along with the desired refund amount.
|
294
305
|
|
295
306
|
**Free Range Refunds**
|
296
307
|
|
297
308
|
When you execute a refund without referencing a previous transaction, we
|
298
309
|
call this a *free range refund*.
|
299
310
|
|
300
|
-
We don't recommend
|
311
|
+
We don't recommend it, but it is permitted. If you absolutely insist on
|
301
312
|
doing it, pass in a Terminal Name and an amount.
|
302
313
|
|
303
314
|
You can execute a manual or keyed refund by passing the `ManualEntry` field
|
@@ -319,11 +330,6 @@ If a refund referencing a previous transaction is executed for the full amount
|
|
319
330
|
before the original transaction's batch is closed, the refund is automatically
|
320
331
|
converted to a void. This saves the merchant a little bit of money.
|
321
332
|
|
322
|
-
**Cryptocurrency**
|
323
|
-
|
324
|
-
Note that refunds are not supported for cryptocurrency. You must refund crypto transactions
|
325
|
-
manually from your cryptocurrency wallet.
|
326
|
-
|
327
333
|
|
328
334
|
|
329
335
|
|
@@ -353,12 +359,55 @@ puts "Response: #{response.inspect}"
|
|
353
359
|
|
354
360
|
```
|
355
361
|
|
356
|
-
####
|
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
|
+
)
|
357
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
|
+
```
|
407
|
+
|
408
|
+
#### Void
|
358
409
|
|
359
410
|
|
360
|
-
* **API Credential Types:** Merchant
|
361
|
-
* **Required Role:** Payment API Access
|
362
411
|
|
363
412
|
Mistakes happen. If a transaction is made by mistake, you can void it
|
364
413
|
with this API. All that's needed is to pass in a Transaction ID and execute
|
@@ -366,11 +415,6 @@ the void before the original transaction's batch closes.
|
|
366
415
|
|
367
416
|
Voids work with EBT and gift card transactions with no additional parameters.
|
368
417
|
|
369
|
-
**Cryptocurrency**
|
370
|
-
|
371
|
-
Note that voids are not supported for cryptocurrency. You must refund crypto transactions
|
372
|
-
manually from your cryptocurrency wallet.
|
373
|
-
|
374
418
|
|
375
419
|
|
376
420
|
|
@@ -402,9 +446,6 @@ puts "Response: #{response.inspect}"
|
|
402
446
|
|
403
447
|
|
404
448
|
|
405
|
-
* **API Credential Types:** Merchant
|
406
|
-
* **Required Role:** Payment API Access
|
407
|
-
|
408
449
|
Payment transactions require a stable network to function correctly and
|
409
450
|
no network is stable all the time. Time out reversals are a great line
|
410
451
|
of defense against accidentally double charging consumers when payments
|
@@ -419,14 +460,9 @@ The only caveat is that developers must use the `transactionRef` property (`txRe
|
|
419
460
|
|
420
461
|
The reason for this requirement is that if a system never receives a definitive
|
421
462
|
response for a transaction, the system would never have received the BlockChyp
|
422
|
-
generated Transaction ID. We have to
|
463
|
+
generated Transaction ID. We have to fallback to Transaction Ref to identify
|
423
464
|
a transaction.
|
424
465
|
|
425
|
-
**Cryptocurrency**
|
426
|
-
|
427
|
-
Note that refunds are not supported for cryptocurrency. You must refund crypto transactions
|
428
|
-
manually from your cryptocurrency wallet.
|
429
|
-
|
430
466
|
|
431
467
|
|
432
468
|
|
@@ -456,18 +492,14 @@ puts "Response: #{response.inspect}"
|
|
456
492
|
#### Gift Card Activation
|
457
493
|
|
458
494
|
|
459
|
-
|
460
|
-
* **API Credential Types:** Merchant
|
461
|
-
* **Required Role:** Payment API Access
|
462
|
-
|
463
|
-
This API activates or adds value to BlockChyp gift cards.
|
495
|
+
This API can be used to activate or add value to BlockChyp gift cards.
|
464
496
|
Just pass in the terminal name and the amount to add to the card.
|
465
497
|
Once the customer swipes their card, the terminal will use keys
|
466
498
|
on the mag stripe to add value to the card.
|
467
499
|
|
468
500
|
You don't need to handle a new gift card activation or a gift card recharge any
|
469
501
|
differently. The terminal firmware will figure out what to do on its
|
470
|
-
own
|
502
|
+
own and also returns the new balance for the gift card.
|
471
503
|
|
472
504
|
This is the part of the system where BlockChyp's blockchain DNA comes
|
473
505
|
closest to the surface. The BlockChyp gift card system doesn't really
|
@@ -496,9 +528,9 @@ voiding or reversing a conventional payment transaction.
|
|
496
528
|
|
497
529
|
BlockChyp does have the ability to import gift card liability from
|
498
530
|
conventional gift card platforms. Unfortunately, BlockChyp does not
|
499
|
-
support activating cards on third party systems
|
531
|
+
support activating cards on third party systems, but you can import
|
500
532
|
your outstanding gift cards and customers can swipe them on the
|
501
|
-
terminals like BlockChyp's standard gift cards.
|
533
|
+
terminals just like BlockChyp's standard gift cards.
|
502
534
|
|
503
535
|
No special coding is required to access this feature. The gateway and
|
504
536
|
terminal firmware handle everything for you.
|
@@ -508,7 +540,7 @@ terminal firmware handle everything for you.
|
|
508
540
|
BlockChyp does not currently provide any native support for other gift card
|
509
541
|
platforms beyond importing gift card liability. We do have a white listing system
|
510
542
|
that can be used to support your own custom gift card implementations. We have a security review
|
511
|
-
process before we
|
543
|
+
process before we allow a BIN range to be white listed, so contact
|
512
544
|
support@blockchyp.com if you need to white list a BIN range.
|
513
545
|
|
514
546
|
|
@@ -543,29 +575,25 @@ puts "Response: #{response.inspect}"
|
|
543
575
|
|
544
576
|
|
545
577
|
|
546
|
-
|
547
|
-
* **Required Role:** Payment API Access
|
548
|
-
|
549
|
-
This API checks a gift or EBT card balance.
|
578
|
+
Checks a gift or EBT card balance.
|
550
579
|
|
551
580
|
**Gift Card Balance Checks**
|
552
581
|
|
553
|
-
For gift cards, pass in a terminal name and the customer will be prompted
|
582
|
+
For gift cards, just pass in a terminal name and the customer will be prompted
|
554
583
|
to swipe a card on that terminal. The remaining balance will be displayed
|
555
584
|
briefly on the terminal screen and the API response will include the gift card's public key and the remaining balance.
|
556
585
|
|
557
586
|
**EBT Balance Checks**
|
558
587
|
|
559
|
-
All EBT transactions require a PIN, so to check an EBT card balance,
|
588
|
+
All EBT transactions require a PIN, so in order to check an EBT card balance,
|
560
589
|
you need to pass in the `ebt` flag just like you would for a normal EBT
|
561
590
|
charge transaction. The customer will be prompted to swipe their card and
|
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.
|
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.
|
564
592
|
|
565
593
|
**Testing Gift Card Balance Checks**
|
566
594
|
|
567
595
|
Test gift card balance checks work no differently than live gift cards. You
|
568
|
-
must activate a test gift card first to test balance checks. Test
|
596
|
+
must activate a test gift card first in order to test balance checks. Test
|
569
597
|
gift cards are real blockchain cards that live on our parallel test blockchain.
|
570
598
|
|
571
599
|
**Testing EBT Gift Card Balance Checks**
|
@@ -604,10 +632,6 @@ puts "Response: #{response.inspect}"
|
|
604
632
|
#### Close Batch
|
605
633
|
|
606
634
|
|
607
|
-
|
608
|
-
* **API Credential Types:** Merchant
|
609
|
-
* **Required Role:** Payment API Access
|
610
|
-
|
611
635
|
This API will close the merchant's batch if it's currently open.
|
612
636
|
|
613
637
|
By default, merchant batches will close automatically at 3 AM in their
|
@@ -646,9 +670,6 @@ puts "Response: #{response.inspect}"
|
|
646
670
|
|
647
671
|
|
648
672
|
|
649
|
-
* **API Credential Types:** Merchant
|
650
|
-
* **Required Role:** Payment API Access
|
651
|
-
|
652
673
|
This API allows you to send an invoice to a customer and capture payment
|
653
674
|
via a BlockChyp hosted payment page.
|
654
675
|
|
@@ -663,26 +684,26 @@ you use the `cashier` flag.)
|
|
663
684
|
|
664
685
|
**Customer Info**
|
665
686
|
|
666
|
-
Unless you're using the `cashier` flag, you must specify a customer
|
667
|
-
creating a new customer record inline or passing in an existing Customer ID or Customer Ref.
|
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.
|
668
689
|
|
669
690
|
**Line Item Level Data**
|
670
691
|
|
671
692
|
It's not strictly required, but we strongly recommend sending line item level
|
672
|
-
detail with every request. It will make the invoice look more complete
|
693
|
+
detail with every request. It will make the invoice look a little more complete
|
673
694
|
and the data format for line item level data is the exact same format used
|
674
695
|
for terminal line item display, so the same code can be used to support both areas.
|
675
696
|
|
676
697
|
**Descriptions**
|
677
698
|
|
678
|
-
You can also provide a free form description or message
|
699
|
+
You can also provide a free form description or message that's displayed near
|
679
700
|
the bottom of the invoice. Usually this is some kind of thank you note
|
680
701
|
or instruction.
|
681
702
|
|
682
703
|
**Terms and Conditions**
|
683
704
|
|
684
705
|
You can include long form contract language with a request and capture
|
685
|
-
terms and conditions
|
706
|
+
terms and conditions acceptance at the same time payment is captured.
|
686
707
|
|
687
708
|
The interface is identical to that used for the terminal based Terms and
|
688
709
|
Conditions API in that you can pass in content directly via `tcContent` or via
|
@@ -691,14 +712,10 @@ agreement acceptance is incorporated into a send link request.
|
|
691
712
|
|
692
713
|
**Auto Send**
|
693
714
|
|
694
|
-
BlockChyp does not send the email notification automatically.
|
695
|
-
emails from going out when you may not expect
|
696
|
-
for you, just add the `autoSend` flag with
|
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.
|
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.
|
702
719
|
|
703
720
|
**Tokenization**
|
704
721
|
|
@@ -708,15 +725,13 @@ in the token vault.
|
|
708
725
|
**Cashier Facing Card Entry**
|
709
726
|
|
710
727
|
BlockChyp can be used to generate internal/cashier facing card entry pages as well. This is
|
711
|
-
designed for situations where you might need to take a phone order and don't
|
712
|
-
have
|
728
|
+
designed for situations where you might need to take a phone order and you don't
|
729
|
+
have a terminal.
|
713
730
|
|
714
|
-
If you pass in the `cashier` flag, no email will be sent and you'll be able to
|
731
|
+
If you pass in the `cashier` flag, no email will be sent and you'll be be able to
|
715
732
|
load the link in a browser or iframe for payment entry. When the `cashier` flag
|
716
733
|
is used, the `autoSend` flag will be ignored.
|
717
734
|
|
718
|
-
Note that cryptocurrency is not supported for cashier facing payment entry.
|
719
|
-
|
720
735
|
**Payment Notifications**
|
721
736
|
|
722
737
|
When a customer successfully submits payment, the merchant will receive an email
|
@@ -758,7 +773,6 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
758
773
|
|
759
774
|
# Set request parameters
|
760
775
|
request = {
|
761
|
-
transactionRef: '<TX REF>',
|
762
776
|
amount: '199.99',
|
763
777
|
description: 'Widget',
|
764
778
|
subject: 'Widget invoice',
|
@@ -780,7 +794,7 @@ request = {
|
|
780
794
|
firstName: 'FirstName',
|
781
795
|
lastName: 'LastName',
|
782
796
|
companyName: 'Company Name',
|
783
|
-
emailAddress: '
|
797
|
+
emailAddress: 'support@blockchyp.com',
|
784
798
|
smsNumber: '(123) 123-1231'
|
785
799
|
}
|
786
800
|
}
|
@@ -796,10 +810,7 @@ puts "Response: #{response.inspect}"
|
|
796
810
|
|
797
811
|
|
798
812
|
|
799
|
-
|
800
|
-
* **Required Role:** Payment API Access
|
801
|
-
|
802
|
-
This API cancels a payment link.
|
813
|
+
Cancels a payment link.
|
803
814
|
|
804
815
|
|
805
816
|
|
@@ -817,7 +828,7 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
817
828
|
|
818
829
|
# Set request parameters
|
819
830
|
request = {
|
820
|
-
linkCode: '
|
831
|
+
linkCode: 'Payment link code to cancel'
|
821
832
|
}
|
822
833
|
|
823
834
|
response = blockchyp.cancelPaymentLink(request)
|
@@ -831,10 +842,7 @@ puts "Response: #{response.inspect}"
|
|
831
842
|
|
832
843
|
|
833
844
|
|
834
|
-
|
835
|
-
* **Required Role:** Payment API Access
|
836
|
-
|
837
|
-
This API returns the current status for any transaction. You can lookup a transaction
|
845
|
+
Returns the current status for any transaction. You can lookup a transaction
|
838
846
|
by its BlockChyp assigned Transaction ID or your own Transaction Ref.
|
839
847
|
|
840
848
|
You should alway use globally unique Transaction Ref values, but in the event
|
@@ -857,7 +865,7 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
857
865
|
|
858
866
|
# Set request parameters
|
859
867
|
request = {
|
860
|
-
transactionId: '
|
868
|
+
transactionId: 'ID of transaction to retrieve'
|
861
869
|
}
|
862
870
|
|
863
871
|
response = blockchyp.transactionStatus(request)
|
@@ -867,18 +875,13 @@ puts "Response: #{response.inspect}"
|
|
867
875
|
|
868
876
|
```
|
869
877
|
|
870
|
-
####
|
871
|
-
|
878
|
+
#### Terminal Clear
|
872
879
|
|
873
880
|
|
874
|
-
* **API Credential Types:** Merchant
|
875
|
-
* **Required Role:** Payment API Access
|
876
881
|
|
877
|
-
This API
|
882
|
+
This API interrupts whatever a terminal may be doing and returns it to the
|
883
|
+
idle state.
|
878
884
|
|
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.
|
882
885
|
|
883
886
|
|
884
887
|
|
@@ -896,46 +899,31 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
896
899
|
|
897
900
|
# Set request parameters
|
898
901
|
request = {
|
899
|
-
|
900
|
-
|
901
|
-
surcharge: true
|
902
|
+
test: true,
|
903
|
+
terminalName: 'Test Terminal'
|
902
904
|
}
|
903
905
|
|
904
|
-
response = blockchyp.
|
906
|
+
response = blockchyp.clear(request)
|
905
907
|
|
906
908
|
puts "Response: #{response.inspect}"
|
907
909
|
|
908
910
|
|
909
911
|
```
|
910
912
|
|
911
|
-
####
|
912
|
-
|
913
|
-
|
914
|
-
|
915
|
-
* **API Credential Types:** Merchant
|
916
|
-
* **Required Role:** Payment API Access
|
917
|
-
|
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.
|
913
|
+
#### Terminal Status
|
922
914
|
|
923
|
-
**Limiting Results**
|
924
915
|
|
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.
|
928
916
|
|
929
|
-
|
930
|
-
|
931
|
-
get the first batch in the dataset.
|
917
|
+
Returns the current status of a payment terminal. This is typically used
|
918
|
+
as a way to determine if the terminal is busy before sending a new transaction.
|
932
919
|
|
933
|
-
|
920
|
+
If the terminal is busy, `idle` will be false and the `status` field will return
|
921
|
+
a short string indicating the transaction type currently in progress. The system
|
922
|
+
will also return the timestamp of the last status change in the `since` field.
|
934
923
|
|
935
|
-
|
936
|
-
|
937
|
-
|
938
|
-
in conjunction with `maxResults` and `startIndex`
|
924
|
+
If the system is running a payment transaction and you wisely passed in a
|
925
|
+
Transaction Ref, this API will also return the Transaction Ref of the in progress
|
926
|
+
transaction.
|
939
927
|
|
940
928
|
|
941
929
|
|
@@ -953,31 +941,57 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
953
941
|
|
954
942
|
# Set request parameters
|
955
943
|
request = {
|
956
|
-
|
957
|
-
startIndex: 0
|
944
|
+
terminalName: 'Test Terminal'
|
958
945
|
}
|
959
946
|
|
960
|
-
response = blockchyp.
|
947
|
+
response = blockchyp.terminalStatus(request)
|
961
948
|
|
962
949
|
puts "Response: #{response.inspect}"
|
963
950
|
|
964
951
|
|
965
952
|
```
|
966
953
|
|
967
|
-
####
|
954
|
+
#### Terms & Conditions Capture
|
968
955
|
|
969
956
|
|
970
957
|
|
971
|
-
|
972
|
-
|
958
|
+
This API allows you to prompt a customer to accept a legal agreement on the terminal
|
959
|
+
and (usually) capture their signature.
|
973
960
|
|
974
|
-
|
975
|
-
|
976
|
-
|
961
|
+
Content for the agreement can be specified in two ways. You can reference a
|
962
|
+
previously configured T&C template or pass in the full agreement text with every request.
|
963
|
+
|
964
|
+
**Using Templates**
|
965
|
+
|
966
|
+
If your application doesn't keep track of agreements you can leverage BlockChyp's
|
967
|
+
template system. You can create any number of T&C Templates in the merchant dashboard
|
968
|
+
and pass in the `tcAlias` flag to specify which one to display.
|
969
|
+
|
970
|
+
**Raw Content**
|
971
|
+
|
972
|
+
If your system keeps track of the agreement language or executes complicated merging
|
973
|
+
and rendering logic, you can bypass our template system and pass in the full text with
|
974
|
+
every transaction. Use the `tcName` to pass in the agreement name and `tcContent` to
|
975
|
+
pass in the contract text. Note that only plain text is supported.
|
976
|
+
|
977
|
+
**Bypassing Signatures**
|
978
|
+
|
979
|
+
Signature images are captured by default. If for some reason this doesn't fit your
|
980
|
+
use case and you'd like to capture acceptance without actually capturing a signature image, set
|
981
|
+
the `disableSignature` flag in the request.
|
982
|
+
|
983
|
+
**Terms & Conditions Log**
|
984
|
+
|
985
|
+
Every time a user accepts an agreement on the terminal, the signature image (if captured),
|
986
|
+
will be uploaded to the gateway and added to the log along with the full text of the
|
987
|
+
agreement. This preserves the historical record in the event that standard agreements
|
988
|
+
or templates change over time.
|
989
|
+
|
990
|
+
**Associating Agreements with Transactions**
|
991
|
+
|
992
|
+
To associate a Terms & Conditions log entry with a transaction, just pass in the
|
993
|
+
Transaction ID or Transaction Ref for the associated transaction.
|
977
994
|
|
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.
|
981
995
|
|
982
996
|
|
983
997
|
|
@@ -995,143 +1009,58 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
995
1009
|
|
996
1010
|
# Set request parameters
|
997
1011
|
request = {
|
998
|
-
|
999
|
-
|
1000
|
-
|
1001
|
-
response = blockchyp.batchDetails(request)
|
1002
|
-
|
1003
|
-
puts "Response: #{response.inspect}"
|
1004
|
-
|
1005
|
-
|
1006
|
-
```
|
1007
|
-
|
1008
|
-
#### Transaction History
|
1009
|
-
|
1012
|
+
test: true,
|
1013
|
+
terminalName: 'Test Terminal',
|
1010
1014
|
|
1015
|
+
# Alias for a Terms and Conditions template configured in the BlockChyp
|
1016
|
+
# dashboard.
|
1017
|
+
tcAlias: 'hippa',
|
1011
1018
|
|
1012
|
-
|
1013
|
-
|
1019
|
+
# Name of the contract or document if not using an alias.
|
1020
|
+
tcName: 'HIPPA Disclosure',
|
1014
1021
|
|
1015
|
-
|
1016
|
-
|
1022
|
+
# Full text of the contract or disclosure if not using an alias.
|
1023
|
+
tcContent: 'Full contract text',
|
1017
1024
|
|
1018
|
-
|
1019
|
-
|
1025
|
+
# File format for the signature image.
|
1026
|
+
sigFormat: SignatureFormat::PNG,
|
1020
1027
|
|
1021
|
-
|
1028
|
+
# Width of the signature image in pixels.
|
1029
|
+
sigWidth: 200,
|
1022
1030
|
|
1023
|
-
|
1024
|
-
|
1025
|
-
|
1031
|
+
# Whether or not a signature is required. Defaults to true.
|
1032
|
+
sigRequired: true
|
1033
|
+
}
|
1026
1034
|
|
1027
|
-
|
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.
|
1035
|
+
response = blockchyp.termsAndConditions(request)
|
1030
1036
|
|
1031
|
-
|
1037
|
+
puts "Response: #{response.inspect}"
|
1032
1038
|
|
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
1039
|
|
1038
|
-
|
1040
|
+
```
|
1039
1041
|
|
1040
|
-
|
1042
|
+
#### Capture Signature
|
1041
1043
|
|
1042
|
-
**Filtering By Terminal**
|
1043
1044
|
|
1044
|
-
To restrict results to those executed on a single terminal, pass in the terminal name.
|
1045
1045
|
|
1046
|
-
|
1046
|
+
This endpoint captures a written signature from the terminal and returns the
|
1047
|
+
image.
|
1047
1048
|
|
1048
|
-
|
1049
|
-
|
1050
|
-
narrower set of results.
|
1049
|
+
Unlike the Terms & Conditions API, this endpoint performs basic signature
|
1050
|
+
capture with no agreement display or signature archival.
|
1051
1051
|
|
1052
|
-
|
1052
|
+
Under the hood, signatures are captured in a proprietary vector format and
|
1053
|
+
must be converted to a common raster format in order to be useful to most
|
1054
|
+
applications. At a minimum, you must specify an image format using the
|
1055
|
+
`sigFormat` parameter. As of this writing JPG and PNG are supported.
|
1053
1056
|
|
1054
|
-
|
1055
|
-
|
1056
|
-
|
1057
|
+
By default, images are returned in the JSON response as hex encoded binary.
|
1058
|
+
You can redirect the binary image output to a file using the `sigFile`
|
1059
|
+
parameter.
|
1057
1060
|
|
1058
|
-
|
1059
|
-
|
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.
|
1061
|
+
You can also scale the output image to your preferred width by
|
1062
|
+
passing in a `sigWidth` parameter. The image will be scaled to that
|
1063
|
+
width, preserving the aspect ratio of the original image.
|
1135
1064
|
|
1136
1065
|
|
1137
1066
|
|
@@ -1150,120 +1079,44 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1150
1079
|
# Set request parameters
|
1151
1080
|
request = {
|
1152
1081
|
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
1082
|
|
1197
|
-
|
1198
|
-
|
1199
|
-
blockchyp = BlockChyp::BlockChyp.new(
|
1200
|
-
ENV['BC_API_KEY'],
|
1201
|
-
ENV['BC_BEARER_TOKEN'],
|
1202
|
-
ENV['BC_SIGNING_KEY']
|
1203
|
-
)
|
1083
|
+
# File format for the signature image.
|
1084
|
+
sigFormat: SignatureFormat::PNG,
|
1204
1085
|
|
1205
|
-
#
|
1206
|
-
|
1207
|
-
terminalName: 'Test Terminal'
|
1086
|
+
# Width of the signature image in pixels.
|
1087
|
+
sigWidth: 200
|
1208
1088
|
}
|
1209
1089
|
|
1210
|
-
response = blockchyp.
|
1090
|
+
response = blockchyp.captureSignature(request)
|
1211
1091
|
|
1212
1092
|
puts "Response: #{response.inspect}"
|
1213
1093
|
|
1214
1094
|
|
1215
1095
|
```
|
1216
1096
|
|
1217
|
-
####
|
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}"
|
1097
|
+
#### New Transaction Display
|
1253
1098
|
|
1254
1099
|
|
1255
|
-
```
|
1256
1100
|
|
1257
|
-
|
1101
|
+
Sends totals and line item level data to the terminal.
|
1258
1102
|
|
1103
|
+
At a minimum, you should send total information as part of a display request,
|
1104
|
+
including `total`, `tax`, and `subtotal`.
|
1259
1105
|
|
1106
|
+
You can also send line item level data and each line item can have a `description`,
|
1107
|
+
`qty`, `price`, and `extended` price.
|
1260
1108
|
|
1261
|
-
|
1262
|
-
|
1109
|
+
If you fail to send an extended price, BlockChyp will multiply the `qty` by the
|
1110
|
+
`price`, but we strongly recommend you precalculate all the fields yourself
|
1111
|
+
to ensure consistency. Your treatment of floating-point multiplication and rounding
|
1112
|
+
may differ slightly from BlockChyp's, for example.
|
1263
1113
|
|
1264
|
-
|
1265
|
-
idle state.
|
1114
|
+
**Discounts**
|
1266
1115
|
|
1116
|
+
You have the option to show discounts on the display as individual line items
|
1117
|
+
with negative values or you can associate discounts with a specific line item.
|
1118
|
+
You can apply any number of discounts to an individual line item with a description
|
1119
|
+
and amount.
|
1267
1120
|
|
1268
1121
|
|
1269
1122
|
|
@@ -1282,1705 +1135,66 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1282
1135
|
# Set request parameters
|
1283
1136
|
request = {
|
1284
1137
|
test: true,
|
1285
|
-
terminalName: 'Test Terminal'
|
1286
|
-
|
1287
|
-
|
1288
|
-
|
1289
|
-
|
1290
|
-
|
1291
|
-
|
1292
|
-
|
1293
|
-
|
1294
|
-
|
1295
|
-
|
1296
|
-
|
1297
|
-
|
1298
|
-
|
1299
|
-
|
1300
|
-
|
1301
|
-
|
1302
|
-
|
1303
|
-
|
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'
|
1138
|
+
terminalName: 'Test Terminal',
|
1139
|
+
transaction: {
|
1140
|
+
subtotal: '60.00',
|
1141
|
+
tax: '5.00',
|
1142
|
+
total: '65.00',
|
1143
|
+
items: [
|
1144
|
+
{
|
1145
|
+
description: 'Leki Trekking Poles',
|
1146
|
+
price: '35.00',
|
1147
|
+
quantity: 2,
|
1148
|
+
extended: '70.00',
|
1149
|
+
discounts: [
|
1150
|
+
{
|
1151
|
+
description: 'memberDiscount',
|
1152
|
+
amount: '10.00'
|
1153
|
+
}
|
1154
|
+
]
|
1155
|
+
}
|
1156
|
+
]
|
1157
|
+
}
|
1330
1158
|
}
|
1331
1159
|
|
1332
|
-
response = blockchyp.
|
1160
|
+
response = blockchyp.newTransactionDisplay(request)
|
1333
1161
|
|
1334
1162
|
puts "Response: #{response.inspect}"
|
1335
1163
|
|
1336
1164
|
|
1337
1165
|
```
|
1338
1166
|
|
1339
|
-
####
|
1340
|
-
|
1341
|
-
|
1167
|
+
#### Update Transaction Display
|
1342
1168
|
|
1343
|
-
* **API Credential Types:** Merchant
|
1344
|
-
* **Required Role:** Payment API Access
|
1345
1169
|
|
1346
|
-
This endpoint captures a written signature from the terminal and returns the
|
1347
|
-
image.
|
1348
1170
|
|
1349
|
-
|
1350
|
-
|
1171
|
+
Similar to *New Transaction Display*, this variant allows developers to update
|
1172
|
+
line item level data currently being displayed on the terminal.
|
1351
1173
|
|
1352
|
-
|
1353
|
-
|
1354
|
-
|
1355
|
-
`sigFormat` parameter. Currently, JPG and PNG are supported.
|
1174
|
+
This is designed for situations where you want to update the terminal display as
|
1175
|
+
items are scanned. This variant means you only have to send information to the
|
1176
|
+
terminal that's changed, which usually means the new line item and updated totals.
|
1356
1177
|
|
1357
|
-
|
1358
|
-
|
1359
|
-
parameter.
|
1178
|
+
If the terminal is not in line item display mode and you invoke this endpoint,
|
1179
|
+
the first invocation will behave like a *New Transaction Display* call.
|
1360
1180
|
|
1361
|
-
|
1362
|
-
|
1363
|
-
width, preserving the aspect ratio of the original image.
|
1181
|
+
At a minimum, you should send total information as part of a display request,
|
1182
|
+
including `total`, `tax`, and `subtotal`.
|
1364
1183
|
|
1184
|
+
You can also send line item level data and each line item can have a `description`,
|
1185
|
+
`qty`, `price`, and `extended` price.
|
1365
1186
|
|
1187
|
+
If you fail to send an extended price, BlockChyp will multiply the `qty` by the
|
1188
|
+
`price`, but we strongly recommend you precalculate all the fields yourself
|
1189
|
+
to ensure consistency. Your treatment of floating-point multiplication and rounding
|
1190
|
+
may differ slightly from BlockChyp's, for example.
|
1366
1191
|
|
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**
|
1192
|
+
**Discounts**
|
1499
1193
|
|
1500
1194
|
You have the option to show discounts on the display as individual line items
|
1501
1195
|
with negative values or you can associate discounts with a specific line item.
|
1502
|
-
You can apply any number of discounts to an individual line item with a description
|
1503
|
-
and amount.
|
1504
|
-
|
1505
|
-
|
1506
|
-
|
1507
|
-
|
1508
|
-
```ruby
|
1509
|
-
# frozen_string_literal: true
|
1510
|
-
|
1511
|
-
require 'blockchyp'
|
1512
|
-
|
1513
|
-
blockchyp = BlockChyp::BlockChyp.new(
|
1514
|
-
ENV['BC_API_KEY'],
|
1515
|
-
ENV['BC_BEARER_TOKEN'],
|
1516
|
-
ENV['BC_SIGNING_KEY']
|
1517
|
-
)
|
1518
|
-
|
1519
|
-
# Set request parameters
|
1520
|
-
request = {
|
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.
|
1196
|
+
You can apply any number of discounts to an individual line item with a description
|
1197
|
+
and amount.
|
2984
1198
|
|
2985
1199
|
|
2986
1200
|
|
@@ -2998,26 +1212,43 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
2998
1212
|
|
2999
1213
|
# Set request parameters
|
3000
1214
|
request = {
|
3001
|
-
|
1215
|
+
test: true,
|
1216
|
+
terminalName: 'Test Terminal',
|
1217
|
+
transaction: {
|
1218
|
+
subtotal: '60.00',
|
1219
|
+
tax: '5.00',
|
1220
|
+
total: '65.00',
|
1221
|
+
items: [
|
1222
|
+
{
|
1223
|
+
description: 'Leki Trekking Poles',
|
1224
|
+
price: '35.00',
|
1225
|
+
quantity: 2,
|
1226
|
+
extended: '70.00',
|
1227
|
+
discounts: [
|
1228
|
+
{
|
1229
|
+
description: 'memberDiscount',
|
1230
|
+
amount: '10.00'
|
1231
|
+
}
|
1232
|
+
]
|
1233
|
+
}
|
1234
|
+
]
|
1235
|
+
}
|
3002
1236
|
}
|
3003
1237
|
|
3004
|
-
response = blockchyp.
|
1238
|
+
response = blockchyp.updateTransactionDisplay(request)
|
3005
1239
|
|
3006
1240
|
puts "Response: #{response.inspect}"
|
3007
1241
|
|
3008
1242
|
|
3009
1243
|
```
|
3010
1244
|
|
3011
|
-
####
|
1245
|
+
#### Display Message
|
3012
1246
|
|
3013
1247
|
|
3014
1248
|
|
3015
|
-
|
3016
|
-
* **Required Role:** Media Management
|
1249
|
+
Displays a message on the payment terminal.
|
3017
1250
|
|
3018
|
-
|
3019
|
-
by the full media library endpoint, including fully qualified URLs pointing to the original media file
|
3020
|
-
and the thumbnail.
|
1251
|
+
Just specify the target terminal and the message using the `message` parameter.
|
3021
1252
|
|
3022
1253
|
|
3023
1254
|
|
@@ -3035,25 +1266,34 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3035
1266
|
|
3036
1267
|
# Set request parameters
|
3037
1268
|
request = {
|
3038
|
-
|
1269
|
+
test: true,
|
1270
|
+
terminalName: 'Test Terminal',
|
1271
|
+
message: 'Thank you for your business.'
|
3039
1272
|
}
|
3040
1273
|
|
3041
|
-
response = blockchyp.
|
1274
|
+
response = blockchyp.message(request)
|
3042
1275
|
|
3043
1276
|
puts "Response: #{response.inspect}"
|
3044
1277
|
|
3045
1278
|
|
3046
1279
|
```
|
3047
1280
|
|
3048
|
-
####
|
1281
|
+
#### Boolean Prompt
|
1282
|
+
|
3049
1283
|
|
3050
1284
|
|
1285
|
+
Prompts the customer to answer a yes or no question.
|
3051
1286
|
|
3052
|
-
|
3053
|
-
|
1287
|
+
You can specify the question or prompt with the `prompt` parameter and
|
1288
|
+
the response is returned in the `response` field.
|
1289
|
+
|
1290
|
+
This can be used for a number of use cases including starting a loyalty enrollment
|
1291
|
+
workflow or customer facing suggestive selling prompts.
|
1292
|
+
|
1293
|
+
**Custom Captions**
|
3054
1294
|
|
3055
|
-
|
3056
|
-
|
1295
|
+
You can optionally override the "YES" and "NO" button captions by
|
1296
|
+
using the `yesCaption` and `noCaption` request parameters.
|
3057
1297
|
|
3058
1298
|
|
3059
1299
|
|
@@ -3071,26 +1311,45 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3071
1311
|
|
3072
1312
|
# Set request parameters
|
3073
1313
|
request = {
|
3074
|
-
|
1314
|
+
test: true,
|
1315
|
+
terminalName: 'Test Terminal',
|
1316
|
+
prompt: 'Would you like to become a member?',
|
1317
|
+
yesCaption: 'Yes',
|
1318
|
+
noCaption: 'No'
|
3075
1319
|
}
|
3076
1320
|
|
3077
|
-
response = blockchyp.
|
1321
|
+
response = blockchyp.booleanPrompt(request)
|
3078
1322
|
|
3079
1323
|
puts "Response: #{response.inspect}"
|
3080
1324
|
|
3081
1325
|
|
3082
1326
|
```
|
3083
1327
|
|
3084
|
-
####
|
1328
|
+
#### Text Prompt
|
1329
|
+
|
1330
|
+
|
1331
|
+
|
1332
|
+
Prompts the customer to enter numeric or alphanumeric data.
|
1333
|
+
|
1334
|
+
Due to PCI rules, free form prompts are not permitted when the response
|
1335
|
+
could be any valid string. The reason for this is that a malicious
|
1336
|
+
developer (not you, of course) could use text prompts to ask the customer to
|
1337
|
+
input a card number or PIN code.
|
3085
1338
|
|
1339
|
+
This means that instead of providing a prompt, you provide a `promptType` instead.
|
3086
1340
|
|
1341
|
+
The prompt types currently supported are listed below:
|
3087
1342
|
|
3088
|
-
* **
|
3089
|
-
* **
|
1343
|
+
* **phone**: Captures a phone number.
|
1344
|
+
* **email**: Captures an email address.
|
1345
|
+
* **first-name**: Captures a first name.
|
1346
|
+
* **last-name**: Captures a last name.
|
1347
|
+
* **customer-number**: Captures a customer number.
|
1348
|
+
* **rewards-number**: Captures a rewards number.
|
3090
1349
|
|
3091
|
-
|
1350
|
+
You can specify the prompt with the `promptType` parameter and
|
1351
|
+
the response is returned in the `response` field.
|
3092
1352
|
|
3093
|
-
Note that slide level data is not returned with this API. Use the Get Slide Show API to get slide level detail.
|
3094
1353
|
|
3095
1354
|
|
3096
1355
|
|
@@ -3108,26 +1367,48 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3108
1367
|
|
3109
1368
|
# Set request parameters
|
3110
1369
|
request = {
|
1370
|
+
test: true,
|
1371
|
+
terminalName: 'Test Terminal',
|
1372
|
+
|
1373
|
+
# Type of prompt. Can be 'email', 'phone', 'customer-number', or
|
1374
|
+
# 'rewards-number'.
|
1375
|
+
promptType: PromptType::EMAIL
|
3111
1376
|
}
|
3112
1377
|
|
3113
|
-
response = blockchyp.
|
1378
|
+
response = blockchyp.textPrompt(request)
|
3114
1379
|
|
3115
1380
|
puts "Response: #{response.inspect}"
|
3116
1381
|
|
3117
1382
|
|
3118
1383
|
```
|
3119
1384
|
|
3120
|
-
####
|
1385
|
+
#### Update Customer
|
1386
|
+
|
1387
|
+
|
1388
|
+
|
1389
|
+
Adds or updates a customer record.
|
1390
|
+
|
1391
|
+
If you pass in customer information including `firstName`, `lastName`, `email`,
|
1392
|
+
or `sms` without any Customer ID or Customer Ref, a new record will
|
1393
|
+
be created.
|
3121
1394
|
|
1395
|
+
If you pass in `customerRef` and `customerId`, the customer record will be updated
|
1396
|
+
if it exists.
|
3122
1397
|
|
1398
|
+
**Customer Ref**
|
3123
1399
|
|
3124
|
-
|
3125
|
-
|
1400
|
+
The `customerRef` field is optional, but highly recommended as this allows you
|
1401
|
+
to use your own customer identifiers instead of storing BlockChyp's Customer IDs
|
1402
|
+
in your systems.
|
3126
1403
|
|
3127
|
-
|
3128
|
-
for each slide.
|
1404
|
+
**Creating Customer Records With Payment Transactions**
|
3129
1405
|
|
3130
|
-
|
1406
|
+
If you have customer information available at the time a payment transaction is
|
1407
|
+
executed, you can pass all the same customer information directly into a payment transaction and
|
1408
|
+
create a customer record at the same time payment is captured. The advantage of this approach is
|
1409
|
+
that the customer's payment card is automatically associated with the customer record in a single step.
|
1410
|
+
If the customer uses the payment card in the future, the customer data will automatically
|
1411
|
+
be returned without needing to ask the customer to provide any additional information.
|
3131
1412
|
|
3132
1413
|
|
3133
1414
|
|
@@ -3145,31 +1426,32 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3145
1426
|
|
3146
1427
|
# Set request parameters
|
3147
1428
|
request = {
|
3148
|
-
|
1429
|
+
customer: {
|
1430
|
+
id: 'ID of the customer to update',
|
1431
|
+
customerRef: 'Customer reference string',
|
1432
|
+
firstName: 'FirstName',
|
1433
|
+
lastName: 'LastName',
|
1434
|
+
companyName: 'Company Name',
|
1435
|
+
emailAddress: 'support@blockchyp.com',
|
1436
|
+
smsNumber: '(123) 123-1231'
|
1437
|
+
}
|
3149
1438
|
}
|
3150
1439
|
|
3151
|
-
response = blockchyp.
|
1440
|
+
response = blockchyp.updateCustomer(request)
|
3152
1441
|
|
3153
1442
|
puts "Response: #{response.inspect}"
|
3154
1443
|
|
3155
1444
|
|
3156
1445
|
```
|
3157
1446
|
|
3158
|
-
####
|
3159
|
-
|
3160
|
-
|
1447
|
+
#### Retrieve Customer
|
3161
1448
|
|
3162
|
-
* **API Credential Types:** Merchant, Partner, & Organization
|
3163
|
-
* **Required Role:** Media Management
|
3164
1449
|
|
3165
|
-
This API updates or creates a slide show. `name`, `delay` and `slides` are required.
|
3166
1450
|
|
3167
|
-
|
3168
|
-
|
3169
|
-
when updating or creating a slide show.
|
1451
|
+
Retrieves detailed information about a customer record, including saved payment
|
1452
|
+
methods if available.
|
3170
1453
|
|
3171
|
-
|
3172
|
-
parameter.
|
1454
|
+
Customers can be looked up by `customerId` or `customerRef`.
|
3173
1455
|
|
3174
1456
|
|
3175
1457
|
|
@@ -3187,30 +1469,24 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3187
1469
|
|
3188
1470
|
# Set request parameters
|
3189
1471
|
request = {
|
3190
|
-
|
3191
|
-
delay: 5,
|
3192
|
-
slides: [
|
3193
|
-
{
|
3194
|
-
mediaId: '<MEDIA ID>'
|
3195
|
-
}
|
3196
|
-
]
|
1472
|
+
customerId: 'ID of the customer to retrieve'
|
3197
1473
|
}
|
3198
1474
|
|
3199
|
-
response = blockchyp.
|
1475
|
+
response = blockchyp.customer(request)
|
3200
1476
|
|
3201
1477
|
puts "Response: #{response.inspect}"
|
3202
1478
|
|
3203
1479
|
|
3204
1480
|
```
|
3205
1481
|
|
3206
|
-
####
|
1482
|
+
#### Search Customer
|
3207
1483
|
|
3208
1484
|
|
3209
1485
|
|
3210
|
-
|
3211
|
-
* **Required Role:** Media Management
|
1486
|
+
Searches the customer database and returns matching results.
|
3212
1487
|
|
3213
|
-
|
1488
|
+
Use `query` to pass in a search string and the system will return all results whose
|
1489
|
+
first or last names contain the query string.
|
3214
1490
|
|
3215
1491
|
|
3216
1492
|
|
@@ -3228,33 +1504,25 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3228
1504
|
|
3229
1505
|
# Set request parameters
|
3230
1506
|
request = {
|
3231
|
-
|
1507
|
+
query: '(123) 123-1234'
|
3232
1508
|
}
|
3233
1509
|
|
3234
|
-
response = blockchyp.
|
1510
|
+
response = blockchyp.customerSearch(request)
|
3235
1511
|
|
3236
1512
|
puts "Response: #{response.inspect}"
|
3237
1513
|
|
3238
1514
|
|
3239
1515
|
```
|
3240
1516
|
|
3241
|
-
####
|
3242
|
-
|
3243
|
-
|
3244
|
-
|
3245
|
-
* **API Credential Types:** Merchant, Partner, & Organization
|
3246
|
-
* **Required Role:** Media Management
|
1517
|
+
#### Cash Discount
|
3247
1518
|
|
3248
|
-
This API returns the full branding stack for a given API scope in the order of priority.
|
3249
1519
|
|
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.
|
3252
1520
|
|
3253
|
-
|
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.
|
1521
|
+
Calculates the surcharge, cash discount, and total amounts for cash transactions.
|
3256
1522
|
|
3257
|
-
|
1523
|
+
If you're using BlockChyp's cash discounting features, you can use this endpoint
|
1524
|
+
to make sure the numbers and receipts for true cash transactions are consistent
|
1525
|
+
with transactions processed by BlockChyp.
|
3258
1526
|
|
3259
1527
|
|
3260
1528
|
|
@@ -3272,86 +1540,43 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3272
1540
|
|
3273
1541
|
# Set request parameters
|
3274
1542
|
request = {
|
1543
|
+
amount: '100.00',
|
1544
|
+
cashDiscount: true,
|
1545
|
+
surcharge: true
|
3275
1546
|
}
|
3276
1547
|
|
3277
|
-
response = blockchyp.
|
1548
|
+
response = blockchyp.cashDiscount(request)
|
3278
1549
|
|
3279
1550
|
puts "Response: #{response.inspect}"
|
3280
1551
|
|
3281
1552
|
|
3282
1553
|
```
|
3283
1554
|
|
3284
|
-
####
|
3285
|
-
|
3286
|
-
|
3287
|
-
|
3288
|
-
* **API Credential Types:** Merchant, Partner, & Organization
|
3289
|
-
* **Required Role:** Media Management
|
3290
|
-
|
3291
|
-
This API updates or creates a single Branding Asset.
|
3292
|
-
|
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.
|
3297
|
-
|
3298
|
-
**Visibility Flags**
|
3299
|
-
|
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.
|
3304
|
-
|
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.
|
1555
|
+
#### Batch History
|
3316
1556
|
|
3317
|
-
**Scheduling**
|
3318
1557
|
|
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.
|
3321
1558
|
|
3322
|
-
|
3323
|
-
|
1559
|
+
This endpoint allows developers to query the gateway for the merchant's batch history.
|
1560
|
+
The data will be returned in descending order of open date with the most recent
|
1561
|
+
batch returned first. The results will include basic information about the batch.
|
1562
|
+
For more detail about a specific batch, consider using the Batch Details API.
|
3324
1563
|
|
3325
|
-
|
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.)
|
1564
|
+
**Limiting Results**
|
3330
1565
|
|
3331
|
-
|
1566
|
+
This API will return a maximum of 250 results. Use the `maxResults` property to
|
1567
|
+
limit maximum results even further and use the `startIndex` property to
|
1568
|
+
page through results that span multiple queries.
|
3332
1569
|
|
3333
|
-
|
3334
|
-
|
3335
|
-
|
3336
|
-
cannot be changed via an API call.
|
1570
|
+
For example, if you want the ten most recent batches, just pass in a value of
|
1571
|
+
`10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
|
1572
|
+
get the first batch in the dataset.
|
3337
1573
|
|
3338
|
-
|
1574
|
+
**Filtering By Date Range**
|
3339
1575
|
|
3340
|
-
|
3341
|
-
|
3342
|
-
|
3343
|
-
|
3344
|
-
* userId
|
3345
|
-
* userName
|
3346
|
-
* thumbnail
|
3347
|
-
* lastModified
|
3348
|
-
* editable
|
3349
|
-
* assetType
|
3350
|
-
* ownerType
|
3351
|
-
* ownerTypeCaption
|
3352
|
-
* previewImage
|
3353
|
-
* narrativeEffectiveDates
|
3354
|
-
* narrativeDisplayPeriod
|
1576
|
+
You can also filter results by date. Use the `startDate` and `endDate`
|
1577
|
+
properties to return only those batches opened between those dates.
|
1578
|
+
You can use either `startDate` and `endDate` and you can use date filters
|
1579
|
+
in conjunction with `maxResults` and `startIndex`
|
3355
1580
|
|
3356
1581
|
|
3357
1582
|
|
@@ -3369,36 +1594,28 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3369
1594
|
|
3370
1595
|
# Set request parameters
|
3371
1596
|
request = {
|
3372
|
-
|
3373
|
-
|
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
|
1597
|
+
maxResults: 250,
|
1598
|
+
startIndex: 1
|
3382
1599
|
}
|
3383
1600
|
|
3384
|
-
response = blockchyp.
|
1601
|
+
response = blockchyp.batchHistory(request)
|
3385
1602
|
|
3386
1603
|
puts "Response: #{response.inspect}"
|
3387
1604
|
|
3388
1605
|
|
3389
1606
|
```
|
3390
1607
|
|
3391
|
-
####
|
3392
|
-
|
1608
|
+
#### Batch Details
|
3393
1609
|
|
3394
1610
|
|
3395
|
-
* **API Credential Types:** Merchant, Partner, & Organization
|
3396
|
-
* **Required Role:** Media Management
|
3397
1611
|
|
3398
|
-
This
|
1612
|
+
This endpoint allows developers to pull down details for a specific batch,
|
1613
|
+
including captured volume, gift card activity, expected deposit, and
|
1614
|
+
captured volume broken down by terminal.
|
3399
1615
|
|
3400
|
-
|
3401
|
-
|
1616
|
+
The only required request parameter is `batchId`. Batch IDs are returned
|
1617
|
+
with every transaction response and can also be discovered using the Batch
|
1618
|
+
History API.
|
3402
1619
|
|
3403
1620
|
|
3404
1621
|
|
@@ -3416,141 +1633,57 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3416
1633
|
|
3417
1634
|
# Set request parameters
|
3418
1635
|
request = {
|
3419
|
-
|
1636
|
+
batchId: 'BATCHID'
|
3420
1637
|
}
|
3421
1638
|
|
3422
|
-
response = blockchyp.
|
1639
|
+
response = blockchyp.batchDetails(request)
|
3423
1640
|
|
3424
1641
|
puts "Response: #{response.inspect}"
|
3425
1642
|
|
3426
1643
|
|
3427
1644
|
```
|
3428
1645
|
|
3429
|
-
|
3430
|
-
|
3431
|
-
|
3432
|
-
These APIs allow partners to manage and configure their merchant portfolios.
|
3433
|
-
|
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.
|
3436
|
-
|
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.
|
3514
|
-
|
3515
|
-
|
3516
|
-
|
1646
|
+
#### Transaction History
|
3517
1647
|
|
3518
|
-
```ruby
|
3519
|
-
# frozen_string_literal: true
|
3520
1648
|
|
3521
|
-
require 'blockchyp'
|
3522
1649
|
|
3523
|
-
|
3524
|
-
|
3525
|
-
ENV['BC_BEARER_TOKEN'],
|
3526
|
-
ENV['BC_SIGNING_KEY']
|
3527
|
-
)
|
1650
|
+
This endpoint provides a number of different methods to sift through
|
1651
|
+
transaction history.
|
3528
1652
|
|
3529
|
-
|
3530
|
-
|
3531
|
-
}
|
1653
|
+
By default with no filtering properties, this endpoint will return the 250
|
1654
|
+
most recent transactions.
|
3532
1655
|
|
3533
|
-
|
1656
|
+
**Limiting Results**
|
3534
1657
|
|
3535
|
-
|
1658
|
+
This API will return a maximum of 50 results in a single query. Use the `maxResults` property
|
1659
|
+
to limit maximum results even further and use the `startIndex` property to
|
1660
|
+
page through results that span multiple queries.
|
3536
1661
|
|
1662
|
+
For example, if you want the ten most recent batches, just pass in a value of
|
1663
|
+
`10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
|
1664
|
+
get the first transaction in the dataset.
|
3537
1665
|
|
3538
|
-
|
1666
|
+
**Filtering By Date Range**
|
3539
1667
|
|
3540
|
-
|
1668
|
+
You can also filter results by date. Use the `startDate` and `endDate`
|
1669
|
+
properties to return only transactions run between those dates.
|
1670
|
+
You can use either `startDate` or `endDate` and you can use date filters
|
1671
|
+
in conjunction with `maxResults` and `startIndex`
|
3541
1672
|
|
1673
|
+
**Filtering By Batch**
|
3542
1674
|
|
1675
|
+
To restrict results to a single batch, pass in the `batchId` parameter.
|
3543
1676
|
|
3544
|
-
|
3545
|
-
* **Required Role:** Merchant Management
|
1677
|
+
**Filtering By Terminal**
|
3546
1678
|
|
3547
|
-
|
1679
|
+
To restrict results to those executed on a single terminal, just
|
1680
|
+
pass in the terminal name.
|
3548
1681
|
|
3549
|
-
|
3550
|
-
results returned include detailed settings including underwriting controlled flags.
|
1682
|
+
**Combining Filters**
|
3551
1683
|
|
3552
|
-
|
3553
|
-
|
1684
|
+
None of the above filters are mutually exclusive. You can combine any of the
|
1685
|
+
above properties in a single request to restrict transaction results to a
|
1686
|
+
narrower set of results.
|
3554
1687
|
|
3555
1688
|
|
3556
1689
|
|
@@ -3568,87 +1701,23 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3568
1701
|
|
3569
1702
|
# Set request parameters
|
3570
1703
|
request = {
|
3571
|
-
|
1704
|
+
maxResults: 10
|
3572
1705
|
}
|
3573
1706
|
|
3574
|
-
response = blockchyp.
|
1707
|
+
response = blockchyp.transactionHistory(request)
|
3575
1708
|
|
3576
1709
|
puts "Response: #{response.inspect}"
|
3577
1710
|
|
3578
1711
|
|
3579
1712
|
```
|
3580
1713
|
|
3581
|
-
####
|
3582
|
-
|
3583
|
-
|
3584
|
-
|
3585
|
-
* **API Credential Types:** Merchant, Partner, & Organization
|
3586
|
-
* **Required Role:** Merchant Management
|
3587
|
-
|
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.
|
1714
|
+
#### Merchant Profile
|
3617
1715
|
|
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
1716
|
|
3640
|
-
**Card Brand and Transaction Settings**
|
3641
1717
|
|
3642
|
-
|
3643
|
-
|
3644
|
-
|
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.
|
1718
|
+
Returns detailed metadata about the merchant's configuraton, including
|
1719
|
+
basic identity information, terminal settings, store and forward settings,
|
1720
|
+
and bank account information for merchants that support split settlement.
|
3652
1721
|
|
3653
1722
|
|
3654
1723
|
|
@@ -3666,33 +1735,22 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3666
1735
|
|
3667
1736
|
# Set request parameters
|
3668
1737
|
request = {
|
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
|
-
}
|
3679
1738
|
}
|
3680
1739
|
|
3681
|
-
response = blockchyp.
|
1740
|
+
response = blockchyp.merchantProfile(request)
|
3682
1741
|
|
3683
1742
|
puts "Response: #{response.inspect}"
|
3684
1743
|
|
3685
1744
|
|
3686
1745
|
```
|
3687
1746
|
|
3688
|
-
####
|
3689
|
-
|
1747
|
+
#### List Queued Transactions
|
3690
1748
|
|
3691
1749
|
|
3692
|
-
* **API Credential Types:** Partner & Organization
|
3693
|
-
* **Required Role:** Merchant Management
|
3694
1750
|
|
3695
|
-
|
1751
|
+
Returns a list of transaction refs of transactions queued on a terminal.
|
1752
|
+
Details about the transactions can be retrieved using the Transaction Status
|
1753
|
+
API.
|
3696
1754
|
|
3697
1755
|
|
3698
1756
|
|
@@ -3710,31 +1768,23 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3710
1768
|
|
3711
1769
|
# Set request parameters
|
3712
1770
|
request = {
|
3713
|
-
|
1771
|
+
terminalName: 'Test Terminal'
|
3714
1772
|
}
|
3715
1773
|
|
3716
|
-
response = blockchyp.
|
1774
|
+
response = blockchyp.listQueuedTransactions(request)
|
3717
1775
|
|
3718
1776
|
puts "Response: #{response.inspect}"
|
3719
1777
|
|
3720
1778
|
|
3721
1779
|
```
|
3722
1780
|
|
3723
|
-
####
|
3724
|
-
|
3725
|
-
|
3726
|
-
|
3727
|
-
* **API Credential Types:** Partner & Organization
|
3728
|
-
* **Required Role:** Merchant Management
|
1781
|
+
#### Delete Queued Transaction
|
3729
1782
|
|
3730
|
-
Invites a new user to join a merchant account. `email`, `firstName`, and `lastName` are required.
|
3731
1783
|
|
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
1784
|
|
3736
|
-
|
3737
|
-
|
1785
|
+
Deletes one or all queued transactions from a terminal. If `*` is passed as
|
1786
|
+
a transaction ref, then the entire terminal queue will be cleared. An error is
|
1787
|
+
returned if the passed transaction ref is not queued on the terminal.
|
3738
1788
|
|
3739
1789
|
|
3740
1790
|
|
@@ -3752,27 +1802,22 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3752
1802
|
|
3753
1803
|
# Set request parameters
|
3754
1804
|
request = {
|
3755
|
-
|
1805
|
+
terminalName: 'Test Terminal',
|
1806
|
+
transactionRef: '*'
|
3756
1807
|
}
|
3757
1808
|
|
3758
|
-
response = blockchyp.
|
1809
|
+
response = blockchyp.deleteQueuedTransaction(request)
|
3759
1810
|
|
3760
1811
|
puts "Response: #{response.inspect}"
|
3761
1812
|
|
3762
1813
|
|
3763
1814
|
```
|
3764
1815
|
|
3765
|
-
####
|
3766
|
-
|
3767
|
-
|
1816
|
+
#### Delete Customer
|
3768
1817
|
|
3769
|
-
* **API Credential Types:** Partner
|
3770
|
-
* **Required Role:** Merchant Management
|
3771
1818
|
|
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.
|
3774
1819
|
|
3775
|
-
|
1820
|
+
Deletes a customer record.
|
3776
1821
|
|
3777
1822
|
|
3778
1823
|
|
@@ -3790,25 +1835,21 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3790
1835
|
|
3791
1836
|
# Set request parameters
|
3792
1837
|
request = {
|
3793
|
-
|
3794
|
-
companyName: 'Corporate Entity Name'
|
1838
|
+
customerId: 'ID of the customer to delete'
|
3795
1839
|
}
|
3796
1840
|
|
3797
|
-
response = blockchyp.
|
1841
|
+
response = blockchyp.deleteCustomer(request)
|
3798
1842
|
|
3799
1843
|
puts "Response: #{response.inspect}"
|
3800
1844
|
|
3801
1845
|
|
3802
1846
|
```
|
3803
1847
|
|
3804
|
-
#### Delete
|
3805
|
-
|
1848
|
+
#### Delete Token
|
3806
1849
|
|
3807
1850
|
|
3808
|
-
* **API Credential Types:** Partner
|
3809
|
-
* **Required Role:** Merchant Management
|
3810
1851
|
|
3811
|
-
|
1852
|
+
Deletes a payment token from the gateway.
|
3812
1853
|
|
3813
1854
|
|
3814
1855
|
|
@@ -3826,20 +1867,16 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
3826
1867
|
|
3827
1868
|
# Set request parameters
|
3828
1869
|
request = {
|
3829
|
-
|
1870
|
+
token: 'Token to delete'
|
3830
1871
|
}
|
3831
1872
|
|
3832
|
-
response = blockchyp.
|
1873
|
+
response = blockchyp.deleteToken(request)
|
3833
1874
|
|
3834
1875
|
puts "Response: #{response.inspect}"
|
3835
1876
|
|
3836
1877
|
|
3837
1878
|
```
|
3838
1879
|
|
3839
|
-
|
3840
|
-
|
3841
|
-
|
3842
|
-
|
3843
1880
|
## Running Integration Tests
|
3844
1881
|
|
3845
1882
|
If you'd like to run the integration tests, create a new file on your system
|