BlockChyp iOS SDK

This is the SDK for iOS. Like all BlockChyp SDKs, it provides a full client for the BlockChyp gateway and BlockChyp payment terminals. The SDK is written in Objective-C, but can be used by Swift developers as well.

Installation

The preferred method of installing BlockChyp is via cocoapods. Add the following dependency to your Podfile and type pod install.

  pod 'BlockChyp', '~> 2.15.24'

Note: If you're using Swift, you'll need to make sure dynamic frameworks are turned on in your Podfile or create a bridging header.

A Simple Objective-C Example

The following snippet illustrates how to run a simple terminal transaction from Objective-C.

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request[@"test"] = @YES;
  request[@"terminalName"] = @"Test Terminal";
  request[@"amount"] = @"55.00";
  [client chargeWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"Approved");
    }
    NSLog(@"%@: %@", @"authCode", [response objectForKey:@"authCode"])
    NSLog(@"%@: %@", @"authorizedAmount", [response objectForKey:@"authorizedAmount"])
  }];
  [pool drain];
  return 0;
}

A Simple Swift Example

The following snippet illustrates how to run a simple terminal transaction from Swift.

import BlockChyp

let client = BlockChyp.init(
  apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
  bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
  signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
)

var request: [String:Any] = [:]
request["test"] = true
request["terminalName"] = "Test Terminal"
request["amount"] = "55.00"
client.charge(withRequest: request, handler: { (request, response, error) in
  let approved = response["approved"] as? Bool
  if (approved.unsafelyUnwrapped) {
    NSLog("Approved")
  }
  NSLog("authCode" + ": " + (response["authCode"] as? String).unsafelyUnwrapped)
  NSLog("authorizedAmount" + ": " + (response["authorizedAmount"] as? String).unsafelyUnwrapped)
})

All calls to the BlockChyp SDK must be asyncronous, so you must provide a BlockChypCompletionHandler block for each call. The completion handler is declared as a type in BlockChypClient.h.

typedef void(^BlockChypCompletionHandler)(NSDictionary *request, NSDictionary *response, NSError * _Nullable error);

The block will be passed a copy of the original request NSDictionary and the response as an NSDictionary along with an NSError with any error information that may be relevant.

Additional Documentation

Complete documentation can be found on our Developer Documentation Portal.

Getting a Developer Kit

In order to test your integration with real terminals, you'll need a BlockChyp Developer Kit. Our kits include a fully functioning payment terminal with test pin encryption keys. Every kit includes a comprehensive set of test cards with test cards for every major card brand and entry method, including Contactless and Contact EMV and mag stripe cards. Each kit also includes test gift cards for our blockchain gift card system.

Access to BlockChyp's developer program is currently invite only, but you can request an invitation by contacting our engineering team at [email protected].

You can also view a number of long form demos and learn more about us on our YouTube Channel.

Transaction Code Examples

You don't want to read words. You want examples. Here's a quick rundown of the stuff you can do with the BlockChyp IOS SDK and a few basic examples.

Payment Endpoints

These are the core payment APIs used to execute and work with payment transactions in BlockChyp.

Charge

• API Credential Types: Merchant
• Required Role: Payment API Access

Our most popular transaction executes a standard authorization and capture. This is the most basic of basic payment transactions, typically used in conventional retail.

Charge transactions can use a payment terminal to capture a payment or use a previously enrolled payment token.

Terminal Transactions

For terminal transactions, make sure you pass in the terminal name using the terminalName property.

Token Transactions

If you have a payment token, omit the terminalName property and pass in the token with the token property instead.

Card Numbers and Mag Stripes

You can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will put you in PCI scope and the most common vector for POS breaches is keylogging. If you use terminals for manual card entry, you'll bypass any keyloggers that might be maliciously running on the point-of-sale system.

Common Variations

• 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.
• EBT: Set the CardType field to [NSNumber numberWithInt:CARD_TYPE_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.
• 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.
• 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 [NSNumber numberWithInt:CARD_TYPE_EBT] for manual EBT card entry.
• 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.
• 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.
• 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.
• 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.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["amount"] = "55.00"
    [client chargeWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
    NSLog(@"%@: %@", @"authCode", [response objectForKey:@"authCode"])
    NSLog(@"%@: %@", @"authorizedAmount", [response objectForKey:@"authorizedAmount"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["amount"] = "55.00"
      client.charge(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
      NSLog("authCode" + ": " + (response["authCode"] as? String).unsafelyUnwrapped)
      NSLog("authorizedAmount" + ": " + (response["authorizedAmount"] as? String).unsafelyUnwrapped)
    })
  }

Preauthorization

• API Credential Types: Merchant
• Required Role: Payment API Access

A preauthorization puts a hold on funds and must be captured later. This is used in scenarios where the final transaction amount might change. A common example is fine dining, where a tip adjustment is required before final settlement.

Another use case for preauthorization is e-commerce. Typically, an online order is preauthorized at the time of the order and then captured when the order ships.

Preauthorizations can use a payment terminal to capture a payment or use a previously enrolled payment token.

Terminal Transactions

For terminal transactions, make sure you pass in the terminal name using the terminalName property.

Token Transactions

If you have a payment token, omit the terminalName property and pass in the token with the token property instead.

Card Numbers and Mag Stripes

You can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will put you in PCI scope and the most common vector for POS breaches is key logging. If you use terminals for manual card entry, you'll bypass any key loggers that might be maliciously running on the point-of-sale system.

Cryptocurrency

Note that preauths are not supported for cryptocurrency.

Common Variations

• 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 [NSNumber numberWithInt:CARD_TYPE_EBT] for manual EBT card entry.
• Inline Tokenization: You can enroll the payment method in the token vault in line 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.
• Prompting for Tips: Set the PromptForTip field if you'd like to prompt the customer for a tip before authorization. You can prompt for tips as part of a preauthorization, although it's not a very common approach.
• Cash Discounting and Surcharging: The Surcharge and CashDiscount fields can be used together to support cash discounting or surcharge problems. Consult the Cash Discount documentation for more details.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["amount"] = "27.00"
    [client preauthWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
    NSLog(@"%@: %@", @"authCode", [response objectForKey:@"authCode"])
    NSLog(@"%@: %@", @"authorizedAmount", [response objectForKey:@"authorizedAmount"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["amount"] = "27.00"
      client.preauth(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
      NSLog("authCode" + ": " + (response["authCode"] as? String).unsafelyUnwrapped)
      NSLog("authorizedAmount" + ": " + (response["authorizedAmount"] as? String).unsafelyUnwrapped)
    })
  }

Capture Preauthorization

• API Credential Types: Merchant
• Required Role: Payment API Access

This API allows you to capture a previously approved preauthorization.

You'll need to make sure you pass in the Transaction ID returned by the original preauth transaction so we know which transaction we're capturing. If you want to capture the transaction for the exact amount of the preauth, the Transaction ID is all you need to pass in.

You can adjust the total if you need to by passing in a new amount. We also recommend you pass in updated amounts for tax and tip as it can sometimes reduce your interchange fees. (Level II Processing, for example.)

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["transactionId"] = "<ORIGINAL TRANSACTION ID>"
  request["amount"] = "32.00"
    [client captureWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["transactionId"] = "<ORIGINAL TRANSACTION ID>"
    request["amount"] = "32.00"
      client.capture(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
    })
  }

Refund

• API Credential Types: Merchant
• Required Role: Payment API Access

It's not ideal, but sometimes customers want their money back.

Our refund API allows you to confront this unpleasant reality by executing refunds in a few different scenarios.

The most fraud resistent method is to execute refunds in the context of a previous transaction. You should always keep track of the Transaction ID returned in a BlockChyp response. To refund the full amount of the previous transaction, just pass in the original Transaction ID with the refund requests.

Partial Refunds

For a partial refund, just pass in an amount along with the Transaction ID. The only rule is that the amount must be equal to or less than the original transaction. You can execute multiple partial refunds against the same original transaction as long as the total refunded amount doesn't exceed the original amount.

Tokenized Refunds

You can also use a token to execute a refund. Pass in a token instead of the Transaction ID and the desired refund amount.

Free Range Refunds

When you execute a refund without referencing a previous transaction, we call this a free range refund.

We don't recommend this type of refund, but it is permitted. If you absolutely insist on doing it, pass in a Terminal Name and an amount.

You can execute a manual or keyed refund by passing the ManualEntry field to a free range refund request.

Gift Card Refunds

Gift card refunds are allowed in the context of a previous transaction, but free range gift card refunds are not allowed. Use the gift card activation API if you need to add more funds to a gift card.

Store and Forward Support

Refunds are not permitted when a terminal falls back to store and forward mode.

Auto Voids

If a refund referencing a previous transaction is executed for the full amount before the original transaction's batch is closed, the refund is automatically converted to a void. This saves the merchant a little bit of money.

Cryptocurrency

Note that refunds are not supported for cryptocurrency. You must refund crypto transactions manually from your cryptocurrency wallet.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["transactionId"] = "<PREVIOUS TRANSACTION ID>"
  request["amount"] = "5.00"
    [client refundWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["transactionId"] = "<PREVIOUS TRANSACTION ID>"
    request["amount"] = "5.00"
      client.refund(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
    })
  }

Void

• API Credential Types: Merchant
• Required Role: Payment API Access

Mistakes happen. If a transaction is made by mistake, you can void it with this API. All that's needed is to pass in a Transaction ID and execute the void before the original transaction's batch closes.

Voids work with EBT and gift card transactions with no additional parameters.

Cryptocurrency

Note that voids are not supported for cryptocurrency. You must refund crypto transactions manually from your cryptocurrency wallet.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["transactionId"] = "<PREVIOUS TRANSACTION ID>"
    [client voidWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["transactionId"] = "<PREVIOUS TRANSACTION ID>"
      client.void(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
    })
  }

Time Out Reversal

• API Credential Types: Merchant
• Required Role: Payment API Access

Payment transactions require a stable network to function correctly and no network is stable all the time. Time out reversals are a great line of defense against accidentally double charging consumers when payments are retried during shaky network conditions.

We highly recommend developers use this API whenever a charge, preauth, or refund transaction times out. If you don't receive a definitive response from BlockChyp, you can't be certain about whether or not the transaction went through.

The best practice in this situation is to send a time out reversal request. Time out reversals check for a transaction and void it if it exists.

The only caveat is that developers must use the transactionRef property (txRef for the CLI) when executing charge, preauth, and refund transactions.

The reason for this requirement is that if a system never receives a definitive response for a transaction, the system would never have received the BlockChyp generated Transaction ID. We have to fall back to Transaction Ref to identify a transaction.

Cryptocurrency

Note that refunds are not supported for cryptocurrency. You must refund crypto transactions manually from your cryptocurrency wallet.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["transactionRef"] = "<LAST TRANSACTION REF>"
    [client reverseWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["transactionRef"] = "<LAST TRANSACTION REF>"
      client.reverse(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
    })
  }

Gift Card Activation

• API Credential Types: Merchant
• Required Role: Payment API Access

This API activates or adds value to BlockChyp gift cards. Just pass in the terminal name and the amount to add to the card. Once the customer swipes their card, the terminal will use keys on the mag stripe to add value to the card.

You don't need to handle a new gift card activation or a gift card recharge any differently. The terminal firmware will figure out what to do on its own while also returning the new balance for the gift card.

This is the part of the system where BlockChyp's blockchain DNA comes closest to the surface. The BlockChyp gift card system doesn't really use gift card numbers. This means they can't be stolen.

BlockChyp identifies cards with an elliptic curve public key instead. Gift card transactions are actually blocks signed with those keys. This means there are no shared secrets sent over the network. To keep track of a BlockChyp gift card, hang on to the public key returned during gift card activation. That's the gift card's elliptic curve public key.

We sometimes print numbers on our gift cards, but these are actually decimal encoded hashes of a portion of the public key to make our gift cards seem normal to normies. They can be used for balance checks and play a lookup role in online gift card authorization, but are of little use beyond that.

Voids and Reversals

Gift card activations can be voided and reversed just like any other BlockChyp transaction. Use the Transaction ID or Transaction Ref to identify the gift activation transaction as you normally would for voiding or reversing a conventional payment transaction.

Importing Gift Cards

BlockChyp does have the ability to import gift card liability from conventional gift card platforms. Unfortunately, BlockChyp does not support activating cards on third party systems. However, you can import your outstanding gift cards and customers can swipe them on the terminals like BlockChyp's standard gift cards.

No special coding is required to access this feature. The gateway and terminal firmware handle everything for you.

Third Party Gift Card Networks

BlockChyp does not currently provide any native support for other gift card platforms beyond importing gift card liability. We do have a white listing system that can be used to support your own custom gift card implementations. We have a security review process before we can allow a BIN range to be white listed, so contact [email protected] if you need to white list a BIN range.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["amount"] = "50.00"
    [client giftActivateWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
    NSLog(@"%@: %@", @"amount", [response objectForKey:@"amount"])
    NSLog(@"%@: %@", @"currentBalance", [response objectForKey:@"currentBalance"])
    NSLog(@"%@: %@", @"publicKey", [response objectForKey:@"publicKey"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["amount"] = "50.00"
      client.giftActivate(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
      NSLog("amount" + ": " + (response["amount"] as? String).unsafelyUnwrapped)
      NSLog("currentBalance" + ": " + (response["currentBalance"] as? String).unsafelyUnwrapped)
      NSLog("publicKey" + ": " + (response["publicKey"] as? String).unsafelyUnwrapped)
    })
  }

Balance

• API Credential Types: Merchant
• Required Role: Payment API Access

This API checks a gift or EBT card balance.

Gift Card Balance Checks

For gift cards, pass in a terminal name and the customer will be prompted to swipe a card on that terminal. The remaining balance will be displayed briefly on the terminal screen and the API response will include the gift card's public key and the remaining balance.

EBT Balance Checks

All EBT transactions require a PIN, so to check an EBT card balance, you need to pass in the ebt flag just like you would for a normal EBT charge transaction. The customer will be prompted to swipe their card and enter a PIN code. If everything checks out, the remaining balance on the card will be displayed on the terminal for the customer and returned with the API response.

Testing Gift Card Balance Checks

Test gift card balance checks work no differently than live gift cards. You must activate a test gift card first to test balance checks. Test gift cards are real blockchain cards that live on our parallel test blockchain.

Testing EBT Gift Card Balance Checks

All test EBT transactions assume a starting balance of $100.00. As a result, test EBT balance checks always return a balance of $100.00.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["cardType"] = [NSNumber numberWithInt:CARD_TYPE_EBT]
    [client balanceWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["cardType"] = [NSNumber numberWithInt:CARD_TYPE_EBT]
      client.balance(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Close Batch

• API Credential Types: Merchant
• Required Role: Payment API Access

This API will close the merchant's batch if it's currently open.

By default, merchant batches will close automatically at 3 AM in their local time zone. The automatic batch closure time can be changed in the Merchant Profile or disabled completely.

If automatic batch closure is disabled, you'll need to use this API to close the batch manually.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
    [client closeBatchWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
      client.closeBatch(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Send Payment Link

• API Credential Types: Merchant
• Required Role: Payment API Access

This API allows you to send an invoice to a customer and capture payment via a BlockChyp hosted payment page.

If you set the autoSend flag, BlockChyp will send a basic invoice email to the customer for you that includes the payment link. If you'd rather have more control over the look of the email message, you can omit the autoSend flag and send the customer email yourself.

There are a lot of optional parameters for this API, but at a minimum you'll need to pass in a total, customer name, and email address. (Unless you use the cashier flag.)

Customer Info

Unless you're using the cashier flag, you must specify a customer; either by creating a new customer record inline or passing in an existing Customer ID or Customer Ref.

Line Item Level Data

It's not strictly required, but we strongly recommend sending line item level detail with every request. It will make the invoice look more complete and the data format for line item level data is the exact same format used for terminal line item display, so the same code can be used to support both areas.

Descriptions

You can also provide a free form description or message to display near the bottom of the invoice. Usually this is some kind of thank you note or instruction.

Terms and Conditions

You can include long form contract language with a request and capture terms and conditions accepted at the same time payment is captured.

The interface is identical to that used for the terminal based Terms and Conditions API in that you can pass in content directly via tcContent or via a preconfigured template via tcAlias. The Terms and Conditions log will also be updated when agreement acceptance is incorporated into a send link request.

Auto Send

BlockChyp does not send the email notification automatically. This safeguard prevents real emails from going out when you may not expect them If you want BlockChyp to send the email for you, just add the autoSend flag with all requests.

Cryptocurrency

If the merchant is configured to support cryptocurrency transactions, the payment page will display additional UI widgets that allowing customers to switch to a crypto payment method.

Tokenization

Add the enroll flag to a send link request to enroll the payment method in the token vault.

Cashier Facing Card Entry

BlockChyp can be used to generate internal/cashier facing card entry pages as well. This is designed for situations where you might need to take a phone order and don't have an available terminal.

If you pass in the cashier flag, no email will be sent and you'll be able to load the link in a browser or iframe for payment entry. When the cashier flag is used, the autoSend flag will be ignored.

Note that cryptocurrency is not supported for cashier facing payment entry.

Payment Notifications

When a customer successfully submits payment, the merchant will receive an email notifying them that the payment was received.

Real Time Callback Notifications

Email notifications are fine, but you may want your system to be informed immediately whenever a payment event occurs. By using the optional callbackUrl request property, you can specify a URL to which the Authorization Response will be posted every time the user submits a payment, whether approved or otherwise.

The response will be sent as a JSON encoded POST request and will be the exact same format as all BlockChyp charge and preauth transaction responses.

Status Polling

If real time callbacks aren't practical or necessary in your environment, you can always use the Transaction Status API described below.

A common use case for the send link API with status polling is curbside pickup. You could have your system check the Transaction Status when a customer arrives to ensure it's been paid without necessarily needing to create background threads to constantly poll for status updates.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["transactionRef"] = "<TX REF>"
  request["amount"] = "199.99"
  request["description"] = "Widget"
  request["subject"] = "Widget invoice"
  var transaction: [String:Any] = [:]
  transaction["subtotal"] = "195.00"
  transaction["tax"] = "4.99"
  transaction["total"] = "199.99"
  var items = [Any]();
  var items1: [String:Any] = [:]
  items1["description"] = "Widget"
  items1["price"] = "195.00"
  items1["quantity"] = 1
  items.append(items1)
  transaction["items"] = items
  request["transaction"] = transaction
  request["autoSend"] = true
  var customer: [String:Any] = [:]
  customer["customerRef"] = "Customer reference string"
  customer["firstName"] = "FirstName"
  customer["lastName"] = "LastName"
  customer["companyName"] = "Company Name"
  customer["emailAddress"] = "[email protected]"
  customer["smsNumber"] = "(123) 123-1231"
  request["customer"] = customer
    [client sendPaymentLinkWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"url", [response objectForKey:@"url"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["transactionRef"] = "<TX REF>"
    request["amount"] = "199.99"
    request["description"] = "Widget"
    request["subject"] = "Widget invoice"
    var transaction: [String:Any] = [:]
    transaction["subtotal"] = "195.00"
    transaction["tax"] = "4.99"
    transaction["total"] = "199.99"
    var items = [Any]();
    var items1: [String:Any] = [:]
    items1["description"] = "Widget"
    items1["price"] = "195.00"
    items1["quantity"] = 1
    items.append(items1)
    transaction["items"] = items
    request["transaction"] = transaction
    request["autoSend"] = true
    var customer: [String:Any] = [:]
    customer["customerRef"] = "Customer reference string"
    customer["firstName"] = "FirstName"
    customer["lastName"] = "LastName"
    customer["companyName"] = "Company Name"
    customer["emailAddress"] = "[email protected]"
    customer["smsNumber"] = "(123) 123-1231"
    request["customer"] = customer
      client.sendPaymentLink(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("url" + ": " + (response["url"] as? String).unsafelyUnwrapped)
    })
  }

Cancel Payment Link

• API Credential Types: Merchant
• Required Role: Payment API Access

This API cancels a payment link.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["linkCode"] = "<PAYMENT LINK CODE>"
    [client cancelPaymentLinkWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["linkCode"] = "<PAYMENT LINK CODE>"
      client.cancelPaymentLink(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Transaction Status

• API Credential Types: Merchant
• Required Role: Payment API Access

This API returns the current status for any transaction. You can lookup a transaction by its BlockChyp assigned Transaction ID or your own Transaction Ref.

You should alway use globally unique Transaction Ref values, but in the event that you duplicate Transaction Refs, the most recent transaction matching your Transaction Ref is returned.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["transactionId"] = "<TRANSACTION ID>"
    [client transactionStatusWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"responseDescription", [response objectForKey:@"responseDescription"])
    NSLog(@"%@: %@", @"authorizedAmount", [response objectForKey:@"authorizedAmount"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["transactionId"] = "<TRANSACTION ID>"
      client.transactionStatus(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("responseDescription" + ": " + (response["responseDescription"] as? String).unsafelyUnwrapped)
      NSLog("authorizedAmount" + ": " + (response["authorizedAmount"] as? String).unsafelyUnwrapped)
    })
  }

Cash Discount

• API Credential Types: Merchant
• Required Role: Payment API Access

This API calculates the surcharge, cash discount, and total amounts for cash transactions.

If you're using BlockChyp's cash discounting features, you can use this endpoint to ensure the numbers and receipts for true cash transactions are consistent with transactions processed by BlockChyp.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["amount"] = "100.00"
  request["cashDiscount"] = true
  request["surcharge"] = true
    [client cashDiscountWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"amount", [response objectForKey:@"amount"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["amount"] = "100.00"
    request["cashDiscount"] = true
    request["surcharge"] = true
      client.cashDiscount(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("amount" + ": " + (response["amount"] as? String).unsafelyUnwrapped)
    })
  }

Batch History

• API Credential Types: Merchant
• Required Role: Payment API Access

This endpoint allows developers to query the gateway for the merchant's batch history. The data will be returned in descending order of open date with the most recent batch returned first. The results will include basic information about the batch. Consider using the Batch Details API for more detail about a specific batch.

Limiting Results

This API will return a maximum of 250 results. Use the maxResults property to limit maximum results even further and use the startIndex property to page through results that span multiple queries.

For example, if you want the ten most recent batches, pass in a value of 10 for maxResults. Also note that startIndex is zero based. Use a value of 0 to get the first batch in the dataset.

Filtering by Date Range

You can also filter results by date. Use the startDate and endDate properties to return only those batches opened between those dates. You can use either startDate and endDate and you can use date filters in conjunction with maxResults and startIndex

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["maxResults"] = 250
  request["startIndex"] = 0
    [client batchHistoryWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["maxResults"] = 250
    request["startIndex"] = 0
      client.batchHistory(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Batch Details

• API Credential Types: Merchant
• Required Role: Payment API Access

This API allows developers to pull down details for a specific batch, including captured volume, gift card activity, expected deposit, and captured volume broken down by terminal.

The only required request parameter is batchId. Batch IDs are returned with every transaction response and can be discovered using the Batch History API.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["batchId"] = "<BATCH ID>"
    [client batchDetailsWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"capturedAmount", [response objectForKey:@"capturedAmount"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["batchId"] = "<BATCH ID>"
      client.batchDetails(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("capturedAmount" + ": " + (response["capturedAmount"] as? String).unsafelyUnwrapped)
    })
  }

Transaction History

• API Credential Types: Merchant
• Required Role: Payment API Access

This endpoint provides several different methods to sift through transaction history.

By default with no filtering properties, this endpoint will return the 250 most recent transactions.

Limiting Results

This API will return a maximum of 50 results in a single query. Use the maxResults property to limit maximum results even further and use the startIndex property to page through results that span multiple queries.

For example, if you want the ten most recent batches, pass in a value of 10 for maxResults. Also note that startIndex is zero based. Use a value of 0 to get the first transaction in the dataset.

Filtering By Date Range

You can also filter results by date. Use the startDate and endDate properties to return only transactions run between those dates. You can use either startDate or endDate and you can use date filters in conjunction with maxResults and startIndex

Filtering By Batch

To restrict results to a single batch, pass in the batchId parameter.

Filtering By Terminal

To restrict results to those executed on a single terminal, pass in the terminal name.

Combining Filters

None of the above filters are mutually exclusive. You can combine any of the above properties in a single request to restrict transaction results to a narrower set of results.

Searching Transaction History

You can search transaction history by passing in search criteria with the query option. The search system will match the amount (requested and authorized), last four of the card number, cardholder name, and the auth code.

Note that when search queries are used, terminalName or batch id filters are not supported.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["maxResults"] = 10
  request["batchId"] = "<BATCH ID>"
    [client transactionHistoryWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["maxResults"] = 10
    request["batchId"] = "<BATCH ID>"
      client.transactionHistory(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

List Queued Transactions

• API Credential Types: Merchant
• Required Role: Payment API Access

Returns a list of transaction refs of transactions queued on a terminal. Details about the transactions can be retrieved using the Transaction Status API.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
    [client listQueuedTransactionsWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
      client.listQueuedTransactions(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Delete Queued Transaction

• API Credential Types: Merchant
• Required Role: Payment API Access

Deletes one or all queued transactions from a terminal. If * is passed as a transaction ref, then the entire terminal queue will be cleared. An error is returned if the passed transaction ref is not queued on the terminal.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
  request["transactionRef"] = "*"
    [client deleteQueuedTransactionWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
    request["transactionRef"] = "*"
      client.deleteQueuedTransaction(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Terminal Management Endpoints

These APIs support terminal management functions and additional terminal features such as line item display, messages, and interactive prompts.
These features can be used to extend a point of sale system's functionality.

Terminal Ping

• API Credential Types: Merchant
• Required Role: Payment API Access

This simple test transaction helps ensure good communication with a payment terminal and is usually the first test you'll run in development.

It tests communication with the terminal and returns a positive response if everything is okay. It works the same way in local or cloud relay mode.

If you get a positive response, you've successfully verified all of the following:

• The terminal is online.
• There is a valid route to the terminal.
• The API Credentials are valid.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
    [client pingWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
      client.ping(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Terminal Locate

• API Credential Types: Merchant
• Required Role: Payment API Access

This endpoint returns a terminal's routing and location information.

The result will indicate whether or not the terminal is in cloud relay mode and will return the local IP address if the terminal is in local mode.

The terminal will also return the public key for the terminal.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
    [client locateWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
      client.locate(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Terminal Clear

• API Credential Types: Merchant
• Required Role: Payment API Access

This API interrupts whatever a terminal may be doing and returns it to the idle state.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
    [client clearWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
      client.clear(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Terminal Status

• API Credential Types: Merchant
• Required Role: Payment API Access

This API returns the current status of a payment terminal. This is typically used as a way to determine if the terminal is busy before sending a new transaction.

If the terminal is busy, idle will be false and the status field will return a short string that indicates the transaction type currently in progress. The system will also return the timestamp of the last status change in the since field.

The cardInSlot field in the response will indicates whether or not a card is currently in the card reader slot.

If the system is running a payment transaction and you wisely passed in a Transaction Ref, this API will also return the Transaction Ref of the in progress transaction.

The table below lists all possible status responses.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
    [client terminalStatusWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"idle", [response objectForKey:@"idle"])
    NSLog(@"%@: %@", @"status", [response objectForKey:@"status"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
      client.terminalStatus(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("idle" + ": " + (response["idle"] as? String).unsafelyUnwrapped)
      NSLog("status" + ": " + (response["status"] as? String).unsafelyUnwrapped)
    })
  }

Capture Signature

• API Credential Types: Merchant
• Required Role: Payment API Access

This endpoint captures a written signature from the terminal and returns the image.

Unlike the Terms & Conditions API, this endpoint performs basic signature capture with no agreement display or signature archival.

Under the hood, signatures are captured in a proprietary vector format and must be converted to a common raster format in order to be useful to most applications. At a minimum, you must specify an image format using the sigFormat parameter. Currently, JPG and PNG are supported.

By default, images are returned in the JSON response as hex encoded binary. You can redirect the binary image output to a file using the sigFile parameter.

You can also scale the output image to your preferred width by passing in a sigWidth parameter. The image will be scaled to that width, preserving the aspect ratio of the original image.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
  request["sigFormat"] = SIGNATURE_FORMAT_PNG
  request["sigWidth"] = 200
    [client captureSignatureWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
    request["sigFormat"] = SIGNATURE_FORMAT_PNG
    request["sigWidth"] = 200
      client.captureSignature(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

New Transaction Display

• API Credential Types: Merchant
• Required Role: Payment API Access

This API sends totals and line item level data to the terminal.

At a minimum, you should send total information as part of a display request, including total, tax, and subtotal.

You can also send line item level data and each line item can have a description, qty, price, and extended price.

If you fail to send an extended price, BlockChyp will multiply the qty by the price. However, we strongly recommend you precalculate all the fields yourself to ensure consistency. For example, your treatment of floating-point multiplication and rounding may differ slightly from BlockChyp's.

Discounts

You have the option to show discounts on the display as individual line items with negative values or you can associate discounts with a specific line item. You can apply any number of discounts to an individual line item with a description and amount.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  var transaction: [String:Any] = [:]
  transaction["subtotal"] = "60.00"
  transaction["tax"] = "5.00"
  transaction["total"] = "65.00"
  var items = [Any]();
  var items1: [String:Any] = [:]
  items1["description"] = "Leki Trekking Poles"
  items1["price"] = "35.00"
  items1["quantity"] = 2
  items1["extended"] = "70.00"
  var discounts = [Any]();
  var discounts1: [String:Any] = [:]
  discounts1["description"] = "memberDiscount"
  discounts1["amount"] = "10.00"
  discounts.append(discounts1)
  items1["discounts"] = discounts
  items.append(items1)
  transaction["items"] = items
  request["transaction"] = transaction
    [client newTransactionDisplayWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    var transaction: [String:Any] = [:]
    transaction["subtotal"] = "60.00"
    transaction["tax"] = "5.00"
    transaction["total"] = "65.00"
    var items = [Any]();
    var items1: [String:Any] = [:]
    items1["description"] = "Leki Trekking Poles"
    items1["price"] = "35.00"
    items1["quantity"] = 2
    items1["extended"] = "70.00"
    var discounts = [Any]();
    var discounts1: [String:Any] = [:]
    discounts1["description"] = "memberDiscount"
    discounts1["amount"] = "10.00"
    discounts.append(discounts1)
    items1["discounts"] = discounts
    items.append(items1)
    transaction["items"] = items
    request["transaction"] = transaction
      client.newTransactionDisplay(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Update Transaction Display

• API Credential Types: Merchant
• Required Role: Payment API Access

Similar to New Transaction Display, this variant allows developers to update line item level data currently being displayed on the terminal.

This feature is designed for situations where you want to update the terminal display as items are scanned. You'll only have to send information to the terminal that's changed, which usually means the new line item and updated totals.

If the terminal is not in line item display mode and you invoke this endpoint, the first invocation will behave like a New Transaction Display call.

At a minimum, you should send total information as part of a display request, including total, tax, and subtotal.

You can also send line item level data and each line item can have a description, qty, price, and extended price.

If you fail to send an extended price, BlockChyp will multiply the qty by the price. However, we strongly recommend you precalculate all the fields yourself to ensure consistency. For example, your treatment of floating-point multiplication and rounding may differ slightly from BlockChyp's.

Discounts

You have the option to show discounts on the display as individual line items with negative values or you can associate discounts with a specific line item. You can apply any number of discounts to an individual line item with a description and amount.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  var transaction: [String:Any] = [:]
  transaction["subtotal"] = "60.00"
  transaction["tax"] = "5.00"
  transaction["total"] = "65.00"
  var items = [Any]();
  var items1: [String:Any] = [:]
  items1["description"] = "Leki Trekking Poles"
  items1["price"] = "35.00"
  items1["quantity"] = 2
  items1["extended"] = "70.00"
  var discounts = [Any]();
  var discounts1: [String:Any] = [:]
  discounts1["description"] = "memberDiscount"
  discounts1["amount"] = "10.00"
  discounts.append(discounts1)
  items1["discounts"] = discounts
  items.append(items1)
  transaction["items"] = items
  request["transaction"] = transaction
    [client updateTransactionDisplayWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    var transaction: [String:Any] = [:]
    transaction["subtotal"] = "60.00"
    transaction["tax"] = "5.00"
    transaction["total"] = "65.00"
    var items = [Any]();
    var items1: [String:Any] = [:]
    items1["description"] = "Leki Trekking Poles"
    items1["price"] = "35.00"
    items1["quantity"] = 2
    items1["extended"] = "70.00"
    var discounts = [Any]();
    var discounts1: [String:Any] = [:]
    discounts1["description"] = "memberDiscount"
    discounts1["amount"] = "10.00"
    discounts.append(discounts1)
    items1["discounts"] = discounts
    items.append(items1)
    transaction["items"] = items
    request["transaction"] = transaction
      client.updateTransactionDisplay(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Display Message

• API Credential Types: Merchant
• Required Role: Payment API Access

This API displays a message on the payment terminal.

Just specify the target terminal and the message using the message parameter.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["message"] = "Thank you for your business."
    [client messageWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["message"] = "Thank you for your business."
      client.message(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Boolean Prompt

• API Credential Types: Merchant
• Required Role: Payment API Access

This API Pprompts the customer to answer a yes or no question.

You can specify the question or prompt with the prompt parameter and the response is returned in the response field.

This can be used for a number of use cases including starting a loyalty enrollment workflow or customer facing suggestive selling prompts.

Custom Captions

You can optionally override the "YES" and "NO" button captions by using the yesCaption and noCaption request parameters.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["prompt"] = "Would you like to become a member?"
  request["yesCaption"] = "Yes"
  request["noCaption"] = "No"
    [client booleanPromptWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"response", [response objectForKey:@"response"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["prompt"] = "Would you like to become a member?"
    request["yesCaption"] = "Yes"
    request["noCaption"] = "No"
      client.booleanPrompt(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("response" + ": " + (response["response"] as? String).unsafelyUnwrapped)
    })
  }

Text Prompt

• API Credential Types: Merchant
• Required Role: Payment API Access

This API prompts the customer to enter numeric or alphanumeric data.

Due to PCI rules, free-form prompts are not permitted when the response could be any valid string. The reason for this is that a malicious developer (not you, of course) could use text prompts to ask the customer to input a card number or PIN code.

This means that instead of providing a prompt, you provide a promptType instead.

The prompt types currently supported are listed below:

• phone: Captures a phone number.
• email: Captures an email address.
• first-name: Captures a first name.
• last-name: Captures a last name.
• customer-number: Captures a customer number.
• rewards-number: Captures a rewards number.

You can specify the prompt with the promptType parameter and the response is returned in the response field.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["promptType"] = PROMPT_TYPE_EMAIL
    [client textPromptWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"response", [response objectForKey:@"response"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["promptType"] = PROMPT_TYPE_EMAIL
      client.textPrompt(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("response" + ": " + (response["response"] as? String).unsafelyUnwrapped)
    })
  }

List Terminals

• API Credential Types: Merchant & Partner
• Required Role: Terminal Management

This API returns details about terminals associated with a merchant account.

Status and resource information is returned for all terminals along with a preview of the current branding image displayed on the terminal

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
    [client terminalsWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
      client.terminals(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Deactivate Terminal

• API Credential Types: Merchant & Partner
• Required Role: Terminal Management

This API deactivates a payment terminal.

If the terminal exists and is currently online, it will be removed from the merchant's terminal inventory. The terminal will be remotely cleared and factory reset.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalId"] = "<TERMINAL ID>"
    [client deactivateTerminalWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalId"] = "<TERMINAL ID>"
      client.deactivateTerminal(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Activate Terminal

• API Credential Types: Merchant & Partner
• Required Role: Terminal Management

This API activates a payment terminal.

If successful, the payment terminal will restart, generate new encryption keys, and download any active branding assets for the merchant account it's been added to.

Activation requests require an activation code and a unique terminal name. All terminal names must be unique across a merchant account.

Optional Parameters

• 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.
• cloudRelay: Activates the terminal in cloud relay mode.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
  request["activationCode"] = "<ACTIVATION CODE>"
    [client activateTerminalWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
    request["activationCode"] = "<ACTIVATION CODE>"
      client.activateTerminal(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Reboot Terminal

• API Credential Types: Merchant
• Required Role: Payment API Access

This API reboots the terminal.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["terminalName"] = "Test Terminal"
    [client rebootWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["terminalName"] = "Test Terminal"
      client.reboot(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Terms & Conditions Endpoints

Developers can use BlockChyp to display and capture acceptance of contracts or agreements related to transactions. These agreements can be any long-form contract ranging from rental agreements to HIPPA disclosures.

There are two basic approaches to terms and conditions capture. Merchants can store contract templates in BlockChyp or they can send the full agreement text as part of every API call. The right approach will largely depend on whether or not the system being integrated with BlockChyp already has a mechanism for organizing and managing agreements. For systems that already have this feature built in, it's probably not necessary to use Terms and Conditions.

When agreements are displayed on a terminal, the consumer can scroll through and read the entire agreement, and provide a signature. Results are returned as part of the API response, but BlockChyp also stores a record of the agreement including the signature image, timestamp, and the full text of the agreement that was agreed to.

The Terms and Conditions Log APIs can be used to search and retrieve acceptance records. Those records can also be linked to a transaction if a transaction id is provided with the original API request.

Terms & Conditions Capture

• API Credential Types: Merchant
• Required Role: Terms & Conditions Management

This API allows you to prompt a customer to accept a legal agreement on the terminal and (usually) capture their signature.

Content for the agreement can be specified in two ways. You can reference a previously configured T&C template or pass in the full agreement text with every request.

Using Templates

If your application doesn't keep track of agreements you can leverage BlockChyp's template system. You can create any number of T&C Templates in the merchant dashboard and pass in the tcAlias flag to specify which one should display.

Raw Content

If your system keeps track of the agreement language or executes complicated merging and rendering logic, you can bypass our template system and pass in the full text with every transaction. Use tcName to pass in the agreement name and tcContent to pass in the contract text. Note that only plain text is supported.

Bypassing Signatures

Signature images are captured by default. If for some reason this doesn't fit your use case and you'd like to capture acceptance without actually capturing a signature image, set the disableSignature flag in the request.

Terms & Conditions Log

Every time a user accepts an agreement on the terminal, the signature image (if captured), will be uploaded to the gateway. The image will also be added to the log along with the full text of the agreement. This preserves the historical record in the event that standard agreements or templates change over time.

Associating Agreements with Transactions

To associate a Terms & Conditions log entry with a transaction, just pass in the Transaction ID or Transaction Ref for the associated transaction.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
  request["tcAlias"] = "hippa"
  request["tcName"] = "HIPPA Disclosure"
  request["tcContent"] = "Full contract text"
  request["sigFormat"] = SIGNATURE_FORMAT_PNG
  request["sigWidth"] = 200
  request["sigRequired"] = true
    [client termsAndConditionsWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"sig", [response objectForKey:@"sig"])
    NSLog(@"%@: %@", @"sigFile", [response objectForKey:@"sigFile"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
    request["tcAlias"] = "hippa"
    request["tcName"] = "HIPPA Disclosure"
    request["tcContent"] = "Full contract text"
    request["sigFormat"] = SIGNATURE_FORMAT_PNG
    request["sigWidth"] = 200
    request["sigRequired"] = true
      client.termsAndConditions(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("sig" + ": " + (response["sig"] as? String).unsafelyUnwrapped)
      NSLog("sigFile" + ": " + (response["sigFile"] as? String).unsafelyUnwrapped)
    })
  }

List Templates

• API Credential Types: Merchant
• Required Role: Terms & Conditions Management

This API returns all terms and conditions templates associated with a merchant account.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
    [client tcTemplatesWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
      client.tcTemplates(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Get Template

• API Credential Types: Merchant
• Required Role: Terms & Conditions Management

This API returns as single terms and conditions template.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["templateId"] = "<TEMPLATE ID>"
    [client tcTemplateWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["templateId"] = "<TEMPLATE ID>"
      client.tcTemplate(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Update Template

• API Credential Types: Merchant
• Required Role: Terms & Conditions Management

This API updates or creates a terms and conditions template.

Terms and conditions templates are fairly simple and essentially consist of a name, content, and alias.

The name is the caption that will be displayed at the top of the screen. The alias is a code or short description that will be used in subsequence API calls to refer to the template.

Content is the full text of the contract or agreement. Currently, no special formatting or merge behavior is supported. Only plain text is supported.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["alias"] = "HIPPA"
  request["name"] = "HIPPA Disclosure"
  request["content"] = "Lorem ipsum dolor sit amet."
    [client tcUpdateTemplateWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["alias"] = "HIPPA"
    request["name"] = "HIPPA Disclosure"
    request["content"] = "Lorem ipsum dolor sit amet."
      client.tcUpdateTemplate(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Delete Template

• API Credential Types: Merchant
• Required Role: Terms & Conditions Management

This API deletes a terms and conditions template.

If a template is deleted, its alias can be reused and any previous Terms & Conditions log entry derived from the template being deleted is fully preserved since log entries always include a complete independent copy of the agreement text.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["templateId"] = "<TEMPLATE ID>"
    [client tcDeleteTemplateWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["templateId"] = "<TEMPLATE ID>"
      client.tcDeleteTemplate(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Terms & Conditions Log

• API Credential Types: Merchant
• Required Role: Terms & Conditions Management

This API allows developers to search and sort through terms and conditions log entries.

The default API call with no parameters will return the last 250 log entries in descending order.

Optional parameters can be used to filter and query the data set.

• transactionId: If provided, returns only those log entries associated with a specific transactions. Paging and date filters are ignored if this parameter is used.
• maxResults: The max number of results to return in a single page. Defaults to 250 and 250 is the maximum value.
• 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.
• startDate: An optional start date for results provided as an ISO 8601 timestamp. (e.g. 2022-05-24T13:51:38+00:00)
• endDate: An optional end date for results provided as an ISO 8601 timestamp. (e.g. 2022-05-24T13:51:38+00:00)

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["logEntryId"] = "<LOG ENTRY ID>"
    [client tcLogWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["logEntryId"] = "<LOG ENTRY ID>"
      client.tcLog(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Terms & Conditions Details

• API Credential Types: Merchant
• Required Role: Terms & Conditions Management

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.

The signature image is returned as Base 64 encoded binary in the image format specified by the sigFormat field. The default format is PNG.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["logEntryId"] = "<ENTRY ID>"
    [client tcEntryWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["logEntryId"] = "<ENTRY ID>"
      client.tcEntry(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Token Management

BlockChyp supports saved payments and recurring payments through the use of tokens. Tokens can be created via the Enroll API or the web tokenizer. Once created, these tokens can be used for subsequent payments or associated with customer records as saved payment methods.

Tokens are limited to a single merchant by default, but can be shared across an organization for multi-location merchants by special arrangement with BlockChyp. Contact your BlockChyp rep to setup token sharing.

Enroll

• API Credential Types: Merchant
• Required Role: Payment API Access

This API allows you to tokenize and enroll a payment method in the token vault. You can also pass in customer information and associate the payment method with a customer record.

A token is returned in the response that can be used in subsequent charge, preauth, and refund transactions.

Gift Cards and EBT

Gift Cards and EBT cards cannot be tokenized.

E-Commerce Tokens

The tokens returned by the enroll API and the e-commerce web tokenizer are the same tokens and can be used interchangeably.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["test"] = true
  request["terminalName"] = "Test Terminal"
    [client enrollWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
    NSLog(@"%@: %@", @"token", [response objectForKey:@"token"])
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["test"] = true
    request["terminalName"] = "Test Terminal"
      client.enroll(withRequest: request, handler: { (request, response, error) in
        let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
      NSLog("token" + ": " + (response["token"] as? String).unsafelyUnwrapped)
    })
  }

Token Metadata

• API Credential Types: Merchant
• Required Role: Payment API Access

This API retrieves status and metadata information about a token, including any links to customer records.

This will also return any customer records related to the card behind the token. If the underlying card has been tokenized multiple times, all customers related to the card will be returned, even if those customer associations are related to other tokens.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["token"] = "<TOKEN>"
    [client tokenMetadataWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["token"] = "<TOKEN>"
      client.tokenMetadata(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Link Token

• API Credential Types: Merchant
• Required Role: Payment API Access

This API links a payment token with a customer record. Usually this would only be needed to reverse a previous unlink operation.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["token"] = "<TOKEN>"
  request["customerId"] = "<CUSTOMER ID>"
    [client linkTokenWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["token"] = "<TOKEN>"
    request["customerId"] = "<CUSTOMER ID>"
      client.linkToken(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Unlink Token

• API Credential Types: Merchant
• Required Role: Payment API Access

This API removes a payment token link from a customer record.

This will remove links between the customer record and all tokens for the same underlying card.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["token"] = "<TOKEN>"
  request["customerId"] = "<CUSTOMER ID>"
    [client unlinkTokenWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}

From Swift:

import BlockChyp

class ExampleClass {

  func example() {
    let client = BlockChyp.init(
      apiKey: "ZN5WQGX5PN6BE2MF75CEAWRETM",
      bearerToken: "SVVHJCYVFWJR2QKYKFWMZQVZL4",
      signingKey: "7c1b9e4d1308e7bbe76a1920ddd9449ce50af2629f6bb70ed3c110365935970b"
    )

    var request: [String:Any] = [:]
    request["token"] = "<TOKEN>"
    request["customerId"] = "<CUSTOMER ID>"
      client.unlinkToken(withRequest: request, handler: { (request, response, error) in
        let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

Delete Token

• API Credential Types: Merchant
• Required Role: Payment API Access

This API deletes a payment token from the gateway. Tokens are automatically deleted if they have not been used for a year.

From Objective-C:

#import <Foundation/Foundation.h>
#import <BlockChyp/BlockChyp.h>

int main (int argc, const char * argv[])
{
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BlockChyp *client = [[BlockChyp alloc]
    initWithApiKey:@"SPBXTSDAQVFFX5MGQMUMIRINVI"
    bearerToken:@"7BXBTBUPSL3BP7I6Z2CFU6H3WQ"
    signingKey:@"bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e"];

  NSMutableDictionary *request = [[NSMutableDictionary alloc] init];
  request["token"] = "<TOKEN>"
    [client deleteTokenWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
      NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}