MSB Pay API

MSB Pay API is an ecommerce tool to enable credit card and checking account payment processing on your website. MSB Pay API provides tools to send shopping cart contents to checkout, allowing easy integration with parent billing accounts registered with MySchoolBucks.

Pay provides tools to send shopping cart contents to the MSB checkout process, allowing easy integration with parent billing accounts registered with MySchoolBucks for meal funding.

Secure Internet Connection

MSB Pay API allows connections to MySchoolBucks using a RESTful web service over secure socket layer (SSL) on port 443. SSL provides data encryption in transit so sensitive school information is protected during transmission. A valid developer ID and authentication key is required to access the web service.

Before You Start

GET developer.msbpayapi.beforeyoustart.url

To interface with the Pay API, you must register for a developer account. Developer accounts are set up by Heartland School Solutions Client Services team.

Review the documentation for API calls and data models to set up your systems to meet our interface.

 GET whoAmI definition

API Specification

The API is documented using the swagger.io toolkit. The links to the right allow access to interactive documentation and the source on which it is based.

Online Docs

 Download Markup

Postman test collection including all calls and some sample data is available. Right-click the download link, copy the destination URL, then import into Postman: "Import" button, "Import From Link" tab, paste link.

 Download Collection

Checkout Flow

While trying to maintain a RESTful structure, there are a few artifacts with Pay that require cache or database backing for the process to provide a hand off to the web servers that authenticate the user and collect payment information. This is handled automatically with the Pay API on our MySchoolBucks servers.

  1. User adds item(s) to a shopping cart on a website.
  2. To initiate checkout, your site sends over item details (name, cost, quantity, etc.) so Pay API can prepare a cart in MSB.
  3. MSB returns a unique identifier for the cart.
  4. Your site may update the cart contents based on shopping activity, adding new products or replacing/the entire cart.
  5. When the cart is ready for payment, your site will redirect to MSB with the unique identifier.
  6. At the MSB checkout, the customer can login to use stored payment methods or continue as a guest and enter a new payment method.
  7. User completes checkout, the cart is authorized and user is redirected back to your website.
  8. Your site can now process the authorized cart and Display a confirmation message to the user.

Send Us Your Cart

POST http://www.myschoolbucks.com/msbpayapi/carts

Post a cart of items to purchase to start a purchase. You will receive a cart id to use while continuing this exchange.

 POST carts definition

The Cart ID

GET http://www.myschoolbucks.com/msbpayapi/carts/{cartId}

Your key piece of data for referring to purchases at MySchoolBucks is the Cart ID. This will be returned when you initiate a cart and is permanently tied to the orders and payments that are created. This is also a key piece of data to supply when requesting a refund.

 GET carts/[cartId] definition

 PUT carts/[cartId] definition

 DELETE carts/[cartId] definition

 POST carts/[cartId]/addItems definition

Ready To Pay

GET http://www.myschoolbucks.com/ver2/stores/msbpay/checkout

When your customer is ready to pay, your site will use a data driven URI to hand off to MySchoolBucks.com site. Browser can redirect to MSB, open a new tab/window, or open a modal window with iFrame. These options should allow you to try to match your site's flow while sending the PCI part of processing over to us. Query parameters are listed below.

  • clientID (required)
    • The clientId value in the query string represents the district name/styling to be applied at checkout on MSB. You may select from any client tied to your developer account.
  • cartID (required)
    • The cartId value created with your submitted items. This will generate the basket for completing checkout on MSB website.

When your customer selects to check out with MySchoolBucks, redirect browser to this URL.

Order Processing

POST http://www.myschoolbucks.com/msbpayapi/carts/{cartId}/process

The final active step is to submit the pre-approved cartId for MSB to push through its payment processors for completion.

Order status for the exchange will be returned immediately.

 GET carts/[cartId]/orders definition

 POST carts/[cartId]/process definition

Payment Status Check

GET http://www.myschoolbucks.com/msbpayapi/carts/{cartId}/payments

Payment gateways are partner systems that route card and check requests to processors and banks. Pay API returns the outcome of the sale immediately as it becomes available, but you can review details of payments on a given cart with the getPayments method.

 GET carts/[cartId]/payments definition

Cart History

GET http://www.myschoolbucks.com/msbpayapi/carts

Cart requests started by this developer key can be retrieved by calling for cart history in the API.

Details of particular cart are available by requesting the history while supplying the Cart ID from the original request. This is also available in the history list with some metadata to help identify the process.

You can also get a list of cart requests that your developer account has initiated by calling /msbpay/1.0/carts.

By default, results are filtered by your developer account, paged and limited to 100 per page. In the “meta” object of the response you will find a total count, current page number, a URL to the previous page of results (if relevant), a URL for the current page you are viewing, and a URL to the next page (if relevant). Below are the filters currently supported by providing query parameters:

  • status=[pending, authorized, closed, canceled]
  • createdDateStart
    • Carts created on or after createdDateStart. Date and time must be ISO8601 format as described below.
  • createdDateEnd
    • Carts created before createdDateEnd. Use this to limit the window of records returned when using the createdDateStart filter. Date and time must be ISO8601 format as described below.
  • updatedDateStart
    • Carts updated on or after updatedDateStart. Date and time must be ISO8601 format as described below.
  • updatedDateEnd
    • Carts updated before updatedDateEnd. Use this to limit the window of records returned when using the updatedDate filter. Date and time must be ISO8601 format as described below.

Cart item level filters are listed here. Carts filtered by item level values will be returned if ANY item in the cart matches ALL filters.

  • itemId
    • The Item ID of the cart item.
  • itemName
    • The Item Name of the cart item.
  • clientId
    • The ID for the district attached to cart item.
  • storeId
    • The ID for the store attached to cart item.
  • paymentMethodId
    • The payment method ID attached to cart item.
  • departmentId
    • The ID for the department attached to cart item.
  • studentName
    • The name of the student attached to cart item.
  • reference
    • The text passed in the reference attached to cart item.

 GET carts definition

Payment History

GET http://www.myschoolbucks.com/msbpayapi/clients/{clientId}/payments

Payments made on carts processed by this developer key can be retrieved by calling for payment history in the API.

This resource is based on a search including the clientId to reduce load on the database, which stores these records on different servers for pools of clients. Periodically polling this URI including transferConfirmed=false&paymentType=credit filters should show MSB payment credit activity, whether it was initiated via API or in the web console.

By default, results are filtered by your developer account, paged and limited to 100 per page. In the “meta” object of the response you will find a total count, current page number, a URL to the previous page of results (if relevant), a URL for the current page you are viewing, and a URL to the next page (if relevant). Below are the filters currently supported by providing query parameters:

  • cartId
    • Search payments for a single cart identifier
  • transferConfirmed=[true, false]
    • Used to optionally filter the payments by the confirmation status - true returns only confirmed payments, false returns only unconfirmed payments, and omitting the filter will return payments without regard for confirmation status
  • paymentType=[sale, credit]
    • sale is a payment made by the customer on the original transaction
    • credit is any refund, decline, reversal, dispute or other negative funds action that would affect the net balance of the payments on the cart
  • startDate
    • Carts created on or after createdDateStart. Date and time must be ISO8601 format as described below.
  • endDate
    • Carts created before createdDateEnd. Use this to limit the window of records returned when using the createdDateStart filter. Date and time must be ISO8601 format as described below.

 GET clients/[clientId]/payments definition

Payment Refunds

POST http://www.myschoolbucks.com/msbpayapi/carts/{cartId}/payments/{paymentId}/refund

Refunds for API initiated sales are implemented at the payment level. Payments can be searched within an MSB client or retrieved directly from a previously closed cart.

There are two exclusive options for refunding, exactly one must be chosen:

  1. Full payment refund - refundFullAmount: true
  2. Partial refund with item level details - refundFullAmount: false, refundItems: [ refundItem ]

The payment items on a full refund of a sale will be copied from the original record and reversed. Partial refund requires specification of item details, quantity, and amount.

If a partial refund has been applied to a payment, the full refund will no longer be available. Remaining balance should be calculated and applied in a new partial request that describes the line items to return the remaining funds.

 GET carts/[cartId]/payments/[paymentId]/refund definition

Confirming Payments

POST http://www.myschoolbucks.com/msbpayapi/clients/{clientId}/payments/{paymentId}/confirm

Sales made from your shopping site should be executed and funded promptly once the payment is processed. The cart status closes and order/payment records are available for review of details.

To assist with a reconciliation of sale origination and payment processing, we make a payment confirmation construct available for matching records from your system to MSB Pay API.

As noted in the Payment History notes, you can retrieve records via an API call that requests all payments that have not been confirmed. Each of these paymentId values can be substituted into this URL to acknowledge the activity and suppress from later requests for unconfirmed records.

 POST clients/[clientId]/payments/[paymentId]/confirm definition

Expressing Dates in Query Strings

All dates and times expressed in MSB Pay API queries and models are based on Coordinated Universal Time (UTC) expressed with a subset of ISO 8601 compliant formatting. MSB Pay API supports three forms of date/time in strings:

  • YYYY-MM-DDThh:mm:ss.sssZ - UTC reference time (returned by MSB Pay API models)
    • ex. 2011-12-03T10:15:30Z
  • YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm - local time, including time zone offset
    • ex. 2011-12-03T10:15:30+01:00
  • YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm[IANA time zone] - local time, including time zone offset and IANA identifier
    • ex. 2011-12-03T10:15:30+01:00[Europe/Paris]

Any other formatting of a date/time should return an error.

Result Paging

You may also specify the page number and row count as query parameters to control paging. If they are not specified, we will assume the defaults stated above (page 1, row count 100).

  • page=[1..n]
  • rowCount=[1..100]