Getting Started

Welcome to our Developer Knowledge Base where you will find everything you need, as a BlueTarp merchant, to integrate with our API services.

Not yet a BlueTarp merchant? Contact us to get enrolled!

Overview

1. Customer applies for terms.

Your customer logs into your portal, requests to apply for a BlueTarp terms account, completes a quick and easy online application, and receives an instant decision.

Learn more about our Applicants API >>

2. Customer pays with terms.

An approved customer can choose BlueTarp as their terms-based payment method at checkout for a real-time authorization.

Learn more about our Orders API >>

3. BlueTarp bills the customer.

BlueTarp collects all finalized orders at the end of each day, and sends branded, detailed billing to the customer on your behalf.

Learn more about our Orders API >>

API Details

BlueTarp's APIs are 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 permitted.

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.

Applicant API
Create Applicant POST /api/v2/applicant Redirect to BlueTarp's online application
Lookup Applicant GET /api/v2/applicant/{token} Get application decision status

Orders API
Create Order POST /api/v2/order/sale Authorize a sale
Cancel Order POST /api/v2/order/cancel Cancel an order
Create Invoice POST /api/v2/order/details/sale FULL REPORTING ONLY
Submit level-3 details for an order and trigger capture/billing
Create Return POST /api/v2/order/details/return Issue a credit
Lookup Purchasers GET /api/v2/customer/purchasers Get purchaser token for a customer

Authenticating

BlueTarp uses JSON Web Tokens (JWT) to authorize API access. Once a token has been obtained, you will use it in your API call requests to BlueTarp.

Obtaining an access token

Once enrolled as a merchant, BlueTarp will be able to provide you with a set of long-lived HTTP Basic credentials (username/password) for you to use to request an access token.

  1. Make an HTTP POST request to the token endpoint using provided credentials

  2. Store the token you receive in the response body for use in your API call requests to BlueTarp


Example token request
$ curl -u <user>:<password> -X POST \
https://api.demo.bluetarp.com/auth/token
{"access_token":"<access_token_value>"}
Example API call request
$ curl -X GET -H "Authorization:Bearer <access_token_value>" \
https://authapi.demo.bluetarp.com/auth/v1.1/<merchant_num>/customers?bluetarp-cid=123456

Re-authenticating an expired token

The response returned for an expired token looks the same as making an unauthenticated request, in that it returns an HTTP 401 status code. Follow the steps below upon receiving this status code.

  1. Login using the provided credentials

  2. Make an HTTP POST request to the token endpoint

  3. Retry your API call using the new token

  4. If another 401 is returned, consider it an unexpected error

 Resources

Status Codes

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

Status Code Description Details
200 OK Successful request
400 Bad Request Invalid request due to formatting issues
401 Unauthorized Invalid or missing client key
404 Not Found Invalid URL or requested resource
500 Internal Server Error BlueTarp processing error

JWT Details

The JWT is a Base64 encoded string with various pieces of data consumed by BlueTarp systems.

Example access_token string:
{ "access_token": "VOIDEDeyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJqd3RzZXJ2aWNlIiwic3ViIjoiYXBpdXNlckB3ZWJzdGF1cmFudHN0b3JlLmNvbSIsImlhdCI6MTU1NjI5NzA2MSwiZXhwIjoxNTU2Mjk4ODYxLCJqdGkiOiJjZGI2Mjk4Zi00YzU3LTQyNDctYjQxOS0wZDlhZWE1NGExNjQiLCJhdXRob3JpdGllcyI6WyJhcGlfY2xpZW50Il0sImF1ZCI6IjE1MTc1In0.Dz5Z1Vj2QRFpqOdifBWd53j9GBGIOyzgde6lMRlN1W7G3Jj0u_amcZQN5D7EavqC1KETKJrpFeIHUGYUPESNRmtXKpVlpdsjM11y_J_MvjXb3QWr7pgBmr9YGq376aJNR-PzBuv4qcBTeThc1nVUpR0hvj6ank_u7UUOyeNioX2jCMb3tHopp3KNBhDSniM4OQsetzCeL4Sw1Ka2TFzQxlQ-imPNNx-UP2VwUtGgU4FZAbEvSoijNoEu699SzAnyhXAIVQB2ebXrrliAwgpvykk-ZZrL6Ihlumi6g6iOyzUBauxh1ch_AWvALNqoqvfpwdlgQPhBBQEXVLdbWukCKbrTWGCL-NYruZBujlY696fl7yOqEDgI8GLG9eIYrxzNp6mNWXkVBxGVAF0_hYPsoXu-XtZsq0Zh319FoaVRsFY07mY5uReuQ_x1pLaMOH_i76U4iVXO_fOCM4sM0I20GDOPl-xosmHo3x07_o8P2IlZspdoojLfWCbZiGpY3Wwfw3QarKOsv3VPnzrr3P-i3txoLanNA2Tpnx7WaADy1nEQP7RC1jQNQNmwahMcz0BY3N8WCmXlfox8IPY3RYQcU26CAmQUlkXn4Yr_yV3ygibzUwhRheaTv7nJUtMLt-5Y7-uiggCR6LElGB02AtcSd6YlklEhbSCvc" }
Example decode of above access_token string:
{ "alg":"RS256" }{ "iss":"jwtservice","sub":"apiuser@somecustomer.com","iat":1556297061,"exp":1556298861,"jti":"cdb6298f-4c57-4247-b419-0d9aea54a164","authorities":["api_client"],"aud":"15175" }

JWT Fields

Header Registered Claims
alg Signing algorithm being used; RS256
iss Issuer, service providing the JWT. In this case; [BlueTarp] jwtservice
sub Subject (usually the requester); @customer domain
iat The time the JWT was issued (epoch)
jti Unique identifier for the JWT
aud Audience; merchant/JWT grouping identifier
authorities Value used by BlueTarp systems to determine accessibility of JWT user (sub)

NOTE: The encryption key is not described in the above table

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.

 Our API

 Applicant API

Create Applicant

Embed an 'apply now' link into your eCommerce web experience to allow your customers to apply for a BlueTarp terms account. When a customer has requested to apply for a BlueTarp account, use the endpoint which will immediately redirect the customer to our online commercial credit application.

Click here to see our SwaggerHub page.

Applicant Lookup

Allows you to poll us for credit decision/status updates for a customer that has requested to apply.

Click here to see our SwaggerHub page.

 Order API

Create Order

Use to request a new authorization when a customer has placed an order using BlueTarp as their payment option. An approved authorization will immediately decrease the customer's available credit by the amount of the order.

An approved authorization for a new order must be captured by BlueTarp in order to (a) bill the customer, and (b) fund you for the order amount via your BlueTarp settlement.

Click here to see our SwaggerHub page.

Cancel Order

Use to void a previously approved authorization for an order that has not yet been finalized (billed).

Click here to see our SwaggerHub page.

Finalize Order

An approved authorization (see Create Order) must be captured by BlueTarp in order to (a) bill the customer, and (b) fund you for the order amount via your BlueTarp settlement. The process to finalize an order depends on your BlueTarp merchant account's configured Reporting Type:

  Full = Customers will be billed with SKU level order information

  Summary = Customers will be billed without SKU level order information


  FULL REPORTING

  If your BlueTarp merchant account has been configured as Full Reporting, you will want to use the /orderDetails/sale endpoint once an order has shipped and you are ready to bill the customer.

  Upon receiving order details from you, we will:

   1. Match them to the originally approved sale authorization

   2. Capture the authorization as a billable transaction overnight

   3. Queue the customer up to receive a bill from us on your behalf

   4. Queue the captured order amount to be funded in your next settlement from BlueTarp


  SUMMARY REPORTING

  If your BlueTarp merchant account has been configured as Summary Reporting, BlueTarp will automatically finalize and capture approved order authorizations each night.

Click here to see our SwaggerHub page.

Create Return

Use to issue a credit back to the customer for part or all of an order that's already been finalized (billed).

Click here to see our SwaggerHub page.

Look Up Purchasers

Use to obtain a customer's purchaserToken (required in calls to Create Order) as needed.

Click here to see our SwaggerHub page.