Retailer API

Integrating with the Bucket Retailer API requires implementing the two API actions that follow. The Create Bucket Transaction action is required at the end of a retail transaction for the POS to receive the necessary information to prepare the receipt for the customer.

 

The Close Interval action is performed once at the end of a business day to indicate to Bucket that no more transactions will be created for the given Interval and that the interval should be considered “closed”. This initiates the ACH settlement process in the Bucket back end.

 

Failure to close a given interval within 48 hours of the initial Create Bucket Transaction request for said interval will result in the Retailer being suspended and no more requests will be accepted from the Retailer.

 

Development should be done against the Sandbox environment. The base URI for the Sandbox API is: https://sandboxretailerapi.bucketthechange.com

For a Sandbox Retailer Id and Secret click here.

Create Bucket Transaction

createTransactionRequest


Resource:
https://[Bucket API Branch Base URI]/api/transaction/[Retailer Identifier]
Content-Type:
application/json; charset=utf-8
Header:
Name: “x-functions-key”
Value: [Retailer Secret]
POST:
{
“amount”: 47,
“totalTransactionAmount”: 853,
“intervalId”: “String – UID”,
“locationId”: “String – UID”,
“clientTransactionId”: “String – UID”,
“terminalId”: “String – UID”
}
Notes:
amount: REQUIRED
Integer representation of “Bucketed” amount in minor currency unit. The major currency is defined at the Retailer level during provisioning.
totalTransactionAmount: OPTIONAL*
Integer representation of the total amount of the transaction in minor currency units.
intervalId: REQUIRED
Retailer-defined unique identifier for the business day. Transactions are settled in a single batch at the intervalId level.
locationId: OPTIONAL*
Retailer-defined unique identifier for location.
clientTransactionId: OPTIONAL*
Retailer-defined unique identifier for individual transaction.
terminalId: REQUIRED
Retailer-defined unique identifier for terminal / register.

*These fields are saved by Bucket along with the transaction and are available to the retailer for reporting or during programmatic settlement.

createTransactionResponse (HTTP StatusCode 200)

{

“customerCode”: “String – UID”,

“qrCodeContent”: “String – URI “,

“bucketTransactionId”: “String – GUID”,

“amount”: 47,

“intervalId”: ” String – UID “,

“locationId”: “String – UID”,

“clientTransactionId”: ” String – UID “,

“terminalId”: ” String – UID “

}

Notes:

customerCode:

Ten-character alphanumeric (zero, “O”, 1, and “I” omitted for clarity) code for alternate redemption of transaction when QR code corrupted or reader unavailable.

qrCodeContent:

URI string for retailer to represent as QR code and print on receipt.

bucketTransactionId:

Bucket-generated unique identifier for transaction.

amount:

intervalId:

locationId:

clientTransactionId:

terminalId:

Echoed from createTransactionRequest

Close Interval

closeIntervalRequest

Resource:
https://[Bucket API Branch Base URI]/api/closeInterval/[Retailer Identifier]/[Interval Id]
Content-Type:
application/json; charset=utf-8

Header:
Name: “x-functions-key”
Value: [Retailer Secret]

Notes:

Closing an interval causes Bucket to initiate an ACH transfer from the retailer’s bank information on file. Attempting to close an interval more than once will result in an exception, as will attempting to POST a transaction with a previously closed intervalId.

closeIntervalRequest (HTTP StatusCode 200)

{

“intervalId”: ” String – UID “,

“intervalAmount”: 4972,

“transactions”: [Array of reconciliationTransaction]

}

Notes:

intervalId:

Echoed from closeIntervalRequest

total:

Integer total “bucketed” by all transactions in specified interval, in minor currency units.  

transactions:

Collection with verbose details of all transactions in the specified intervalId.

reconciliationTransaction

{

“bucketTransactionId”: “String – GUID”,

“amount”: 47,

“locationId”: “String – UID”,

“clientTransactionId”: ” String – UID “,

“terminalId”: ” String – UID “

}

Notes:

bucketTransactionId:

Bucket-generated unique identifier for transaction.

amount:

intervalId:

locationId:

clientTransactionId:

terminalId:

Echoed from initial createTransactionRequest

errorResponse (HTTP StatusCode 400)

{

“errorCode”: “Error Code”,

“message”: “Verbose Error Message”

}

Error Code

Message

InvalidCredentials

Please check Retailer Id and Secret Code.

VerificationError

Account requires verification or verification has lapsed. Please contact Bucket support.

ZeroTransaction

Non-zero amount required.

NoIntervalId

intervalId required.

ClosedIntervalId

intervalId = [intervalId Value] has been previously closed.

Register Terminal

registerTerminalRequest

Resource: https://[Bucket API Branch Base URI]/api/registerterminal

Content-Type: application/json; charset=utf-8

POST:

{

“retailerId”:“String – UID”,

“terminalId”:“String-Device Hardware ID”

}

Notes:

terminalId*: REQUIRED

This should be the globally unique hardware id associated with the terminal.

*Be mindful that when using a MAC address in desktop terminal or modular network adapter environments (where the MAC address could be deliberately changed in software or mistakenly by replacing hardware components), Bucket will no longer accept requests from that terminal until the terminal is registered and approved for the specific retailer.

registerTerminalResponse (HTTP Status Code 201)

{

  ” isApproved “: false,

  ” apiKey”: “String – Empty”

}

Response when the terminal is successfully registered to this Retailer.

**

Please note that after terminal registration, user action is required on the Bucket Retailer site to confirm that the terminal is approved to send transactions.

**

registerTerminalResponse (HTTP Status Code 200)

{

” isApproved “: false,

  ” apiKey”: “String”

}

ApiKey is returned to the terminal only when the API is called with a previously approved terminal

 

Possible errorResponses

 

HttpStatusCodeerrorCodemessage
401InvalidRetailerPlease Check Retailer Id
403TerminalNotApprovedUser action required on Bucket site.
409AlreadyRegisteredTerminalId is registered to another Retailer – Contact Bucket Support

Version 1.1 ; April 6, 2018