Introduction

BlueTarp's real time authorization API allows developers to integrate with our proprietary transaction authorization system. This document provides the technical specifications that developers will need to understand in order to support payments using BlueTarp.

The API supports the processing of Sale, Credit (Return), Void, Deposit Hold (Credit Reserve) and Deposit Collect transactions as well as finding transactions to void and finding deposits to cancel or collect.

It also enables merchants to support card-not-present transactions by giving integrators the ability to lookup customers purchasing at a merchant's location. This ability is what allows merchant point of sale systems to identify an in-house account's BlueTarp purchaser information without compromising security or requiring the customer to present their purchaser identity at the point of sale.

As of version 1.1, the API also supports the ability for merchants to register customers with existing BlueTarp accounts so that a new customer with a BlueTarp card may immediately start making purchases at the merchant's fully integrated location.

You can reach the development team at api-support@bluetarp.com.

API Details

The BlueTarp Authorization API is exposed as a RESTful-style service that can be accessed securely using the HTTP protocol over TLS/SSL. For security, only the encrypted https scheme is supported. Unencrypted http access is not allowed.

The following table provides a summary of the API endpoints. To skip to more complete details of a particular endpoint, simply click the appropriate link.

/auth POST Create a new Authorization
/customers GET Get a list of Customers
/transactions/void GET Get a list of Voidable Transactions
/transactions/deposit GET Get a list of Collectable Deposit Transactions
/register POST Register a relationship with a BlueTarp customer

URL Pattern

https://integration.bluetarp.com/auth/<version>/<merchant_number>/<object>?<query>

<version>
The API version.
<merchant_number>
The BlueTarp merchant number making the request.
<object>
The object to perform actions on. Currently the valid objects are:
  • customers
  • transactions/void
  • transactions/deposit
<query>
Additional query parameters supported by the resource.

Example URLs

          https://integration.bluetarp.com/auth/v1.1
          /merchantNumber/  [POST]
          /merchantNumber/customers
          /merchantNumber/customers?bluetarp-cid=cid
          /merchantNumber/customers?merchant-cid=cid
          /merchantNumber/transactions/void
          /merchantNumber/transactions/deposit
          /merchantNumber/register  [POST]

Authenticating

All requests must be authenticated by including your BlueTarp issued client key as a Bearer token using the HTTP Authorization header.

Example HTTP Authentication Header

Authorization: Bearer XnqTfhlJAPURvmA4cJwc5H

Please contact BlueTarp implementation support to request a client key.

Status Codes

Every response will return an HTTP status code and may return detailed informational messages.

Example Responses

200 OK
Success.
400 Bad Request
The request was not valid for some reason. Malformed, missing data etc.
401 Unauthorized
A valid Client Key was not provided with the request.
404 Not Found
The URL is invalid or the requested resource does not exist.
500 Internal Server Error
There was a problem on BlueTarp's end.

Response Codes

Every response with a 200 HTTP status code should return a response code, denoted by the element bt:code, that can be used to better identify a more specific reason if the authorization was declined.

Response codes

00 Approved
Approved
02 Declined
Invalid merchant account status
05 Declined
Invalid customer account status
06 Declined
Invalid customer card status
12 Declined
Insufficient funds
62 Declined
Processing error or exceeded restricted transaction limit
66 Declined
Invalid card
70 Declined
Transaction cannot be voided
73 Declined
Original transaction not found
89 Declined
Invalid customer

Idempotency

An endpoint is considered idempotent if a request (identified by transaction-id) can be sent multiple times and the result is the same as sending it once. This allows the client to ensure that the desired result when the connection quality is poor.

For example, you may request an authorization and receive a network timeout response. You don't know where in the network the failure occurred, so you aren't sure if the authorization went through. If the endpoint is idempotent, you can send the request again without fear of a duplicate authorization being registered.

To make your requests idempotent, pass the header, "X-Idempotent" = "true" with your request, and identify your transaction by passing your UUID in the transaction-id field. When you retry the authorization, make sure to pass the same UUID in the transaction-id.

Idempotency Header

X-Idempotent: true

Code Samples

We have created basic code examples in various languages to help you get started. We publish the examples on GitHub.

C# https://github.com/BlueTarp/auth-csharp
Python https://github.com/BlueTarp/auth-python
Visual Basic 6 https://github.com/BlueTarp/auth-vb6
Java https://github.com/BlueTarp/auth-java

Clone our examples

          # C-Sharp
          git clone https://github.com/BlueTarp/auth-csharp.git

          # Python
          git clone https://github.com/BlueTarp/auth-python.git

          # VisualBasic 6
          git clone https://github.com/BlueTarp/auth-vb6.git

          # Java
          git clone https://github.com/BlueTarp/auth-java.git

Authorizing Transactions

Authorization requests are made by submitting a properly formed XML document as an HTTP POST to the following URL:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>

XML Elements
merchant-number required BlueTarp merchant id
client-id required Merchant-assigned terminal identifier or name
transaction-id required UUID generated by the submitting merchant for the transaction

We have provided a diagram describing the authorization workflow for a typical BlueTarp transaction authorization. The following sections describe the various transaction documents in more detail.

Example Authorization Body

<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:client-id>Test Terminal</bt:client-id>
    <bt:transaction-id>6aa73f01-4557-454f-9279-e84526a61246</bt:transaction-id>
    <bt:purchaser>
      <bt:token>Tpkmefso8mbTtqgfpVXFcgYrVPXsQC</bt:token>
    </bt:purchaser>
    <bt:sale>
      <bt:amount>1000.00</bt:amount>
      <bt:job-code />
      <bt:invoice />
    </bt:sale>
  </bt:authorization-request>
</bt:bluetarp-authorization>

Transaction Types

Sale with Card Number

Sales using card numbers are intended only for authorizing transactions where the purchaser is presenting a physical card with a valid BlueTarp card number.

XML Elements
number required Contains a BlueTarp card number identifying the purchaser
amount required Amount in US dollars
job-code optional Customer-assigned job code
invoice optional Merchant-assigned invoice number

Sale flow diagram

<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:client-id>Test Terminal</bt:client-id>
    <bt:transaction-id>63f9f8e0-a1a0-42dc-9dda-a3e9defddf49</bt:transaction-id>
    <bt:purchaser>
      <bt:number>1234567890123456</bt:number>
    </bt:purchaser>
    <bt:sale>
      <bt:amount>100.00</bt:amount>
      <bt:job-code>MISC</bt:job-code>
      <bt:invoice>J08223</bt:invoice>
    </bt:sale>
  </bt:authorization-request>
</bt:bluetarp-authorization>

Sale with Tokens

Sales using tokens are the preferred for transactions where the purchaser is not presenting a physical card. You obtain a purchaser's token by performing a customer lookup.

XML Elements
token required BlueTarp-assigned token for the purchaser
amount required Amount in US dollars
job-code optional Customer-assigned job code
invoice optional Merchant-assigned invoice number

Sale flow diagram

<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:client-id>Test Terminal</bt:client-id>
    <bt:transaction-id>ebf0e519-37af-47ce-9291-3251e60bf218</bt:transaction-id>
    <bt:purchaser-with-token>
      <bt:token>iYWL4uqwU4HGjZ1s1VjjhxsBRfRXmd</bt:token>
    </bt:purchaser-with-token>
    <bt:sale>
      <bt:amount>100.00</bt:amount>
      <bt:job-code>MISC</bt:job-code>
      <bt:invoice>J08223</bt:invoice>
    </bt:sale>
  </bt:authorization-request>
</bt:bluetarp-authorization>

Credit

To credit an amount back to the purchaser's credit line.

XML Elements
token required BlueTarp-assigned token for the purchaser
amount required Amount in US dollars
job-code optional Customer-assigned job code
invoice optional Merchant-assigned invoice number
original-invoice optional Original invoice number for the sale

Credit flow diagram

<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:client-id>Test Terminal</bt:client-id>
    <bt:transaction-id>143e1641-66d9-4f9f-a291-f0fd118b7b01</bt:transaction-id>
    <bt:purchaser-with-token>
      <bt:token>36xRoR04fIzcsRNqmKununx1Wf55Wj</bt:token>
    </bt:purchaser-with-token>
    <bt:credit>
      <bt:amount>100.00</bt:amount>
      <bt:job-code>1k23rh</bt:job-code>
      <bt:invoice>J08223</bt:invoice>
      <bt:original-invoice>602437</bt:original-invoice>
    </bt:credit>
  </bt:authorization-request>
</bt:bluetarp-authorization>

Deposit Hold

To reserve an amount on the purchaser's credit line. Use the deposit collect to complete the sale.

XML Elements
token required BlueTarp-assigned token for the purchaser
amount required Amount in US dollars
job-code optional Customer-assigned job code
invoice optional Merchant-assigned invoice number

Deposit hold flow diagram

<?xml version='1.0' encoding='utf-8'?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:client-id>Test Terminal</bt:client-id>
    <bt:transaction-id>cd79b4a4-0065-410e-84d1-8b97853d31f7</bt:transaction-id>
    <bt:purchaser-with-token>
      <bt:token>AXGADAAxVe2fcJaRZonTAhal0gsgEj</bt:token>
    </bt:purchaser-with-token>
    <bt:deposit-hold>
      <bt:amount>100.00</bt:amount>
      <bt:job-code>1k23rh</bt:job-code>
      <bt:invoice>J08223</bt:invoice>
    </bt:deposit-hold>
  </bt:authorization-request>
</bt:bluetarp-authorization>

Deposit Collect

To complete a sale using an amount previously reserved by a deposit hold.

XML Elements
token required BlueTarp-assigned token for the purchaser
amount required Amount in US dollars
auth-seq required Authorization sequence number from an approved deposit hold
job-code optional Customer-assigned job code
invoice optional Merchant-assigned invoice number

Deposit collect flow diagram

<?xml version='1.0' encoding='utf-8'?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:client-id>Test Terminal</bt:client-id>
    <bt:transaction-id>7ddf8b12-c5d2-4b2b-9e7d-8a4185cb0f1b</bt:transaction-id>
    <bt:purchaser-with-token>
      <bt:token>aLCsIs0aoJdimlduVJasHvapvsbuOM</bt:token>
    </bt:purchaser-with-token>
    <bt:deposit-collect>
      <bt:amount>100.00</bt:amount>
      <bt:auth-seq>9806536</bt:auth-seq>
      <bt:job-code>1k23rh</bt:job-code>
      <bt:invoice>J08223</bt:invoice>
    </bt:deposit-collect>
  </bt:authorization-request>
</bt:bluetarp-authorization>

Void

To void an approved transaction.

XML Elements
token required BlueTarp-assigned token for the purchaser
auth-seq required Authorization sequence number from an approved transaction

Transaction void flow diagram

<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:client-id>Test Terminal</bt:client-id>
    <bt:transaction-id>6c4ef62a-220b-467f-aa79-48f762f0b8df</bt:transaction-id>
    <bt:purchaser-with-token>
      <bt:token>o8rysQbhoJCLtmEPsBQ4tNlZ5wlcxb</bt:token>
    </bt:purchaser-with-token>
    <bt:void>
      <bt:auth-seq>740893</bt:auth-seq>
    </bt:void>
  </bt:authorization-request>
</bt:bluetarp-authorization>

Responses

Success Response

Successful authorizations will return an HTTP status code of 200 and a response comprised of the following information (you can find more about our response codes under Response Codes):

code BlueTarp status code. 00 indicates an approved transaction
message Short message indicating status of authorization
transactionId The merchant-generated transaction id sent in the request
auth-seq BlueTarp-assigned identifier for this transaction
approval-code Approval code for this transaction 
<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-response>
    <bt:code>00</bt:code>
    <bt:message>APPROVED</bt:message>
    <bt:transactionId>6c4ef62a-220b-467f-aa79-48f762f0b8df</bt:transactionId>
    <bt:auth-seq>11262769</bt:auth-seq>
    <bt:approval-code>262769</bt:approval-code>
  </bt:authorization-response>
</bt:bluetarp-authorization>

Failure Response

Failed authorizations will return an HTTP status code of 200 and a response comprised of the following information:

code BlueTarp status code. 66 indicates a failed transaction
message Short message indicating why the authorization failed
transactionId The merchant-generated transaction id sent in the request 
<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:authorization-response>
    <bt:code>66</bt:code>
    <bt:message>DECLINED</bt:message>
    <bt:transactionId>6c4ef62a-220b-467f-aa79-48f762f0b8df</bt:transactionId>
  </bt:authorization-response>
</bt:bluetarp-authorization>

Customer Lookup

Retrieving all Customers

Retrieving a merchant's active customers can be done by sending a GET request to the following URL:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers

The response includes the list of active customers that can purchase at the given merchant. The response does not include credit data for the customers. 

<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:customer-response>
    <bt:customers>
      <bt:customer>
        <bt:number>1398</bt:number>
        <bt:name>ACME Masonry Contractors Inc</bt:name>
        <bt:merchant-identifier>828</bt:merchant-identifier>
        <bt:status>Active</bt:status>
        <bt:reason>Purchasing</bt:reason>
        <bt:address>
          <bt:line1>443 Congress St</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>8071</bt:last4>
            <bt:name></bt:name>
            <bt:token>87b8dafa-d8e8-4c4a-ab74-a5801049444a</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
      <bt:customer>
        <bt:number>1341</bt:number>
        <bt:merchant-identifier></bt:merchant-identifier>
        <bt:name>ACME Dairy Inc</bt:name>
        <bt:status>Active</bt:status>
        <bt:reason>Purchasing</bt:reason>
        <bt:address>
          <bt:line1>4 Canal Plaza</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>0351</bt:last4>
            <bt:name></bt:name>
            <bt:token>b74a94cc-0289-4da5-911c-b9d64e178297</bt:token>
          </bt:purchaser>
          <bt:purchaser>
            <bt:last4>0571</bt:last4>
            <bt:name>John Doe</bt:name>
            <bt:token>a9399568-0708-4778-b7dd-6827da823943</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
    </bt:customers>
  </bt:customer-response>
</bt:bluetarp-authorization>

Customer Lookup by Name

To search for a customer by company name, a GET request can be made to:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?cname=<partial_name>

...where <partial_name> is any part of the customer's company name. The search is case insensitive. The response will include all customers whose company name contains <partial_name>.


Customer Lookup by Phone

To search for a customer by phone number, a GET request can be made to:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?q=<phone>

...where <phone> is the 10-digit phone number for the customer, without any punctuation (numbers only). Note that the phone number must contain exactly ten digits.

An example of a response that might be returned for a customer lookup with parameter 'cname=acme': 
<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
                           xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:customer-response>
    <bt:customers>
      <bt:customer>
        <bt:number>1398</bt:number>
        <bt:name>ACME Masonry Contractors Inc</bt:name>
        <bt:merchant-identifier>828</bt:merchant-identifier>
        <bt:available-credit>50000.00</bt:available-credit>
        <bt:credit-limit>50000.00</bt:credit-limit>
        <bt:status>Active</bt:status>
        <bt:reason>Purchasing</bt:reason>
        <bt:address>
          <bt:line1>443 Congress St</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>8071</bt:last4>
            <bt:name>John Doe</bt:name>
            <bt:token>Tpkmefso8mbTtqgfpVXFcgYrVPXsQC </bt:token>
          </bt:purchaser>
          <bt:purchaser>
            <bt:last4>8086</bt:last4>
            <bt:name>Jane Smith</bt:name>
            <bt:token>b74a94cc-0289-4da5-911c-b9d64e178297</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
      <bt:customer>
        <bt:number>1354</bt:number>
        <bt:name>MacMerry Flooring</bt:name>
        <bt:merchant-identifier></bt:merchant-identifier>
        <bt:available-credit>20000.00</bt:available-credit>
        <bt:credit-limit>30000.00</bt:credit-limit>
        <bt:status>Active</bt:status>
        <bt:reason>Purchasing</bt:reason>
        <bt:address>
          <bt:line1>123 Main St</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>8012</bt:last4>
            <bt:name>Dana MacMerry</bt:name>
            <bt:token>qW1cDSxnKHCW18KkEFQ1N0asHGyzwt</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
    </bt:customers>
  </bt:customer-response>
</bt:bluetarp-authorization>

Customer Lookup by Merchant Identifier

To search for a customer by the merchant's identifier for the customer, a GET request can be made to:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?merchant-cid=<cid>

...where <cid> is the merchant's identifier for the customer.


Customer Lookup by BlueTarp Identifier

To search for a customer by their unique BlueTarp id number, a GET request can be made to:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?bluetarp-cid=<cid>

...where <cid> is BlueTarp's id number for the customer. 

<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
                           xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:customer-response>
    <bt:customers>
      <bt:customer>
        <bt:number>1398</bt:number>
        <bt:merchant-identifier>828</bt:merchant-identifier>
        <bt:name>ACME Masonry Contractors Inc</bt:name>
        <bt:status>Active</bt:status>
        <bt:reason>Purchasing</bt:reason>
        <bt:credit-limit>15000.00</bt:credit-limit>
        <bt:available-credit>13239.89</bt:available-credit>
        <bt:address>
          <bt:line1>443 Congress St</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>8071</bt:last4>
            <bt:name></bt:name>
            <bt:token>87b8dafa-d8e8-4c4a-ab74-a5801049444a</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
    </bt:customers>
  </bt:customer-response>
</bt:bluetarp-authorization>

Retrieving Credit Data

To retrieve a customer's available credit and credit limit, a GET request can be made to:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?bluetarp-cid=<customer_number>

...where <customer_number> is the unique BlueTarp-assigned customer number obtained from a customer lookup. The response will include both the available credit and credit limit for the customer as well as additional information usually returned in the complete customer list.

Flow diagram for checking a credit line

<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:customer-response>
    <bt:customers>
      <bt:customer>
        <bt:number>1398</bt:number>
        <bt:merchant-identifier>828</bt:merchant-identifier>
        <bt:name>ACME Masonry Contractors Inc</bt:name>
        <bt:status>Active</bt:status>
        <bt:reason>Purchasing</bt:reason>
        <bt:credit-limit>15000.00</bt:credit-limit>
        <bt:available-credit>13239.89</bt:available-credit>
        <bt:address>
          <bt:line1>443 Congress St</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>8071</bt:last4>
            <bt:name></bt:name>
            <bt:token>87b8dafa-d8e8-4c4a-ab74-a5801049444a</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
    </bt:customers>
  </bt:customer-response>
</bt:bluetarp-authorization>

Paging Customer Lookup Results

To optionally page the customer lookup results, include the page parameter to your GET request*:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?page=pageNumber

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?merchant-cid=123&page=pageNumber

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?q=John+Doe&page=pageNumber

...where <pageNumber> is an integer starting at 1. The customer response will be a subset of customers that match for a particular query. For instance, if the search matched 1,000 customers, you will get back customers 1-100 for page 1, customers 101-200 on page 2, etc. In addition, when the page parameter is present in the GET request, the customer response includes an extra XML element, more-pages, which will contain a value of either true or false. A true value means you can safely increment the pageNumber by 1, and re-issue the same query to receive the next set of customers. A value of false means this is the last page of the results for the query. The results are in ascending order by customer number.

* Paging is only supported on the following endpoints:

  • Retrieve all customers
  • Query by name
  • Query by phone
  • Query by merchant identifier
<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
                           xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:customer-response>
    <bt:customers>
      <bt:customer>
        <bt:number>1398</bt:number>
        <bt:merchant-identifier>828</bt:merchant-identifier>
        <bt:name>ACME Masonry Contractors Inc</bt:name>
        <bt:status>Active</bt:status>
        <bt:reason>Purchasing</bt:reason>
        <bt:credit-limit>15000.00</bt:credit-limit>
        <bt:available-credit>13239.89</bt:available-credit>
        <bt:address>
          <bt:line1>443 Congress St</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>8071</bt:last4>
            <bt:name></bt:name>
            <bt:token>87b8dafa-d8e8-4c4a-ab74-a5801049444a</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
      ...
    </bt:customers>
    <more-pages>true</more-pages>
  </bt:customer-response>
</bt:bluetarp-authorization>

Inactive Customers

By default, the customer lookup API returns only active customers. We define active customers with the following status and reason values:

  • Status = Active and Reason = Enrolled
  • Status = Active and Reason = Purchasing
  • Status = Temp Stop and Reason = Credit Hold
  • Status = Suspended and Reason = Inactivity

In some scenarios, it may be desirable to include inactive customers in the lookup results. For instance, you may want to distinguish between customers who don't have a BlueTarp account and those whose account has gone inactive. We define inactive customers with the following status and reason values:

  • Status = Closed and Reason = (reason value will be empty)
  • Status = Suspended and Reason = Credit Hold

To include inactive customers in the lookup results, add the include-inactive parameter to your GET request:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?include-inactive=true

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?bluetarp-cid=123&include-inactive=true

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?merchant-cid=123&include-inactive=true

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/customers?q=John+Doe&include-inactive=true

<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
                           xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:customer-response>
    <bt:customers>
      <bt:customer>
        <bt:number>1400</bt:number>
        <bt:merchant-identifier>900</bt:merchant-identifier>
        <bt:name>ACME Lumber Yard</bt:name>
        <bt:status>Closed</bt:status>
        <bt:reason></bt:reason>
        <bt:address>
          <bt:line1>443 Congress St</bt:line1>
          <bt:line2></bt:line2>
          <bt:city>Portland</bt:city>
          <bt:state>ME</bt:state>
          <bt:zip>04103</bt:zip>
        </bt:address>
        <bt:purchasers>
          <bt:purchaser>
            <bt:last4>9052</bt:last4>
            <bt:name></bt:name>
            <bt:token>87b8dafa-d8e8-4c4a-ab74-a5801049444a</bt:token>
          </bt:purchaser>
        </bt:purchasers>
      </bt:customer>
    </bt:customers>
  </bt:customer-response>
</bt:bluetarp-authorization>

Transaction Lookup

Voidable Transactions

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/transactions/void

The transactions response includes information on voidable transactions. The auth-seq number is required to void a transaction. 

<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:transaction-response>
    <bt:transactions>
      <bt:transaction>
        <bt:amount>15.00</bt:amount>
        <bt:auth-seq>11600096</bt:auth-seq>
        <bt:customer>
          <bt:number>23296</bt:number>
          <bt:name>ACME Wall Co</bt:name>
          <bt:merchant-identifier>3420</bt:merchant-identifier>
          <bt:purchasers>
            <bt:purchaser>
              <bt:last4>2598</bt:last4>
              <bt:name/>
              <bt:token>6299275a-fa12-41d8-944f-c8a570ec0bbc</bt:token>
            </bt:purchaser>
          </bt:purchasers>
        </bt:customer>
        <bt:invoice/>
        <bt:job-code/>
        <bt:original-invoice/>
      </bt:transaction>
      <bt:transaction>
        <bt:amount>36.05</bt:amount>
        <bt:auth-seq>11600101</bt:auth-seq>
        <bt:customer>
          <bt:number>23296</bt:number>
          <bt:name>ACME Wall Co</bt:name>
          <bt:merchant-identifier>3420</bt:merchant-identifier>
          <bt:purchasers>
            <bt:purchaser>
              <bt:last4>2278</bt:last4>
              <bt:name>John Doe</bt:name>
              <bt:token>bc0a5b9d-6cb1-4529-91fd-cb0a4a67a6f9</bt:token>
            </bt:purchaser>
          </bt:purchasers>
        </bt:customer>
        <bt:invoice/>
        <bt:job-code/>
        <bt:original-invoice/>
      </bt:transaction>
    </bt:transactions>
  </bt:transaction-response>
</bt:bluetarp-authorization>

Deposit Collect Transactions

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/transactions/deposit

This resource returns a list of all open deposit hold transactions for a merchant. 

<?xml version="1.0" encoding="utf-8"?>
<bt:bluetarp-authorization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.bluetarp.com/ns/1.0
                        https://api.bluetarp.com/auth/v1.1/Authorization.xsd"
    xmlns:bt="http://api.bluetarp.com/ns/1.0">
  <bt:transaction-response>
    <bt:transactions>
      <bt:transaction>
        <bt:amount>25.00</bt:amount>
        <bt:auth-seq>11600098</bt:auth-seq>
        <bt:customer>
          <bt:number>22506</bt:number>
          <bt:name>ACME Systems Inc</bt:name>
          <bt:merchant-identifier>5487</bt:merchant-identifier>
          <bt:purchasers>
            <bt:purchaser>
              <bt:last4>1083</bt:last4>
              <bt:token>5e2dc3fe-168a-4ccd-b28f-41f62ac7748d</bt:token>
            </bt:purchaser>
          </bt:purchasers>
        </bt:customer>
        <bt:invoice/>
        <bt:job-code/>
        <bt:original-invoice/>
      </bt:transaction>
      <bt:transaction>
        <bt:amount>100.00</bt:amount>
        <bt:auth-seq>11600099</bt:auth-seq>
        <bt:customer>
          <bt:number>14536</bt:number>
          <bt:name>ACME Painting &amp;amp; Decorating</bt:name>
          <bt:merchant-identifier>1847</bt:merchant-identifier>
          <bt:purchasers>
            <bt:purchaser>
              <bt:last4>9382</bt:last4>
              <bt:name>Jane Doe</bt:name>
              <bt:token>e7da664d-3e2d-42e6-a40c-bab4de00d227</bt:token>
            </bt:purchaser>
          </bt:purchasers>
        </bt:customer>
        <bt:invoice/>
        <bt:job-code/>
        <bt:original-invoice/>
      </bt:transaction>
    </bt:transactions>
  </bt:transaction-response>
</bt:bluetarp-authorization>

Registering Customers

To allow a customer with an existing BlueTarp account to begin purchasing with a fully-integrated merchant. Existing customers must be able to provide their purchasing ID # and their company's billing zip code. The purchasing ID # must be associated with an active card. A merchant may send a registration request to update a customer's account identifier in our systems.

Requests

Registration requests are made by submitting a properly formed XML document as an HTTP POST to the following URL:

https://integration.bluetarp.com/auth/v1.1/<merchant_number>/register

XML Elements
merchant-number required BlueTarp merchant id
merchant-customer-id required The merchant's identifier for the customer
bluetarp-card-number required The customer's 16 digit card number
zip-code required The zip code for the customer's billing address

Flow diagram for registering a customer.

<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:bt="http://api.bluetarp.com/ns/1.0"
                           xmlns:schemaLocation="http://api.bluetarp.com/ns/1.0
                           https://api.bluetarp.com/v1.1/Authorization.xsd"
                           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <bt:register-customer-request>
    <bt:merchant-number>3458</bt:merchant-number>
    <bt:merchant-customer-id>CUST-0001</bt:merchant-customer-id>
    <bt:bluetarp-card-number>1234567890123456</bt:bluetarp-card-number>
    <bt:zip-code>12345</bt:zip-code>
  </bt:register-customer-request>
</bt:bluetarp-authorization>

Register Customer Responses

Success Response

Successful registrations will return an HTTP status code of 200 and a response comprised of the following information:

response-code SUCCESS
message Short message indicating result of request (customer was added or updated)
bluetarp-customer-number The customer's BlueTarp account number 
<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:bt="http://api.bluetarp.com/ns/1.0" 
    xmlns:schemaLocation="http://api.bluetarp.com/ns/1.0
                          https://api.bluetarp.com/v1.1/Authorization.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <bt:register-customer-response>
    <bt:response-code>SUCCESS</bt:response-code>
    <bt:message>Customer was successfully updated</bt:message>
    <bt:bluetarp-customer-number>11111</bt:bluetarp-customer-number>
  </bt:register-customer-response>
</bt:bluetarp-authorization>

Failure Response

Failed registrations will return an HTTP status code of 200 and a response comprised of the following information. (Note: a status code other than 200 also indicates failure, but will not include a response body):

response-code One of: DECLINED or ERROR
message Short message indicating the reason for failure (e.g. customer not found) 
<?xml version="1.0" encoding="UTF-8"?>
<bt:bluetarp-authorization xmlns:bt="http://api.bluetarp.com/ns/1.0" 
    xmlns:schemaLocation="http://api.bluetarp.com/ns/1.0
                          https://api.bluetarp.com/v1.1/Authorization.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <bt:register-customer-response>
    <bt:response-code>DECLINED</bt:response-code>
    <bt:message>customer not found</bt:message>
  </bt:register-customer-response>
</bt:bluetarp-authorization>

Testing

BlueTarp will provide implementing merchants with a test key for use in a secure, sanitized testing environment. A set of test cases will also be provided to verify the correctness of the implementation. These tests must all pass and the implementation certified by BlueTarp engineers before production keys are issued and the production url is provided.

BlueTarp can provide code samples that can be used as a reference when building custom implementations.