NAV Navbar
shell go csharp java php ruby python javascript objective_c swift

Overview

BlockChyp is a semi-integrated payment system that makes it easy to integrate card-present payment terminals with third party software. Usually this means on premise retail and restaurant point-of-sale systems, but it can mean just about anything ranging from cloud based point-of-sale to law and medical practice management systems.

Semi-Integrated?

Semi-Integrated is one of many payments industry nonsense terms. In payments lingo, a fully integrated system means that the payment terminal is a dumb peripheral and you handle all the authorization and network communication yourself. This puts you in PCI and Level 3 EMV certification scope. You don't want that. You want the terminal to talk directly to our gateway and the payment networks so your code never touches anything sensitive. The payments industry calls this approach semi-integrated because that obviously makes everything crystal clear.

Use Payment Hardware Like A Web Service

The idea behind BlockChyp is that you can interact with payment terminal hardware using the same techniques you're already used to for other services you consume. BlockChyp allows you to interact with terminal hardware using REST APIs.

But, of course, even REST APIs are too much work these days.

Most developers would rather type a quick command (like npm i @blockchyp/blockchyp-js) or drop a dependency snippet in their project somewhere, download a library and go. That's how BlockChyp works. Add one of our SDK libraries to your project and start running transactions, usually within minutes.

The SDKs deal with finding the terminals on your local network or via the cloud and handle all the security and network plumbing you'd have to otherwise build yourself.

Hopefully Your Last Groundhog Day

Before we get too much further, we want to acknowledge that we understand the Groundhog Day feeling you might be having. The suits have made yet another deal with a payment processor and it's your job to do the integration.

We've been there. We started BlockChyp because we've done these tedious and brittle integrations with all the usual suspects and we know how much it usually sucks. It shocked us that some of the largest companies in the world paid so little attention to how us developers actually work. They make things hard for no reason and half they stuff they promise you is half finished or doesn't work at all. We feel your pain and have done everything we could to not put you through the usual misery.

You notice how we didn't make you sign an NDA or log into a sketchy FTP server to get your hands on the SDK code or documentation? That's because we live in modern times and we assume you do, too. We also don't have the certification process a lot of processors have because we further assume that you're a grown up professional that knows how to do your job. BlockChyp handles all cardholder data and it's pretty hard to get yourself in trouble.

Just make sure you follow the Receipt Requirements and you'll be fine.

Getting Started

To get started with BlockChyp sign up for a developer account on the BlockChyp Web Site and order a BlockChyp Developer Kit. The kit will include a fully functioning payment terminal along with contactless, chip, mag stripe, and gift test cards.

Next, examine the list of SDKs and Clients and follow the instructions for your technology ecosystem.

SDKs and Client Libraries

All supported BlockChyp SDKs are open source and hosted on Github. Binaries are distributed via all the usual package management systems for each platform. (Maven for Java, Nuget for C#, etc.)

Follow the link for your platform to Github and follow the instructions in the project README to download the libraries.

What if my platform isn't listed?

Fear not, the Command Line Interface has you covered.

Y U No C++?

We left C/C++ off the SDK list because there are so many different ways to do REST APIs in C++. When you factor in Linux support, it's hard to create a C++ library in such a way that it's suitable for all C++ developers. We chickened out and hope you understand.

Command Line Interface

Support for nine of the most popular programming languages is pretty good, but it doesn't cover everybody. Believe it or not, we have some folks using all sorts of wild things like COBOL and Assembler and, of course, C++.

So we've developed an executable command line interface that any language can access as a shell command. It's also a good way to experiment with BlockChyp without writing any code.

Since Go compiles to native code with no extra runtime requirements, we built the CLI in Go and it's part of our open source Go SDK. The project includes additional build scripts that create Windows and Linux command line executables. We also distribute binaries over at Github if you're into that sort of thing.

CLI Links: Downloads Docs

Stuff You'll Need For Testing

Before you start developing an integration with BlockChyp, you'll need a terminal, some test cards, a test merchant account, and some API credentials. You'll also want to read a quick blurb about the test transaction flag.

Test Terminals

Hopefully the suits already took care of ordering a Developer Kit for you. If not, login to your developer account and order one. (And since you've taken the trouble to read the docs, help yourself to promo code RTFM and take 20% off your developer kit.) The kit includes a terminal, the necessary cabling, a set of test cards, and an official BlockChyp Laptop Sticker. Display it with pride.

Test Cards

BlockChyp Developer Kits include four EMV test cards with a good mix of CVMs (customer verification methods) and card brands. A few of them are also dual interface, which means you can use them to run Contactless EMV tests.

We include MSR test cards for all four major card brands because mag stripes are still a thing. We also include three special mag stripe test cards you can use for simulating declines, partial authorizations, and network failures.

The highlight of every Developer Kit is a selection of BlockChyp test gift cards. These use our magical blockchain stuff. Instead of gift card numbers, our gift card system works by having the terminals sign transaction blocks with keys that are on the gift card's mag stripe. More on that later.

Standard Test Card Numbers

Because BlockChyp's focus is terminals, you'll want to use real plastic most of the time. But, for testing e-commerce and manually entered transactions, any valid test card numbers will work, but we recommend these...

Card Brand Card Number Cardholder Name Expiration CVV
VISA 4111 1111 1111 1111 RICHARD HENDRICKS 12/2025 000
MC 5105 1051 0510 5118 JARED DUNN 12/2025 000
AMEX 3782 822463 10005 PETER GREGORY 12/2025 0000
DISC 6011 1111 1111 1117 ERLICH BACHMAN 12/2025 000

Adverse Event Cards and Trigger Amounts

Because BlockChyp is compatible with reality, we make it easy to simulate bad things happening. The table below lists special card numbers and trigger amounts and what adverse events they simulate.

Event Type Trigger Card Trigger Amount Notes
decline 4111 1111 1111 1129 201.00
error 6011 0009 9013 9424 00.11
fraud 3714 496353 98431 66.00 Sets the fraud probability flag
partial-auth 5105 1051 0510 5100 55.00 Authorized Amount: $25.00
no-response 4111 1111 1111 1137 72.00 Returns no response.
timeout 5555 5555 5555 4444 68.00 Gateway hangs for 30 seconds.

Believe it or not, you can customize adverse events. If you don't like our standard trigger cards or trigger amounts, you can change them or add your own in the developer portal. You can even have different trigger cards and trigger amounts for different test merchant accounts. This means your QA people could have their own setup, which QA people tend to want.

Test Merchant Accounts

Once you have all the gear and test plastic, you'll need to create a test merchant account. Just login into the BlockChyp portal, expand Developer Tools and click Test Merchants. You'll be able to add a test merchant from there.

When you click on a test merchant, you'll notice you get a Merchant Tools section on your navigation just like live merchants. You can adjust merchant settings here and upload media to troll your peers with. You'll also notice a Test Settings button on the test merchant landing page. This allows access to restricted settings that you wouldn't have access to for live merchants, but might need to tweak for testing different scenarios.

Activating Terminals

Next, pair your terminal with the test merchant account by touching the terminal screen where it says "TOUCH TO ACTIVATE". Click ACTIVATE TERMINAL on the test merchant dashboard and enter the code you see on the terminal. Give the terminal a name and decide whether or not you'll be using the terminal in cloud relay mode. If your application is web based or won't be residing on the same network as the terminal, check the box. Otherwise, leave it be.

API Credentials

The final step before you can start coding is to generate API credentials. Just click the API CREDENTIALS button and generate a new set of credentials. You can have any number of unique credentials for a given merchant account. You can also lock them to protect them from accidental deletion or add some notes to remind yourself about how you might be using the credentials.

When you generate credentials, you get three things for the price of one click:

The Test Flag

Linux/Mac OS:  ./blockchyp -type="charge" -terminal="Test Terminal" -amount="2.59" -test

Windows:  blockchyp.exe -type="charge" -terminal="Test Terminal" -amount="2.59" -test
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.AuthorizationRequest{
        Test:         true, //setting the test flag
        TerminalName: "Test Terminal",
        Amount:       "55.00",
    }

    response, err := client.Charge(request)
AuthorizationRequest request = new AuthorizationRequest
{
    Test = true,
    TerminalName = "Test Terminal", //setting the test flag
    Amount = "55.00",
};

// Run the transaction.
AuthorizationResponse response = await blockchyp.ChargeAsync(request);
AuthorizationRequest request = new AuthorizationRequest();
request.setTest(true);  //setting the test flag
request.setTerminalName("Test Terminal");
request.setAmount("55.00");

// Send the request
AuthorizationResponse response = client.charge(request);
$request = [
    'test' => true, //setting the test flag
    'terminalName' => 'Test Terminal',
    'amount' => '55.00',
];

$response = BlockChyp::charge($request);

The astute payment integration veterans among you may have noted that we don't ask you to put a Gateway URL anywhere in your configuration. You're welcome, but PCI "law" forbids processing test transactions on the same servers as live transactions.

For this reason, all test transactions must be flagged at test transactions. All sample code in this documentation will include the test flag because we assume you use the documentation while testing, but you'll need to remove it when you start running transactions for live merchants.

The sample code shows how you set the test flag on platforms.

Transaction Reference

Terminal Ping

Terminal Ping Example:

Linux/Mac OS: ./blockchyp -test -type="ping" -terminal="Test Terminal"

Windows: ./blockchyp.exe -test -type="ping" -terminal="Test Terminal"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func pingExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.PingRequest{
        TerminalName: "Test Terminal",
    }

    response, err := client.Ping(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
PingRequest request = new PingRequest
{
    TerminalName = "Test Terminal",
};

// Run the transaction.
PingResponse response = await blockchyp.PingAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.PingRequest;
import com.blockchyp.client.dto.PingResponse;


public class PingExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        PingRequest request = new PingRequest();
        request.setTerminalName("Test Terminal");

        // Send the request
        PingResponse response = client.ping(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
];

$response = BlockChyp::ping($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "terminalName": 'Test Terminal'
}

response = blockchyp.ping(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "terminalName": "Test Terminal",
}

# run the transaction.
response = client.ping(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      terminalName: 'Test Terminal',
  }

  response = client.ping(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "transactionId": "",
  "transactionType": "ping",
  "timestamp": "",
  "tickBlock": "",
  "test": true
}

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

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:

Charge

Charge Example:

Linux/Mac OS: ./blockchyp -test -type="charge" -terminal="Test Terminal" -amount="25.00"

Windows: ./blockchyp.exe -test -type="charge" -terminal="Test Terminal" -amount="25.00"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func chargeExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.AuthorizationRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        Amount:       "55.00",
    }

    response, err := client.Charge(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
AuthorizationRequest request = new AuthorizationRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    Amount = "55.00",
};

// Run the transaction.
AuthorizationResponse response = await blockchyp.ChargeAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.AuthorizationRequest;
import com.blockchyp.client.dto.AuthorizationResponse;


public class ChargeExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        AuthorizationRequest request = new AuthorizationRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setAmount("55.00");

        // Send the request
        AuthorizationResponse response = client.charge(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'amount' => '55.00',
];

$response = BlockChyp::charge($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "amount": '55.00'
}

response = blockchyp.charge(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "amount": "55.00",
}

# run the transaction.
response = client.charge(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      amount: '55.00',
  }

  response = client.charge(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "approved",
  "approved": true,
  "authCode": "052509",
  "transactionId": "KJ3DPHULBAI6VOTSNSLM7WZLHE",
  "transactionRef": "04781125618",
  "transactionType": "charge",
  "timestamp": "2020-04-30T18:28:10Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "partialAuth": false,
  "altCurrency": false,
  "fsaAuth": false,
  "currencyCode": "USD",
  "requestedAmount": "25.00",
  "authorizedAmount": "25.00",
  "remainingBalance": "",
  "tipAmount": "0.00",
  "taxAmount": "0.00",
  "requestedCashBackAmount": "0.00",
  "authorizedCashBackAmount": "0.00",
  "entryMethod": "CHIP",
  "paymentType": "VISA",
  "maskedPan": "************0010",
  "cardHolder": "UAT USA/Test Card 04",
  "avsResponse": "",
  "receiptSuggestions": {
    "aid": "A0000000031010",
    "arqc": "BDFD1A64620D9382",
    "iad": "06010A03A0B800",
    "tvr": "8000008800",
    "tsi": "6800",
    "merchantName": "Test Merchant",
    "applicationLabel": "VISA CREDIT",
    "requestSignature": false,
    "maskedPan": "************0010",
    "authorizedAmount": "25.00",
    "transactionType": "charge",
    "entryMethod": "CHIP",
    "cashBackAmount": "0.00",
    "surcharge": "0.00",
    "cashDiscount": "0.00"
  },
  "customer": null,
  "whiteListedCard": null,
  "storeAndForward": false
}

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. 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.

Common Variations

Preauthorization

Preauthorization Example:

Linux/Mac OS: ./blockchyp -test -type="preauth" -terminal="Test Terminal" -amount="27.00"

Windows: ./blockchyp.exe -test -type="preauth" -terminal="Test Terminal" -amount="27.00"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func preauthExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.AuthorizationRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        Amount:       "27.00",
    }

    response, err := client.Preauth(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
AuthorizationRequest request = new AuthorizationRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    Amount = "27.00",
};

// Run the transaction.
AuthorizationResponse response = await blockchyp.PreauthAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.AuthorizationRequest;
import com.blockchyp.client.dto.AuthorizationResponse;


public class PreauthExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        AuthorizationRequest request = new AuthorizationRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setAmount("27.00");

        // Send the request
        AuthorizationResponse response = client.preauth(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'amount' => '27.00',
];

$response = BlockChyp::preauth($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "amount": '27.00'
}

response = blockchyp.preauth(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "amount": "27.00",
}

# run the transaction.
response = client.preauth(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      amount: '27.00',
  }

  response = client.preauth(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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"] = @"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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "approved",
  "approved": true,
  "authCode": "462305",
  "transactionId": "KJ3DPHULBAI6VOTTNSLM7WZLHE",
  "transactionRef": "22265850802",
  "transactionType": "preauth",
  "timestamp": "2020-04-30T18:36:21Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "partialAuth": false,
  "altCurrency": false,
  "fsaAuth": false,
  "currencyCode": "USD",
  "requestedAmount": "27.00",
  "authorizedAmount": "27.00",
  "remainingBalance": "",
  "tipAmount": "0.00",
  "taxAmount": "0.00",
  "requestedCashBackAmount": "0.00",
  "authorizedCashBackAmount": "0.00",
  "entryMethod": "CHIP",
  "paymentType": "VISA",
  "maskedPan": "************0010",
  "cardHolder": "UAT USA/Test Card 04",
  "avsResponse": "",
  "receiptSuggestions": {
    "aid": "A0000000031010",
    "arqc": "F1D11638D5A4C91D",
    "iad": "06010A03A0B800",
    "tvr": "8000008800",
    "tsi": "6800",
    "merchantName": "Test Merchant",
    "applicationLabel": "VISA CREDIT",
    "requestSignature": false,
    "maskedPan": "************0010",
    "authorizedAmount": "27.00",
    "transactionType": "preauth",
    "entryMethod": "CHIP",
    "cashBackAmount": "0.00",
    "surcharge": "0.00",
    "cashDiscount": "0.00"
  },
  "customer": null,
  "whiteListedCard": null,
  "storeAndForward": false
}

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 examples would be fine dining where a tip adjustment is required prior to 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. 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.

Common Variations

Capture Preauthorization

Capture Preauthorization Example:

Linux/Mac OS: ./blockchyp -test -type="capture" -tx="<PREAUTH TRANSACTION ID>" -tip="5.00" -amount="32.00"

Windows: ./blockchyp.exe -test -type="capture" -tx="<PREAUTH TRANSACTION ID>" -tip="5.00" -amount="32.00"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func captureExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.CaptureRequest{
        Test:          true,
        TransactionID: "<PREAUTH TRANSACTION ID>",
    }

    response, err := client.Capture(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
CaptureRequest request = new CaptureRequest
{
    Test = true,
    TransactionId = "<PREAUTH TRANSACTION ID>",
};

// Run the transaction.
CaptureResponse response = await blockchyp.CaptureAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.CaptureRequest;
import com.blockchyp.client.dto.CaptureResponse;


public class CaptureExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        CaptureRequest request = new CaptureRequest();
        request.setTest(true);
        request.setTransactionId("<PREAUTH TRANSACTION ID>");

        // Send the request
        CaptureResponse response = client.capture(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'transactionId' => '<PREAUTH TRANSACTION ID>',
];

$response = BlockChyp::capture($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "transactionId": '<PREAUTH TRANSACTION ID>'
}

response = blockchyp.capture(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "transactionId": "<PREAUTH TRANSACTION ID>",
}

# run the transaction.
response = client.capture(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      transactionId: '<PREAUTH TRANSACTION ID>',
  }

  response = client.capture(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"transactionId"] = @"<PREAUTH TRANSACTION ID>";
  [client captureWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"approved"];
    if (success.boolValue) {
      NSLog(@"approved");
    }
  }];
  [pool drain];
  return 0;
}


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"] = "<PREAUTH TRANSACTION ID>"
    client.capture(withRequest: request, handler: { (request, response, error) in
      let approved = response["approved"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("approved")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "approved",
  "approved": true,
  "authCode": "337092",
  "transactionId": "KJ3DPHULBAI6VOTUNSLM7WZLHE",
  "batchId": "KJ3DPFELBAI6VOTRNSLM7WZLHE",
  "transactionType": "capture",
  "timestamp": "2020-04-30T19:03:00Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "partialAuth": false,
  "altCurrency": false,
  "fsaAuth": false,
  "currencyCode": "USD",
  "requestedAmount": "32.00",
  "authorizedAmount": "32.00",
  "remainingBalance": "",
  "tipAmount": "5.00",
  "taxAmount": "0.00",
  "requestedCashBackAmount": "",
  "authorizedCashBackAmount": "",
  "entryMethod": "CHIP",
  "paymentType": "VISA",
  "maskedPan": "************0010",
  "avsResponse": "",
  "receiptSuggestions": {
    "requestSignature": false,
    "authorizedAmount": "",
    "transactionType": ""
  },
  "customer": null
}

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 reduce your interchange fees in some cases. (Level II Processing, for example.)

Refund

Refund Example:

Linux/Mac OS: ./blockchyp -test -type="refund" -tx="<PREAUTH TRANSACTION ID>"

Windows: ./blockchyp.exe -test -type="refund" -tx="<PREAUTH TRANSACTION ID>"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func refundExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.RefundRequest{
        TransactionID: "<PREVIOUS TRANSACTION ID>",

        // Optional amount for partial refunds.
        Amount: "5.00",
    }

    response, err := client.Refund(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
RefundRequest request = new RefundRequest
{
    TransactionId = "<PREVIOUS TRANSACTION ID>",
    Amount = "5.00",
};

// Run the transaction.
AuthorizationResponse response = await blockchyp.RefundAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.RefundRequest;
import com.blockchyp.client.dto.AuthorizationResponse;


public class RefundExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        RefundRequest request = new RefundRequest();
        request.setTransactionId("<PREVIOUS TRANSACTION ID>");
        request.setAmount("5.00");

        // Send the request
        AuthorizationResponse response = client.refund(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'transactionId' => '<PREVIOUS TRANSACTION ID>',

    // Optional amount for partial refunds.
    'amount' => '5.00',
];

$response = BlockChyp::refund($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "transactionId": '<PREVIOUS TRANSACTION ID>',

  # Optional amount for partial refunds.
  "amount": '5.00'
}

response = blockchyp.refund(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "transactionId": "<PREVIOUS TRANSACTION ID>",

    # Optional amount for partial refunds.
    "amount": "5.00",
}

# run the transaction.
response = client.refund(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      transactionId: '<PREVIOUS TRANSACTION ID>',

      // Optional amount for partial refunds.
      amount: '5.00',
  }

  response = client.refund(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "approved",
  "approved": true,
  "authCode": "778648",
  "transactionId": "KJ3DPHULBAI6VOTVNSLM7WZLHE",
  "batchId": "KJ3DPFELBAI6VOTRNSLM7WZLHE",
  "transactionType": "refund",
  "timestamp": "2020-04-30T20:14:38Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "partialAuth": false,
  "altCurrency": false,
  "fsaAuth": false,
  "currencyCode": "USD",
  "requestedAmount": "",
  "authorizedAmount": "27.00",
  "remainingBalance": "",
  "tipAmount": "0.00",
  "taxAmount": "0.00",
  "requestedCashBackAmount": "",
  "authorizedCashBackAmount": "",
  "entryMethod": "CHIP",
  "paymentType": "VISA",
  "maskedPan": "************0010",
  "avsResponse": "",
  "receiptSuggestions": {
    "merchantName": "Test Merchant",
    "requestSignature": false,
    "maskedPan": "************0010",
    "authorizedAmount": "27.00",
    "transactionType": "refund",
    "entryMethod": "CHIP"
  },
  "customer": null,
  "whiteListedCard": null,
  "storeAndForward": false
}

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 has to 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 along with 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 it, 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 manual flag 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.

Enroll

Enroll Example:

Linux/Mac OS: ./blockchyp -test -type="enroll" -terminal="Test Terminal"

Windows: ./blockchyp.exe -test -type="enroll" -terminal="Test Terminal"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func enrollExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.EnrollRequest{
        Test:         true,
        TerminalName: "Test Terminal",
    }

    response, err := client.Enroll(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
EnrollRequest request = new EnrollRequest
{
    Test = true,
    TerminalName = "Test Terminal",
};

// Run the transaction.
EnrollResponse response = await blockchyp.EnrollAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.EnrollRequest;
import com.blockchyp.client.dto.EnrollResponse;


public class EnrollExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        EnrollRequest request = new EnrollRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");

        // Send the request
        EnrollResponse response = client.enroll(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
];

$response = BlockChyp::enroll($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal'
}

response = blockchyp.enroll(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
}

# run the transaction.
response = client.enroll(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
  }

  response = client.enroll(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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";
  [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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "approved",
  "approved": true,
  "authCode": "727291",
  "transactionId": "KJ3DPKELBAI6VOTWNSLM7WZLHE",
  "transactionRef": "64614152008",
  "transactionType": "enroll",
  "timestamp": "2020-04-30T20:49:26Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "token": "EKROTO2K5BCQJT4I555LQJLMWA",
  "entryMethod": "CHIP",
  "paymentType": "VISA",
  "maskedPan": "************0010",
  "cardHolder": "UAT USA/Test Card 04",
  "avsResponse": "",
  "receiptSuggestions": {
    "aid": "A0000000031010",
    "arqc": "3404F82DA10F3FF5",
    "iad": "06010A03A0B800",
    "tvr": "8000008800",
    "tsi": "6800",
    "merchantName": "Test Merchant",
    "applicationLabel": "VISA CREDIT",
    "requestSignature": false,
    "maskedPan": "************0010",
    "authorizedAmount": "",
    "transactionType": "enroll",
    "entryMethod": "CHIP"
  },
  "customer": null
}

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.

Void

Void Example:

Linux/Mac OS: ./blockchyp -test -type="void" -tx="<PREAUTH TRANSACTION ID>"

Windows: ./blockchyp.exe -test -type="void" -tx="<PREAUTH TRANSACTION ID>"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func voidExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.VoidRequest{
        Test:          true,
        TransactionID: "<PREVIOUS TRANSACTION ID>",
    }

    response, err := client.Void(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
VoidRequest request = new VoidRequest
{
    Test = true,
    TransactionId = "<PREVIOUS TRANSACTION ID>",
};

// Run the transaction.
VoidResponse response = await blockchyp.VoidAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.VoidRequest;
import com.blockchyp.client.dto.VoidResponse;


public class VoidExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        VoidRequest request = new VoidRequest();
        request.setTest(true);
        request.setTransactionId("<PREVIOUS TRANSACTION ID>");

        // Send the request
        VoidResponse response = client.voidTx(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'transactionId' => '<PREVIOUS TRANSACTION ID>',
];

$response = BlockChyp::void($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "transactionId": '<PREVIOUS TRANSACTION ID>'
}

response = blockchyp.void(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "transactionId": "<PREVIOUS TRANSACTION ID>",
}

# run the transaction.
response = client.void(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      transactionId: '<PREVIOUS TRANSACTION ID>',
  }

  response = client.void(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"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;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "approved",
  "approved": true,
  "authCode": "537045",
  "transactionId": "KJ3DPKELBAI6VOTYNSLM7WZLHE",
  "batchId": "KJ3DPFELBAI6VOTRNSLM7WZLHE",
  "transactionType": "void",
  "timestamp": "2020-04-30T21:19:09Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "entryMethod": "CHIP",
  "paymentType": "VISA",
  "avsResponse": "",
  "receiptSuggestions": {
    "requestSignature": false,
    "authorizedAmount": "",
    "transactionType": ""
  },
  "customer": null
}

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.

Time Out Reversal

Time Out Reversal Example:

Linux/Mac OS: ./blockchyp -test -type="reverse" -txRef="YOURTXREF"

Windows: ./blockchyp.exe -test -type="reverse" -txRef="YOURTXREF"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func reverseExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.AuthorizationRequest{
        TransactionRef: "<LAST TRANSACTION REF>",
    }

    response, err := client.Reverse(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
AuthorizationRequest request = new AuthorizationRequest
{
    TransactionRef = "<LAST TRANSACTION REF>",
};

// Run the transaction.
AuthorizationResponse response = await blockchyp.ReverseAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.AuthorizationRequest;
import com.blockchyp.client.dto.AuthorizationResponse;


public class ReverseExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        AuthorizationRequest request = new AuthorizationRequest();
        request.setTransactionRef("<LAST TRANSACTION REF>");

        // Send the request
        AuthorizationResponse response = client.reverse(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'transactionRef' => '<LAST TRANSACTION REF>',
];

$response = BlockChyp::reverse($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "transactionRef": '<LAST TRANSACTION REF>'
}

response = blockchyp.reverse(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "transactionRef": "<LAST TRANSACTION REF>",
}

# run the transaction.
response = client.reverse(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      transactionRef: '<LAST TRANSACTION REF>',
  }

  response = client.reverse(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "approved",
  "approved": true,
  "authCode": "130621",
  "transactionId": "KJ3DPMULBAI6VOTZNSLM7WZLHE",
  "batchId": "KJ3DPFELBAI6VOTRNSLM7WZLHE",
  "transactionRef": "YOURTXREF",
  "transactionType": "reverse",
  "timestamp": "2020-04-30T21:29:38Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "partialAuth": false,
  "altCurrency": false,
  "fsaAuth": false,
  "currencyCode": "USD",
  "requestedAmount": "",
  "authorizedAmount": "0.00",
  "remainingBalance": "",
  "tipAmount": "0.00",
  "taxAmount": "0.00",
  "requestedCashBackAmount": "",
  "authorizedCashBackAmount": "",
  "entryMethod": "CHIP",
  "paymentType": "VISA",
  "maskedPan": "************0010",
  "avsResponse": "",
  "receiptSuggestions": {
    "merchantName": "Test Merchant",
    "requestSignature": false,
    "maskedPan": "************0010",
    "authorizedAmount": "0.00",
    "transactionType": "reverse",
    "entryMethod": "CHIP",
    "surcharge": "0.00",
    "cashDiscount": "0.00"
  },
  "customer": null,
  "whiteListedCard": null,
  "storeAndForward": false
}

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 fallback to Transaction Ref to identify a transaction.

Gift Card Activation

Gift Card Activation Example:

Linux/Mac OS: ./blockchyp -test -type="gift-activate" -terminal="Test Terminal" -amount="50.00"

Windows: ./blockchyp.exe -test -type="gift-activate" -terminal="Test Terminal" -amount="50.00"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func giftActivateExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.GiftActivateRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        Amount:       "50.00",
    }

    response, err := client.GiftActivate(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Approved {
        fmt.Println("approved")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
GiftActivateRequest request = new GiftActivateRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    Amount = "50.00",
};

// Run the transaction.
GiftActivateResponse response = await blockchyp.GiftActivateAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.GiftActivateRequest;
import com.blockchyp.client.dto.GiftActivateResponse;


public class GiftActivateExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        GiftActivateRequest request = new GiftActivateRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setAmount("50.00");

        // Send the request
        GiftActivateResponse response = client.giftActivate(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'amount' => '50.00',
];

$response = BlockChyp::giftActivate($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "amount": '50.00'
}

response = blockchyp.giftActivate(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "amount": "50.00",
}

# run the transaction.
response = client.gift_activate(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      amount: '50.00',
  }

  response = client.giftActivate(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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"] = @"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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "APPROVED",
  "transactionId": "KJ3DPPELBAI6VOT4NSLM7WZLHE",
  "transactionType": "gift_activate",
  "timestamp": "2020-04-30T22:41:23Z",
  "tickBlock": "000966828e6b196be72a480bf3a70e77c685262b6a4249b560ef770c8fb51eac",
  "test": true,
  "approved": true,
  "amount": "50.00",
  "currentBalance": "50.00",
  "currencyCode": "USD",
  "publicKey": "13TwUmBCg286Lw8N6EA3QgNu9LRerfhDcHwWKVSLnuNw9etWWfr",
  "maskedPan": "************3904"
}

This API can be used to activate or add 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 and also returns 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, but you can import your outstanding gift cards and customers can swipe them on the terminals just 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 allow a BIN range to be white listed, so contact support@blockchyp.com if you need to white list a BIN range.

Balance

Balance Example:

Linux/Mac OS: ./blockchyp -test -type="balance" -terminal="Test Terminal"

Windows: ./blockchyp.exe -test -type="balance" -terminal="Test Terminal"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func balanceExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.BalanceRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        CardType:     blockchyp.CardTypeEBT,
    }

    response, err := client.Balance(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
BalanceRequest request = new BalanceRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    CardType = CardType.EBT,
};

// Run the transaction.
BalanceResponse response = await blockchyp.BalanceAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.BalanceRequest;
import com.blockchyp.client.dto.BalanceResponse;
import com.blockchyp.client.dto.CardType;


public class BalanceExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        BalanceRequest request = new BalanceRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setCardType(CardType.EBT);

        // Send the request
        BalanceResponse response = client.balance(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'cardType' => BlockChyp::CARD_TYPE_EBT,
];

$response = BlockChyp::balance($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "cardType": CardType::EBT
}

response = blockchyp.balance(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "cardType": blockchyp.CardType.EBT,
}

# run the transaction.
response = client.balance(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      cardType: CardType.EBT,
  }

  response = client.balance(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"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;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "transactionId": "KJ3DPMULBAI6VOT3NSLM7WZLHE",
  "transactionType": "balance",
  "timestamp": "",
  "tickBlock": "0006bea9b77d4452be3e7979eaedd357d0da22cc0d1a85f6027176a2f00d0bea",
  "test": true,
  "paymentType": "BC_GIFT",
  "maskedPan": "************3904",
  "publicKey": "13TwUmBCg286Lw8N6EA3QgNu9LRerfhDcHwWKVSLnuNw9etWWfr",
  "avsResponse": "",
  "receiptSuggestions": {
    "merchantName": "Test Merchant",
    "requestSignature": false,
    "maskedPan": "************3904",
    "authorizedAmount": "",
    "transactionType": "balance",
    "entryMethod": "SWIPE"
  },
  "customer": null,
  "remainingBalance": "50.00"
}

Checks a gift or EBT card balance.

Gift Card Balance Checks

For gift cards, just 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 in order 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 in the API.

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 in order 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.

Close Batch

Close Batch Example:

Linux/Mac OS: ./blockchyp -test -type="close-batch"

Windows: ./blockchyp.exe -test -type="close-batch"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func closeBatchExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.CloseBatchRequest{
        Test: true,
    }

    response, err := client.CloseBatch(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
CloseBatchRequest request = new CloseBatchRequest
{
    Test = true,
};

// Run the transaction.
CloseBatchResponse response = await blockchyp.CloseBatchAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.CloseBatchRequest;
import com.blockchyp.client.dto.CloseBatchResponse;


public class CloseBatchExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        CloseBatchRequest request = new CloseBatchRequest();
        request.setTest(true);

        // Send the request
        CloseBatchResponse response = client.closeBatch(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
];

$response = BlockChyp::closeBatch($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true
}

response = blockchyp.closeBatch(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
}

# run the transaction.
response = client.close_batch(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
  }

  response = client.closeBatch(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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;
  [client closeBatchWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"capturedTotal", [response objectForKey:@"capturedTotal"])
    NSLog(@"%@: %@", @"openPreauths", [response objectForKey:@"openPreauths"])
  }];
  [pool drain];
  return 0;
}


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")
      }
      NSLog("capturedTotal" + ": " + (response["capturedTotal"] as? String).unsafelyUnwrapped)
      NSLog("openPreauths" + ": " + (response["openPreauths"] as? String).unsafelyUnwrapped)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "transactionId": "",
  "batchId": "KJ3DPFELBAI6VOTRNSLM7WZLHE",
  "transactionType": "",
  "timestamp": "",
  "tickBlock": "",
  "test": true,
  "currencyCode": "USD",
  "capturedTotal": "55.00",
  "openPreauths": "0.00"
}

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.

Send Payment Link Example:

Linux/Mac OS: ./blockchyp -test -type="send-link" -displaySubtotal="120.05" -displayTax="5.00" -displayTotal="125.05" -lineItemDescription="Leki Trekking Poles" -lineItemQty=1 -lineItemPrice="135.05" -lineItemDiscountDescription="Member Discount" -lineItemDiscountAmount="10.00" -lineItemExtended="120.05" -desc="Thank you for your order. Your order will be ready in 20 minutes" -email="pgregory@raviga.com" -firstName="Peter" -lastName="Gregory" -amount="125.05" -orderRef="12345" -txRef="MYTXREF" -autoSend

Windows: ./blockchyp.exe -test -type="send-link" -displaySubtotal="120.05" -displayTax="5.00" -displayTotal="125.05" -lineItemDescription="Leki Trekking Poles" -lineItemQty=1 -lineItemPrice="135.05" -lineItemDiscountDescription="Member Discount" -lineItemDiscountAmount="10.00" -lineItemExtended="120.05" -desc="Thank you for your order. Your order will be ready in 20 minutes" -email="pgregory@raviga.com" -firstName="Peter" -lastName="Gregory" -amount="125.05" -orderRef="12345" -txRef="MYTXREF" -autoSend
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func sendPaymentLinkExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.PaymentLinkRequest{
        Amount:      "199.99",
        Description: "Widget",
        Subject:     "Widget invoice",
        Transaction: &blockchyp.TransactionDisplayTransaction{
            Subtotal: "195.00",
            Tax:      "4.99",
            Total:    "199.99",
            Items: []*blockchyp.TransactionDisplayItem{
                &blockchyp.TransactionDisplayItem{
                    Description: "Widget",
                    Price:       "195.00",
                    Quantity:    1,
                },
            },
        },
        AutoSend: true,
        Customer: blockchyp.Customer{
            CustomerRef:  "Customer reference string",
            FirstName:    "FirstName",
            LastName:     "LastName",
            CompanyName:  "Company Name",
            EmailAddress: "support@blockchyp.com",
            SmsNumber:    "(123) 123-1231",
        },
    }

    response, err := client.SendPaymentLink(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
PaymentLinkRequest request = new PaymentLinkRequest
{
    Amount = "199.99",
    Description = "Widget",
    Subject = "Widget invoice",
    Transaction = new TransactionDisplayTransaction
    {
        Subtotal = "195.00",
        Tax = "4.99",
        Total = "199.99",
        Items = new List<TransactionDisplayItem>
        {
            new TransactionDisplayItem
            {
                Description = "Widget",
                Price = "195.00",
                Quantity = 1,
            }
        },
    },
    AutoSend = true,
    Customer = new Customer
    {
        CustomerRef = "Customer reference string",
        FirstName = "FirstName",
        LastName = "LastName",
        CompanyName = "Company Name",
        EmailAddress = "support@blockchyp.com",
        SmsNumber = "(123) 123-1231",
    },
};

// Run the transaction.
PaymentLinkResponse response = await blockchyp.SendPaymentLinkAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.PaymentLinkRequest;
import com.blockchyp.client.dto.PaymentLinkResponse;
import com.blockchyp.client.dto.TransactionDisplayTransaction;
import com.blockchyp.client.dto.TransactionDisplayItem;
import com.blockchyp.client.dto.Customer;


public class SendPaymentLinkExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        PaymentLinkRequest request = new PaymentLinkRequest();
        request.setAmount("199.99");
        request.setDescription("Widget");
        request.setSubject("Widget invoice");

        TransactionDisplayTransaction transaction = new TransactionDisplayTransaction();
        transaction.setSubtotal("195.00");
        transaction.setTax("4.99");
        transaction.setTotal("199.99");

        Collection items = new ArrayList();
        TransactionDisplayItem items0 = new TransactionDisplayItem();
        items0.setDescription("Widget");
        items0.setPrice("195.00");
        items0.setQuantity(1);
        items.add(items0);
        transaction.setItems(items);
        request.setTransaction(transaction);
        request.setAutoSend(true);

        Customer customer = new Customer();
        customer.setCustomerRef("Customer reference string");
        customer.setFirstName("FirstName");
        customer.setLastName("LastName");
        customer.setCompanyName("Company Name");
        customer.setEmailAddress("support@blockchyp.com");
        customer.setSmsNumber("(123) 123-1231");
        request.setCustomer(customer);

        // Send the request
        PaymentLinkResponse response = client.sendPaymentLink(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'amount' => '199.99',
    'description' => 'Widget',
    'subject' => 'Widget invoice',
    'transaction' => [
        'subtotal' => '195.00',
        'tax' => '4.99',
        'total' => '199.99',
        'items' => [
            [
                'description' => 'Widget',
                'price' => '195.00',
                'quantity' => 1,
            ],
        ],
    ],
    'autoSend' => true,
    'customer' => [
        'customerRef' => 'Customer reference string',
        'firstName' => 'FirstName',
        'lastName' => 'LastName',
        'companyName' => 'Company Name',
        'emailAddress' => 'support@blockchyp.com',
        'smsNumber' => '(123) 123-1231',
    ],
];

$response = BlockChyp::sendPaymentLink($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "amount": '199.99',
  "description": 'Widget',
  "subject": 'Widget invoice',
  "transaction": {
    "subtotal": '195.00',
    "tax": '4.99',
    "total": '199.99',
    "items": [
      {
        "description": 'Widget',
        "price": '195.00',
        "quantity": 1
      }
    ]
  },
  "autoSend": true,
  "customer": {
    "customerRef": 'Customer reference string',
    "firstName": 'FirstName',
    "lastName": 'LastName',
    "companyName": 'Company Name',
    "emailAddress": 'support@blockchyp.com',
    "smsNumber": '(123) 123-1231'
  }
}

response = blockchyp.sendPaymentLink(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "amount": "199.99",
    "description": "Widget",
    "subject": "Widget invoice",
    "transaction": {
        "subtotal": "195.00",
        "tax": "4.99",
        "total": "199.99",
        "items": [
            {
                "description": "Widget",
                "price": "195.00",
                "quantity": 1,
            },
        ],
    },
    "autoSend": True,
    "customer": {
        "customerRef": "Customer reference string",
        "firstName": "FirstName",
        "lastName": "LastName",
        "companyName": "Company Name",
        "emailAddress": "support@blockchyp.com",
        "smsNumber": "(123) 123-1231",
    },
}

# run the transaction.
response = client.send_payment_link(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      amount: '199.99',
      description: 'Widget',
      subject: 'Widget invoice',
      transaction:   {
      subtotal: '195.00',
      tax: '4.99',
      total: '199.99',
      items: [
        {
          description: 'Widget',
          price: '195.00',
          quantity: 1,
      },
      ],
  },
      autoSend: true,
      customer:   {
      customerRef: 'Customer reference string',
      firstName: 'FirstName',
      lastName: 'LastName',
      companyName: 'Company Name',
      emailAddress: 'support@blockchyp.com',
      smsNumber: '(123) 123-1231',
  },
  }

  response = client.sendPaymentLink(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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"] = @"199.99";
  request[@"description"] = @"Widget";
  request[@"subject"] = @"Widget invoice";
  [request setObject:[self newTransactionDisplayTransaction] forKey:@"transaction"];
  request[@"autoSend"] = @YES;
  [request setObject:[self newCustomer] forKey:@"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;
}

- (NSDictionary *) newTransactionDisplayTransaction {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"subtotal"] = @"195.00";
  val[@"tax"] = @"4.99";
  val[@"total"] = @"199.99";
  val[@"items"] = [self newTransactionDisplayItems];
  return val;
}
- (NSArray *) newTransactionDisplayItems {
  NSMutableArray *val = [[NSMutableArray alloc] init];
  [val addObject: [self newTransactionDisplayItem2]];
  return val;
}
- (NSDictionary *) newTransactionDisplayItem2 {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"description"] = @"Widget";
  val[@"price"] = @"195.00";
  return val;
}
- (NSDictionary *) newCustomer {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"customerRef"] = @"Customer reference string";
  val[@"firstName"] = @"FirstName";
  val[@"lastName"] = @"LastName";
  val[@"companyName"] = @"Company Name";
  val[@"emailAddress"] = @"support@blockchyp.com";
  val[@"smsNumber"] = @"(123) 123-1231";
  return val;
}

import BlockChyp

class ExampleClass {

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

    var request: [String:Any] = [:]
    request["amount"] = "199.99"
    request["description"] = "Widget"
    request["subject"] = "Widget invoice"
    request["transaction"] = newTransactionDisplayTransaction()
    request["autoSend"] = true
    request["customer"] = newCustomer()
    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)
    })
  }

  func newTransactionDisplayTransaction() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"subtotal"] = @"195.00";
  val[@"tax"] = @"4.99";
  val[@"total"] = @"199.99";
  val[@"items"] = [self newTransactionDisplayItems];
    return val
  }
  func newTransactionDisplayItems()  -> [[String:Any]] {
    var val = [[String:Any]]()
    val.append(newTransactionDisplayItem2())
    return val
  }
  func newTransactionDisplayItem2() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"description"] = @"Widget";
  val[@"price"] = @"195.00";
    return val;
  }
  func newCustomer() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"customerRef"] = @"Customer reference string";
  val[@"firstName"] = @"FirstName";
  val[@"lastName"] = @"LastName";
  val[@"companyName"] = @"Company Name";
  val[@"emailAddress"] = @"support@blockchyp.com";
  val[@"smsNumber"] = @"(123) 123-1231";
    return val
  }

Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "linkCode": "JUC37V2V57337Q5FA7WWTK6GAQ",
  "url": "https://test.blockchyp.com/pay/JUC37V2V57337Q5FA7WWTK6GAQ",
  "customerId": "BUF36REL4QI6VBVHNSLM7WZLHE"
}

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 by 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 a little 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 that's displayed 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 acceptance 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 is a safeguard to prevent real emails from going out when you may not expect it. If you want BlockChyp to send the email for you, just add the autoSend flag with all requests.

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 you don't have a terminal.

If you pass in the cashier flag, no email will be sent and you'll be 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.

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.

Transaction Status

Transaction Status Example:

Linux/Mac OS: ./blockchyp -test -type="tx-status" -tx="<TRANSACTION ID>"

Windows: ./blockchyp.exe -test -type="tx-status" -tx="<TRANSACTION ID>"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func transactionStatusExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.TransactionStatusRequest{
        TransactionID: "ID of transaction to retrieve",
    }

    response, err := client.TransactionStatus(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
TransactionStatusRequest request = new TransactionStatusRequest
{
    TransactionId = "ID of transaction to retrieve",
};

// Run the transaction.
AuthorizationResponse response = await blockchyp.TransactionStatusAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.TransactionStatusRequest;
import com.blockchyp.client.dto.AuthorizationResponse;


public class TransactionStatusExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        TransactionStatusRequest request = new TransactionStatusRequest();
        request.setTransactionId("ID of transaction to retrieve");

        // Send the request
        AuthorizationResponse response = client.transactionStatus(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'transactionId' => 'ID of transaction to retrieve',
];

$response = BlockChyp::transactionStatus($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "transactionId": 'ID of transaction to retrieve'
}

response = blockchyp.transactionStatus(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "transactionId": "ID of transaction to retrieve",
}

# run the transaction.
response = client.transaction_status(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      transactionId: 'ID of transaction to retrieve',
  }

  response = client.transactionStatus(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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"] = @"ID of transaction to retrieve";
  [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;
}


import BlockChyp

class ExampleClass {

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

    var request: [String:Any] = [:]
    request["transactionId"] = "ID of transaction to retrieve"
    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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "approved": true,
  "authCode": "782472",
  "transactionId": "GH7FEIUL64I6VILZNSLM7WZLHE",
  "batchId": "GH7EWQUL64I6VILZNSLM7WZLHE",
  "transactionRef": "MYTXREF",
  "transactionType": "charge",
  "timestamp": "2020-05-01T22:00:39Z",
  "tickBlock": "009991a8ac7b6a4420760e1e14e1689c88be2a610a033d6908c1b04b5c00f9da",
  "test": true,
  "partialAuth": false,
  "altCurrency": false,
  "fsaAuth": false,
  "currencyCode": "USD",
  "requestedAmount": "125.05",
  "authorizedAmount": "125.05",
  "remainingBalance": "",
  "tipAmount": "0.00",
  "taxAmount": "0.00",
  "requestedCashBackAmount": "0.00",
  "authorizedCashBackAmount": "",
  "entryMethod": "KEYED",
  "paymentType": "VISA",
  "maskedPan": "************1111",
  "cardHolder": "PETER GREGORY",
  "avsResponse": "N",
  "receiptSuggestions": {
    "merchantName": "Test Merchant",
    "merchantId": "BUF36EUL4QI6VBUZNSLM7WZLHE",
    "requestSignature": false,
    "maskedPan": "************1111",
    "authorizedAmount": "125.05",
    "transactionType": "charge",
    "entryMethod": "KEYED"
  },
  "customer": {
    "id": "BUF36REL4QI6VBVJNSLM7WZLHE",
    "customerRef": "",
    "firstName": "Peter",
    "lastName": "Gregory",
    "companyName": "",
    "emailAddress": "pgregory@raviga.com",
    "smsNumber": "",
    "paymentMethods": null
  },
  "whiteListedCard": null,
  "storeAndForward": false
}

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.

Terminal Clear

Terminal Clear Example:

Linux/Mac OS: ./blockchyp -test -type="clear" -terminal="Test Terminal"

Windows: ./blockchyp.exe -test -type="clear" -terminal="Test Terminal"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func clearExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.ClearTerminalRequest{
        Test:         true,
        TerminalName: "Test Terminal",
    }

    response, err := client.Clear(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
ClearTerminalRequest request = new ClearTerminalRequest
{
    Test = true,
    TerminalName = "Test Terminal",
};

// Run the transaction.
Acknowledgement response = await blockchyp.ClearAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.ClearTerminalRequest;
import com.blockchyp.client.dto.Acknowledgement;


public class ClearExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        ClearTerminalRequest request = new ClearTerminalRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");

        // Send the request
        Acknowledgement response = client.clear(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
];

$response = BlockChyp::clear($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal'
}

response = blockchyp.clear(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
}

# run the transaction.
response = client.clear(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
  }

  response = client.clear(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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";
  [client clearWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": ""
}

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

Terminal Status

Terminal Status Example:

Linux/Mac OS: ./blockchyp -test -type="terminal-status" -terminal="Test Terminal"

Windows: ./blockchyp.exe -test -type="terminal-status" -terminal="Test Terminal"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func terminalStatusExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.TerminalStatusRequest{
        TerminalName: "Test Terminal",
    }

    response, err := client.TerminalStatus(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
TerminalStatusRequest request = new TerminalStatusRequest
{
    TerminalName = "Test Terminal",
};

// Run the transaction.
TerminalStatusResponse response = await blockchyp.TerminalStatusAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.TerminalStatusRequest;
import com.blockchyp.client.dto.TerminalStatusResponse;


public class TerminalStatusExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        TerminalStatusRequest request = new TerminalStatusRequest();
        request.setTerminalName("Test Terminal");

        // Send the request
        TerminalStatusResponse response = client.terminalStatus(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
];

$response = BlockChyp::terminalStatus($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "terminalName": 'Test Terminal'
}

response = blockchyp.terminalStatus(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "terminalName": "Test Terminal",
}

# run the transaction.
response = client.terminal_status(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      terminalName: 'Test Terminal',
  }

  response = client.terminalStatus(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "idle": false,
  "status": "charge",
  "transactionRef": "MYTXREF",
  "since": "2020-05-01T22:26:08.54243745Z"
}

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 indicating the transaction type currently in progress. The system will also return the timestamp of the last status change in the since field.

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.

Terms & Conditions Capture

Terms & Conditions Capture Example:

Linux/Mac OS: ./blockchyp -test -type="tc" -terminal="Test Terminal" -tcName="HIPPA Disclosure" -tcContent="Loreum Ipsum..."

Windows: ./blockchyp.exe -test -type="tc" -terminal="Test Terminal" -tcName="HIPPA Disclosure" -tcContent="Loreum Ipsum..."
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func termsAndConditionsExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.TermsAndConditionsRequest{
        Test:         true,
        TerminalName: "Test Terminal",

        // Alias for a Terms and Conditions template configured in the BlockChyp dashboard.
        TCAlias: "hippa",

        // Name of the contract or document if not using an alias.
        TCName: "HIPPA Disclosure",

        // Full text of the contract or disclosure if not using an alias.
        TCContent: "Full contract text",

        // file format for the signature image.
        SigFormat: blockchyp.SignatureFormatPNG,

        // width of the signature image in pixels.
        SigWidth: 200,

        // Whether or not a signature is required. Defaults to true.
        SigRequired: true,
    }

    response, err := client.TermsAndConditions(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
TermsAndConditionsRequest request = new TermsAndConditionsRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    TcAlias = "hippa",
    TcName = "HIPPA Disclosure",
    TcContent = "Full contract text",
    SigFormat = SignatureFormat.PNG,
    SigWidth = 200,
    SigRequired = true,
};

// Run the transaction.
TermsAndConditionsResponse response = await blockchyp.TermsAndConditionsAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.TermsAndConditionsRequest;
import com.blockchyp.client.dto.TermsAndConditionsResponse;
import com.blockchyp.client.dto.SignatureFormat;


public class TermsAndConditionsExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        TermsAndConditionsRequest request = new TermsAndConditionsRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setTcAlias("hippa");
        request.setTcName("HIPPA Disclosure");
        request.setTcContent("Full contract text");
        request.setSigFormat(SignatureFormat.PNG);
        request.setSigWidth(200);
        request.setSigRequired(true);

        // Send the request
        TermsAndConditionsResponse response = client.termsAndConditions(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',

    // Alias for a Terms and Conditions template configured in the BlockChyp
    // dashboard.
    'tcAlias' => 'hippa',

    // Name of the contract or document if not using an alias.
    'tcName' => 'HIPPA Disclosure',

    // Full text of the contract or disclosure if not using an alias.
    'tcContent' => 'Full contract text',

    // File format for the signature image.
    'sigFormat' => BlockChyp::SIGNATURE_FORMAT_PNG,

    // Width of the signature image in pixels.
    'sigWidth' => 200,

    // Whether or not a signature is required. Defaults to true.
    'sigRequired' => true,
];

$response = BlockChyp::termsAndConditions($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',

  # Alias for a Terms and Conditions template configured in the BlockChyp
  # dashboard.
  "tcAlias": 'hippa',

  # Name of the contract or document if not using an alias.
  "tcName": 'HIPPA Disclosure',

  # Full text of the contract or disclosure if not using an alias.
  "tcContent": 'Full contract text',

  # File format for the signature image.
  "sigFormat": SignatureFormat::PNG,

  # Width of the signature image in pixels.
  "sigWidth": 200,

  # Whether or not a signature is required. Defaults to true.
  "sigRequired": true
}

response = blockchyp.termsAndConditions(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",

    # Alias for a Terms and Conditions template configured in the BlockChyp
    # dashboard.
    "tcAlias": "hippa",

    # Name of the contract or document if not using an alias.
    "tcName": "HIPPA Disclosure",

    # Full text of the contract or disclosure if not using an alias.
    "tcContent": "Full contract text",

    # File format for the signature image.
    "sigFormat": blockchyp.SignatureFormat.PNG,

    # Width of the signature image in pixels.
    "sigWidth": 200,

    # Whether or not a signature is required. Defaults to true.
    "sigRequired": True,
}

# run the transaction.
response = client.terms_and_conditions(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',

      // Alias for a Terms and Conditions template configured in the BlockChyp
      // dashboard.
      tcAlias: 'hippa',

      // Name of the contract or document if not using an alias.
      tcName: 'HIPPA Disclosure',

      // Full text of the contract or disclosure if not using an alias.
      tcContent: 'Full contract text',

      // File format for the signature image.
      sigFormat: SignatureFormat.PNG,

      // Width of the signature image in pixels.
      sigWidth: 200,

      // Whether or not a signature is required. Defaults to true.
      sigRequired: true,
  }

  response = client.termsAndConditions(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"tcAlias"] = @"hippa";
  request[@"tcName"] = @"HIPPA Disclosure";
  request[@"tcContent"] = @"Full contract text";
  request[@"sigFormat"] = SIGNATURE_FORMAT_PNG;
  request[@"sigWidth"] = @200;
  request[@"sigRequired"] = @YES;
  [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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "test": true
}

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 to 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 the 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 and 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.

Capture Signature

Capture Signature Example:

Linux/Mac OS: ./blockchyp -test -type="capture-signature" -terminal="Test Terminal" -sigFormat="png" -sigWidth="400" -sigFile="sig.png"

Windows: ./blockchyp.exe -test -type="capture-signature" -terminal="Test Terminal" -sigFormat="png" -sigWidth="400" -sigFile="sig.png"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func captureSignatureExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.CaptureSignatureRequest{
        TerminalName: "Test Terminal",

        // file format for the signature image.
        SigFormat: blockchyp.SignatureFormatPNG,

        // width of the signature image in pixels.
        SigWidth: 200,
    }

    response, err := client.CaptureSignature(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
CaptureSignatureRequest request = new CaptureSignatureRequest
{
    TerminalName = "Test Terminal",
    SigFormat = SignatureFormat.PNG,
    SigWidth = 200,
};

// Run the transaction.
CaptureSignatureResponse response = await blockchyp.CaptureSignatureAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.CaptureSignatureRequest;
import com.blockchyp.client.dto.CaptureSignatureResponse;
import com.blockchyp.client.dto.SignatureFormat;


public class CaptureSignatureExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        CaptureSignatureRequest request = new CaptureSignatureRequest();
        request.setTerminalName("Test Terminal");
        request.setSigFormat(SignatureFormat.PNG);
        request.setSigWidth(200);

        // Send the request
        CaptureSignatureResponse response = client.captureSignature(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',

    // File format for the signature image.
    'sigFormat' => BlockChyp::SIGNATURE_FORMAT_PNG,

    // Width of the signature image in pixels.
    'sigWidth' => 200,
];

$response = BlockChyp::captureSignature($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "terminalName": 'Test Terminal',

  # File format for the signature image.
  "sigFormat": SignatureFormat::PNG,

  # Width of the signature image in pixels.
  "sigWidth": 200
}

response = blockchyp.captureSignature(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "terminalName": "Test Terminal",

    # File format for the signature image.
    "sigFormat": blockchyp.SignatureFormat.PNG,

    # Width of the signature image in pixels.
    "sigWidth": 200,
}

# run the transaction.
response = client.capture_signature(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      terminalName: 'Test Terminal',

      // File format for the signature image.
      sigFormat: SignatureFormat.PNG,

      // Width of the signature image in pixels.
      sigWidth: 200,
  }

  response = client.captureSignature(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": ""
}

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. As of this writing 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.

New Transaction Display

New Transaction Display Example:

Linux/Mac OS: ./blockchyp -test -type="display" -terminal="Test Terminal" -displaySubtotal="120.05" -displayTax="5.00" -displayTotal="125.05" -lineItemDescription="Leki Trekking Poles" -lineItemQty="1" -lineItemPrice="135.05" -lineItemDiscountDescription="Member Discount" -lineItemDiscountAmount="10.00" -lineItemExtended="120.05"

Windows: ./blockchyp.exe -test -type="display" -terminal="Test Terminal" -displaySubtotal="120.05" -displayTax="5.00" -displayTotal="125.05" -lineItemDescription="Leki Trekking Poles" -lineItemQty="1" -lineItemPrice="135.05" -lineItemDiscountDescription="Member Discount" -lineItemDiscountAmount="10.00" -lineItemExtended="120.05"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func newTransactionDisplayExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.TransactionDisplayRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        Transaction: &blockchyp.TransactionDisplayTransaction{
            Subtotal: "60.00",
            Tax:      "5.00",
            Total:    "65.00",
            Items: []*blockchyp.TransactionDisplayItem{
                &blockchyp.TransactionDisplayItem{
                    Description: "Leki Trekking Poles",
                    Price:       "35.00",
                    Quantity:    2,
                    Extended:    "70.00",
                    Discounts: []*blockchyp.TransactionDisplayDiscount{
                        &blockchyp.TransactionDisplayDiscount{
                            Description: "memberDiscount",
                            Amount:      "10.00",
                        },
                    },
                },
            },
        },
    }

    response, err := client.NewTransactionDisplay(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
TransactionDisplayRequest request = new TransactionDisplayRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    Transaction = new TransactionDisplayTransaction
    {
        Subtotal = "60.00",
        Tax = "5.00",
        Total = "65.00",
        Items = new List<TransactionDisplayItem>
        {
            new TransactionDisplayItem
            {
                Description = "Leki Trekking Poles",
                Price = "35.00",
                Quantity = 2,
                Extended = "70.00",
                Discounts = new List<TransactionDisplayDiscount>
                {
                    new TransactionDisplayDiscount
                    {
                        Description = "memberDiscount",
                        Amount = "10.00",
                    }
                },
            }
        },
    },
};

// Run the transaction.
Acknowledgement response = await blockchyp.NewTransactionDisplayAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.TransactionDisplayRequest;
import com.blockchyp.client.dto.Acknowledgement;
import com.blockchyp.client.dto.TransactionDisplayTransaction;
import com.blockchyp.client.dto.TransactionDisplayItem;
import com.blockchyp.client.dto.TransactionDisplayDiscount;


public class NewTransactionDisplayExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        TransactionDisplayRequest request = new TransactionDisplayRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");

        TransactionDisplayTransaction transaction = new TransactionDisplayTransaction();
        transaction.setSubtotal("60.00");
        transaction.setTax("5.00");
        transaction.setTotal("65.00");

        Collection items = new ArrayList();
        TransactionDisplayItem items0 = new TransactionDisplayItem();
        items0.setDescription("Leki Trekking Poles");
        items0.setPrice("35.00");
        items0.setQuantity(2);
        items0.setExtended("70.00");

        Collection discounts = new ArrayList();
        TransactionDisplayDiscount discounts0 = new TransactionDisplayDiscount();
        discounts0.setDescription("memberDiscount");
        discounts0.setAmount("10.00");
        discounts.add(discounts0);
        items0.setDiscounts(discounts);
        items.add(items0);
        transaction.setItems(items);
        request.setTransaction(transaction);

        // Send the request
        Acknowledgement response = client.newTransactionDisplay(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'transaction' => [
        'subtotal' => '60.00',
        'tax' => '5.00',
        'total' => '65.00',
        'items' => [
            [
                'description' => 'Leki Trekking Poles',
                'price' => '35.00',
                'quantity' => 2,
                'extended' => '70.00',
                'discounts' => [
                    [
                        'description' => 'memberDiscount',
                        'amount' => '10.00',
                    ],
                ],
            ],
        ],
    ],
];

$response = BlockChyp::newTransactionDisplay($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "transaction": {
    "subtotal": '60.00',
    "tax": '5.00',
    "total": '65.00',
    "items": [
      {
        "description": 'Leki Trekking Poles',
        "price": '35.00',
        "quantity": 2,
        "extended": '70.00',
        "discounts": [
          {
            "description": 'memberDiscount',
            "amount": '10.00'
          }
        ]
      }
    ]
  }
}

response = blockchyp.newTransactionDisplay(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "transaction": {
        "subtotal": "60.00",
        "tax": "5.00",
        "total": "65.00",
        "items": [
            {
                "description": "Leki Trekking Poles",
                "price": "35.00",
                "quantity": 2,
                "extended": "70.00",
                "discounts": [
                    {
                        "description": "memberDiscount",
                        "amount": "10.00",
                    },
                ],
            },
        ],
    },
}

# run the transaction.
response = client.new_transaction_display(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      transaction:   {
      subtotal: '60.00',
      tax: '5.00',
      total: '65.00',
      items: [
        {
          description: 'Leki Trekking Poles',
          price: '35.00',
          quantity: 2,
          extended: '70.00',
          discounts: [
          {
            description: 'memberDiscount',
            amount: '10.00',
        },
        ],
      },
      ],
  },
  }

  response = client.newTransactionDisplay(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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 setObject:[self newTransactionDisplayTransaction] forKey:@"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;
}

- (NSDictionary *) newTransactionDisplayTransaction {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"subtotal"] = @"60.00";
  val[@"tax"] = @"5.00";
  val[@"total"] = @"65.00";
  val[@"items"] = [self newTransactionDisplayItems];
  return val;
}
- (NSArray *) newTransactionDisplayItems {
  NSMutableArray *val = [[NSMutableArray alloc] init];
  [val addObject: [self newTransactionDisplayItem2]];
  return val;
}
- (NSDictionary *) newTransactionDisplayItem2 {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"description"] = @"Leki Trekking Poles";
  val[@"price"] = @"35.00";
  val[@"extended"] = @"70.00";
  val[@"discounts"] = [self newTransactionDisplayDiscounts];
  return val;
}
- (NSArray *) newTransactionDisplayDiscounts {
  NSMutableArray *val = [[NSMutableArray alloc] init];
  [val addObject: [self newTransactionDisplayDiscount2]];
  return val;
}
- (NSDictionary *) newTransactionDisplayDiscount2 {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"description"] = @"memberDiscount";
  val[@"amount"] = @"10.00";
  return val;
}

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["transaction"] = newTransactionDisplayTransaction()
    client.newTransactionDisplay(withRequest: request, handler: { (request, response, error) in
      let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

  func newTransactionDisplayTransaction() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"subtotal"] = @"60.00";
  val[@"tax"] = @"5.00";
  val[@"total"] = @"65.00";
  val[@"items"] = [self newTransactionDisplayItems];
    return val
  }
  func newTransactionDisplayItems()  -> [[String:Any]] {
    var val = [[String:Any]]()
    val.append(newTransactionDisplayItem2())
    return val
  }
  func newTransactionDisplayItem2() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"description"] = @"Leki Trekking Poles";
  val[@"price"] = @"35.00";
  val[@"extended"] = @"70.00";
  val[@"discounts"] = [self newTransactionDisplayDiscounts];
    return val;
  }
  func newTransactionDisplayDiscounts()  -> [[String:Any]] {
    var val = [[String:Any]]()
    val.append(newTransactionDisplayDiscount2())
    return val
  }
  func newTransactionDisplayDiscount2() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"description"] = @"memberDiscount";
  val[@"amount"] = @"10.00";
    return val;
  }

Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": ""
}

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, but we strongly recommend you precalculate all the fields yourself to ensure consistency. Your treatment of floating-point multiplication and rounding may differ slightly from BlockChyp's, for example.

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.

Update Transaction Display

Update Transaction Display Example:

Linux/Mac OS: ./blockchyp -test -type="display" -terminal="Test Terminal" -displaySubtotal="120.05" -displayTax="5.00" -displayTotal="125.05" -lineItemDescription="Leki Trekking Poles" -lineItemQty="1" -lineItemPrice="135.05" -lineItemDiscountDescription="Member Discount" -lineItemDiscountAmount="10.00" -lineItemExtended="120.05"

Windows: ./blockchyp.exe -test -type="display" -terminal="Test Terminal" -displaySubtotal="120.05" -displayTax="5.00" -displayTotal="125.05" -lineItemDescription="Leki Trekking Poles" -lineItemQty="1" -lineItemPrice="135.05" -lineItemDiscountDescription="Member Discount" -lineItemDiscountAmount="10.00" -lineItemExtended="120.05"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func updateTransactionDisplayExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.TransactionDisplayRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        Transaction: &blockchyp.TransactionDisplayTransaction{
            Subtotal: "60.00",
            Tax:      "5.00",
            Total:    "65.00",
            Items: []*blockchyp.TransactionDisplayItem{
                &blockchyp.TransactionDisplayItem{
                    Description: "Leki Trekking Poles",
                    Price:       "35.00",
                    Quantity:    2,
                    Extended:    "70.00",
                    Discounts: []*blockchyp.TransactionDisplayDiscount{
                        &blockchyp.TransactionDisplayDiscount{
                            Description: "memberDiscount",
                            Amount:      "10.00",
                        },
                    },
                },
            },
        },
    }

    response, err := client.UpdateTransactionDisplay(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
TransactionDisplayRequest request = new TransactionDisplayRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    Transaction = new TransactionDisplayTransaction
    {
        Subtotal = "60.00",
        Tax = "5.00",
        Total = "65.00",
        Items = new List<TransactionDisplayItem>
        {
            new TransactionDisplayItem
            {
                Description = "Leki Trekking Poles",
                Price = "35.00",
                Quantity = 2,
                Extended = "70.00",
                Discounts = new List<TransactionDisplayDiscount>
                {
                    new TransactionDisplayDiscount
                    {
                        Description = "memberDiscount",
                        Amount = "10.00",
                    }
                },
            }
        },
    },
};

// Run the transaction.
Acknowledgement response = await blockchyp.UpdateTransactionDisplayAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.TransactionDisplayRequest;
import com.blockchyp.client.dto.Acknowledgement;
import com.blockchyp.client.dto.TransactionDisplayTransaction;
import com.blockchyp.client.dto.TransactionDisplayItem;
import com.blockchyp.client.dto.TransactionDisplayDiscount;


public class UpdateTransactionDisplayExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        TransactionDisplayRequest request = new TransactionDisplayRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");

        TransactionDisplayTransaction transaction = new TransactionDisplayTransaction();
        transaction.setSubtotal("60.00");
        transaction.setTax("5.00");
        transaction.setTotal("65.00");

        Collection items = new ArrayList();
        TransactionDisplayItem items0 = new TransactionDisplayItem();
        items0.setDescription("Leki Trekking Poles");
        items0.setPrice("35.00");
        items0.setQuantity(2);
        items0.setExtended("70.00");

        Collection discounts = new ArrayList();
        TransactionDisplayDiscount discounts0 = new TransactionDisplayDiscount();
        discounts0.setDescription("memberDiscount");
        discounts0.setAmount("10.00");
        discounts.add(discounts0);
        items0.setDiscounts(discounts);
        items.add(items0);
        transaction.setItems(items);
        request.setTransaction(transaction);

        // Send the request
        Acknowledgement response = client.updateTransactionDisplay(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'transaction' => [
        'subtotal' => '60.00',
        'tax' => '5.00',
        'total' => '65.00',
        'items' => [
            [
                'description' => 'Leki Trekking Poles',
                'price' => '35.00',
                'quantity' => 2,
                'extended' => '70.00',
                'discounts' => [
                    [
                        'description' => 'memberDiscount',
                        'amount' => '10.00',
                    ],
                ],
            ],
        ],
    ],
];

$response = BlockChyp::updateTransactionDisplay($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "transaction": {
    "subtotal": '60.00',
    "tax": '5.00',
    "total": '65.00',
    "items": [
      {
        "description": 'Leki Trekking Poles',
        "price": '35.00',
        "quantity": 2,
        "extended": '70.00',
        "discounts": [
          {
            "description": 'memberDiscount',
            "amount": '10.00'
          }
        ]
      }
    ]
  }
}

response = blockchyp.updateTransactionDisplay(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "transaction": {
        "subtotal": "60.00",
        "tax": "5.00",
        "total": "65.00",
        "items": [
            {
                "description": "Leki Trekking Poles",
                "price": "35.00",
                "quantity": 2,
                "extended": "70.00",
                "discounts": [
                    {
                        "description": "memberDiscount",
                        "amount": "10.00",
                    },
                ],
            },
        ],
    },
}

# run the transaction.
response = client.update_transaction_display(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      transaction:   {
      subtotal: '60.00',
      tax: '5.00',
      total: '65.00',
      items: [
        {
          description: 'Leki Trekking Poles',
          price: '35.00',
          quantity: 2,
          extended: '70.00',
          discounts: [
          {
            description: 'memberDiscount',
            amount: '10.00',
        },
        ],
      },
      ],
  },
  }

  response = client.updateTransactionDisplay(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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 setObject:[self newTransactionDisplayTransaction] forKey:@"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;
}

- (NSDictionary *) newTransactionDisplayTransaction {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"subtotal"] = @"60.00";
  val[@"tax"] = @"5.00";
  val[@"total"] = @"65.00";
  val[@"items"] = [self newTransactionDisplayItems];
  return val;
}
- (NSArray *) newTransactionDisplayItems {
  NSMutableArray *val = [[NSMutableArray alloc] init];
  [val addObject: [self newTransactionDisplayItem2]];
  return val;
}
- (NSDictionary *) newTransactionDisplayItem2 {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"description"] = @"Leki Trekking Poles";
  val[@"price"] = @"35.00";
  val[@"extended"] = @"70.00";
  val[@"discounts"] = [self newTransactionDisplayDiscounts];
  return val;
}
- (NSArray *) newTransactionDisplayDiscounts {
  NSMutableArray *val = [[NSMutableArray alloc] init];
  [val addObject: [self newTransactionDisplayDiscount2]];
  return val;
}
- (NSDictionary *) newTransactionDisplayDiscount2 {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"description"] = @"memberDiscount";
  val[@"amount"] = @"10.00";
  return val;
}

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["transaction"] = newTransactionDisplayTransaction()
    client.updateTransactionDisplay(withRequest: request, handler: { (request, response, error) in
      let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }

  func newTransactionDisplayTransaction() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"subtotal"] = @"60.00";
  val[@"tax"] = @"5.00";
  val[@"total"] = @"65.00";
  val[@"items"] = [self newTransactionDisplayItems];
    return val
  }
  func newTransactionDisplayItems()  -> [[String:Any]] {
    var val = [[String:Any]]()
    val.append(newTransactionDisplayItem2())
    return val
  }
  func newTransactionDisplayItem2() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"description"] = @"Leki Trekking Poles";
  val[@"price"] = @"35.00";
  val[@"extended"] = @"70.00";
  val[@"discounts"] = [self newTransactionDisplayDiscounts];
    return val;
  }
  func newTransactionDisplayDiscounts()  -> [[String:Any]] {
    var val = [[String:Any]]()
    val.append(newTransactionDisplayDiscount2())
    return val
  }
  func newTransactionDisplayDiscount2() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"description"] = @"memberDiscount";
  val[@"amount"] = @"10.00";
    return val;
  }

Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": ""
}

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

This is designed for situations where you want to update the terminal display as items are scanned. This variant means you 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, but we strongly recommend you precalculate all the fields yourself to ensure consistency. Your treatment of floating-point multiplication and rounding may differ slightly from BlockChyp's, for example.

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.

Display Message

Display Message Example:

Linux/Mac OS: ./blockchyp -test -type="message" -terminal="Test Terminal" -message="Thank you for your business."

Windows: ./blockchyp.exe -test -type="message" -terminal="Test Terminal" -message="Thank you for your business."
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func messageExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.MessageRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        Message:      "Thank you for your business.",
    }

    response, err := client.Message(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
MessageRequest request = new MessageRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    Message = "Thank you for your business.",
};

// Run the transaction.
Acknowledgement response = await blockchyp.MessageAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.MessageRequest;
import com.blockchyp.client.dto.Acknowledgement;


public class MessageExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        MessageRequest request = new MessageRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setMessage("Thank you for your business.");

        // Send the request
        Acknowledgement response = client.message(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'message' => 'Thank you for your business.',
];

$response = BlockChyp::message($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "message": 'Thank you for your business.'
}

response = blockchyp.message(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "message": "Thank you for your business.",
}

# run the transaction.
response = client.message(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      message: 'Thank you for your business.',
  }

  response = client.message(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"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;
}


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")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": ""
}

Displays a message on the payment terminal.

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

Boolean Prompt

Boolean Prompt Example:

Linux/Mac OS: ./blockchyp -test -type="boolean-prompt" -terminal="Test Terminal" -prompt="Would you like to become a member?"

Windows: ./blockchyp.exe -test -type="boolean-prompt" -terminal="Test Terminal" -prompt="Would you like to become a member?"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func booleanPromptExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.BooleanPromptRequest{
        Test:         true,
        TerminalName: "Test Terminal",
        Prompt:       "Would you like to become a member?",
        YesCaption:   "Yes",
        NoCaption:    "No",
    }

    response, err := client.BooleanPrompt(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
BooleanPromptRequest request = new BooleanPromptRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    Prompt = "Would you like to become a member?",
    YesCaption = "Yes",
    NoCaption = "No",
};

// Run the transaction.
BooleanPromptResponse response = await blockchyp.BooleanPromptAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.BooleanPromptRequest;
import com.blockchyp.client.dto.BooleanPromptResponse;


public class BooleanPromptExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        BooleanPromptRequest request = new BooleanPromptRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setPrompt("Would you like to become a member?");
        request.setYesCaption("Yes");
        request.setNoCaption("No");

        // Send the request
        BooleanPromptResponse response = client.booleanPrompt(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'prompt' => 'Would you like to become a member?',
    'yesCaption' => 'Yes',
    'noCaption' => 'No',
];

$response = BlockChyp::booleanPrompt($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',
  "prompt": 'Would you like to become a member?',
  "yesCaption": 'Yes',
  "noCaption": 'No'
}

response = blockchyp.booleanPrompt(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",
    "prompt": "Would you like to become a member?",
    "yesCaption": "Yes",
    "noCaption": "No",
}

# run the transaction.
response = client.boolean_prompt(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',
      prompt: 'Would you like to become a member?',
      yesCaption: 'Yes',
      noCaption: 'No',
  }

  response = client.booleanPrompt(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "response": true
}

Prompts 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.

Text Prompt

Text Prompt Example:

Linux/Mac OS: ./blockchyp -test -type="text-prompt" -terminal="Test Terminal" -promptType="phone"

Windows: ./blockchyp.exe -test -type="text-prompt" -terminal="Test Terminal" -promptType="phone"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func textPromptExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.TextPromptRequest{
        Test:         true,
        TerminalName: "Test Terminal",

        // Type of prompt. Can be 'email', 'phone', 'customer-number', or 'rewards-number'.
        PromptType: blockchyp.PromptTypeEmail,
    }

    response, err := client.TextPrompt(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
TextPromptRequest request = new TextPromptRequest
{
    Test = true,
    TerminalName = "Test Terminal",
    PromptType = PromptType.Email,
};

// Run the transaction.
TextPromptResponse response = await blockchyp.TextPromptAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.TextPromptRequest;
import com.blockchyp.client.dto.TextPromptResponse;
import com.blockchyp.client.dto.PromptType;


public class TextPromptExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        TextPromptRequest request = new TextPromptRequest();
        request.setTest(true);
        request.setTerminalName("Test Terminal");
        request.setPromptType(PromptType.EMAIL);

        // Send the request
        TextPromptResponse response = client.textPrompt(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',

    // Type of prompt. Can be 'email', 'phone', 'customer-number', or
    // 'rewards-number'.
    'promptType' => BlockChyp::PROMPT_TYPE_EMAIL,
];

$response = BlockChyp::textPrompt($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "test": true,
  "terminalName": 'Test Terminal',

  # Type of prompt. Can be 'email', 'phone', 'customer-number', or
  # 'rewards-number'.
  "promptType": PromptType::EMAIL
}

response = blockchyp.textPrompt(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "test": True,
    "terminalName": "Test Terminal",

    # Type of prompt. Can be 'email', 'phone', 'customer-number', or
    # 'rewards-number'.
    "promptType": blockchyp.PromptType.EMAIL,
}

# run the transaction.
response = client.text_prompt(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      test: true,
      terminalName: 'Test Terminal',

      // Type of prompt. Can be 'email', 'phone', 'customer-number', or
      // 'rewards-number'.
      promptType: PromptType.EMAIL,
  }

  response = client.textPrompt(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "response": "9136488888"
}

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:

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

Update Customer

Update Customer Example:

Linux/Mac OS: ./blockchyp -test -type="update-customer" -firstName="Peter" -lastName="Gregory" -companyName="Raviga Capital" -email="peter@raviga.capital" -sms="9136488888"

Windows: ./blockchyp.exe -test -type="update-customer" -firstName="Peter" -lastName="Gregory" -companyName="Raviga Capital" -email="peter@raviga.capital" -sms="9136488888"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func updateCustomerExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.UpdateCustomerRequest{
        Customer: blockchyp.Customer{
            ID:           "ID of the customer to update",
            CustomerRef:  "Customer reference string",
            FirstName:    "FirstName",
            LastName:     "LastName",
            CompanyName:  "Company Name",
            EmailAddress: "support@blockchyp.com",
            SmsNumber:    "(123) 123-1231",
        },
    }

    response, err := client.UpdateCustomer(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
UpdateCustomerRequest request = new UpdateCustomerRequest
{
    Customer = new Customer
    {
        Id = "ID of the customer to update",
        CustomerRef = "Customer reference string",
        FirstName = "FirstName",
        LastName = "LastName",
        CompanyName = "Company Name",
        EmailAddress = "support@blockchyp.com",
        SmsNumber = "(123) 123-1231",
    },
};

// Run the transaction.
CustomerResponse response = await blockchyp.UpdateCustomerAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.UpdateCustomerRequest;
import com.blockchyp.client.dto.CustomerResponse;
import com.blockchyp.client.dto.Customer;


public class UpdateCustomerExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        UpdateCustomerRequest request = new UpdateCustomerRequest();

        Customer customer = new Customer();
        customer.setId("ID of the customer to update");
        customer.setCustomerRef("Customer reference string");
        customer.setFirstName("FirstName");
        customer.setLastName("LastName");
        customer.setCompanyName("Company Name");
        customer.setEmailAddress("support@blockchyp.com");
        customer.setSmsNumber("(123) 123-1231");
        request.setCustomer(customer);

        // Send the request
        CustomerResponse response = client.updateCustomer(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'customer' => [
        'id' => 'ID of the customer to update',
        'customerRef' => 'Customer reference string',
        'firstName' => 'FirstName',
        'lastName' => 'LastName',
        'companyName' => 'Company Name',
        'emailAddress' => 'support@blockchyp.com',
        'smsNumber' => '(123) 123-1231',
    ],
];

$response = BlockChyp::updateCustomer($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "customer": {
    "id": 'ID of the customer to update',
    "customerRef": 'Customer reference string',
    "firstName": 'FirstName',
    "lastName": 'LastName',
    "companyName": 'Company Name',
    "emailAddress": 'support@blockchyp.com',
    "smsNumber": '(123) 123-1231'
  }
}

response = blockchyp.updateCustomer(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "customer": {
        "id": "ID of the customer to update",
        "customerRef": "Customer reference string",
        "firstName": "FirstName",
        "lastName": "LastName",
        "companyName": "Company Name",
        "emailAddress": "support@blockchyp.com",
        "smsNumber": "(123) 123-1231",
    },
}

# run the transaction.
response = client.update_customer(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      customer:   {
      id: 'ID of the customer to update',
      customerRef: 'Customer reference string',
      firstName: 'FirstName',
      lastName: 'LastName',
      companyName: 'Company Name',
      emailAddress: 'support@blockchyp.com',
      smsNumber: '(123) 123-1231',
  },
  }

  response = client.updateCustomer(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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 setObject:[self newCustomer] forKey:@"customer"];
  [client updateCustomerWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"customer", [response objectForKey:@"customer"])
  }];
  [pool drain];
  return 0;
}

- (NSDictionary *) newCustomer {
  NSMutableDictionary *val = [[NSMutableDictionary alloc] init];
  val[@"id"] = @"ID of the customer to update";
  val[@"customerRef"] = @"Customer reference string";
  val[@"firstName"] = @"FirstName";
  val[@"lastName"] = @"LastName";
  val[@"companyName"] = @"Company Name";
  val[@"emailAddress"] = @"support@blockchyp.com";
  val[@"smsNumber"] = @"(123) 123-1231";
  return val;
}

import BlockChyp

class ExampleClass {

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

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

  func newCustomer() -> [String:Any] {
    var val: [String:Any] = [:]
  val[@"id"] = @"ID of the customer to update";
  val[@"customerRef"] = @"Customer reference string";
  val[@"firstName"] = @"FirstName";
  val[@"lastName"] = @"LastName";
  val[@"companyName"] = @"Company Name";
  val[@"emailAddress"] = @"support@blockchyp.com";
  val[@"smsNumber"] = @"(123) 123-1231";
    return val
  }

Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "customer": {
    "id": "P7UV23UOEII6VJCUAJBKYEIAAI",
    "customerRef": "",
    "firstName": "Peter",
    "lastName": "Gregory",
    "companyName": "Raviga Capital",
    "emailAddress": "peter@raviga.capital",
    "smsNumber": "9136488888",
    "paymentMethods": null
  }
}

Adds or updates a customer record.

If you pass in customer information including firstName, lastName, email, email, or sms without any Customer ID or Customer Ref, a new record will be created.

If you pass in customerRef and customerId, the customer record will be updated if it exists.

Customer Ref

The customerRef field is optional, but highly recommended as this allows you to use your own customer identifiers instead of storing BlockChyp's Customer IDs in your systems.

Creating Customer Records With Payment Transactions

If you have customer information available at the time a payment transaction is executed, you can pass all the same customer information directly into a payment transaction and create a customer record at the same time payment is captured. The advantage of this approach is that the customer's payment card is automatically associated with the customer record in a single step. If the customer uses the payment card in the future, the customer data will automatically be returned without needing to ask the customer to provide any additional information.

Retrieve Customer

Retrieve Customer Example:

Linux/Mac OS: ./blockchyp -test -type="get-customer" -customerId="P7UV23UOEII6VJCUAJBKYEIAAI"

Windows: ./blockchyp.exe -test -type="get-customer" -customerId="P7UV23UOEII6VJCUAJBKYEIAAI"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func customerExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.CustomerRequest{
        CustomerID: "ID of the customer to retrieve",
    }

    response, err := client.Customer(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
CustomerRequest request = new CustomerRequest
{
    CustomerId = "ID of the customer to retrieve",
};

// Run the transaction.
CustomerResponse response = await blockchyp.CustomerAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.CustomerRequest;
import com.blockchyp.client.dto.CustomerResponse;


public class CustomerExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        CustomerRequest request = new CustomerRequest();
        request.setCustomerId("ID of the customer to retrieve");

        // Send the request
        CustomerResponse response = client.customer(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'customerId' => 'ID of the customer to retrieve',
];

$response = BlockChyp::customer($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "customerId": 'ID of the customer to retrieve'
}

response = blockchyp.customer(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "customerId": "ID of the customer to retrieve",
}

# run the transaction.
response = client.customer(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      customerId: 'ID of the customer to retrieve',
  }

  response = client.customer(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"customerId"] = @"ID of the customer to retrieve";
  [client customerWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"customer", [response objectForKey:@"customer"])
  }];
  [pool drain];
  return 0;
}


import BlockChyp

class ExampleClass {

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

    var request: [String:Any] = [:]
    request["customerId"] = "ID of the customer to retrieve"
    client.customer(withRequest: request, handler: { (request, response, error) in
      let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("customer" + ": " + (response["customer"] as? String).unsafelyUnwrapped)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "customer": {
    "id": "P7UV23UOEII6VJCUAJBKYEIAAI",
    "customerRef": "",
    "firstName": "Peter",
    "lastName": "Gregory",
    "companyName": "Raviga Capital",
    "emailAddress": "peter@raviga.capital",
    "smsNumber": "9136488888",
    "paymentMethods": [
      {
        "token": "JFDODVEUTFIXIKG5G4NWQFLKV4",
        "maskedPan": "************0010",
        "expiryMonth": "12",
        "expiryYear": "22",
        "paymentType": "VISA"
      }
    ]
  }
}

Retrieves detailed information about a customer record, including saved payment methods if available.

Customers can be looked up by customerId or customerRef.

Search Customer

Search Customer Example:

Linux/Mac OS: ./blockchyp -test -type="search-customer" -query="Peter"

Windows: ./blockchyp.exe -test -type="search-customer" -query="Peter"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func customerSearchExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.CustomerSearchRequest{
        Query: "(123) 123-1234",
    }

    response, err := client.CustomerSearch(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
CustomerSearchRequest request = new CustomerSearchRequest
{
    Query = "(123) 123-1234",
};

// Run the transaction.
CustomerSearchResponse response = await blockchyp.CustomerSearchAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.CustomerSearchRequest;
import com.blockchyp.client.dto.CustomerSearchResponse;


public class CustomerSearchExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        CustomerSearchRequest request = new CustomerSearchRequest();
        request.setQuery("(123) 123-1234");

        // Send the request
        CustomerSearchResponse response = client.customerSearch(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'query' => '(123) 123-1234',
];

$response = BlockChyp::customerSearch($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "query": '(123) 123-1234'
}

response = blockchyp.customerSearch(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "query": "(123) 123-1234",
}

# run the transaction.
response = client.customer_search(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      query: '(123) 123-1234',
  }

  response = client.customerSearch(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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[@"query"] = @"(123) 123-1234";
  [client customerSearchWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
    NSLog(@"%@: %@", @"customers", [response objectForKey:@"customers"])
  }];
  [pool drain];
  return 0;
}


import BlockChyp

class ExampleClass {

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

    var request: [String:Any] = [:]
    request["query"] = "(123) 123-1234"
    client.customerSearch(withRequest: request, handler: { (request, response, error) in
      let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
      NSLog("customers" + ": " + (response["customers"] as? String).unsafelyUnwrapped)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "customers": [
    {
      "id": "EWEMCMDO2YI6VHR6AJBKYEIAAM",
      "customerRef": "",
      "firstName": "Peter",
      "lastName": "Pan",
      "companyName": "Lost Boys",
      "emailAddress": "peter@blockchyp.com",
      "smsNumber": "",
      "paymentMethods": null
    },
    {
      "id": "P7UV23UOEII6VJCUAJBKYEIAAI",
      "customerRef": "",
      "firstName": "Peter",
      "lastName": "Gregory",
      "companyName": "Raviga Capital",
      "emailAddress": "peter@raviga.capital",
      "smsNumber": "9136488888",
      "paymentMethods": null
    }
  ]
}

Searches the customer database and returns matching results.

Use query to pass in a search string and the system will return all results whose first or last names contain the query string.

Cash Discount

Cash Discount Example:

Linux/Mac OS: ./blockchyp -test -type="cash-discount" -amount="100.00" -surcharge -cashDiscount

Windows: ./blockchyp.exe -test -type="cash-discount" -amount="100.00" -surcharge -cashDiscount
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func cashDiscountExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.CashDiscountRequest{
        Amount:       "100.00",
        CashDiscount: true,
        Surcharge:    true,
    }

    response, err := client.CashDiscount(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
CashDiscountRequest request = new CashDiscountRequest
{
    Amount = "100.00",
    CashDiscount = true,
    Surcharge = true,
};

// Run the transaction.
CashDiscountResponse response = await blockchyp.CashDiscountAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.CashDiscountRequest;
import com.blockchyp.client.dto.CashDiscountResponse;


public class CashDiscountExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        CashDiscountRequest request = new CashDiscountRequest();
        request.setAmount("100.00");
        request.setCashDiscount(true);
        request.setSurcharge(true);

        // Send the request
        CashDiscountResponse response = client.cashDiscount(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'amount' => '100.00',
    'cashDiscount' => true,
    'surcharge' => true,
];

$response = BlockChyp::cashDiscount($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "amount": '100.00',
  "cashDiscount": true,
  "surcharge": true
}

response = blockchyp.cashDiscount(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "amount": "100.00",
    "cashDiscount": True,
    "surcharge": True,
}

# run the transaction.
response = client.cash_discount(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      amount: '100.00',
      cashDiscount: true,
      surcharge: true,
  }

  response = client.cashDiscount(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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"] = @YES;
  request[@"surcharge"] = @YES;
  [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;
}


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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "currencyCode": "",
  "amount": "100.00",
  "taxExempt": false,
  "surcharge": "3.81",
  "cashDiscount": "3.81"
}

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 make sure the numbers and receipts for true cash transactions are consistent with transactions processed by BlockChyp.

Batch History

Batch History Example:

Linux/Mac OS: ./blockchyp -test -type="batch-history" -maxResults="250" -startIndex="1"

Windows: ./blockchyp.exe -test -type="batch-history" -maxResults="250" -startIndex="1"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func batchHistoryExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.BatchHistoryRequest{
        MaxResults: 250,
        StartIndex: 1,
    }

    response, err := client.BatchHistory(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
BatchHistoryRequest request = new BatchHistoryRequest
{
    MaxResults = 250,
    StartIndex = 1,
};

// Run the transaction.
BatchHistoryResponse response = await blockchyp.BatchHistoryAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.BatchHistoryRequest;
import com.blockchyp.client.dto.BatchHistoryResponse;


public class BatchHistoryExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        BatchHistoryRequest request = new BatchHistoryRequest();
        request.setMaxResults(250);
        request.setStartIndex(1);

        // Send the request
        BatchHistoryResponse response = client.batchHistory(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'maxResults' => 250,
    'startIndex' => 1,
];

$response = BlockChyp::batchHistory($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "maxResults": 250,
  "startIndex": 1
}

response = blockchyp.batchHistory(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "maxResults": 250,
    "startIndex": 1,
}

# run the transaction.
response = client.batch_history(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      maxResults: 250,
      startIndex: 1,
  }

  response = client.batchHistory(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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"] = @1;
  [client batchHistoryWithRequest:request handler:^(NSDictionary *request, NSDictionary *response, NSError *error) {
    NSNumber *success = [response objectForKey:@"success"];
    if (success.boolValue) {
      NSLog(@"Success");
    }
  }];
  [pool drain];
  return 0;
}


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"] = 1
    client.batchHistory(withRequest: request, handler: { (request, response, error) in
      let approved = response["success"] as? Bool
      if (approved.unsafelyUnwrapped) {
        NSLog("Success")
      }
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "startDate": "",
  "endDate": "",
  "batches": [
    {
      "batchId": "OPXQNZEUSAI6VL2FNSLM7WZLHE",
      "capturedAmount": "146.44",
      "open": true,
      "openDate": "2020-05-12T20:45:28Z",
      "closeDate": "0001-01-01T00:00:00Z"
    },
    {
      "batchId": "OPXQNZEUSAI6VL2CNSLM7WZLHE",
      "capturedAmount": "57.79",
      "open": false,
      "openDate": "2020-05-12T20:44:11Z",
      "closeDate": "2020-05-12T20:45:00Z"
    }
  ],
  "maxResults": 250,
  "startIndex": 1,
  "totalResultCount": 2
}

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. For more detail about a specific batch, consider using the Batch Details API.

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, just 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

Batch Details

Batch Details Example:

Linux/Mac OS: ./blockchyp -test -type="batch-details" -batchId="BATCHID"

Windows: ./blockchyp.exe -test -type="batch-details" -batchId="BATCHID"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func batchDetailsExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.BatchDetailsRequest{
        BatchID: "BATCHID",
    }

    response, err := client.BatchDetails(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
BatchDetailsRequest request = new BatchDetailsRequest
{
    BatchId = "BATCHID",
};

// Run the transaction.
BatchDetailsResponse response = await blockchyp.BatchDetailsAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.BatchDetailsRequest;
import com.blockchyp.client.dto.BatchDetailsResponse;


public class BatchDetailsExample {

    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static void main(String[] args) throws Exception {

        APICredentials creds = new APICredentials();
        creds.setApiKey(System.getenv("BC_API_KEY"));
        creds.setBearerToken(System.getenv("BC_BEARER_TOKEN"));
        creds.setSigningKey(System.getenv("BC_SIGNING_KEY"));

        BlockChypClient client = new BlockChypClient(creds);

        // Set request parameters
        BatchDetailsRequest request = new BatchDetailsRequest();
        request.setBatchId("BATCHID");

        // Send the request
        BatchDetailsResponse response = client.batchDetails(request);

        // View the result
        System.out.println("Response: " + prettyPrint(response));

    }

    public static String prettyPrint(Object object) throws Exception {

        ObjectWriter writer = new ObjectMapper()
            .writer()
            .withDefaultPrettyPrinter();

        return object.getClass().getSimpleName()
            + ": "
            + writer.writeValueAsString(object);

    }
}

<?php
// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'batchId' => 'BATCHID',
];

$response = BlockChyp::batchDetails($request);

// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

# frozen_string_literal: true

require 'blockchyp'

blockchyp = BlockChyp::BlockChyp.new(
  ENV['BC_API_KEY'],
  ENV['BC_BEARER_TOKEN'],
  ENV['BC_SIGNING_KEY']
)

# Set request parameters
request = {
  "batchId": 'BATCHID'
}

response = blockchyp.batchDetails(request)

puts "Response: #{response.inspect}"

import os

import blockchyp

# initialize a client.
client = blockchyp.Client(
    api_key=os.environ["BC_API_KEY"],
    bearer_token=os.environ["BC_BEARER_TOKEN"],
    signing_key=os.environ["BC_SIGNING_KEY"],
)

# populate request parameters.
request = {
    "batchId": "BATCHID",
}

# run the transaction.
response = client.batch_details(request)

print("Response: %r" % response)

  let BlockChyp = require("BlockChyp");

  let client = BlockChyp.newClient({
      apiKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
      bearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
      signingKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947"
    });

  // setup request object
  request = {
      batchId: 'BATCHID',
  }

  response = client.batchDetails(request)


  // view the result
  console.log("Response: " + JSON.stringify(response))

#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"] = @"BATCHID";
  [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;
}


import BlockChyp

class ExampleClass {

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

    var request: [String:Any] = [:]
    request["batchId"] = "BATCHID"
    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)
    })
  }


Example response encoded as JSON:

{
  "success": true,
  "error": "",
  "responseDescription": "",
  "batchId": "OPXQNZEUSAI6VL2FNSLM7WZLHE",
  "capturedAmount": "294.12",
  "openPreauths": "0.00",
  "totalVolume": "294.12",
  "transactionCount": 5,
  "giftCardsSold": "50.00",
  "giftCardVolume": "12.00",
  "expectedDeposit": "282.12",
  "open": true,
  "openDate": "2020-05-12T20:45:28Z",
  "closeDate": "0001-01-01T00:00:00Z",
  "volumeByTerminal": [
    {
      "terminalName": "POS1",
      "serialNumber": "A18290030XXXX",
      "terminalType": "LUXE8000",
      "capturedAmount": "147.68",
      "transactionCount": 2
    },
    {
      "terminalName": "POS2",
      "serialNumber": "A182700300XXXX",
      "terminalType": "LUXE8000",
      "capturedAmount": "146.44",
      "transactionCount": 3
    }
  ]
}

This endpoint 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 also be discovered using the Batch History API.

Transaction History

Transaction History Example:

Linux/Mac OS: ./blockchyp -test -type="tx-history" -batch="BATCHID" -maxResults="10"

Windows: ./blockchyp.exe -test -type="tx-history" -batch="BATCHID" -maxResults="10"
package main

import (
    "fmt"
    "log"

    blockchyp "github.com/blockchyp/blockchyp-go"
)

func transactionHistoryExample() {
    // sample credentials
    creds := blockchyp.APICredentials{
        APIKey:      "ZDSMMZLGRPBPRTJUBTAFBYZ33Q",
        BearerToken: "ZLBW5NR4U5PKD5PNP3ZP3OZS5U",
        SigningKey:  "9c6a5e8e763df1c9256e3d72bd7f53dfbd07312938131c75b3bfd254da787947",
    }

    // instantiate the client
    client := blockchyp.NewClient(creds)

    // setup request object
    request := blockchyp.TransactionHistoryRequest{
        MaxResults: 10,
    }

    response, err := client.TransactionHistory(request)

    if err != nil {
        log.Fatal(err)
    }

    //process the result
    if response.Success {
        fmt.Println("Success")
    }

    fmt.Printf("Response: %+v\n", response)
}

// Populate request parameters.
TransactionHistoryRequest request = new TransactionHistoryRequest
{
    MaxResults = 10,
};

// Run the transaction.
TransactionHistoryResponse response = await blockchyp.TransactionHistoryAsync(request);

// View the result.
Console.WriteLine(response);

package com.blockchyp.client.examples;

import java.util.ArrayList;
import java.util.Collection;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.ObjectWriter;

import com.blockchyp.client.APICredentials;
import com.blockchyp.client.BlockChypClient;
import com.blockchyp.client.dto.TransactionHistoryRequest;
import com.blockchyp.client.dto.TransactionHistoryResponse;