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,
“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.
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: OPTIONAL*
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.

Version 1.1 ; April 6, 2018