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 https://www.myschoolbucks.com/msbpay/1.0/whoAmI

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 https://www.myschoolbucks.com/msbpay/1.0/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

Cart Fields

Field Name Required Description
cartItems An array of cart items, defined below. Optional upon cart creation, but users cannot complete checkout with an empty cart.
redirectUrl The URL to redirect to after checkout. When the user reaches this URL, you should process the cart using the Process Cart call.
allowDuplicatePayments   Choose whether or not MySchoolBucks should attempt to prevent duplicate transactions. Value is either "true" or "false", and defaults to "false".
returnToSiteURL   A URL that will be provided to the user as a link upon checkout, so that they can navigate to their cart. Should be a URL that leads to the cart page in your application if provided. If no URL is given, the user will not be shown a link to navigate back.

Cart Item Fields

Field Name Required Description
itemId Identifier for the item. Can be set to arbitrary values less than 60 characters, for your internal use.
itemName Name for the item. Can be set to arbitrary values less than 80 characters, for display to the user.
clientId   ID of the client this cart item should be associated with. If not provided, the default for your developer account will be used.
departmentId   ID of the department this cart item should be associated with. If not provided, the default for your developer account will be used.
storeId   ID of the store this cart item should be associated with. If not provided, the default for your developer account will be used.
paymentMethodId   ID of the payment method this cart item should be associated with. If not provided, the default for your developer account will be used.
quantity Amount of this item in the cart. Must be greater than 0.
unitPrice Price per unit of this item. Must be a positive number.
studentName   Name of the student that this item is associated with.
reference   An internal reference field that can be used for your own needs. Must be less than or equal to 80 characters.
properties   Array of objects containing "name" and "value" fields, used to apply arbitrary properties to an item, such as size or color.
glAccountId   Identifier for the G/L Account to use when processing this item.

The Cart ID

GET https://www.myschoolbucks.com/msbpay/1.0/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 https://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 https://www.myschoolbucks.com/msbpay/1.0/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 https://www.myschoolbucks.com/msbpay/1.0/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 https://www.myschoolbucks.com/msbpay/1.0/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 https://www.myschoolbucks.com/msbpay/1.0/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 https://www.myschoolbucks.com/msbpay/1.0/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/msbpay/1.0/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. 2018-12-16T22:59:20Z
  • YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm - local time, including time zone offset
    • ex. 2018-12-17T05:59:20+01:00
  • YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm[IANA time zone] - local time, including time zone offset and IANA identifier
    • ex. 2018-12-17T05:59:20+01:00[Central European Time]

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]

Searching for Payment Methods, Stores, Departments, and G/L Accounts

GET http://www.myschoolbucks.com/msbpay/1.0/clients/{clientId}/paymentMethods
GET http://www.myschoolbucks.com/msbpay/1.0/clients/{clientId}/stores
GET http://www.myschoolbucks.com/msbpay/1.0/clients/{clientId}/departments
GET http://www.myschoolbucks.com/msbpay/1.0/clients/{clientId}/glAccounts

If your account has permission, you can query the API to find the IDs for payment methods, stores, departments, and G/L accounts for use during other queries.

These calls are paginated, and allow string searching using the searchText query parameter.

Frequently Asked Questions

How will I know if a payment is successful after it is processed?

Successful payments /process response will look something like this:

{
    "result": "Success",
    "errors": [],
    "resultCodes": [
        "Your payment (confirmation code: \"7M29F93EE5MRTER\") is being processed. Thank you!",
        "Your payment (confirmation code: \"8TW7890RC4PSGKQ\") is being processed. Thank you!",
        "Your payment (confirmation code: \"D9YH41TRP80QOM9\") is being processed. Thank you!",
        "Your payment (confirmation code: \"FRX3596CS41IKGQ\") is being processed. Thank you!"
    ],
    "cartId": "41c67809-cdbd-4cdc-a6af-e45344c2b862"
}

A response code result = "success" and result codes indicating "Your payment (confirmation code: "7M29F93EE5MRTER") is being processed. Thank you!" is what you will use to mark a successful transaction. If you do not receive the "confirmation code" response in the resultCodes, then there is a payment processing failure. There are different failures that can be sent back related to expiration date, account number, etc. The basic logic would be to mark payments with the confirmation code as good, and anything else as failed.

"response" =>
	{
		"result"=>"Success",
		"errors"=>[],
		"resultCodes"=>["The supplied expiration date does not match"],
		"cartId"=>"57fa5cc4-d468-4925-b686-3ebf36b7d5f3"
	}

Here is an example of a failed payment /process response.

Can I reprocess the same cart id if the payment fails?

No. A new cart will need to be created and sent to checkout with updated payment information in order to process for a successful payment. You cannot reprocess a cart after it has been processed, no matter if it successful or failed. This prevents duplicate payments.

Does MSB Pay API check for duplicate payments?

Yes. A duplicate payment is checked is done by comparing the following:

  • Client
  • StoreID
  • Gateway
  • User
  • Billing Account
  • Payment in last 2 hours
  • Product Name
  • Properties
  • Amount
  • Payee Name
  • Payee Card / ACH #

By providing

"allowDuplicatePayments" : "true"
in a cart's body, the checks above will be bypassed when the cart is processed.

Can a credit card refund be processed same day?

Yes. A refund processed same day will void a successful payment. Refunds processed after 24 hrs, will apply as a credit.

Can I process a partial refund?

Yes. A refund can be processed for a partial amount. Multiple refunds can be processed, as long as the total amount of the refunds are no greater than the original transaction amount. Example: Original transaction amount $50.00. Refund #1 for $45.00. Refund #2 for $5.00.

How do I reconcile payments?

You can use a combination of the Payment History (https://www.myschoolbucks.com/ver2/developer/msbpayapi#paymenthistory) and Confirming Payments (https://www.myschoolbucks.com/ver2/developer/msbpayapi#confirmpayments) to reconcile your payments.

Initially polling all of your payments using the payment history call, and marking reconciled payments as confirmed will then allow you to set the transferConfirmed=false parameter for follow up calls. You can also limit your polling call to specific date ranges with the startDate and endDate parameters.

What happens if a refund is processed in MySchoolBucks (not with MSB Pay API)?

Refunds can be processed in MSB by a customer admin or client support. A credit amount is created when the refund is posted in MySchoolBucks. This credit will be linked to the original CartID. If you are polling payments regularly, you will capture this new payment as an unreconciled payment.

How will a refund processed in MySchoolBucks (not via MSB Pay API) reconcile via API?

The refund will create a new payment record with a credit value. If you run reconciliation polling, you will capture this new payment record linked to the original cartID.

How long does it take for an eCheck/ACH payment to settle?

It varies by financial institution, but a good estimate is 2-3 business days.

Can funds be deposited to different bank accounts based on different products?

Yes. PaymentmethodID will determine the payment account settings in MySchoolBucks, and is configurable for each item you add to a Cart. If you have multiple Payment Methods in MySchoolBucks that you wish to use, you can configure different products to different paymentmethodId’s. Multiple products with different paymentmethodids can be used in the same checkout. The user will receive a single checkout experience, and the funds will be routed to separate accounts according to the payment methods used.

How do I get setup with a sandbox account?

Complete our Support Request form (https://www.myschoolbucks.com/ver2/etc/getsupportrequest) and ask to get an MSB Pay API sandbox account created. Our client services team will contact you with more details.

Is student information required for a transaction?

No. Student info (ID or Name) is not required for a cart item. You can pass the student name in the studentName field. MSB Pay API does not link studentName to a student database, so this field is only for reference in reporting.

What is the purpose of the redirectUrl?

The redirectURL is a URL that we send the user to after they complete the payment information steps of the transaction. This URL typically points back to your originating site or software and automatically runs the /process call to complete the payment. You can then display the payment processing response (confirmation code or failure message).

Does a user have to create an account on MySchoolBucks in order to complete a payment?

MySchoolBucks will allow guest checkout, and this option will not require a user account. Guest checkout may be disabled, and in this case it would require a username and password before the payment can be processed. School districts determine if they will allow guest checkout or not, it is not configurable per transaction.

Is there a limit on the number or rows per call MSB Pay API will return?

Yes. By default 100 rows are returned. If there are more than 100 rows, the "next" value in the meta block will have the URL of the next 100 rows.

What is the properties field in the Cart used for?

The properties field can be used to include additional data related to the line item. Each properties item has a name and value. There is no limit on how many you can create, and there is no character limit on the name and value fields.

What is a Developer Account?

To interface with MSB Pay API, you must have a developer account. Developer accounts are setup with an ID and API Key to authenticate with MySchoolBucks.

What is a clientId?

The clientId is a unique identifier for the school district or partner the payment is for. A clientID is assigned to an existing developer account. Multiple clientId’s can be assigned to a developer account. A default clientId can be configured for a developer account. A developer account can only process transactions for clientId’s assigned to their account.

What is departmentId?

The departmentId is used to identify a specific department setup in MySchoolBucks. This is used primarily for reporting and is not a required field. A default department can be assigned to a clientId in the developer account setup.

What is storeId?

The storeId is used to identify a specific store setup in MySchoolBucks. A default store can be assigned to a clientId in the developer account setup. The storeId field can be blank if there is a default configuration present.

What is paymentMethodId?

The paymentmethodId is used to identify a specific payment method setup in MySchoolBucks. Payment methods in MySchoolBucks are configured to specific bank accounts and accepted forms of payment (credit cards and echecks). A default payment method can be assigned to a clientId in the developer account setup. The payment method field can be blank if there is a default configuration present.

Can I bypass a duplicate payment check?

Yes. Setting allowduplicatePayments to true in a cart body will disable the duplicate payment checks for the cart.

Can I pass a GL Accounting Codes for the items in my Cart?

Yes. Using the glAccountID in the Cart body will assign existing GL Codes in MySchoolBucks to the cart items.

Can I get a list of Payment Methods for a specific district?

Yes. Use the /clients/{clientId}/PaymentMethods call to return a list of PaymentMethodIDs associated with a specific clientID (district).

Can I get a list of Stores for a specific district?

Yes. Use the /clients/{clientId}stores call to return a list of Stores associated with a specific clientID (district).

Can I get a list of Departments for a specific district?

Yes. Use the /clients/{clientId}/departments call to return a list of departments associated with a specific clientID (district).

Can I get a list of GL Accounts for a specific district?

Yes. Use the /clients/{clientId}/glAccounts call to return a list of GL Accounts associated with a specific clientID (district).

Are there character limits on any fields?

Yes. Please refer to the Swagger documentation for specific character limits on each field.

What is the returnToSiteUrl used for?

Proving a returnToSiteUrl will allow the customer the option to click a button that will take them back to your original website before initiating the MSB Pay API checkout. This option provides an alternative to the customer clicking the browser’s “Back” button.

Is there a different response for partial or full refunds?

No. In a recent API update, these calls were modified to return the same format.