blockchyp 2.12.1 → 2.13.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +2356 -546
- data/lib/blockchyp/version.rb +1 -1
- data/lib/blockchyp.rb +202 -8
- data/lib/blockchyp_client.rb +78 -0
- data/test/activate_terminal_test.rb +45 -0
- data/test/add_test_merchant_test.rb +56 -0
- data/test/batch_history_test.rb +10 -6
- data/test/boolean_prompt_test.rb +10 -4
- data/test/cancel_payment_link_test.rb +10 -6
- data/test/capture_signature_test.rb +10 -4
- data/test/deactivate_terminal_test.rb +42 -0
- data/test/delete_branding_asset_test.rb +50 -0
- data/test/delete_customer_test.rb +10 -6
- data/test/delete_media_asset_test.rb +53 -0
- data/test/delete_queued_transaction_test.rb +56 -0
- data/test/delete_slide_show_test.rb +50 -0
- data/test/delete_survey_question_test.rb +51 -0
- data/test/delete_test_merchant_test.rb +59 -0
- data/test/delete_token_test.rb +10 -6
- data/test/empty_branding_asset_test.rb +44 -0
- data/test/empty_slide_show_test.rb +45 -0
- data/test/gateway_timeout_test.rb +10 -3
- data/test/get_customer_test.rb +10 -6
- data/test/get_merchants_test.rb +52 -0
- data/test/invite_merchant_user_test.rb +45 -0
- data/test/link_token_test.rb +10 -6
- data/test/list_queued_transactions_test.rb +55 -0
- data/test/list_terminals_test.rb +42 -0
- data/test/media_asset_test.rb +57 -0
- data/test/media_test.rb +42 -0
- data/test/media_upload_test.rb +52 -0
- data/test/merchant_platforms_test.rb +59 -0
- data/test/merchant_profile_test.rb +10 -5
- data/test/merchant_users_test.rb +42 -0
- data/test/new_transaction_display_test.rb +10 -4
- data/test/pan_charge_test.rb +10 -4
- data/test/pan_enroll_test.rb +10 -4
- data/test/pan_preauth_test.rb +10 -4
- data/test/partial_refund_test.rb +10 -5
- data/test/search_customer_test.rb +10 -6
- data/test/send_payment_link_test.rb +10 -5
- data/test/simple_batch_close_test.rb +10 -6
- data/test/simple_capture_test.rb +10 -6
- data/test/simple_gift_activate_test.rb +10 -4
- data/test/simple_locate_test.rb +10 -5
- data/test/simple_message_test.rb +10 -4
- data/test/simple_ping_test.rb +10 -4
- data/test/simple_refund_test.rb +10 -5
- data/test/simple_reversal_test.rb +10 -6
- data/test/simple_void_test.rb +10 -6
- data/test/slide_show_test.rb +51 -0
- data/test/slide_shows_test.rb +49 -0
- data/test/survey_question_test.rb +48 -0
- data/test/survey_questions_test.rb +50 -0
- data/test/survey_results_test.rb +48 -0
- data/test/tc_delete_template_test.rb +51 -0
- data/test/tc_entry_test.rb +56 -0
- data/test/tc_log_test.rb +42 -0
- data/test/tc_template_test.rb +53 -0
- data/test/tc_template_update_test.rb +48 -0
- data/test/tc_templates_test.rb +42 -0
- data/test/terminal_branding_test.rb +42 -0
- data/test/terminal_charge_test.rb +10 -4
- data/test/terminal_clear_test.rb +10 -4
- data/test/terminal_ebt_balance_test.rb +10 -4
- data/test/terminal_ebt_charge_test.rb +10 -4
- data/test/terminal_enroll_test.rb +10 -4
- data/test/terminal_gift_card_balance_test.rb +10 -4
- data/test/terminal_keyed_charge_test.rb +10 -4
- data/test/terminal_manual_ebt_charge_test.rb +10 -4
- data/test/terminal_preauth_test.rb +10 -4
- data/test/terminal_queued_transaction_test.rb +51 -0
- data/test/terminal_status_test.rb +10 -4
- data/test/terminal_timeout_test.rb +10 -3
- data/test/terms_and_conditions_test.rb +10 -4
- data/test/test_helper.rb +0 -2
- data/test/testdata/aviato.png +0 -0
- data/test/text_prompt_test.rb +10 -4
- data/test/token_metadata_test.rb +10 -6
- data/test/transaction_history_test.rb +10 -6
- data/test/unlink_token_test.rb +10 -6
- data/test/update_branding_asset_test.rb +62 -0
- data/test/update_customer_test.rb +10 -5
- data/test/update_merchant_platforms_test.rb +61 -0
- data/test/update_merchant_test.rb +60 -0
- data/test/update_slide_show_test.rb +60 -0
- data/test/update_survey_question_test.rb +47 -0
- data/test/update_transaction_display_test.rb +10 -4
- data/test/upload_status_test.rb +53 -0
- metadata +42 -2
data/README.md
CHANGED
@@ -74,84 +74,19 @@ You can also view a number of long form demos and learn more about us on our [Yo
|
|
74
74
|
You don't want to read words. You want examples. Here's a quick rundown of the
|
75
75
|
stuff you can do with the BlockChyp Ruby SDK and a few basic examples.
|
76
76
|
|
77
|
-
|
78
|
-
|
79
|
-
|
80
|
-
This simple test transaction helps ensure you have good communication with a payment terminal and is usually the first one you'll run in development.
|
81
|
-
|
82
|
-
It tests communication with the terminal and returns a positive response if everything
|
83
|
-
is okay. It works the same way in local or cloud relay mode.
|
84
|
-
|
85
|
-
If you get a positive response, you've successfully verified all of the following:
|
86
|
-
|
87
|
-
* The terminal is online.
|
88
|
-
* There is a valid route to the terminal.
|
89
|
-
* The API Credentials are valid.
|
90
|
-
|
91
|
-
|
92
|
-
|
93
|
-
|
94
|
-
```ruby
|
95
|
-
# frozen_string_literal: true
|
96
|
-
|
97
|
-
require 'blockchyp'
|
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}"
|
113
|
-
|
114
|
-
|
115
|
-
```
|
116
|
-
|
117
|
-
#### Terminal Locate
|
118
|
-
|
119
|
-
|
120
|
-
This endpoint returns routing and location information for a terminal.
|
121
|
-
|
122
|
-
The result will indicate whether or not the terminal is in cloud relay mode and will
|
123
|
-
return the local IP address if the terminal is in local mode.
|
124
|
-
|
125
|
-
The terminal will also return the public key for the terminal.
|
126
|
-
|
77
|
+
### Payment Endpoints
|
127
78
|
|
128
79
|
|
80
|
+
These are the core payment APIs used to execute and work with payment transactions in BlockChyp.
|
129
81
|
|
130
|
-
```ruby
|
131
|
-
# frozen_string_literal: true
|
132
|
-
|
133
|
-
require 'blockchyp'
|
134
|
-
|
135
|
-
blockchyp = BlockChyp::BlockChyp.new(
|
136
|
-
ENV['BC_API_KEY'],
|
137
|
-
ENV['BC_BEARER_TOKEN'],
|
138
|
-
ENV['BC_SIGNING_KEY']
|
139
|
-
)
|
140
|
-
|
141
|
-
# Set request parameters
|
142
|
-
request = {
|
143
|
-
terminalName: 'Test Terminal'
|
144
|
-
}
|
145
|
-
|
146
|
-
response = blockchyp.locate(request)
|
147
82
|
|
148
|
-
puts "Response: #{response.inspect}"
|
149
83
|
|
84
|
+
#### Charge
|
150
85
|
|
151
|
-
```
|
152
86
|
|
153
|
-
#### Charge
|
154
87
|
|
88
|
+
* **API Credential Types:** Merchant
|
89
|
+
* **Required Role:** Payment API Access
|
155
90
|
|
156
91
|
Our most popular transaction executes a standard authorization and capture.
|
157
92
|
This is the most basic of
|
@@ -171,21 +106,21 @@ property instead.
|
|
171
106
|
|
172
107
|
**Card Numbers and Mag Stripes**
|
173
108
|
|
174
|
-
You can also pass in PANs and Mag Stripes, but you probably shouldn't
|
175
|
-
put you in PCI scope and the most common vector for POS breaches is
|
176
|
-
If you use terminals for manual card entry, you'll bypass any
|
109
|
+
You can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will
|
110
|
+
put you in PCI scope and the most common vector for POS breaches is keylogging.
|
111
|
+
If you use terminals for manual card entry, you'll bypass any keyloggers that
|
177
112
|
might be maliciously running on the point-of-sale system.
|
178
113
|
|
179
114
|
**Common Variations**
|
180
115
|
|
181
|
-
* **Gift Card Redemption**: There's no special API for gift card redemption in BlockChyp.
|
116
|
+
* **Gift Card Redemption**: There's no special API for gift card redemption in BlockChyp. Simply execute a plain charge transaction and if the customer swipes a gift card, our terminals will identify the gift card and run a gift card redemption. Also note that if for some reason the gift card's original purchase transaction is associated with fraud or a chargeback, the transaction will be rejected.
|
182
117
|
* **EBT**: Set the `CardType` field to `CardType::EBT` to process an EBT SNAP transaction. Note that test EBT transactions always assume a balance of $100.00, so test EBT transactions over that amount may be declined.
|
183
118
|
* **Cash Back**: To enable cash back for debit transactions, set the `CashBack` field. If the card presented isn't a debit card, the `CashBack` field will be ignored.
|
184
119
|
* **Manual Card Entry**: Set the `ManualEntry` field to enable manual card entry. Good as a backup when chips and MSR's don't work or for more secure phone orders. You can even combine the `ManualEntry` field with the `CardType` field set to `CardType::EBT` for manual EBT card entry.
|
185
120
|
* **Inline Tokenization**: You can enroll the payment method in the token vault inline with a charge transaction by setting the `Enroll` field. You'll get a token back in the response. You can even bind the token to a customer record if you also pass in customer data.
|
186
121
|
* **Prompting for Tips**: Set the `PromptForTip` field if you'd like to prompt the customer for a tip before authorization. Good for pay-at-the-table and other service related scenarios.
|
187
122
|
* **Cash Discounting and Surcharging**: The `Surcharge` and `CashDiscount` fields can be used together to support cash discounting or surcharge problems. Consult the Cash Discount documentation for more details.
|
188
|
-
|
123
|
+
* **Cryptocurrency** The `Cryptocurrency` field can be used to switch the standard present card screen to a cryptocurrency screen. The field value can be `ANY` to enable any supported cryptocurrency or a single currency code such as `BTC` for Bitcoin.
|
189
124
|
|
190
125
|
|
191
126
|
|
@@ -217,9 +152,13 @@ puts "Response: #{response.inspect}"
|
|
217
152
|
#### Preauthorization
|
218
153
|
|
219
154
|
|
155
|
+
|
156
|
+
* **API Credential Types:** Merchant
|
157
|
+
* **Required Role:** Payment API Access
|
158
|
+
|
220
159
|
A preauthorization puts a hold on funds and must be captured later. This is used
|
221
|
-
in scenarios where the final transaction amount might change. A common
|
222
|
-
|
160
|
+
in scenarios where the final transaction amount might change. A common example is
|
161
|
+
fine dining, where a tip adjustment is required before final settlement.
|
223
162
|
|
224
163
|
Another use case for preauthorization is e-commerce. Typically, an online order
|
225
164
|
is preauthorized at the time of the order and then captured when the order ships.
|
@@ -238,11 +177,15 @@ property instead.
|
|
238
177
|
|
239
178
|
**Card Numbers and Mag Stripes**
|
240
179
|
|
241
|
-
You can also pass in PANs and Mag Stripes, but you probably shouldn't
|
180
|
+
You can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will
|
242
181
|
put you in PCI scope and the most common vector for POS breaches is key logging.
|
243
182
|
If you use terminals for manual card entry, you'll bypass any key loggers that
|
244
183
|
might be maliciously running on the point-of-sale system.
|
245
184
|
|
185
|
+
**Cryptocurrency**
|
186
|
+
|
187
|
+
Note that preauths are not supported for cryptocurrency.
|
188
|
+
|
246
189
|
**Common Variations**
|
247
190
|
|
248
191
|
* **Manual Card Entry**: Set the `ManualEntry` field to enable manual card entry. Good as a backup when chips and MSR's don't work or for more secure phone orders. You can even combine the `ManualEntry` field with `CardType` set to `CardType::EBT` for manual EBT card entry.
|
@@ -281,14 +224,19 @@ puts "Response: #{response.inspect}"
|
|
281
224
|
#### Capture Preauthorization
|
282
225
|
|
283
226
|
|
227
|
+
|
228
|
+
* **API Credential Types:** Merchant
|
229
|
+
* **Required Role:** Payment API Access
|
230
|
+
|
284
231
|
This API allows you to capture a previously approved preauthorization.
|
285
232
|
|
286
|
-
You'll need to make sure you pass in the Transaction ID returned by the original preauth transaction
|
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
|
287
235
|
exact amount of the preauth, the Transaction ID is all you need to pass in.
|
288
236
|
|
289
237
|
You can adjust the total if you need to by passing in a new `amount`. We
|
290
238
|
also recommend you pass in updated amounts for `tax` and `tip` as it can
|
291
|
-
reduce your interchange fees
|
239
|
+
sometimes reduce your interchange fees. (Level II Processing, for example.)
|
292
240
|
|
293
241
|
|
294
242
|
|
@@ -307,7 +255,8 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
307
255
|
# Set request parameters
|
308
256
|
request = {
|
309
257
|
test: true,
|
310
|
-
transactionId: '<
|
258
|
+
transactionId: '<ORIGINAL TRANSACTION ID>',
|
259
|
+
amount: '32.00'
|
311
260
|
}
|
312
261
|
|
313
262
|
response = blockchyp.capture(request)
|
@@ -320,6 +269,10 @@ puts "Response: #{response.inspect}"
|
|
320
269
|
#### Refund
|
321
270
|
|
322
271
|
|
272
|
+
|
273
|
+
* **API Credential Types:** Merchant
|
274
|
+
* **Required Role:** Payment API Access
|
275
|
+
|
323
276
|
It's not ideal, but sometimes customers want their money back.
|
324
277
|
|
325
278
|
Our refund API allows you to confront this unpleasant reality by executing refunds in a few different scenarios.
|
@@ -330,21 +283,21 @@ returned in a BlockChyp response. To refund the full amount of the previous tra
|
|
330
283
|
**Partial Refunds**
|
331
284
|
|
332
285
|
For a partial refund, just pass in an amount along with the Transaction ID.
|
333
|
-
The only rule is that the amount
|
286
|
+
The only rule is that the amount must be equal to or less than the original
|
334
287
|
transaction. You can execute multiple partial refunds against the same
|
335
288
|
original transaction as long as the total refunded amount doesn't exceed the original amount.
|
336
289
|
|
337
290
|
**Tokenized Refunds**
|
338
291
|
|
339
292
|
You can also use a token to execute a refund. Pass in a token instead
|
340
|
-
of the Transaction ID
|
293
|
+
of the Transaction ID and the desired refund amount.
|
341
294
|
|
342
295
|
**Free Range Refunds**
|
343
296
|
|
344
297
|
When you execute a refund without referencing a previous transaction, we
|
345
298
|
call this a *free range refund*.
|
346
299
|
|
347
|
-
We don't recommend
|
300
|
+
We don't recommend this type of refund, but it is permitted. If you absolutely insist on
|
348
301
|
doing it, pass in a Terminal Name and an amount.
|
349
302
|
|
350
303
|
You can execute a manual or keyed refund by passing the `ManualEntry` field
|
@@ -366,6 +319,11 @@ If a refund referencing a previous transaction is executed for the full amount
|
|
366
319
|
before the original transaction's batch is closed, the refund is automatically
|
367
320
|
converted to a void. This saves the merchant a little bit of money.
|
368
321
|
|
322
|
+
**Cryptocurrency**
|
323
|
+
|
324
|
+
Note that refunds are not supported for cryptocurrency. You must refund crypto transactions
|
325
|
+
manually from your cryptocurrency wallet.
|
326
|
+
|
369
327
|
|
370
328
|
|
371
329
|
|
@@ -393,64 +351,26 @@ response = blockchyp.refund(request)
|
|
393
351
|
puts "Response: #{response.inspect}"
|
394
352
|
|
395
353
|
|
396
|
-
```
|
397
|
-
|
398
|
-
#### Enroll
|
399
|
-
|
400
|
-
|
401
|
-
This API allows you to tokenize and enroll a payment method in the token
|
402
|
-
vault. You can also pass in customer information and associate the
|
403
|
-
payment method with a customer record.
|
404
|
-
|
405
|
-
A token is returned in the response that can be used in subsequent charge,
|
406
|
-
preauth, and refund transactions.
|
407
|
-
|
408
|
-
**Gift Cards and EBT**
|
409
|
-
|
410
|
-
Gift Cards and EBT cards cannot be tokenized.
|
411
|
-
|
412
|
-
**E-Commerce Tokens**
|
413
|
-
|
414
|
-
The tokens returned by the enroll API and the e-commerce web tokenizer
|
415
|
-
are the same tokens and can be used interchangeably.
|
416
|
-
|
417
|
-
|
418
|
-
|
419
|
-
|
420
|
-
```ruby
|
421
|
-
# frozen_string_literal: true
|
422
|
-
|
423
|
-
require 'blockchyp'
|
424
|
-
|
425
|
-
blockchyp = BlockChyp::BlockChyp.new(
|
426
|
-
ENV['BC_API_KEY'],
|
427
|
-
ENV['BC_BEARER_TOKEN'],
|
428
|
-
ENV['BC_SIGNING_KEY']
|
429
|
-
)
|
430
|
-
|
431
|
-
# Set request parameters
|
432
|
-
request = {
|
433
|
-
test: true,
|
434
|
-
terminalName: 'Test Terminal'
|
435
|
-
}
|
436
|
-
|
437
|
-
response = blockchyp.enroll(request)
|
438
|
-
|
439
|
-
puts "Response: #{response.inspect}"
|
440
|
-
|
441
|
-
|
442
354
|
```
|
443
355
|
|
444
356
|
#### Void
|
445
357
|
|
446
358
|
|
447
359
|
|
360
|
+
* **API Credential Types:** Merchant
|
361
|
+
* **Required Role:** Payment API Access
|
362
|
+
|
448
363
|
Mistakes happen. If a transaction is made by mistake, you can void it
|
449
364
|
with this API. All that's needed is to pass in a Transaction ID and execute
|
450
365
|
the void before the original transaction's batch closes.
|
451
366
|
|
452
367
|
Voids work with EBT and gift card transactions with no additional parameters.
|
453
368
|
|
369
|
+
**Cryptocurrency**
|
370
|
+
|
371
|
+
Note that voids are not supported for cryptocurrency. You must refund crypto transactions
|
372
|
+
manually from your cryptocurrency wallet.
|
373
|
+
|
454
374
|
|
455
375
|
|
456
376
|
|
@@ -482,6 +402,9 @@ puts "Response: #{response.inspect}"
|
|
482
402
|
|
483
403
|
|
484
404
|
|
405
|
+
* **API Credential Types:** Merchant
|
406
|
+
* **Required Role:** Payment API Access
|
407
|
+
|
485
408
|
Payment transactions require a stable network to function correctly and
|
486
409
|
no network is stable all the time. Time out reversals are a great line
|
487
410
|
of defense against accidentally double charging consumers when payments
|
@@ -496,9 +419,14 @@ The only caveat is that developers must use the `transactionRef` property (`txRe
|
|
496
419
|
|
497
420
|
The reason for this requirement is that if a system never receives a definitive
|
498
421
|
response for a transaction, the system would never have received the BlockChyp
|
499
|
-
generated Transaction ID. We have to
|
422
|
+
generated Transaction ID. We have to fall back to Transaction Ref to identify
|
500
423
|
a transaction.
|
501
424
|
|
425
|
+
**Cryptocurrency**
|
426
|
+
|
427
|
+
Note that refunds are not supported for cryptocurrency. You must refund crypto transactions
|
428
|
+
manually from your cryptocurrency wallet.
|
429
|
+
|
502
430
|
|
503
431
|
|
504
432
|
|
@@ -528,14 +456,18 @@ puts "Response: #{response.inspect}"
|
|
528
456
|
#### Gift Card Activation
|
529
457
|
|
530
458
|
|
531
|
-
|
459
|
+
|
460
|
+
* **API Credential Types:** Merchant
|
461
|
+
* **Required Role:** Payment API Access
|
462
|
+
|
463
|
+
This API activates or adds value to BlockChyp gift cards.
|
532
464
|
Just pass in the terminal name and the amount to add to the card.
|
533
465
|
Once the customer swipes their card, the terminal will use keys
|
534
466
|
on the mag stripe to add value to the card.
|
535
467
|
|
536
468
|
You don't need to handle a new gift card activation or a gift card recharge any
|
537
469
|
differently. The terminal firmware will figure out what to do on its
|
538
|
-
own
|
470
|
+
own while also returning the new balance for the gift card.
|
539
471
|
|
540
472
|
This is the part of the system where BlockChyp's blockchain DNA comes
|
541
473
|
closest to the surface. The BlockChyp gift card system doesn't really
|
@@ -564,9 +496,9 @@ voiding or reversing a conventional payment transaction.
|
|
564
496
|
|
565
497
|
BlockChyp does have the ability to import gift card liability from
|
566
498
|
conventional gift card platforms. Unfortunately, BlockChyp does not
|
567
|
-
support activating cards on third party systems,
|
499
|
+
support activating cards on third party systems. However, you can import
|
568
500
|
your outstanding gift cards and customers can swipe them on the
|
569
|
-
terminals
|
501
|
+
terminals like BlockChyp's standard gift cards.
|
570
502
|
|
571
503
|
No special coding is required to access this feature. The gateway and
|
572
504
|
terminal firmware handle everything for you.
|
@@ -576,7 +508,7 @@ terminal firmware handle everything for you.
|
|
576
508
|
BlockChyp does not currently provide any native support for other gift card
|
577
509
|
platforms beyond importing gift card liability. We do have a white listing system
|
578
510
|
that can be used to support your own custom gift card implementations. We have a security review
|
579
|
-
process before we allow a BIN range to be white listed, so contact
|
511
|
+
process before we can allow a BIN range to be white listed, so contact
|
580
512
|
support@blockchyp.com if you need to white list a BIN range.
|
581
513
|
|
582
514
|
|
@@ -611,25 +543,29 @@ puts "Response: #{response.inspect}"
|
|
611
543
|
|
612
544
|
|
613
545
|
|
614
|
-
|
546
|
+
* **API Credential Types:** Merchant
|
547
|
+
* **Required Role:** Payment API Access
|
548
|
+
|
549
|
+
This API checks a gift or EBT card balance.
|
615
550
|
|
616
551
|
**Gift Card Balance Checks**
|
617
552
|
|
618
|
-
For gift cards,
|
553
|
+
For gift cards, pass in a terminal name and the customer will be prompted
|
619
554
|
to swipe a card on that terminal. The remaining balance will be displayed
|
620
555
|
briefly on the terminal screen and the API response will include the gift card's public key and the remaining balance.
|
621
556
|
|
622
557
|
**EBT Balance Checks**
|
623
558
|
|
624
|
-
All EBT transactions require a PIN, so
|
559
|
+
All EBT transactions require a PIN, so to check an EBT card balance,
|
625
560
|
you need to pass in the `ebt` flag just like you would for a normal EBT
|
626
561
|
charge transaction. The customer will be prompted to swipe their card and
|
627
|
-
enter a PIN code. If everything checks out, the remaining balance on the
|
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.
|
628
564
|
|
629
565
|
**Testing Gift Card Balance Checks**
|
630
566
|
|
631
567
|
Test gift card balance checks work no differently than live gift cards. You
|
632
|
-
must activate a test gift card first
|
568
|
+
must activate a test gift card first to test balance checks. Test
|
633
569
|
gift cards are real blockchain cards that live on our parallel test blockchain.
|
634
570
|
|
635
571
|
**Testing EBT Gift Card Balance Checks**
|
@@ -668,6 +604,10 @@ puts "Response: #{response.inspect}"
|
|
668
604
|
#### Close Batch
|
669
605
|
|
670
606
|
|
607
|
+
|
608
|
+
* **API Credential Types:** Merchant
|
609
|
+
* **Required Role:** Payment API Access
|
610
|
+
|
671
611
|
This API will close the merchant's batch if it's currently open.
|
672
612
|
|
673
613
|
By default, merchant batches will close automatically at 3 AM in their
|
@@ -706,6 +646,9 @@ puts "Response: #{response.inspect}"
|
|
706
646
|
|
707
647
|
|
708
648
|
|
649
|
+
* **API Credential Types:** Merchant
|
650
|
+
* **Required Role:** Payment API Access
|
651
|
+
|
709
652
|
This API allows you to send an invoice to a customer and capture payment
|
710
653
|
via a BlockChyp hosted payment page.
|
711
654
|
|
@@ -720,26 +663,26 @@ you use the `cashier` flag.)
|
|
720
663
|
|
721
664
|
**Customer Info**
|
722
665
|
|
723
|
-
Unless you're using the `cashier` flag, you must specify a customer
|
724
|
-
creating a new customer record inline or
|
666
|
+
Unless you're using the `cashier` flag, you must specify a customer; either by
|
667
|
+
creating a new customer record inline or passing in an existing Customer ID or Customer Ref.
|
725
668
|
|
726
669
|
**Line Item Level Data**
|
727
670
|
|
728
671
|
It's not strictly required, but we strongly recommend sending line item level
|
729
|
-
detail with every request. It will make the invoice look
|
672
|
+
detail with every request. It will make the invoice look more complete
|
730
673
|
and the data format for line item level data is the exact same format used
|
731
674
|
for terminal line item display, so the same code can be used to support both areas.
|
732
675
|
|
733
676
|
**Descriptions**
|
734
677
|
|
735
|
-
You can also provide a free form description or message
|
678
|
+
You can also provide a free form description or message to display near
|
736
679
|
the bottom of the invoice. Usually this is some kind of thank you note
|
737
680
|
or instruction.
|
738
681
|
|
739
682
|
**Terms and Conditions**
|
740
683
|
|
741
684
|
You can include long form contract language with a request and capture
|
742
|
-
terms and conditions
|
685
|
+
terms and conditions accepted at the same time payment is captured.
|
743
686
|
|
744
687
|
The interface is identical to that used for the terminal based Terms and
|
745
688
|
Conditions API in that you can pass in content directly via `tcContent` or via
|
@@ -748,10 +691,14 @@ agreement acceptance is incorporated into a send link request.
|
|
748
691
|
|
749
692
|
**Auto Send**
|
750
693
|
|
751
|
-
BlockChyp does not send the email notification automatically.
|
752
|
-
|
753
|
-
|
754
|
-
|
694
|
+
BlockChyp does not send the email notification automatically. This safeguard prevents real
|
695
|
+
emails from going out when you may not expect them If you want BlockChyp to send the email
|
696
|
+
for you, just add the `autoSend` flag with all requests.
|
697
|
+
|
698
|
+
**Cryptocurrency**
|
699
|
+
|
700
|
+
If the merchant is configured to support cryptocurrency transactions, the payment page will
|
701
|
+
display additional UI widgets that allowing customers to switch to a crypto payment method.
|
755
702
|
|
756
703
|
**Tokenization**
|
757
704
|
|
@@ -761,13 +708,15 @@ in the token vault.
|
|
761
708
|
**Cashier Facing Card Entry**
|
762
709
|
|
763
710
|
BlockChyp can be used to generate internal/cashier facing card entry pages as well. This is
|
764
|
-
designed for situations where you might need to take a phone order and
|
765
|
-
have
|
711
|
+
designed for situations where you might need to take a phone order and don't
|
712
|
+
have an available terminal.
|
766
713
|
|
767
|
-
If you pass in the `cashier` flag, no email will be sent and you'll be
|
714
|
+
If you pass in the `cashier` flag, no email will be sent and you'll be able to
|
768
715
|
load the link in a browser or iframe for payment entry. When the `cashier` flag
|
769
716
|
is used, the `autoSend` flag will be ignored.
|
770
717
|
|
718
|
+
Note that cryptocurrency is not supported for cashier facing payment entry.
|
719
|
+
|
771
720
|
**Payment Notifications**
|
772
721
|
|
773
722
|
When a customer successfully submits payment, the merchant will receive an email
|
@@ -809,6 +758,7 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
809
758
|
|
810
759
|
# Set request parameters
|
811
760
|
request = {
|
761
|
+
transactionRef: '<TX REF>',
|
812
762
|
amount: '199.99',
|
813
763
|
description: 'Widget',
|
814
764
|
subject: 'Widget invoice',
|
@@ -846,7 +796,10 @@ puts "Response: #{response.inspect}"
|
|
846
796
|
|
847
797
|
|
848
798
|
|
849
|
-
|
799
|
+
* **API Credential Types:** Merchant
|
800
|
+
* **Required Role:** Payment API Access
|
801
|
+
|
802
|
+
This API cancels a payment link.
|
850
803
|
|
851
804
|
|
852
805
|
|
@@ -864,7 +817,7 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
864
817
|
|
865
818
|
# Set request parameters
|
866
819
|
request = {
|
867
|
-
linkCode: '
|
820
|
+
linkCode: '<PAYMENT LINK CODE>'
|
868
821
|
}
|
869
822
|
|
870
823
|
response = blockchyp.cancelPaymentLink(request)
|
@@ -878,7 +831,10 @@ puts "Response: #{response.inspect}"
|
|
878
831
|
|
879
832
|
|
880
833
|
|
881
|
-
|
834
|
+
* **API Credential Types:** Merchant
|
835
|
+
* **Required Role:** Payment API Access
|
836
|
+
|
837
|
+
This API returns the current status for any transaction. You can lookup a transaction
|
882
838
|
by its BlockChyp assigned Transaction ID or your own Transaction Ref.
|
883
839
|
|
884
840
|
You should alway use globally unique Transaction Ref values, but in the event
|
@@ -901,7 +857,7 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
901
857
|
|
902
858
|
# Set request parameters
|
903
859
|
request = {
|
904
|
-
transactionId: 'ID
|
860
|
+
transactionId: '<TRANSACTION ID>'
|
905
861
|
}
|
906
862
|
|
907
863
|
response = blockchyp.transactionStatus(request)
|
@@ -911,13 +867,18 @@ puts "Response: #{response.inspect}"
|
|
911
867
|
|
912
868
|
```
|
913
869
|
|
914
|
-
####
|
870
|
+
#### Cash Discount
|
915
871
|
|
916
872
|
|
917
873
|
|
918
|
-
|
919
|
-
|
874
|
+
* **API Credential Types:** Merchant
|
875
|
+
* **Required Role:** Payment API Access
|
876
|
+
|
877
|
+
This API calculates the surcharge, cash discount, and total amounts for cash transactions.
|
920
878
|
|
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.
|
921
882
|
|
922
883
|
|
923
884
|
|
@@ -935,31 +896,46 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
935
896
|
|
936
897
|
# Set request parameters
|
937
898
|
request = {
|
938
|
-
|
939
|
-
|
899
|
+
amount: '100.00',
|
900
|
+
cashDiscount: true,
|
901
|
+
surcharge: true
|
940
902
|
}
|
941
903
|
|
942
|
-
response = blockchyp.
|
904
|
+
response = blockchyp.cashDiscount(request)
|
943
905
|
|
944
906
|
puts "Response: #{response.inspect}"
|
945
907
|
|
946
908
|
|
947
909
|
```
|
948
910
|
|
949
|
-
####
|
911
|
+
#### Batch History
|
950
912
|
|
951
913
|
|
952
914
|
|
953
|
-
|
954
|
-
|
915
|
+
* **API Credential Types:** Merchant
|
916
|
+
* **Required Role:** Payment API Access
|
955
917
|
|
956
|
-
|
957
|
-
|
958
|
-
|
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.
|
959
922
|
|
960
|
-
|
961
|
-
|
962
|
-
|
923
|
+
**Limiting Results**
|
924
|
+
|
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
|
+
|
929
|
+
For example, if you want the ten most recent batches, pass in a value of
|
930
|
+
`10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
|
931
|
+
get the first batch in the dataset.
|
932
|
+
|
933
|
+
**Filtering by Date Range**
|
934
|
+
|
935
|
+
You can also filter results by date. Use the `startDate` and `endDate`
|
936
|
+
properties to return only those batches opened between those dates.
|
937
|
+
You can use either `startDate` and `endDate` and you can use date filters
|
938
|
+
in conjunction with `maxResults` and `startIndex`
|
963
939
|
|
964
940
|
|
965
941
|
|
@@ -977,57 +953,31 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
977
953
|
|
978
954
|
# Set request parameters
|
979
955
|
request = {
|
980
|
-
|
956
|
+
maxResults: 250,
|
957
|
+
startIndex: 0
|
981
958
|
}
|
982
959
|
|
983
|
-
response = blockchyp.
|
960
|
+
response = blockchyp.batchHistory(request)
|
984
961
|
|
985
962
|
puts "Response: #{response.inspect}"
|
986
963
|
|
987
964
|
|
988
965
|
```
|
989
966
|
|
990
|
-
####
|
991
|
-
|
992
|
-
|
993
|
-
|
994
|
-
This API allows you to prompt a customer to accept a legal agreement on the terminal
|
995
|
-
and (usually) capture their signature.
|
996
|
-
|
997
|
-
Content for the agreement can be specified in two ways. You can reference a
|
998
|
-
previously configured T&C template or pass in the full agreement text with every request.
|
999
|
-
|
1000
|
-
**Using Templates**
|
1001
|
-
|
1002
|
-
If your application doesn't keep track of agreements you can leverage BlockChyp's
|
1003
|
-
template system. You can create any number of T&C Templates in the merchant dashboard
|
1004
|
-
and pass in the `tcAlias` flag to specify which one to display.
|
1005
|
-
|
1006
|
-
**Raw Content**
|
1007
|
-
|
1008
|
-
If your system keeps track of the agreement language or executes complicated merging
|
1009
|
-
and rendering logic, you can bypass our template system and pass in the full text with
|
1010
|
-
every transaction. Use the `tcName` to pass in the agreement name and `tcContent` to
|
1011
|
-
pass in the contract text. Note that only plain text is supported.
|
1012
|
-
|
1013
|
-
**Bypassing Signatures**
|
1014
|
-
|
1015
|
-
Signature images are captured by default. If for some reason this doesn't fit your
|
1016
|
-
use case and you'd like to capture acceptance without actually capturing a signature image, set
|
1017
|
-
the `disableSignature` flag in the request.
|
967
|
+
#### Batch Details
|
1018
968
|
|
1019
|
-
**Terms & Conditions Log**
|
1020
969
|
|
1021
|
-
Every time a user accepts an agreement on the terminal, the signature image (if captured),
|
1022
|
-
will be uploaded to the gateway and added to the log along with the full text of the
|
1023
|
-
agreement. This preserves the historical record in the event that standard agreements
|
1024
|
-
or templates change over time.
|
1025
970
|
|
1026
|
-
**
|
971
|
+
* **API Credential Types:** Merchant
|
972
|
+
* **Required Role:** Payment API Access
|
1027
973
|
|
1028
|
-
|
1029
|
-
|
974
|
+
This API allows developers to pull down details for a specific batch,
|
975
|
+
including captured volume, gift card activity, expected deposit, and
|
976
|
+
captured volume broken down by terminal.
|
1030
977
|
|
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.
|
1031
981
|
|
1032
982
|
|
1033
983
|
|
@@ -1045,58 +995,68 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1045
995
|
|
1046
996
|
# Set request parameters
|
1047
997
|
request = {
|
1048
|
-
|
1049
|
-
terminalName: 'Test Terminal',
|
1050
|
-
|
1051
|
-
# Alias for a Terms and Conditions template configured in the BlockChyp
|
1052
|
-
# dashboard.
|
1053
|
-
tcAlias: 'hippa',
|
1054
|
-
|
1055
|
-
# Name of the contract or document if not using an alias.
|
1056
|
-
tcName: 'HIPPA Disclosure',
|
1057
|
-
|
1058
|
-
# Full text of the contract or disclosure if not using an alias.
|
1059
|
-
tcContent: 'Full contract text',
|
1060
|
-
|
1061
|
-
# File format for the signature image.
|
1062
|
-
sigFormat: SignatureFormat::PNG,
|
1063
|
-
|
1064
|
-
# Width of the signature image in pixels.
|
1065
|
-
sigWidth: 200,
|
1066
|
-
|
1067
|
-
# Whether or not a signature is required. Defaults to true.
|
1068
|
-
sigRequired: true
|
998
|
+
batchId: '<BATCH ID>'
|
1069
999
|
}
|
1070
1000
|
|
1071
|
-
response = blockchyp.
|
1001
|
+
response = blockchyp.batchDetails(request)
|
1072
1002
|
|
1073
1003
|
puts "Response: #{response.inspect}"
|
1074
1004
|
|
1075
1005
|
|
1076
1006
|
```
|
1077
1007
|
|
1078
|
-
####
|
1008
|
+
#### Transaction History
|
1079
1009
|
|
1080
1010
|
|
1081
1011
|
|
1082
|
-
|
1083
|
-
|
1012
|
+
* **API Credential Types:** Merchant
|
1013
|
+
* **Required Role:** Payment API Access
|
1084
1014
|
|
1085
|
-
|
1086
|
-
|
1015
|
+
This endpoint provides several different methods to sift through
|
1016
|
+
transaction history.
|
1087
1017
|
|
1088
|
-
|
1089
|
-
|
1090
|
-
applications. At a minimum, you must specify an image format using the
|
1091
|
-
`sigFormat` parameter. As of this writing JPG and PNG are supported.
|
1018
|
+
By default with no filtering properties, this endpoint will return the 250
|
1019
|
+
most recent transactions.
|
1092
1020
|
|
1093
|
-
|
1094
|
-
You can redirect the binary image output to a file using the `sigFile`
|
1095
|
-
parameter.
|
1021
|
+
**Limiting Results**
|
1096
1022
|
|
1097
|
-
|
1098
|
-
|
1099
|
-
|
1023
|
+
This API will return a maximum of 50 results in a single query. Use the `maxResults` property
|
1024
|
+
to limit maximum results even further and use the `startIndex` property to
|
1025
|
+
page through results that span multiple queries.
|
1026
|
+
|
1027
|
+
For example, if you want the ten most recent batches, pass in a value of
|
1028
|
+
`10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
|
1029
|
+
get the first transaction in the dataset.
|
1030
|
+
|
1031
|
+
**Filtering By Date Range**
|
1032
|
+
|
1033
|
+
You can also filter results by date. Use the `startDate` and `endDate`
|
1034
|
+
properties to return only transactions run between those dates.
|
1035
|
+
You can use either `startDate` or `endDate` and you can use date filters
|
1036
|
+
in conjunction with `maxResults` and `startIndex`
|
1037
|
+
|
1038
|
+
**Filtering By Batch**
|
1039
|
+
|
1040
|
+
To restrict results to a single batch, pass in the `batchId` parameter.
|
1041
|
+
|
1042
|
+
**Filtering By Terminal**
|
1043
|
+
|
1044
|
+
To restrict results to those executed on a single terminal, pass in the terminal name.
|
1045
|
+
|
1046
|
+
**Combining Filters**
|
1047
|
+
|
1048
|
+
None of the above filters are mutually exclusive. You can combine any of the
|
1049
|
+
above properties in a single request to restrict transaction results to a
|
1050
|
+
narrower set of results.
|
1051
|
+
|
1052
|
+
**Searching Transaction History**
|
1053
|
+
|
1054
|
+
You can search transaction history by passing in search criteria with the
|
1055
|
+
`query` option. The search system will match the amount (requested and authorized),
|
1056
|
+
last four of the card number, cardholder name, and the auth code.
|
1057
|
+
|
1058
|
+
Note that when search queries are used, terminalName or
|
1059
|
+
batch id filters are not supported.
|
1100
1060
|
|
1101
1061
|
|
1102
1062
|
|
@@ -1114,45 +1074,119 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1114
1074
|
|
1115
1075
|
# Set request parameters
|
1116
1076
|
request = {
|
1117
|
-
|
1077
|
+
maxResults: 10,
|
1078
|
+
batchId: '<BATCH ID>'
|
1079
|
+
}
|
1118
1080
|
|
1119
|
-
|
1120
|
-
sigFormat: SignatureFormat::PNG,
|
1081
|
+
response = blockchyp.transactionHistory(request)
|
1121
1082
|
|
1122
|
-
|
1123
|
-
|
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'
|
1124
1116
|
}
|
1125
1117
|
|
1126
|
-
response = blockchyp.
|
1118
|
+
response = blockchyp.listQueuedTransactions(request)
|
1127
1119
|
|
1128
1120
|
puts "Response: #{response.inspect}"
|
1129
1121
|
|
1130
1122
|
|
1131
1123
|
```
|
1132
1124
|
|
1133
|
-
####
|
1125
|
+
#### Delete Queued Transaction
|
1134
1126
|
|
1135
1127
|
|
1136
1128
|
|
1137
|
-
|
1129
|
+
* **API Credential Types:** Merchant
|
1130
|
+
* **Required Role:** Payment API Access
|
1138
1131
|
|
1139
|
-
|
1140
|
-
|
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.
|
1141
1135
|
|
1142
|
-
You can also send line item level data and each line item can have a `description`,
|
1143
|
-
`qty`, `price`, and `extended` price.
|
1144
1136
|
|
1145
|
-
If you fail to send an extended price, BlockChyp will multiply the `qty` by the
|
1146
|
-
`price`, but we strongly recommend you precalculate all the fields yourself
|
1147
|
-
to ensure consistency. Your treatment of floating-point multiplication and rounding
|
1148
|
-
may differ slightly from BlockChyp's, for example.
|
1149
1137
|
|
1150
|
-
**Discounts**
|
1151
1138
|
|
1152
|
-
|
1153
|
-
|
1154
|
-
|
1155
|
-
|
1139
|
+
```ruby
|
1140
|
+
# frozen_string_literal: true
|
1141
|
+
|
1142
|
+
require 'blockchyp'
|
1143
|
+
|
1144
|
+
blockchyp = BlockChyp::BlockChyp.new(
|
1145
|
+
ENV['BC_API_KEY'],
|
1146
|
+
ENV['BC_BEARER_TOKEN'],
|
1147
|
+
ENV['BC_SIGNING_KEY']
|
1148
|
+
)
|
1149
|
+
|
1150
|
+
# Set request parameters
|
1151
|
+
request = {
|
1152
|
+
terminalName: 'Test Terminal',
|
1153
|
+
transactionRef: '*'
|
1154
|
+
}
|
1155
|
+
|
1156
|
+
response = blockchyp.deleteQueuedTransaction(request)
|
1157
|
+
|
1158
|
+
puts "Response: #{response.inspect}"
|
1159
|
+
|
1160
|
+
|
1161
|
+
```
|
1162
|
+
|
1163
|
+
### Terminal Management Endpoints
|
1164
|
+
|
1165
|
+
|
1166
|
+
These APIs support terminal management functions and additional terminal
|
1167
|
+
features such as line item display, messages, and interactive prompts.
|
1168
|
+
These features can be used to extend a point of sale system's functionality.
|
1169
|
+
|
1170
|
+
|
1171
|
+
|
1172
|
+
#### Terminal Ping
|
1173
|
+
|
1174
|
+
|
1175
|
+
|
1176
|
+
* **API Credential Types:** Merchant
|
1177
|
+
* **Required Role:** Payment API Access
|
1178
|
+
|
1179
|
+
This simple test transaction helps ensure good communication with a payment terminal
|
1180
|
+
and is usually the first test you'll run in development.
|
1181
|
+
|
1182
|
+
It tests communication with the terminal and returns a positive response if everything
|
1183
|
+
is okay. It works the same way in local or cloud relay mode.
|
1184
|
+
|
1185
|
+
If you get a positive response, you've successfully verified all of the following:
|
1186
|
+
|
1187
|
+
* The terminal is online.
|
1188
|
+
* There is a valid route to the terminal.
|
1189
|
+
* The API Credentials are valid.
|
1156
1190
|
|
1157
1191
|
|
1158
1192
|
|
@@ -1170,67 +1204,66 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1170
1204
|
|
1171
1205
|
# Set request parameters
|
1172
1206
|
request = {
|
1173
|
-
|
1174
|
-
terminalName: 'Test Terminal',
|
1175
|
-
transaction: {
|
1176
|
-
subtotal: '60.00',
|
1177
|
-
tax: '5.00',
|
1178
|
-
total: '65.00',
|
1179
|
-
items: [
|
1180
|
-
{
|
1181
|
-
description: 'Leki Trekking Poles',
|
1182
|
-
price: '35.00',
|
1183
|
-
quantity: 2,
|
1184
|
-
extended: '70.00',
|
1185
|
-
discounts: [
|
1186
|
-
{
|
1187
|
-
description: 'memberDiscount',
|
1188
|
-
amount: '10.00'
|
1189
|
-
}
|
1190
|
-
]
|
1191
|
-
}
|
1192
|
-
]
|
1193
|
-
}
|
1207
|
+
terminalName: 'Test Terminal'
|
1194
1208
|
}
|
1195
1209
|
|
1196
|
-
response = blockchyp.
|
1210
|
+
response = blockchyp.ping(request)
|
1197
1211
|
|
1198
1212
|
puts "Response: #{response.inspect}"
|
1199
1213
|
|
1200
1214
|
|
1201
1215
|
```
|
1202
1216
|
|
1203
|
-
####
|
1217
|
+
#### Terminal Locate
|
1204
1218
|
|
1205
1219
|
|
1206
1220
|
|
1207
|
-
|
1208
|
-
|
1221
|
+
* **API Credential Types:** Merchant
|
1222
|
+
* **Required Role:** Payment API Access
|
1209
1223
|
|
1210
|
-
This
|
1211
|
-
items are scanned. This variant means you only have to send information to the
|
1212
|
-
terminal that's changed, which usually means the new line item and updated totals.
|
1224
|
+
This endpoint returns a terminal's routing and location information.
|
1213
1225
|
|
1214
|
-
|
1215
|
-
the
|
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.
|
1216
1228
|
|
1217
|
-
|
1218
|
-
including `total`, `tax`, and `subtotal`.
|
1229
|
+
The terminal will also return the public key for the terminal.
|
1219
1230
|
|
1220
|
-
You can also send line item level data and each line item can have a `description`,
|
1221
|
-
`qty`, `price`, and `extended` price.
|
1222
1231
|
|
1223
|
-
If you fail to send an extended price, BlockChyp will multiply the `qty` by the
|
1224
|
-
`price`, but we strongly recommend you precalculate all the fields yourself
|
1225
|
-
to ensure consistency. Your treatment of floating-point multiplication and rounding
|
1226
|
-
may differ slightly from BlockChyp's, for example.
|
1227
1232
|
|
1228
|
-
**Discounts**
|
1229
1233
|
|
1230
|
-
|
1231
|
-
|
1232
|
-
|
1233
|
-
|
1234
|
+
```ruby
|
1235
|
+
# frozen_string_literal: true
|
1236
|
+
|
1237
|
+
require 'blockchyp'
|
1238
|
+
|
1239
|
+
blockchyp = BlockChyp::BlockChyp.new(
|
1240
|
+
ENV['BC_API_KEY'],
|
1241
|
+
ENV['BC_BEARER_TOKEN'],
|
1242
|
+
ENV['BC_SIGNING_KEY']
|
1243
|
+
)
|
1244
|
+
|
1245
|
+
# Set request parameters
|
1246
|
+
request = {
|
1247
|
+
terminalName: 'Test Terminal'
|
1248
|
+
}
|
1249
|
+
|
1250
|
+
response = blockchyp.locate(request)
|
1251
|
+
|
1252
|
+
puts "Response: #{response.inspect}"
|
1253
|
+
|
1254
|
+
|
1255
|
+
```
|
1256
|
+
|
1257
|
+
#### Terminal Clear
|
1258
|
+
|
1259
|
+
|
1260
|
+
|
1261
|
+
* **API Credential Types:** Merchant
|
1262
|
+
* **Required Role:** Payment API Access
|
1263
|
+
|
1264
|
+
This API interrupts whatever a terminal may be doing and returns it to the
|
1265
|
+
idle state.
|
1266
|
+
|
1234
1267
|
|
1235
1268
|
|
1236
1269
|
|
@@ -1249,42 +1282,1594 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1249
1282
|
# Set request parameters
|
1250
1283
|
request = {
|
1251
1284
|
test: true,
|
1252
|
-
terminalName: 'Test Terminal'
|
1253
|
-
transaction: {
|
1254
|
-
subtotal: '60.00',
|
1255
|
-
tax: '5.00',
|
1256
|
-
total: '65.00',
|
1257
|
-
items: [
|
1258
|
-
{
|
1259
|
-
description: 'Leki Trekking Poles',
|
1260
|
-
price: '35.00',
|
1261
|
-
quantity: 2,
|
1262
|
-
extended: '70.00',
|
1263
|
-
discounts: [
|
1264
|
-
{
|
1265
|
-
description: 'memberDiscount',
|
1266
|
-
amount: '10.00'
|
1267
|
-
}
|
1268
|
-
]
|
1269
|
-
}
|
1270
|
-
]
|
1271
|
-
}
|
1285
|
+
terminalName: 'Test Terminal'
|
1272
1286
|
}
|
1273
1287
|
|
1274
|
-
response = blockchyp.
|
1288
|
+
response = blockchyp.clear(request)
|
1289
|
+
|
1290
|
+
puts "Response: #{response.inspect}"
|
1291
|
+
|
1292
|
+
|
1293
|
+
```
|
1294
|
+
|
1295
|
+
#### Terminal Status
|
1296
|
+
|
1297
|
+
|
1298
|
+
|
1299
|
+
* **API Credential Types:** Merchant
|
1300
|
+
* **Required Role:** Payment API Access
|
1301
|
+
|
1302
|
+
This API returns the current status of a payment terminal. This is typically used
|
1303
|
+
as a way to determine if the terminal is busy before sending a new transaction.
|
1304
|
+
|
1305
|
+
If the terminal is busy, `idle` will be false and the `status` field will return
|
1306
|
+
a short string that indicates the transaction type currently in progress. The system
|
1307
|
+
will also return the timestamp of the last status change in the `since` field.
|
1308
|
+
|
1309
|
+
If the system is running a payment transaction and you wisely passed in a
|
1310
|
+
Transaction Ref, this API will also return the Transaction Ref of the in progress
|
1311
|
+
transaction.
|
1312
|
+
|
1313
|
+
|
1314
|
+
|
1315
|
+
|
1316
|
+
```ruby
|
1317
|
+
# frozen_string_literal: true
|
1318
|
+
|
1319
|
+
require 'blockchyp'
|
1320
|
+
|
1321
|
+
blockchyp = BlockChyp::BlockChyp.new(
|
1322
|
+
ENV['BC_API_KEY'],
|
1323
|
+
ENV['BC_BEARER_TOKEN'],
|
1324
|
+
ENV['BC_SIGNING_KEY']
|
1325
|
+
)
|
1326
|
+
|
1327
|
+
# Set request parameters
|
1328
|
+
request = {
|
1329
|
+
terminalName: 'Test Terminal'
|
1330
|
+
}
|
1331
|
+
|
1332
|
+
response = blockchyp.terminalStatus(request)
|
1333
|
+
|
1334
|
+
puts "Response: #{response.inspect}"
|
1335
|
+
|
1336
|
+
|
1337
|
+
```
|
1338
|
+
|
1339
|
+
#### Capture Signature
|
1340
|
+
|
1341
|
+
|
1342
|
+
|
1343
|
+
* **API Credential Types:** Merchant
|
1344
|
+
* **Required Role:** Payment API Access
|
1345
|
+
|
1346
|
+
This endpoint captures a written signature from the terminal and returns the
|
1347
|
+
image.
|
1348
|
+
|
1349
|
+
Unlike the Terms & Conditions API, this endpoint performs basic signature
|
1350
|
+
capture with no agreement display or signature archival.
|
1351
|
+
|
1352
|
+
Under the hood, signatures are captured in a proprietary vector format and
|
1353
|
+
must be converted to a common raster format in order to be useful to most
|
1354
|
+
applications. At a minimum, you must specify an image format using the
|
1355
|
+
`sigFormat` parameter. Currently, JPG and PNG are supported.
|
1356
|
+
|
1357
|
+
By default, images are returned in the JSON response as hex encoded binary.
|
1358
|
+
You can redirect the binary image output to a file using the `sigFile`
|
1359
|
+
parameter.
|
1360
|
+
|
1361
|
+
You can also scale the output image to your preferred width by
|
1362
|
+
passing in a `sigWidth` parameter. The image will be scaled to that
|
1363
|
+
width, preserving the aspect ratio of the original image.
|
1364
|
+
|
1365
|
+
|
1366
|
+
|
1367
|
+
|
1368
|
+
```ruby
|
1369
|
+
# frozen_string_literal: true
|
1370
|
+
|
1371
|
+
require 'blockchyp'
|
1372
|
+
|
1373
|
+
blockchyp = BlockChyp::BlockChyp.new(
|
1374
|
+
ENV['BC_API_KEY'],
|
1375
|
+
ENV['BC_BEARER_TOKEN'],
|
1376
|
+
ENV['BC_SIGNING_KEY']
|
1377
|
+
)
|
1378
|
+
|
1379
|
+
# Set request parameters
|
1380
|
+
request = {
|
1381
|
+
terminalName: 'Test Terminal',
|
1382
|
+
|
1383
|
+
# File format for the signature image.
|
1384
|
+
sigFormat: SignatureFormat::PNG,
|
1385
|
+
|
1386
|
+
# Width of the signature image in pixels.
|
1387
|
+
sigWidth: 200
|
1388
|
+
}
|
1389
|
+
|
1390
|
+
response = blockchyp.captureSignature(request)
|
1391
|
+
|
1392
|
+
puts "Response: #{response.inspect}"
|
1393
|
+
|
1394
|
+
|
1395
|
+
```
|
1396
|
+
|
1397
|
+
#### New Transaction Display
|
1398
|
+
|
1399
|
+
|
1400
|
+
|
1401
|
+
* **API Credential Types:** Merchant
|
1402
|
+
* **Required Role:** Payment API Access
|
1403
|
+
|
1404
|
+
This API sends totals and line item level data to the terminal.
|
1405
|
+
|
1406
|
+
At a minimum, you should send total information as part of a display request,
|
1407
|
+
including `total`, `tax`, and `subtotal`.
|
1408
|
+
|
1409
|
+
You can also send line item level data and each line item can have a `description`,
|
1410
|
+
`qty`, `price`, and `extended` price.
|
1411
|
+
|
1412
|
+
If you fail to send an extended price, BlockChyp will multiply the `qty` by the
|
1413
|
+
`price`. However, we strongly recommend you precalculate all the fields yourself
|
1414
|
+
to ensure consistency. For example, your treatment of floating-point multiplication
|
1415
|
+
and rounding may differ slightly from BlockChyp's.
|
1416
|
+
|
1417
|
+
**Discounts**
|
1418
|
+
|
1419
|
+
You have the option to show discounts on the display as individual line items
|
1420
|
+
with negative values or you can associate discounts with a specific line item.
|
1421
|
+
You can apply any number of discounts to an individual line item with a description
|
1422
|
+
and amount.
|
1423
|
+
|
1424
|
+
|
1425
|
+
|
1426
|
+
|
1427
|
+
```ruby
|
1428
|
+
# frozen_string_literal: true
|
1429
|
+
|
1430
|
+
require 'blockchyp'
|
1431
|
+
|
1432
|
+
blockchyp = BlockChyp::BlockChyp.new(
|
1433
|
+
ENV['BC_API_KEY'],
|
1434
|
+
ENV['BC_BEARER_TOKEN'],
|
1435
|
+
ENV['BC_SIGNING_KEY']
|
1436
|
+
)
|
1437
|
+
|
1438
|
+
# Set request parameters
|
1439
|
+
request = {
|
1440
|
+
test: true,
|
1441
|
+
terminalName: 'Test Terminal',
|
1442
|
+
transaction: {
|
1443
|
+
subtotal: '60.00',
|
1444
|
+
tax: '5.00',
|
1445
|
+
total: '65.00',
|
1446
|
+
items: [
|
1447
|
+
{
|
1448
|
+
description: 'Leki Trekking Poles',
|
1449
|
+
price: '35.00',
|
1450
|
+
quantity: 2,
|
1451
|
+
extended: '70.00',
|
1452
|
+
discounts: [
|
1453
|
+
{
|
1454
|
+
description: 'memberDiscount',
|
1455
|
+
amount: '10.00'
|
1456
|
+
}
|
1457
|
+
]
|
1458
|
+
}
|
1459
|
+
]
|
1460
|
+
}
|
1461
|
+
}
|
1462
|
+
|
1463
|
+
response = blockchyp.newTransactionDisplay(request)
|
1464
|
+
|
1465
|
+
puts "Response: #{response.inspect}"
|
1466
|
+
|
1467
|
+
|
1468
|
+
```
|
1469
|
+
|
1470
|
+
#### Update Transaction Display
|
1471
|
+
|
1472
|
+
|
1473
|
+
|
1474
|
+
* **API Credential Types:** Merchant
|
1475
|
+
* **Required Role:** Payment API Access
|
1476
|
+
|
1477
|
+
Similar to *New Transaction Display*, this variant allows developers to update
|
1478
|
+
line item level data currently being displayed on the terminal.
|
1479
|
+
|
1480
|
+
This feature is designed for situations where you want to update the terminal display as
|
1481
|
+
items are scanned. You'll only have to send information to the
|
1482
|
+
terminal that's changed, which usually means the new line item and updated totals.
|
1483
|
+
|
1484
|
+
If the terminal is not in line item display mode and you invoke this endpoint,
|
1485
|
+
the first invocation will behave like a *New Transaction Display* call.
|
1486
|
+
|
1487
|
+
At a minimum, you should send total information as part of a display request,
|
1488
|
+
including `total`, `tax`, and `subtotal`.
|
1489
|
+
|
1490
|
+
You can also send line item level data and each line item can have a `description`,
|
1491
|
+
`qty`, `price`, and `extended` price.
|
1492
|
+
|
1493
|
+
If you fail to send an extended price, BlockChyp will multiply the `qty` by the
|
1494
|
+
`price`. However, we strongly recommend you precalculate all the fields yourself
|
1495
|
+
to ensure consistency. For example, your treatment of floating-point multiplication and rounding
|
1496
|
+
may differ slightly from BlockChyp's.
|
1497
|
+
|
1498
|
+
**Discounts**
|
1499
|
+
|
1500
|
+
You have the option to show discounts on the display as individual line items
|
1501
|
+
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: 'support@blockchyp.com',
|
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.
|
1275
2848
|
|
1276
|
-
|
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.
|
1277
2852
|
|
2853
|
+
The order of priority for the Terminal Branding Stack is given below.
|
1278
2854
|
|
1279
|
-
|
2855
|
+
* Terminal
|
2856
|
+
* Terminal Group
|
2857
|
+
* Merchant
|
2858
|
+
* Organization (Region, Chain, etc)
|
2859
|
+
* Partner
|
2860
|
+
* BlockChyp Default Logo
|
1280
2861
|
|
1281
|
-
#### Display Message
|
1282
2862
|
|
1283
2863
|
|
2864
|
+
#### Media Library
|
1284
2865
|
|
1285
|
-
Displays a message on the payment terminal.
|
1286
2866
|
|
1287
|
-
|
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.
|
1288
2873
|
|
1289
2874
|
|
1290
2875
|
|
@@ -1302,34 +2887,54 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1302
2887
|
|
1303
2888
|
# Set request parameters
|
1304
2889
|
request = {
|
1305
|
-
test: true,
|
1306
|
-
terminalName: 'Test Terminal',
|
1307
|
-
message: 'Thank you for your business.'
|
1308
2890
|
}
|
1309
2891
|
|
1310
|
-
response = blockchyp.
|
2892
|
+
response = blockchyp.media(request)
|
1311
2893
|
|
1312
2894
|
puts "Response: #{response.inspect}"
|
1313
2895
|
|
1314
2896
|
|
1315
2897
|
```
|
1316
2898
|
|
1317
|
-
####
|
2899
|
+
#### Upload Media
|
1318
2900
|
|
1319
2901
|
|
1320
2902
|
|
1321
|
-
|
2903
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
2904
|
+
* **Required Role:** Media Management
|
1322
2905
|
|
1323
|
-
|
1324
|
-
the
|
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.
|
1325
2910
|
|
1326
|
-
|
1327
|
-
|
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.
|
1328
2913
|
|
1329
|
-
|
2914
|
+
The following file formats are accepted as valid uploads:
|
1330
2915
|
|
1331
|
-
|
1332
|
-
|
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.
|
1333
2938
|
|
1334
2939
|
|
1335
2940
|
|
@@ -1347,45 +2952,35 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1347
2952
|
|
1348
2953
|
# Set request parameters
|
1349
2954
|
request = {
|
1350
|
-
|
1351
|
-
|
1352
|
-
|
1353
|
-
yesCaption: 'Yes',
|
1354
|
-
noCaption: 'No'
|
2955
|
+
fileName: 'aviato.png',
|
2956
|
+
fileSize: 18843,
|
2957
|
+
uploadId: '<RANDOM ID>'
|
1355
2958
|
}
|
1356
2959
|
|
1357
|
-
|
2960
|
+
file = File.open("aviato.png")
|
2961
|
+
content = file.read
|
2962
|
+
response = blockchyp.uploadMedia(request, content)
|
1358
2963
|
|
1359
2964
|
puts "Response: #{response.inspect}"
|
1360
2965
|
|
1361
2966
|
|
1362
2967
|
```
|
1363
2968
|
|
1364
|
-
####
|
1365
|
-
|
1366
|
-
|
2969
|
+
#### Upload Status
|
1367
2970
|
|
1368
|
-
Prompts the customer to enter numeric or alphanumeric data.
|
1369
2971
|
|
1370
|
-
Due to PCI rules, free form prompts are not permitted when the response
|
1371
|
-
could be any valid string. The reason for this is that a malicious
|
1372
|
-
developer (not you, of course) could use text prompts to ask the customer to
|
1373
|
-
input a card number or PIN code.
|
1374
|
-
|
1375
|
-
This means that instead of providing a prompt, you provide a `promptType` instead.
|
1376
2972
|
|
1377
|
-
|
2973
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
2974
|
+
* **Required Role:** Media Management
|
1378
2975
|
|
1379
|
-
|
1380
|
-
* **email**: Captures an email address.
|
1381
|
-
* **first-name**: Captures a first name.
|
1382
|
-
* **last-name**: Captures a last name.
|
1383
|
-
* **customer-number**: Captures a customer number.
|
1384
|
-
* **rewards-number**: Captures a rewards number.
|
2976
|
+
This API returns status and progress information about in progress or recently completed uploads.
|
1385
2977
|
|
1386
|
-
|
1387
|
-
the response is returned in the `response` field.
|
2978
|
+
Before calling this API, developers must first start a file upload with `fileSize` and `uploadId` parameters.
|
1388
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.
|
1389
2984
|
|
1390
2985
|
|
1391
2986
|
|
@@ -1403,48 +2998,62 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1403
2998
|
|
1404
2999
|
# Set request parameters
|
1405
3000
|
request = {
|
1406
|
-
|
1407
|
-
terminalName: 'Test Terminal',
|
1408
|
-
|
1409
|
-
# Type of prompt. Can be 'email', 'phone', 'customer-number', or
|
1410
|
-
# 'rewards-number'.
|
1411
|
-
promptType: PromptType::EMAIL
|
3001
|
+
uploadId: '<UPLOAD ID>'
|
1412
3002
|
}
|
1413
3003
|
|
1414
|
-
response = blockchyp.
|
3004
|
+
response = blockchyp.uploadStatus(request)
|
1415
3005
|
|
1416
3006
|
puts "Response: #{response.inspect}"
|
1417
3007
|
|
1418
3008
|
|
1419
3009
|
```
|
1420
3010
|
|
1421
|
-
####
|
3011
|
+
#### Get Media Asset
|
1422
3012
|
|
1423
3013
|
|
1424
3014
|
|
1425
|
-
|
3015
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3016
|
+
* **Required Role:** Media Management
|
1426
3017
|
|
1427
|
-
|
1428
|
-
|
1429
|
-
|
3018
|
+
This API returns a detailed media asset. The data returned includes the exact same media information returned
|
3019
|
+
by the full media library endpoint, including fully qualified URLs pointing to the original media file
|
3020
|
+
and the thumbnail.
|
1430
3021
|
|
1431
|
-
If you pass in `customerRef` and `customerId`, the customer record will be updated
|
1432
|
-
if it exists.
|
1433
3022
|
|
1434
|
-
**Customer Ref**
|
1435
3023
|
|
1436
|
-
The `customerRef` field is optional, but highly recommended as this allows you
|
1437
|
-
to use your own customer identifiers instead of storing BlockChyp's Customer IDs
|
1438
|
-
in your systems.
|
1439
3024
|
|
1440
|
-
|
3025
|
+
```ruby
|
3026
|
+
# frozen_string_literal: true
|
1441
3027
|
|
1442
|
-
|
1443
|
-
|
1444
|
-
|
1445
|
-
|
1446
|
-
|
1447
|
-
|
3028
|
+
require 'blockchyp'
|
3029
|
+
|
3030
|
+
blockchyp = BlockChyp::BlockChyp.new(
|
3031
|
+
ENV['BC_API_KEY'],
|
3032
|
+
ENV['BC_BEARER_TOKEN'],
|
3033
|
+
ENV['BC_SIGNING_KEY']
|
3034
|
+
)
|
3035
|
+
|
3036
|
+
# Set request parameters
|
3037
|
+
request = {
|
3038
|
+
mediaId: '<MEDIA ASSET ID>'
|
3039
|
+
}
|
3040
|
+
|
3041
|
+
response = blockchyp.mediaAsset(request)
|
3042
|
+
|
3043
|
+
puts "Response: #{response.inspect}"
|
3044
|
+
|
3045
|
+
|
3046
|
+
```
|
3047
|
+
|
3048
|
+
#### Delete Media Asset
|
3049
|
+
|
3050
|
+
|
3051
|
+
|
3052
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3053
|
+
* **Required Role:** Media Management
|
3054
|
+
|
3055
|
+
This API deletes a media asset. Note that a media asset cannot be deleted if it is in use in a slide
|
3056
|
+
show or in the terminal branding stack.
|
1448
3057
|
|
1449
3058
|
|
1450
3059
|
|
@@ -1462,32 +3071,26 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1462
3071
|
|
1463
3072
|
# Set request parameters
|
1464
3073
|
request = {
|
1465
|
-
|
1466
|
-
id: 'ID of the customer to update',
|
1467
|
-
customerRef: 'Customer reference string',
|
1468
|
-
firstName: 'FirstName',
|
1469
|
-
lastName: 'LastName',
|
1470
|
-
companyName: 'Company Name',
|
1471
|
-
emailAddress: 'support@blockchyp.com',
|
1472
|
-
smsNumber: '(123) 123-1231'
|
1473
|
-
}
|
3074
|
+
mediaId: '<MEDIA ASSET ID>'
|
1474
3075
|
}
|
1475
3076
|
|
1476
|
-
response = blockchyp.
|
3077
|
+
response = blockchyp.deleteMediaAsset(request)
|
1477
3078
|
|
1478
3079
|
puts "Response: #{response.inspect}"
|
1479
3080
|
|
1480
3081
|
|
1481
3082
|
```
|
1482
3083
|
|
1483
|
-
####
|
3084
|
+
#### List Slide Shows
|
1484
3085
|
|
1485
3086
|
|
1486
3087
|
|
1487
|
-
|
1488
|
-
|
3088
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3089
|
+
* **Required Role:** Media Management
|
1489
3090
|
|
1490
|
-
|
3091
|
+
This API returns all slide shows.
|
3092
|
+
|
3093
|
+
Note that slide level data is not returned with this API. Use the Get Slide Show API to get slide level detail.
|
1491
3094
|
|
1492
3095
|
|
1493
3096
|
|
@@ -1505,24 +3108,26 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1505
3108
|
|
1506
3109
|
# Set request parameters
|
1507
3110
|
request = {
|
1508
|
-
customerId: 'ID of the customer to retrieve'
|
1509
3111
|
}
|
1510
3112
|
|
1511
|
-
response = blockchyp.
|
3113
|
+
response = blockchyp.slideShows(request)
|
1512
3114
|
|
1513
3115
|
puts "Response: #{response.inspect}"
|
1514
3116
|
|
1515
3117
|
|
1516
3118
|
```
|
1517
3119
|
|
1518
|
-
####
|
3120
|
+
#### Get Slide Show
|
1519
3121
|
|
1520
3122
|
|
1521
3123
|
|
1522
|
-
|
3124
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3125
|
+
* **Required Role:** Media Management
|
1523
3126
|
|
1524
|
-
|
1525
|
-
|
3127
|
+
This API returns a single slide show. Slide level detail is returned with the fully qualified thumbnail URL
|
3128
|
+
for each slide.
|
3129
|
+
|
3130
|
+
`slideShowId` is the only required parameter.
|
1526
3131
|
|
1527
3132
|
|
1528
3133
|
|
@@ -1540,25 +3145,31 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1540
3145
|
|
1541
3146
|
# Set request parameters
|
1542
3147
|
request = {
|
1543
|
-
|
3148
|
+
slideShowId: '<SLIDE SHOW ID>'
|
1544
3149
|
}
|
1545
3150
|
|
1546
|
-
response = blockchyp.
|
3151
|
+
response = blockchyp.slideShow(request)
|
1547
3152
|
|
1548
3153
|
puts "Response: #{response.inspect}"
|
1549
3154
|
|
1550
3155
|
|
1551
3156
|
```
|
1552
3157
|
|
1553
|
-
####
|
3158
|
+
#### Update Slide Show
|
1554
3159
|
|
1555
3160
|
|
1556
3161
|
|
1557
|
-
|
3162
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3163
|
+
* **Required Role:** Media Management
|
1558
3164
|
|
1559
|
-
|
1560
|
-
|
1561
|
-
|
3165
|
+
This API updates or creates a slide show. `name`, `delay` and `slides` are required.
|
3166
|
+
|
3167
|
+
The slides property is an array of slides. The Slide data structure has ordinal and thumbnail URL fields,
|
3168
|
+
but these are not required when updating or creating a slide show. Only the `mediaId` field is required
|
3169
|
+
when updating or creating a slide show.
|
3170
|
+
|
3171
|
+
When using the CLI, slides can be specified by sending a comma-separated list of media ids via the `-mediaId`
|
3172
|
+
parameter.
|
1562
3173
|
|
1563
3174
|
|
1564
3175
|
|
@@ -1576,43 +3187,30 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1576
3187
|
|
1577
3188
|
# Set request parameters
|
1578
3189
|
request = {
|
1579
|
-
|
1580
|
-
|
1581
|
-
|
3190
|
+
name: 'Test Slide Show',
|
3191
|
+
delay: 5,
|
3192
|
+
slides: [
|
3193
|
+
{
|
3194
|
+
mediaId: '<MEDIA ID>'
|
3195
|
+
}
|
3196
|
+
]
|
1582
3197
|
}
|
1583
3198
|
|
1584
|
-
response = blockchyp.
|
3199
|
+
response = blockchyp.updateSlideShow(request)
|
1585
3200
|
|
1586
3201
|
puts "Response: #{response.inspect}"
|
1587
3202
|
|
1588
3203
|
|
1589
3204
|
```
|
1590
3205
|
|
1591
|
-
####
|
1592
|
-
|
1593
|
-
|
1594
|
-
|
1595
|
-
This endpoint allows developers to query the gateway for the merchant's batch history.
|
1596
|
-
The data will be returned in descending order of open date with the most recent
|
1597
|
-
batch returned first. The results will include basic information about the batch.
|
1598
|
-
For more detail about a specific batch, consider using the Batch Details API.
|
1599
|
-
|
1600
|
-
**Limiting Results**
|
3206
|
+
#### Delete Slide Show
|
1601
3207
|
|
1602
|
-
This API will return a maximum of 250 results. Use the `maxResults` property to
|
1603
|
-
limit maximum results even further and use the `startIndex` property to
|
1604
|
-
page through results that span multiple queries.
|
1605
3208
|
|
1606
|
-
For example, if you want the ten most recent batches, just pass in a value of
|
1607
|
-
`10` for `maxResults`. Also note that `startIndex` is zero based. Use a value of `0` to
|
1608
|
-
get the first batch in the dataset.
|
1609
3209
|
|
1610
|
-
**
|
3210
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3211
|
+
* **Required Role:** Media Management
|
1611
3212
|
|
1612
|
-
|
1613
|
-
properties to return only those batches opened between those dates.
|
1614
|
-
You can use either `startDate` and `endDate` and you can use date filters
|
1615
|
-
in conjunction with `maxResults` and `startIndex`
|
3213
|
+
This API deletes a slide show `slideShowId` is the only required parameter.
|
1616
3214
|
|
1617
3215
|
|
1618
3216
|
|
@@ -1630,28 +3228,33 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1630
3228
|
|
1631
3229
|
# Set request parameters
|
1632
3230
|
request = {
|
1633
|
-
|
1634
|
-
startIndex: 1
|
3231
|
+
slideShowId: '<SLIDE SHOW ID>'
|
1635
3232
|
}
|
1636
3233
|
|
1637
|
-
response = blockchyp.
|
3234
|
+
response = blockchyp.deleteSlideShow(request)
|
1638
3235
|
|
1639
3236
|
puts "Response: #{response.inspect}"
|
1640
3237
|
|
1641
3238
|
|
1642
3239
|
```
|
1643
3240
|
|
1644
|
-
####
|
3241
|
+
#### Terminal Branding
|
1645
3242
|
|
1646
3243
|
|
1647
3244
|
|
1648
|
-
|
1649
|
-
|
1650
|
-
captured volume broken down by terminal.
|
3245
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3246
|
+
* **Required Role:** Media Management
|
1651
3247
|
|
1652
|
-
|
1653
|
-
|
1654
|
-
|
3248
|
+
This API returns the full branding stack for a given API scope in the order of priority.
|
3249
|
+
|
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
|
+
|
3253
|
+
The `thumbnail` and `previewImage` attributes can be used to support building user interfaces for
|
3254
|
+
managing the branding stack. `previewImage` differs from `thumbnail` in that the preview image is
|
3255
|
+
intended to show how an asset would actually look when displayed on the terminal.
|
3256
|
+
|
3257
|
+
`activeAsset` returns the asset that is currently visible on the terminal.
|
1655
3258
|
|
1656
3259
|
|
1657
3260
|
|
@@ -1669,66 +3272,86 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1669
3272
|
|
1670
3273
|
# Set request parameters
|
1671
3274
|
request = {
|
1672
|
-
batchId: 'BATCHID'
|
1673
3275
|
}
|
1674
3276
|
|
1675
|
-
response = blockchyp.
|
3277
|
+
response = blockchyp.terminalBranding(request)
|
1676
3278
|
|
1677
3279
|
puts "Response: #{response.inspect}"
|
1678
3280
|
|
1679
3281
|
|
1680
3282
|
```
|
1681
3283
|
|
1682
|
-
####
|
3284
|
+
#### Update Branding Asset
|
1683
3285
|
|
1684
3286
|
|
1685
3287
|
|
1686
|
-
|
1687
|
-
|
3288
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3289
|
+
* **Required Role:** Media Management
|
1688
3290
|
|
1689
|
-
|
1690
|
-
most recent transactions.
|
3291
|
+
This API updates or creates a single Branding Asset.
|
1691
3292
|
|
1692
|
-
|
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.
|
1693
3297
|
|
1694
|
-
|
1695
|
-
to limit maximum results even further and use the `startIndex` property to
|
1696
|
-
page through results that span multiple queries.
|
3298
|
+
**Visibility Flags**
|
1697
3299
|
|
1698
|
-
|
1699
|
-
|
1700
|
-
|
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.
|
1701
3304
|
|
1702
|
-
**
|
3305
|
+
**Order and Sequencing**
|
1703
3306
|
|
1704
|
-
|
1705
|
-
|
1706
|
-
You can use either `startDate` or `endDate` and you can use date filters
|
1707
|
-
in conjunction with `maxResults` and `startIndex`
|
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.
|
1708
3309
|
|
1709
|
-
**
|
3310
|
+
**Padding Images**
|
1710
3311
|
|
1711
|
-
|
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.
|
1712
3316
|
|
1713
|
-
**
|
3317
|
+
**Scheduling**
|
1714
3318
|
|
1715
|
-
|
1716
|
-
|
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.
|
1717
3321
|
|
1718
|
-
|
3322
|
+
Branding Assets can be scheduled with effective start and stop dates for seasonal campaigns. These assets can
|
3323
|
+
also be scheduled for specific times of day and specific days of the week.
|
1719
3324
|
|
1720
|
-
|
1721
|
-
|
1722
|
-
|
3325
|
+
* **startDate:** Optional date after which the Branding Asset is eligible for display. Can be provided in MM/DD/YYYY or YYYY-MM-DD format.
|
3326
|
+
* **endDate:** Optional date before which the Branding Asset is eligible for display. Can be provided in MM/DD/YYYY or YYYY-MM-DD format.
|
3327
|
+
* **startTime** Optional time of day after which the branding asset is eligible for display. Must be provided in 24 hour time: HH:MM.
|
3328
|
+
* **endTime** Optional time of day before which the branding asset is eligible for display. Must be provided in 24 hour time format: HH:MM
|
3329
|
+
* **daysOfWeek** For branding assets that should only be displayed on certain days of the week, this field is an array of day of the week constants. (Constants vary by SDK platform.)
|
1723
3330
|
|
1724
|
-
**
|
3331
|
+
**Read Only Fields**
|
1725
3332
|
|
1726
|
-
|
1727
|
-
|
1728
|
-
|
3333
|
+
The Branding Asset data structure has a number of read only fields that are returned when Branding Assets are
|
3334
|
+
retrieved. But these fields are ignored when you try to send them as part of an update. These are derived
|
3335
|
+
or calculated fields and are helpful for displaying branding assets in a management user interface, but
|
3336
|
+
cannot be changed via an API call.
|
1729
3337
|
|
1730
|
-
|
1731
|
-
|
3338
|
+
These fields are:
|
3339
|
+
|
3340
|
+
* ownerId
|
3341
|
+
* merchantId
|
3342
|
+
* organizationId
|
3343
|
+
* partnerId
|
3344
|
+
* userId
|
3345
|
+
* userName
|
3346
|
+
* thumbnail
|
3347
|
+
* lastModified
|
3348
|
+
* editable
|
3349
|
+
* assetType
|
3350
|
+
* ownerType
|
3351
|
+
* ownerTypeCaption
|
3352
|
+
* previewImage
|
3353
|
+
* narrativeEffectiveDates
|
3354
|
+
* narrativeDisplayPeriod
|
1732
3355
|
|
1733
3356
|
|
1734
3357
|
|
@@ -1746,23 +3369,36 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1746
3369
|
|
1747
3370
|
# Set request parameters
|
1748
3371
|
request = {
|
1749
|
-
|
3372
|
+
mediaId: '<MEDIA ID>',
|
3373
|
+
padded: true,
|
3374
|
+
ordinal: 10,
|
3375
|
+
startDate: '01/06/2021',
|
3376
|
+
startTime: '14:00',
|
3377
|
+
endDate: '11/05/2024',
|
3378
|
+
endTime: '16:00',
|
3379
|
+
notes: 'Test Branding Asset',
|
3380
|
+
preview: false,
|
3381
|
+
enabled: true
|
1750
3382
|
}
|
1751
3383
|
|
1752
|
-
response = blockchyp.
|
3384
|
+
response = blockchyp.updateBrandingAsset(request)
|
1753
3385
|
|
1754
3386
|
puts "Response: #{response.inspect}"
|
1755
3387
|
|
1756
3388
|
|
1757
3389
|
```
|
1758
3390
|
|
1759
|
-
####
|
3391
|
+
#### Delete Branding Asset
|
1760
3392
|
|
1761
3393
|
|
1762
3394
|
|
1763
|
-
|
1764
|
-
|
1765
|
-
|
3395
|
+
* **API Credential Types:** Merchant, Partner, & Organization
|
3396
|
+
* **Required Role:** Media Management
|
3397
|
+
|
3398
|
+
This API deletes a Branding Asset from the branding stack.
|
3399
|
+
|
3400
|
+
Note that deleting a Branding Asset does not delete the underlying media from the media library or slide
|
3401
|
+
show from the slide show library.
|
1766
3402
|
|
1767
3403
|
|
1768
3404
|
|
@@ -1780,22 +3416,101 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1780
3416
|
|
1781
3417
|
# Set request parameters
|
1782
3418
|
request = {
|
3419
|
+
assetId: '<BRANDING ASSET ID>'
|
1783
3420
|
}
|
1784
3421
|
|
1785
|
-
response = blockchyp.
|
3422
|
+
response = blockchyp.deleteBrandingAsset(request)
|
1786
3423
|
|
1787
3424
|
puts "Response: #{response.inspect}"
|
1788
3425
|
|
1789
3426
|
|
1790
3427
|
```
|
1791
3428
|
|
1792
|
-
|
3429
|
+
### Merchant Management
|
1793
3430
|
|
1794
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.
|
1795
3439
|
|
1796
|
-
|
1797
|
-
|
1798
|
-
|
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.
|
1799
3514
|
|
1800
3515
|
|
1801
3516
|
|
@@ -1813,23 +3528,29 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1813
3528
|
|
1814
3529
|
# Set request parameters
|
1815
3530
|
request = {
|
1816
|
-
terminalName: 'Test Terminal'
|
1817
3531
|
}
|
1818
3532
|
|
1819
|
-
response = blockchyp.
|
3533
|
+
response = blockchyp.merchantProfile(request)
|
1820
3534
|
|
1821
3535
|
puts "Response: #{response.inspect}"
|
1822
3536
|
|
1823
3537
|
|
1824
3538
|
```
|
1825
3539
|
|
1826
|
-
####
|
3540
|
+
#### Get Merchants
|
1827
3541
|
|
1828
3542
|
|
1829
3543
|
|
1830
|
-
|
1831
|
-
|
1832
|
-
|
3544
|
+
* **API Credential Types:** Partner & Organization
|
3545
|
+
* **Required Role:** Merchant Management
|
3546
|
+
|
3547
|
+
This is a partner or organization level API that can be used to return the merchant portfolio.
|
3548
|
+
|
3549
|
+
Live merchants are returned by default. Use the `test` flag to return only test merchants. The
|
3550
|
+
results returned include detailed settings including underwriting controlled flags.
|
3551
|
+
|
3552
|
+
A maximum of 250 merchants are returned by default. For large merchant portfolios, the `maxResults`
|
3553
|
+
and `startIndex` field can be used to reduce the page size and page through multiple pages of results.
|
1833
3554
|
|
1834
3555
|
|
1835
3556
|
|
@@ -1847,22 +3568,87 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1847
3568
|
|
1848
3569
|
# Set request parameters
|
1849
3570
|
request = {
|
1850
|
-
|
1851
|
-
transactionRef: '*'
|
3571
|
+
test: true
|
1852
3572
|
}
|
1853
3573
|
|
1854
|
-
response = blockchyp.
|
3574
|
+
response = blockchyp.getMerchants(request)
|
1855
3575
|
|
1856
3576
|
puts "Response: #{response.inspect}"
|
1857
3577
|
|
1858
3578
|
|
1859
3579
|
```
|
1860
3580
|
|
1861
|
-
####
|
3581
|
+
#### Update Merchant
|
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**
|
1862
3596
|
|
3597
|
+
The following fields are basic descriptive fields that can be used to describe and identify merchants.
|
1863
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.
|
1864
3613
|
|
1865
|
-
|
3614
|
+
**Batch and Terminal Settings**
|
3615
|
+
|
3616
|
+
The following fields are used to control batch closure and high level terminal configuration.
|
3617
|
+
|
3618
|
+
* **batchCloseTime:** Time in 24 hour HH:MM format when batches will automatically close in the merchant's local time. Defaults to 3 AM.
|
3619
|
+
* **autoBatchClose:** Flag the determines whether or not batches will automatically close. Defaults to true.
|
3620
|
+
* **disableBatchEmails:** Flag that optionally turns off automatic batch closure notification emails.
|
3621
|
+
* **cooldownTimeout:** The amount of time in seconds after a transactions for which the transaction response is displayed on the terminal. After the cooldown period elapses, the terminal will revert to the idle state and display the currently active terminal branding.
|
3622
|
+
* **surveyTimeout:** The amount of time in seconds a survey question should be displayed on a terminal before reverting to the idle screen.
|
3623
|
+
* **pinEnabled:** Enables pin code entry for debit cards, EBT cards, and EMV cards with pin CVMs. Will be ignored if terminals are not injected with the proper encryption keys.
|
3624
|
+
* **pinBypassEnabled:** Enable pin bypass for debit transactions.
|
3625
|
+
* **cashBackEnabled:** Enables cash back for debit transactions.
|
3626
|
+
* **cashbackPresets:** An array of four default values for cashback amounts when cashback is enabled.
|
3627
|
+
* **storeAndForwardEnabled:** Enables automatic store and forward during network outages. Store and Forward does not support cash back, refunds, EBT, or gift card transactions.
|
3628
|
+
* **storeAndForwardFloorLimit:** Maximum dollar value of a store and forward transaction.
|
3629
|
+
* **ebtEnabled:** Enables EBT (SNAP) on BlockChyp terminals.
|
3630
|
+
* **tipEnabled:** Enables tips entry on the terminal.
|
3631
|
+
* **promptForTip:** If true, the terminal will always prompt for a tip, even if the API call does not request a tip prompt.
|
3632
|
+
* **tipDefaults:** An array of exactly three percentages that will be used to calculate default tip amounts.
|
3633
|
+
* **giftCardsDisabled:** Disables BlockChyp gift cards. Normally only used if the merchant is using an alternate gift card system.
|
3634
|
+
* **digitalSignaturesEnabled:** Enables electronic signature capture for mag stripe cards and EMV cards with Signature CVMs.
|
3635
|
+
* **digitalSignatureReversal:** Will cause a transaction to auto-reverse if the consumer refuses to provide a signature.
|
3636
|
+
* **manualEntryEnabled:** Enables manual card entry.
|
3637
|
+
* **manualEntryPromptZip:** Requires zip code based address verification for manual card entry.
|
3638
|
+
* **manualEntryPromptStreetNumber:** Requires street/address based verification for manual card entry.
|
3639
|
+
|
3640
|
+
**Card Brand and Transaction Settings**
|
3641
|
+
|
3642
|
+
* **freeRangeRefundsEnabled:** Enables direct refunds that do not reference a previous transaction.
|
3643
|
+
* **partialAuthEnabled:** Indicates that partial authorizations (usually for gift card support) are enabled.
|
3644
|
+
* **splitBankAccountsEnabled:** Used for law firm merchants only.
|
3645
|
+
* **contactlessEmv:** Enables contactless/tap transactions on a terminal. Defaults to true.
|
3646
|
+
* **visa:** Enables Visa transactions.
|
3647
|
+
* **masterCard:** Enables MasterCard transactions.
|
3648
|
+
* **amex:** Enables American Express transactions.
|
3649
|
+
* **discover:** Enables Discover transactions.
|
3650
|
+
* **jcb:** Enables JCB (Japan Card Bureau) transactions.
|
3651
|
+
* **unionPay:** Enables China UnionPay transactions.
|
1866
3652
|
|
1867
3653
|
|
1868
3654
|
|
@@ -1880,21 +3666,33 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1880
3666
|
|
1881
3667
|
# Set request parameters
|
1882
3668
|
request = {
|
1883
|
-
|
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
|
+
}
|
1884
3679
|
}
|
1885
3680
|
|
1886
|
-
response = blockchyp.
|
3681
|
+
response = blockchyp.updateMerchant(request)
|
1887
3682
|
|
1888
3683
|
puts "Response: #{response.inspect}"
|
1889
3684
|
|
1890
3685
|
|
1891
3686
|
```
|
1892
3687
|
|
1893
|
-
####
|
3688
|
+
#### Merchant Users
|
1894
3689
|
|
1895
3690
|
|
1896
3691
|
|
1897
|
-
|
3692
|
+
* **API Credential Types:** Partner & Organization
|
3693
|
+
* **Required Role:** Merchant Management
|
3694
|
+
|
3695
|
+
This API returns all users and pending invites associated with a merchant account including any assigned role codes.
|
1898
3696
|
|
1899
3697
|
|
1900
3698
|
|
@@ -1912,27 +3710,31 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1912
3710
|
|
1913
3711
|
# Set request parameters
|
1914
3712
|
request = {
|
1915
|
-
|
3713
|
+
merchantId: '<MERCHANT ID>'
|
1916
3714
|
}
|
1917
3715
|
|
1918
|
-
response = blockchyp.
|
3716
|
+
response = blockchyp.merchantUsers(request)
|
1919
3717
|
|
1920
3718
|
puts "Response: #{response.inspect}"
|
1921
3719
|
|
1922
3720
|
|
1923
3721
|
```
|
1924
3722
|
|
1925
|
-
####
|
3723
|
+
#### Invite Merchant User
|
1926
3724
|
|
1927
3725
|
|
1928
3726
|
|
1929
|
-
|
1930
|
-
|
3727
|
+
* **API Credential Types:** Partner & Organization
|
3728
|
+
* **Required Role:** Merchant Management
|
1931
3729
|
|
1932
|
-
|
1933
|
-
|
1934
|
-
|
1935
|
-
|
3730
|
+
Invites a new user to join a merchant account. `email`, `firstName`, and `lastName` are required.
|
3731
|
+
|
3732
|
+
The user will be sent an invite email with steps for creating a BlockChyp account and linking it to
|
3733
|
+
a merchant account. If the user already has a BlockChyp user account, the new user signup wil be skipped
|
3734
|
+
and the existing user account will be linked to the merchant account.
|
3735
|
+
|
3736
|
+
Developers can optionally restrict the user's access level by sending one or more role codes.
|
3737
|
+
Otherwise, the user will be given the default merchant user role. (STDMERCHANT)
|
1936
3738
|
|
1937
3739
|
|
1938
3740
|
|
@@ -1950,22 +3752,27 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1950
3752
|
|
1951
3753
|
# Set request parameters
|
1952
3754
|
request = {
|
1953
|
-
|
3755
|
+
email: 'Email address for the invite'
|
1954
3756
|
}
|
1955
3757
|
|
1956
|
-
response = blockchyp.
|
3758
|
+
response = blockchyp.inviteMerchantUser(request)
|
1957
3759
|
|
1958
3760
|
puts "Response: #{response.inspect}"
|
1959
3761
|
|
1960
3762
|
|
1961
3763
|
```
|
1962
3764
|
|
1963
|
-
####
|
3765
|
+
#### Add Test Merchant
|
1964
3766
|
|
1965
3767
|
|
1966
3768
|
|
1967
|
-
|
1968
|
-
|
3769
|
+
* **API Credential Types:** Partner
|
3770
|
+
* **Required Role:** Merchant Management
|
3771
|
+
|
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
|
+
|
3775
|
+
Settings can be changed by using the Update Merchant API.
|
1969
3776
|
|
1970
3777
|
|
1971
3778
|
|
@@ -1983,25 +3790,25 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
1983
3790
|
|
1984
3791
|
# Set request parameters
|
1985
3792
|
request = {
|
1986
|
-
|
1987
|
-
|
3793
|
+
dbaName: 'DBA Name',
|
3794
|
+
companyName: 'Corporate Entity Name'
|
1988
3795
|
}
|
1989
3796
|
|
1990
|
-
response = blockchyp.
|
3797
|
+
response = blockchyp.addTestMerchant(request)
|
1991
3798
|
|
1992
3799
|
puts "Response: #{response.inspect}"
|
1993
3800
|
|
1994
3801
|
|
1995
3802
|
```
|
1996
3803
|
|
1997
|
-
####
|
3804
|
+
#### Delete Test Merchant
|
1998
3805
|
|
1999
3806
|
|
2000
3807
|
|
2001
|
-
|
3808
|
+
* **API Credential Types:** Partner
|
3809
|
+
* **Required Role:** Merchant Management
|
2002
3810
|
|
2003
|
-
This
|
2004
|
-
for the same underlying card.
|
3811
|
+
This partner API can be used to delete unused test merchant accounts. `merchantId` is a required parameter.
|
2005
3812
|
|
2006
3813
|
|
2007
3814
|
|
@@ -2019,17 +3826,20 @@ blockchyp = BlockChyp::BlockChyp.new(
|
|
2019
3826
|
|
2020
3827
|
# Set request parameters
|
2021
3828
|
request = {
|
2022
|
-
|
2023
|
-
customerId: 'Customer to unlink'
|
3829
|
+
merchantId: '<MERCHANT ID>'
|
2024
3830
|
}
|
2025
3831
|
|
2026
|
-
response = blockchyp.
|
3832
|
+
response = blockchyp.deleteTestMerchant(request)
|
2027
3833
|
|
2028
3834
|
puts "Response: #{response.inspect}"
|
2029
3835
|
|
2030
3836
|
|
2031
3837
|
```
|
2032
3838
|
|
3839
|
+
|
3840
|
+
|
3841
|
+
|
3842
|
+
|
2033
3843
|
## Running Integration Tests
|
2034
3844
|
|
2035
3845
|
If you'd like to run the integration tests, create a new file on your system
|