Payment Gateway REST API Reference

BlockChyp consists of two REST APIs: the small API that runs on every BlockChyp payment terminal and the Gateway API.

Like everything in BlockChyp, the Gateway was designed to be simple. With a few exceptions, the concepts should be familiar to anyone who’s done a previous payment gateway implementation.

Endpoints

BlockChyp uses completely separate systems for live and test transactions. Make sure you route test and live transactions to the correct endpoints as given below:

Live Transactions:
 https://api.blockchyp.com
Test Transactions:
 https://test.blockchyp.com

Note

Note that plain HTTP is not supported by the payment gateway API.

A Sample Transaction

Let’s dive into a sample API request. The following sample shows a conventional charge transaction using a previously enrolled recurring payment token.

Sample Request and Response:

Request:

POST /api/charge HTTP/1.1
Host: api.blockchyp.com
Nonce: HHU8JX48KKX8AYHENKRYMJ5MB6YHM43GHWW7VDRJQDVY0YTBWRGG
Authorization: Dual PCZFLPXD2PWI7B7VVFHD4VJ4KE:NNSNQ6ASHUHSCMEVOD666VZZLA:b695b1af23f9d1ce2983f1f69237866b7fa69878dcdc873ed3507374d8c0508b
Timestamp: 2018-12-10T18:07:15Z

{
  "transactionRef": "2Q9M727KXH1UYAH57ZV009HGKWXX704URY2GRUPV39MVF27FUFDG",
  "amount":"25.23",
  "token":"JTLQJNLSM4IGCKJC2MK7COW2VA"
}

Response:

HTTP/1.1 200 OK

{
  "transactionRef": "2Q9M727KXH1UYAH57ZV009HGKWXX704URY2GRUPV39MVF27FUFDG",
  "approved":true,
  "responseDescription":"Approved",
  "transactionId":"LA76MWH4UYI6RGOTNSLM7WZLHE",
  "batchId":"F2FGMPX2LEI6RBPSNSLM7WZLHE",
  "transactionType":"charge",
  "timestamp":"2018-12-10T18:07:15Z",
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",
  "authCode":"404739",
  "entryMethod":"KEYED",
  "paymentType":"VISA",
  "maskedPan":"************1111",
  "partialAuth":false,
  "altCurrency":false,
  "currencyCode":"USD",
  "requestedAmount":"25.23",
  "authorizedAmount":"25.23",
  "tipAmount":"0.00",
  "taxAmount":"0.00",
  "receiptSuggestions":{
    "requestSignature":false
  }
}

This example shows the mechanics of a simple token based transaction using the common VISA test card number of 4111 1111 1111 1111.

transactionRef is where you would provide your own ID for a transaction. It’s not required, but highly recommended because it allows you to track responses against your own ID scheme, and more importantly, time out reversals are not supported unless you provide a transactionRef value.

Most notable in this sample request are the three headers used by BlockChyp’s Dual authentication scheme (Timestamp, Nonce, and Authorization).

Authentication Headers

BlockChyp credentials take the form of an API Key, a Bearer Token, and a Signing Key - and are generated by the BlockChyp dashboard. These three credentials are used to assemble the Authorization header.

Gateway API requests are protected using a combination of Bearer Tokens and HMAC headers. The reason for this is that HMAC headers and Bearer Tokens provide offsetting security benefits.

For example, Bearer Tokens can be stored in the BlockChyp datastore as salted one way hashes which protects them in the event of a database breach. But Bearer Tokens must be sent over the network with every request where they might be vulnerable to interception in the event of a TLS or SSL vulnerability.

To offset this risk, we also require every API request include a digital signature in the form of an HMAC value computed via the Signing Key. Since HMAC signatures change for every request, they are of no value to a hacker, even if intercepted.

All API requests require the following three headers:

Nonce

Example Header:

Nonce: HHU8JX48KKX8AYHENKRYMJ5MB6YHM43GHWW7VDRJQDVY0YTBWRGG

This header should be a unique string with a minimum length of 16 characters. Developers are encouraged to use a cryptographically secure random number generator to produce nonces. Nonces are checked for uniqueness in real time.

The Nonce has to be sent in its own header as shown above and also must be fed into the HMAC computation as part of the Authorization header.

Timestamp

Example Header:

Timestamp: 2018-12-10T18:07:15Z

This header should be the ISO 8601 formatted timestamp at the time the transaction is executed in UTC. The timestamp must be within 10 minutes of the current time or the gateway will reject the transaction.

Authorization

Example Header:

Authorization: Dual PCZFLPXD2PWI7B7VVFHD4VJ4KE:NNSNQ6ASHUHSCMEVOD666VZZLA:b695b1af23f9d..

Authorization: Dual <Bearer Token>:<API Key>:<HMAC Signature>

The authorization header is assembled by starting with the keyword “Dual” which references BlockChyp’s Dual authentication scheme.

Add a space and then the Bearer Token followed by the API Key, separated by a colon.

To compute the HMAC Signature, first concatenate the API Key, Bearer Token, Timestamp and Nonce with no separator. (This is a bit simpler than other common HMAC authentication schemes.)

Next, compute an SHA 256 HMAC with the Signing Key and encode it as a hexadecimal string.

The sample code below shows how to compute an HMAC value in the Go Language.

Go Language HMAC Example:

import (
      "bytes"
      "crypto/hmac"
      "crypto/sha256"
      "encoding/hex"
)

/*
ComputeHmac computes an hmac for the the given headers and secret key.
*/
func ComputeHmac(APIKey, bearerToken, timestamp, nonce, signingKey string) string {

      buf := bytes.Buffer{}

      buf.WriteString(APIKey)
      buf.WriteString(bearerToken)
      buf.WriteString(timestamp)
      buf.WriteString(nonce)

      key, _ := hex.DecodeString(signingKey)

      mac := hmac.New(sha256.New, key)
      mac.Write(buf.Bytes())
      hash := mac.Sum(nil)

      return hex.EncodeToString(hash)

}

Note

HMAC headers are usually the hardest part of an implementation to get right. We recommend that developers doing direct REST implementations start by writing an integration test against the Heartbeat API described next.

Heartbeat (/api/heartbeat)

HTTP Method:GET
Path:/api/heartbeat

This endpoint is used to test connectivity with the Gateway and get updated time reference information. This API will return a response even if the big three authentication headers are not provided so it’s usually a good API to start an implementation with.

If a valid Authorization header is provided, this API will also return the Blockchain public key of the merchant. This is a simple GET request and accepts no path or query string parameters.

Sample Request and Response:

Request:

GET /api/heartbeat HTTP/1.1
Host: api.blockchyp.com
Nonce: HHU8JX48KKX8AYHENKRYMJ5MB6YHM43GHWW7VDRJQDVY0YTBWRGG
Authorization: Dual PCZFLPXD2PWI7B7VVFHD4VJ4KE:NNSNQ6ASHUHSCMEVOD666VZZLA:b695b1af23f9d1ce2983f1f69237866b7fa69878dcdc873ed3507374d8c0508b
Timestamp: 2018-12-10T18:07:15Z

Response:

HTTP/1.1 200 OK

{
 "success": true,
 "timestamp": "2018-12-10T11:16:06.2246-08:00",
 "latestTick": "000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",
 "merchantPk": "145kEAfQUj619jC1hbpegu1DprnYhoaqikXeCgcX8ZoXPi5oE8t"
}

The heartbeat response includes the latest Gateway Timestamp, the latest tick block for the Blockchain and if your Authorization headers are valid, the Blockchain Public Key of the merchant.

We recommend you write an integration test that ensures that merchantPk is non-null as a way to test your Authorization and HMAC implementation.

Terminal Route (/api/terminal-route)

HTTP Method:GET
Path:/api/terminal-route
Query String Parameter Description Required
terminal Name assigned to the terminal at activation. Yes

This API is used to get current metadata about BlockChyp terminals including the terminal’s IP Address on the private network along with transient credentials and blockchain public key information.

We strongly recommend that payment terminals be configured with static IP addresses, but we also understand that real life point-of-sale or merchant networks can be chaotic environments where recommendations aren’t always followed.

This API is part of a set of techniques BlockChyp uses to try and cope with real world merchant networks. Terminals check in with the BlockChyp network when they’re activated and periodically throughout the day. They report their IP address on the private network along with some internal metrics used to monitor the overall health of the network and for fraud detection.

The Terminal Route API can be used to lookup a terminal’s IP Address by the name assigned to the terminal at activation. It serves as a simple DNS system for terminals and makes merchant networks more robust, even if all terminals are left on the default DHCP settings.

Sample Request and Response:

Request:

GET /api/terminal-route?terminal=Cashier%20#1 HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

Response:

HTTP/1.1 200 OK
{
  "success":true,
  "terminalName":"Cashier #1",
  "ipAddress":"192.168.50.245",
  "cloudRelayEnabled": false,
  "transientCredentials": {
    "apiKey": "CINR73MIHX337KMRHW7BI5I2AM",
    "bearerToken": "JTLQJNLSM4IGCKJC2MK7COW2VA",
    "signingKey": "c7722b911f9821e742f248af8449f12f06304c18b48b902f7cdef3d9dea7ed34"
  },
  "publicKey":"112hvhQwGa22QJSuqZwdMT5BhBNcrE9pwfHzFicx4ZMLkAe6chRi",
  "rawKey": {
    "curve":"P256",
    "x":"e09f8673361cc828cda624221d5f2b517c4c4285d959e502511b531f324ece0a",
    "y":"cced17b1d95dcbcc5bf2b2f06ba4bdb4b482bd0e081ac54fb49b6db2ab40a5b4"
  }
}

The response includes the following data elements:

ipAddress:The current local IP address of the terminal on the private network. If the point-of-sale or client application is on the same network as the terminal, the terminal’s REST API can be found at ports 8080 and 8443 at the given IP Address.
cloudRelayEnabled:
 Indicates that this terminal is accessible via the Gateway. Not recommended, but unavoidable if the point-of-sale system and terminal are on different network segments.
transientCredentials:
 Special credentials restricted for use only with the given terminal. All direct API calls to terminals should use these credentials, especially if the merchants are unable to run TLS/SSL on their local network.
publicKey:The blockchain public key for the terminal in BlockChyp’s compressed key format. Can be used to validate the signatures of terminal responses.
rawKey:The raw version of the terminal’s blockchain public key. Includes the name of the standard elliptic curve (usually P256) and the raw x and y coordinates of the public key in hexadecimal format.

Charge (/api/charge)

HTTP Method:POST
Path:/api/charge

Executes a direct auth and capture. For cloud enabled terminals, the terminalName method routes a transaction to a cloud based terminal. Also used for token based transactions.

terminalName or token are required in the request, but not both.

Note

Sensitive information like track data or account numbers are never returned by any BlockChyp API.

Sample Request and Response:

Request:

POST /api/charge HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

{

  // application defined transaction identifier, up to 64 characters in length
  // optional, but recommended since time out reversals won't work without it
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // flags this as a test transaction - no real money will change hands
  "test": false,

  // name of the terminal - for cloud based terminal transactions
  "terminalName":"Desk Terminal",

  // reusable token
  "token": "CINR73MIHX337KMRHW7BI5I2AM",

  // ISO three character currency code, optional, defaults to USD
  "currencyCode": "USD",

  // total amount to authorize
  "amount":"12.67",

  // optional tip amount, if known
  "tipAmount":"0.00",

  // optional tax amount, if known
  "taxAmount":"0.00",

  // if true, the user will be prompted to add a tip before presenting
  // their payment card
  "promptForTip":false,

  // if true, the payment method will be tokenized for use in future
  // transactions
  "enroll": false,

  // an optional description for the transaction
  // for credit card transactions, this will appear on the statement
  "description": "Comic Books"
}

Response:

HTTP/1.1 200 OK
{

  // whether or not the transaction went through
  "approved":true,

  // narrative description of the response
  "responseDescription": "Approved",

  // authorization code
  "authCode":"054321",

  // indicates whether or not the authorized amount was less than the requested amount
  "partialAuth":false,

  // the final requested amount
  // this could be more than the original request's amount if you prompted
  // the user for a tip.
  "requestedAmount":"12.67",

  // amount authorized by the payment network
  "authorizedAmount":"12.67",

  // tip amount, could be different if you prompted the user for a tip
  "tipAmount":"0.00",

  // tax amount from the original request echoed back
  "taxAmount":"0.00",

  // currency for the authorization
  "currencyCode":"USD",

  // for conventional credit card transactions, the BlockChyp assigned batch id
  "batchId": "UEOHSRX2MYI6RA2WSSDM7WZLHE",

  // original transaction reference, echoed back
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // original test flag setting, echoed back
  "test": false,

  // BlockChyp assigned transaction Id.  Use this in any subsequent void requests.
  "transactionId":"UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // transaction type, echoed back
  "transactionType":"charge",

  // timestamp of the transaction in UTC
  "timestamp":"2018-12-07T21:25:37Z",

  // hash of the latest tick block on the BlockChyp clockchain
  // this is essentially blockchain time
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",

  // could be CHIP, SWIPE, APPLEPAY, etc
  "entryMethod":"CHIP",

  // could be VISA, MC, DISC, AMEX, or GIFT
  "paymentType":"VISA",

  // masked account number with just the last four digits visible
  "maskedPan":"************0119",


  // reusable payment token, if requested by setting the enroll flag to "true"
  "token": "",

  // public key for BlockChyp gift cards
  "publicKey": "",


  "receiptSuggestions":{
    // EMV Application Identifier - required on all EMV receipts
    "AID":"A0000000031010",

    // Application Request Cryptogram - digital signature for an EMV transaction
    "ARQC":"6218309BF7D48CC7",

    // Issuer Application Data
    "IAD":"06010A03A0A800",

    // Terminal Verification Results
    "TVR":"8000008000",

    // Transaction Status Indicator
    "TSI":"6800",

    // if true, the system should print a signature line on the receipt
    "requestSignature":true
  }

}

Preauth (/api/preauth)

HTTP Method:POST
Path:/api/preauth

Executes a preauthorization. For cloud enabled terminals, the terminalName method routes a transaction to a cloud based terminal. Can also be used for token based transactions.

terminalName or token are required in the request, but not both.

Note

Must be captured later with a capture transaction.

Note

Sensitive information like track data or account numbers are never returned by any BlockChyp API.

Sample Request and Response:

Request:

POST /api/preauth HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

{

  // application defined transaction identifier, up to 64 characters in length
  // optional, but recommended since time out reversals won't work without it
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // flags this as a test transaction - no real money will change hands
  "test": false,

  // name of the terminal - for cloud based terminal transactions
  "terminalName":"Desk Terminal",

  // reusable token
  "token": "CINR73MIHX337KMRHW7BI5I2AM",

  // ISO three character currency code, optional, defaults to USD
  "currencyCode": "USD",

  // total amount to authorize
  "amount":"12.67",

  // optional tip amount, if known
  "tipAmount":"0.00",

  // optional tax amount, if known
  "taxAmount":"0.00",

  // if true, the user will be prompted to add a tip before presenting
  // their payment card
  "promptForTip":false,

  // if true, the payment method will be tokenized for use in future
  // transactions
  "enroll": false,

  // an optional description for the transaction
  // for credit card transactions, this will appear on the statement
  "description": "Comic Books"
}

Response:

HTTP/1.1 200 OK
{

  // whether or not the transaction went through
  "approved":true,

  // narrative description of the response
  "responseDescription": "Approved",

  // authorization code
  "authCode":"054321",

  // indicates whether or not the authorized amount was less than the requested amount
  "partialAuth":false,

  // the final requested amount
  // this could be more than the original request's amount if you prompted
  // the user for a tip.
  "requestedAmount":"12.67",

  // amount authorized by the payment network
  "authorizedAmount":"12.67",

  // tip amount, could be different if you prompted the user for a tip
  "tipAmount":"0.00",

  // tax amount from the original request echoed back
  "taxAmount":"0.00",

  // currency for the authorization
  "currencyCode":"USD",

  // for conventional credit card transactions, the BlockChyp assigned batch id
  "batchId": "UEOHSRX2MYI6RA2WSSDM7WZLHE",

  // original transaction reference, echoed back
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // original test flag setting, echoed back
  "test": false,

  // BlockChyp assigned transaction Id.  Use this in any subsequent void requests.
  "transactionId":"UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // transaction type, echoed back
  "transactionType":"preauth",

  // timestamp of the transaction in UTC
  "timestamp":"2018-12-07T21:25:37Z",

  // hash of the latest tick block on the BlockChyp clockchain
  // this is essentially blockchain time
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",

  // could be CHIP, SWIPE, APPLEPAY, etc
  "entryMethod":"CHIP",

  // could be VISA, MC, DISC, AMEX, or GIFT
  "paymentType":"VISA",

  // masked account number with just the last four digits visible
  "maskedPan":"************0119",


  // reusable payment token, if requested by setting the enroll flag to "true"
  "token": "",

  // public key for BlockChyp gift cards
  "publicKey": "",


  "receiptSuggestions":{
    // EMV Application Identifier - required on all EMV receipts
    "AID":"A0000000031010",

    // Application Request Cryptogram - digital signature for an EMV transaction
    "ARQC":"6218309BF7D48CC7",

    // Issuer Application Data
    "IAD":"06010A03A0A800",

    // Terminal Verification Results
    "TVR":"8000008000",

    // Transaction Status Indicator
    "TSI":"6800",

    // if true, the system should print a signature line on the receipt
    "requestSignature":true
  }

}

Capture (/api/capture)

HTTP Method:POST
Path:/api/capture

This API captures a preauthorization. Requires the transaction ID from a previous transaction.

Sample Request and Response:

Request:

POST /api/capture HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

{

  // application defined transaction identifier, up to 64 characters in length
  // optional, but recommended since time out reversals won't work without it
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // id of a previous transaction, required
  "transactionId": "UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // flags this as a test transaction - no real money will change hands
  "test": false,

  // ISO three character currency code, optional, defaults to USD
  "currencyCode": "USD",

  // total amount to capture, if different from the original preauth
  "amount":"17.67",

  // optional tip amount added to the transaction
  "tipAmount": "5.00",

}

Response:

HTTP/1.1 200 OK
{

  // whether or not the transaction went through
  "approved":true,

  // narrative description of the response
  "responseDescription": "Approved",

  // authorization code
  "authCode":"054321",

  // indicates whether or not the authorized amount was less than the requested amount
  "partialAuth":false,

  // the final requested amount
  // this could be more than the original request's amount if you prompted
  // the user for a tip.
  "requestedAmount":"17.67",

  // amount authorized by the payment network
  "authorizedAmount":"17.67",

  // tip amount, could be different if you prompted the user for a tip
  "tipAmount":"5.00",

  // tax amount from the original request echoed back
  "taxAmount":"0.00",

  // currency for the authorization
  "currencyCode":"USD",

  // for conventional credit card transactions, the BlockChyp assigned batch id
  "batchId": "UEOHSRX2MYI6RA2WSSDM7WZLHE",

  // original transaction reference, echoed back
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // original test flag setting, echoed back
  "test": false,

  // BlockChyp assigned transaction Id.  Use this in any subsequent void requests.
  "transactionId":"UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // transaction type, echoed back
  "transactionType":"capture",

  // timestamp of the transaction in UTC
  "timestamp":"2018-12-07T21:25:37Z",

  // hash of the latest tick block on the BlockChyp clockchain
  // this is essentially blockchain time
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",

  // could be CHIP, SWIPE, APPLEPAY, etc
  "entryMethod":"CHIP",

  // could be VISA, MC, DISC, AMEX, or GIFT
  "paymentType":"VISA",

  // masked account number with just the last four digits visible
  "maskedPan":"************0119"

}

Refund (/api/refund)

HTTP Method:POST
Path:/api/refund

This API refunds a previous transaction. Refunds are typically used to process refunds for transactions from a previous batch. If you need to unwind a transaction from the current batch, use void instead.

BlockChyp does not support open ended refunds. All refund transactions must refer to a previous transaction ID.

Sample Request and Response:

Request:

POST /api/refund HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

{

  // application defined transaction identifier, up to 64 characters in length
  // optional, but recommended since time out reversals won't work without it
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // id of a previous transaction, required
  "transactionId": "UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // flags this as a test transaction - no real money will change hands
  "test": false,

  // reusable token
  "token": "CINR73MIHX337KMRHW7BI5I2AM",

  // ISO three character currency code, optional, defaults to USD
  "currencyCode": "USD",

  // total amount to refund, if different from the original transaction amount
  // cannot exceed the authorized amount of the original transaction
  "amount":"12.67",

  // an optional description for the transaction
  // for credit card transactions, this will appear on the statement
  "description": "Comic Books"
}

Response:

HTTP/1.1 200 OK
{

  // whether or not the transaction went through
  "approved":true,

  // narrative description of the response
  "responseDescription": "Approved",

  // authorization code
  "authCode":"054321",

  // indicates whether or not the authorized amount was less than the requested amount
  "partialAuth":false,

  // the final requested amount
  // this could be more than the original request's amount if you prompted
  // the user for a tip.
  "requestedAmount":"12.67",

  // amount authorized by the payment network
  "authorizedAmount":"12.67",

  // tip amount, could be different if you prompted the user for a tip
  "tipAmount":"0.00",

  // tax amount from the original request echoed back
  "taxAmount":"0.00",

  // currency for the authorization
  "currencyCode":"USD",

  // for conventional credit card transactions, the BlockChyp assigned batch id
  "batchId": "UEOHSRX2MYI6RA2WSSDM7WZLHE",

  // original transaction reference, echoed back
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // original test flag setting, echoed back
  "test": false,

  // BlockChyp assigned transaction Id.  Use this in any subsequent void requests.
  "transactionId":"UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // transaction type, echoed back
  "transactionType":"refund",

  // timestamp of the transaction in UTC
  "timestamp":"2018-12-07T21:25:37Z",

  // hash of the latest tick block on the BlockChyp clockchain
  // this is essentially blockchain time
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",

  // could be CHIP, SWIPE, APPLEPAY, etc
  "entryMethod":"CHIP",

  // could be VISA, MC, DISC, AMEX, or GIFT
  "paymentType":"VISA",

  // masked account number with just the last four digits visible
  "maskedPan":"************0119"

}

Void (/api/void)

HTTP Method:POST
Path:/api/void

Voids or cancels a transaction in the current batch. Can be used to void charges, captures, or refunds, and to discard pending preauthorizations.

Sample Request and Response:

Request:

POST /api/void HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

{

  // application defined transaction identifier, up to 64 characters in length
  // optional, but recommended since time out reversals won't work without it
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // id of a previous transaction, required
  "transactionId": "UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // flags this as a test transaction - no real money will change hands
  "test": false,

}

Response:

HTTP/1.1 200 OK
{

  // whether or not the transaction went through
  "approved":true,

  // narrative description of the response
  "responseDescription": "Approved",

  // authorization code
  "authCode":"054321",

  // currency for the authorization
  "currencyCode":"USD",

  // for conventional credit card transactions, the BlockChyp assigned batch id
  "batchId": "UEOHSRX2MYI6RA2WSSDM7WZLHE",

  // original transaction reference, echoed back
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // original test flag setting, echoed back
  "test": false,

  // BlockChyp assigned transaction Id.  Use this in any subsequent void requests.
  "transactionId":"UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // transaction type, echoed back
  "transactionType":"void",

  // timestamp of the transaction in UTC
  "timestamp":"2018-12-07T21:25:37Z",

  // hash of the latest tick block on the BlockChyp clockchain
  // this is essentially blockchain time
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",

  // could be CHIP, SWIPE, APPLEPAY, etc
  "entryMethod":"CHIP",

  // could be VISA, MC, DISC, AMEX, or GIFT
  "paymentType":"VISA",

  // masked account number with just the last four digits visible
  "maskedPan":"************0119"

}

Time Out Reversal (/api/reverse)

HTTP Method:POST
Path:/api/reverse

Voids transactions that may have timed out during processing. Must be sent with a transactionRef. If the network has a record of the transaction and the transaction was submitted within the last 2 minutes, it will be voided or reversed.

Sample Request and Response:

Request:

POST /api/reverse HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

{

  // application defined transaction identifier, up to 64 characters in length
  // required for reverse transactions
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // flags this as a test transaction - no real money will change hands
  "test": false,

}

Response:

HTTP/1.1 200 OK
{

  // whether or not the transaction went through
  "approved":true,

  // narrative description of the response
  "responseDescription": "Approved",

  // authorization code
  "authCode":"054321",

  // currency for the authorization
  "currencyCode":"USD",

  // for conventional credit card transactions, the BlockChyp assigned batch id
  "batchId": "UEOHSRX2MYI6RA2WSSDM7WZLHE",

  // original transaction reference, echoed back
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // original test flag setting, echoed back
  "test": false,

  // BlockChyp assigned transaction Id.  Use this in any subsequent void requests.
  "transactionId":"UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // transaction type, echoed back
  "transactionType":"reverse",

  // timestamp of the transaction in UTC
  "timestamp":"2018-12-07T21:25:37Z",

  // hash of the latest tick block on the BlockChyp clockchain
  // this is essentially blockchain time
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",

  // could be CHIP, SWIPE, APPLEPAY, etc
  "entryMethod":"CHIP",

  // could be VISA, MC, DISC, AMEX, or GIFT
  "paymentType":"VISA",

  // masked account number with just the last four digits visible
  "maskedPan":"************0119"

}

Close Batch (/api/close-batch)

HTTP Method:POST
Path:/api/close-batch

This transaction allows developers to execute manual batch closures. By default, BlockChyp batches close every day at 4 AM in the merchant’s local time. Merchants can change this time via the dashboard and even disable automatic batch closure.

Manual batch closures are sometimes needed by businesses with unusual hours, especially 24 hour businesses or night life businesses in which batches can’t be closed until all tips have been entered for the last shift.

Note that batch closure is not required for BlockChyp gift cards since gift cards are recorded directly on the blockchain.

Sample Request and Response:

Request:

POST /api/close-batch HTTP/1.1
Host: api.blockchyp.com
Authorization: Dual JTLQJNLSM4IGCKJC2MK7COW2VA:CINR73MIHX337KMRHW7BI5I2AM:7721b505f6cc4540e471d03e42388e3a5a1567b29dedf589ef881995e9ca74cc
Nonce: MNAYY7YCXME215ZBZ96BW7D1JFPX5VBX563EGAGH4E6KA8RV8BE0
Timestamp: 2018-11-20T18:04:25Z

{

  // application defined transaction identifier, up to 64 characters in length
  // required for reverse transactions
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // flags this as a test transaction - will close the test batch
  "test": false,

}

Response:

HTTP/1.1 200 OK
{

  // narrative description of the response
  "responseDescription": "Closed",

  // for conventional credit card transactions, the BlockChyp assigned batch id
  "batchId": "UEOHSRX2MYI6RA2WSSDM7WZLHE",

  // original transaction reference, echoed back
  "transactionRef": "b944f032e997d944cdabb03cf1aa260ba3cde3d3b572b138eceb27bb41e54332",

  // original test flag setting, echoed back
  "test": false,

  // BlockChyp assigned transaction Id
  "transactionId":"UEOHSRX2MYI6RA2LNSLM7WZLHE",

  // transaction type, echoed back
  "transactionType":"close-batch",

  // timestamp of the transaction in UTC
  "timestamp":"2018-12-07T21:25:37Z",

  // hash of the latest tick block on the BlockChyp clockchain
  // this is essentially blockchain time
  "tickBlock":"000a40ada947bd35886f19c8908cd84e521f713cc2637c0bf70b3b2ea63ffe7d",

  // currency for the current batch
  "currencyCode":"USD",

  // total amount of money captured - the merchant should expect a deposit
  // in this amount less processing fees
  "capturedTotal": "1712.04",

  // amount of un-captured preauthorizations in the batch
  "openPreauths": "120.00",

  // a breakdown of the captured total by card brand
  "cardBrands": {
    "VISA": "500.00",
    "MC": "120.00",
    "AMEX": "800.00",
    "DISC": "292.04"
  }


}