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.

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