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
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>
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.
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 |
<?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.
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 |
<?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.
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 |
<?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.
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 |
<?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.
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 |
<?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.
token | required BlueTarp-assigned token for the purchaser |
---|---|
auth-seq | required Authorization sequence number from an approved 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-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.
<?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.
<?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; 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
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 |
<?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.