Bucket POS Integration Guide

Bucket’s POS Partners are very important to us and we thank you for the time and effort it will take to integrate with our API.  Our mission to accelerate humanity’s transition to a digital economy starts with the very first step: making sure our retailers and their POS systems have Bucket as a native feature.


While integrating with Bucket is relatively straight forward from the perspective of interacting with our API, it will of course introduce new elements into your product, both at the terminal and the Back Office. We hope to make you aware of some common design considerations and challenges and if you should need any extra resources.  As always, Bucket is here to help. If you have any questions, please email dev@buckettechnologies.com and our technical team will reach out to you shortly. 

Back Office – A single administrative node that all registers can communicate with. Note that in some cases (like desktop based POS systems), the Register and the Back Office might be one and the same.

Bucket Transaction – Within the larger POS Transaction, the request to the Bucket API that returns a Customer Code that represents the amount to be Bucketed.

Customer Code – A unique 12 digit alphanumeric code and QR code for Customers to redeem

Interval – POS-defined unique identifier for a business day.  All Bucket Transactions performed during an Interval are batched and reconciled in a single ACH transfer performed between the Retailer and Bucket.

IntervalID – The intervalId is a unique identifier corresponding to the current business day

Payment Method/Tender Type – Identifies the form of payment a customer tenders to a Register to complete a POS Transaction.

Cash Tender Screen – POS Screen where cashier provides details (denomination, etc) on the cash transaction.

POS Transaction – The entire customer interaction with the POS system

Register – An individual terminal that can perform retail transactions

Retailer Account – Bucket creates Retailer Accounts at the banking level. For example, a retailer with many locations that share a bank account for purposes of reconciliation with Bucket would be considered a single Retailer, while a similar multi-unit operation where each wishes to use a different bank account for reconciliation would each need its own unique Retailer Account.


Modifications To Register User Interface


On most POS systems, after the Cash Payment Method is selected, there is typically a secondary Cash Tender Screen where the cashier enter the amount of cash given by the customer. Once the cashier enters or selects the amount received from the customer, the POS Transaction is completed by the cashier selecting a “Tender” button that subsequently opens the cash drawer and prints a receipt.


To implement the Bucket integration, an additional button labeled “Bucket” or “Bucket + Tender” should be added.


This should trigger the same action of opening the cash drawer (if there is paper change due to the customer), but the Create Bucket Transaction action will be performed against our API in order to retrieve the Bucket specific content needed for the receipt.

Modifications To Start of Business Day Event


Performing the Create Bucket Transaction action against the Bucket API requires an Interval be identified by intervalId. Some POS systems will already have a native concept (and corresponding value) for an intervalId, but it may not be exposed to individual Registers but rather generated and stored in the Back Office for accounting / reporting purposes. In this case, the code on the Registers might need to be modified to fetch this value from the Back Office at the beginning of the Interval and store it locally in order to have it available when performing the Create Bucket Transaction action.


Please note that the Natural Change Function works universally and might be the ideal implementation in a cross-currency or currency-agnostic POS. It does introduce the need for the POS to store a reference object with the bill denominations available in the local currency.

Modifications To End of Business Day Event


The Back Office will need to be modified to be able to perform the Close Interval action against the Bucket API. This action will return a collection of the individual Bucket Transactions that were created during the Interval as well as the total amount (in minor currency units).



Notes on IntervalIds


Once the Close Interval action is performed, the Bucket API will reject any requests for Create Bucket Transaction actions that attempt to use a previously closed IntervalId.


If the POS supports the “rolling” into a new business day (Interval) during business hours, there will need to be a mechanism for the Back Office to actively “push” the new IntervalId value onto individual Registers.


There will be situations where there is no concept of an IntervalId native to your POS. In that case, either a “random” UID can be generated in the Back Office and the above flow adhered to, or the Register may just send a string representation of the current calendar day (say, in format YYYYMMDD).


If choosing the latter, the Back Office should not perform the Close Interval action exactly at the end of the calendar day to avoid issues where clock drift in a Register could lead to it attempting to perform a Create Bucket Transaction action on a previously closed Interval.


In practice, this might for instance just mean that the Interval should be closed at 1 AM instead of 12:01 AM.

Modifications To Reporting


This will vary from one POS to the next, but with no modifications all Registers would collectively show an overage of the total amount that was Bucketed by each Register.


This should be accounted for at the Register level (and not just at the Back Office level) so that a cashier at the end of his or her shift does not show an overage.

Calculating the Amount To Be “Bucketed”

In most locations and with most currencies, the calculation of what amount should be sent in the Create Bucket Transaction action is very straightforward — it is just the minor currency units to the right of the decimal place of the change that would otherwise be due to the customer.


However, there could be locations where this is not the case. When the lowest bill denomination is greater than a single currency unit, the amount that would be bucketed is the modulo (or remainder after division) of the change due and the lowest bill denomination (E.g. 7.20 mod 2 = 1.20).


Even still there are locations where this simple calculation would be problematic where the second lowest bill denomination is not evenly divisible by the lowest bill denomination.

Take the case of a location with currency X where the highest coin denomination is 1X and the lowest two bill denominations are 2X and 5X.


In this case, the intended effect of having Bucket remove coins from the transaction is not achieved by simply bucketing all minor currency units right of the decimal point since it would lead to customers getting a 1X coin half of the time.


Using the above example and applying the [Change Due] mod [Lowest Bill Denomination] logic, a transaction where 6.20X is due back before bucketing would yield a .20X bucketed amount and instruct the cashier to hand the customer 6X, which would either lead to the cashier unnaturally giving the customer 3 2X bills or a 5X bill and a 1X coin, defeating the spirit of the product.


In this case the solution is to apply the Natural Change Function, which describes the way that a human being makes change. The calculation would in that case be to iterate through every bill denomination lower than the amount due back, starting with the highest and proceeding in descending order, performing the modulo function on the results.

Using the example of 6.20X due back, the bucketed amount would be: (6.20X mod 5) mod 2 = 1.20X and the customer would get a single 5X bill back.

Building The Receipt

The Bucket portion of the receipt should contain three areas:


  1. Human readable 12 character alphanumeric code representing the transaction (returned from Create Bucket Transaction action as field “customerCode”)
  2. QR Code representing the URL of the code redemption page. The QR Code should be generated client-side* using the “qrCodeContent” in the Create Bucket Transaction response as the content.
  3. The abbreviated Bucket terms of service. This is a legal requirement and it should always be the fixed copy:

Per your request, your change has been Bucketed. This receipt contains the Code linked to your Bucketed funds. Please TREAT THIS CODE AS CASH.  Lost or stolen codes will not be replaced. No cash refunds, except as required by law.  See www.buckettechnologies.com for additional details.

Code is issued by Sutton Bank,: Member FDIC.

Sample Bucket Portion in Receipt:


*There are many free libraries available for generating a QR code from a string. Here is a sample one whose license allows free commercial use.


Actions against Bucket API

In production, there are only two interactions that your product will make with the Bucket API:

  1. Create Bucket Transaction
  2. Close Interval

Please see SandBox Retailer API documentation.

Retailers and Bucket Implementation

Any action performed against the Bucket API will require that a retailerId and a RetailerSecret be sent in the request. Bucket generates these values during the Retailer Sign Up process once the Retailer is validated and their bank account verified (through our ACH partner Dwolla).


In order to be able to get these values into the individual Registers, the integration should at the very least allow them to enter these values into the Back Office and then “push” them into the individual Registers.


However, in order to provide our mutual Retailer customers with the best and most secure user experience in implementing Bucket, we would love to work with you in coming up with a strategy that conforms to your native architecture and would allow us to securely get these values into a safe store as a “side effect” of the retailer creating an account with Bucket.


All development should be done against the Sandbox environment. The base URI for the Sandbox API is: https://sandboxretailerapi.bucketthechange.com.  Please fill out the form below for a Sandbox Retailer Id and Secret.


Note: Although different retailers will use different processes for end-of-day settlement with Bucket independent of their POS vendor, they must all perform the Close of Interval action to then trigger the specific mode of financial settlement agreed upon between Bucket and the Retailer. Therefore in SandBox, the closing of the interval will only trigger the creation of an email indicating that the transfer of fictitious funds has occurred.

The base URL for the Production API is: https://retailerapi.bucketthechange.com


Version 1.1 ; April 6, 2018