Customer Statements - API Specifications

A fully automated statement communication tool designed to get your merchants paid. Our Customer Statements API allows you to perform a payment request via text or email, attach a base 64 encoded image of the eStatement, collect a payment, and retrieve payment results in real-time via a WebHook.

• Supports Credit and Debit Cards
• PA-DSS Out of Scope
• Supports Payment Requests via Text to Pay or Email.
• Statement Image Attachments
• Simple JSON format specification

These terms will be used throughout the guide.

Once you have your credentials, you’ll need to create a Service Location.

To create a Service Location, send a POST request to the setServiceLocation endpoint. If everything is good, we’ll return a successful response with the info for your Service Location. Otherwise, we’ll return an error letting you know what went wrong.

Postman Example

Now it’s time to add a Customer to your Service Location.

To create a Customer, send a POST request to the setCustomer endpoint. If all is well, you’ll receive a response that includes an ID for the Customer you just created.

To update an existing Customer, include the Customer ID in your request payload.

Keep in mind, we use the ‘primaryPhone’ and ‘primaryEmail’ attributes to determine where to send Statement Notifications (Phone is preferred, but we’ll use email if no Phone is provided).

Postman Example

Now that you have a Customer, it’s time to create a Statement for them.

To create a Statement, send a POST request to the setStatement endpoint. If successful, you’ll receive a response that includes an ID for that particular statement. We’ll automatically notify your Customer that they have a statement available.

Every Customer can have only 1 statement at a time, so their statement link will always show the newest info.

An attachment can be added to the statement in PDF format as a raw Base64 encoded string (See the Postman example showing ‘Statement with Attachment’)

Note on PDF Attachments:

PDF’s should meet the following criteria:

• 1 attachment per Statement
• Max size of 5mb on disk or 7 million characters when base64 encoded
• For SMS, attachments larger than 10 pages are truncated (first 10 pages will be delivered)

You can decrease PDF size by:

• Compressing and downsampling PDF Images
• Choosing the RGB colour space for your PDF images
• Subsetting Your Fonts
• Eliminating Frills

Postman Example

You can view the statement using the link in your Customer’s notification, or the link we return in the Statement request (see Step 3 for ‘Location-As-Navigable-Url’).

Click the ‘Pay Now’ button to make a Credit Card payment for that statement.

You can easily find out when a Payment is posted using the PUSH option below. (PULL is in pre-release) 

PUSH

1. Setup a Webhook that can receive PUSH notifications
2. Send the URL to your Integration Specialist, and we'll configure our system to PUSH to that Webhook
3. When a payment is completed, we will PUSH a notification to your Webhook. That notification has all the info you need to update your records.
4. You'll send a Statement request with the updated Balance Due.

Example:

1. Customer John pays his entire statement balance ($49.95)
2. we PUSH that notification to your webhook
3. You update your records (John now owes $0.00)
4. You send a Statement request with that updated Balance. (John's new statement balance is $0.00)

PUSH Postman Example

PULL (pre-release)

1. Poll the "Queue Package Home" endpoint with a GET request
2. If there are items in the queue, perform a GET with the "Package Pickup" URL to retrieve the item ID and item type
3. If the item type is a Payment, perform a GET request to the "Payment" endpoint with the ID to retrieve the payment details
4. After you have handled an item (updated your records, etc...), send a POST to the "Queue Package Action" endpoint. This action removes that item from the queue.

PULL Example (pre-release)

1. Customer John pays his entire statement balance ($49.95)
2. You PULL the payment message from our system
   1. Poll the "Queue Package Home" endpoint
   2. When the response shows an item in the queue, grab the "Package Pickup" and "Queue Package Action" urls from the response; you'll use these in the next steps
   3. Send a GET to the "Package Pickup" url, and grab the Item ID and Type from the response
   4. If the Item type is a Payment, send a GET to the "Payment" endpoint, and John's payment details are returned
   5. Update your records (John now owes $0.00), and POST to "Queue Package Action" to remove that item from the queue
3. You send a Statement request with that updated Balance. (John's new statement balance is $0.00)

PULL Postman Example

You can easily configure Customer Statements behavior and branding by using our Configuration UI (available via Token & Pop).

Token & Pop is an action driven service that creates User Interfaces. In other words, you tell us what you want to do, and we'll provide the UI to get it done.

For example, if you want to change some configuration settings for your Service Location:

1. You'll make a 'Token & Pop' API call, and specify the 'administerServiceLocation' action.
2. A tinyLink is returned, and you'll display (Pop) that url within an iframe in your application.
3. That's it! You can change the settings or update branding, without building a user interface or making any complex API calls.

Postman Example