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

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.	Online Docs V2 (current) Online Docs 1.0
	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 V2 Collection (current)  Download 1.0 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 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.
loginPolicy		When the user redirects to MySchoolBucks to check out, this value can override a district's default login policy. Value is either "none" (guest checkout OK, no login prompt), "optional" (guest checkout OK, login prompt before cart), "required" (login or signup required before cart) or null (district default behavior).
checkoutStyle		When the user redirects to MySchoolBucks to check out, this will define the experience. Requires a pre-existing setup of static address details for the developer account. Contact your account rep for setup. Value is either "express" (minimum payment info collection) or null (ordinary checkout).
paymentPreauthPolicy (v2 only)		When the user is checking out at MySchoolBucks, attempt to preauthorize the entire cart value with card issuer to verify the whole cart will be paid for. User will be informed if funds can't be processed and given an opportunity to try a different card or account. This can help prevent split cart values when more than one store or payemnt method is selected in the cart. Value is either "none", "fullpay" or null. Recommended value is "none" or null if your organization is not using multiple stores or multiple items per cart.

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. Format: "[glAcctId]:[providerId]"

The Cart ID

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

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 or open a new tab/window. 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 cart for completing checkout on MSB website.

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

Order Processing

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

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

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

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

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.

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

To calculate the remaining refundable balance available on a payment just call the Payment Status Check and look for "remainingRefundableAmount" at the cart payment level. The remaining refundable amount is returned within the call below for each cart payment. This represents the total refundable amount that can be made on the payment. Refundable payments ("txnType": "SALE") will have a value >= 0.00. Refund Payments ("txnType": "REFUND") will have a value of null.

 GET carts/[cartId]/payments definition

Confirming Payments

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. 2024-04-16T14:00:01Z
• YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm - local time, including time zone offset
• ex. 2024-04-16T21:00:01+02:00
• YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm[IANA time zone] - local time, including time zone offset and IANA identifier
• ex. 2024-04-16T21:00:01+02:00[Central European Summer 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

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.

New For Version 2

What changed with version 2 of MSB Pay API?

Version 2 of the API has been publicly released with MSB release 10.0 for the 2020-21 school year.

Changes include:

• Errors in responses are now presented in a list, instead of concatenated strings. This should make error handling easier for clients.
• The paymentPreauthPolicy cart attribute allows for the cart contents to be preauthorized by the card issuer before the user leaves the payment screen. This can help complete payments without creating a new cart on the sales site.
• The API has an exception testing apparatus that you can use to generate each type of exception that could possibly be thrown by the server.
• The returnToSiteUrl and redirectUrl cart parameters now support URL lengths up to 1900 characters.

What is the exception tester used for?

It's often difficult to catch unknown or unseen errors with an application before they happen. This method allows a developer to create tests against responses that could be created by the web server while processing a Pay API request.

Please note that some exceptions are handled slightly differently between the versions. Testing your entire integration should be completed before shipping code against the new API.

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 body, the checks above will be bypassed when the cart is processed.

Can I bypass a duplicate payment check?

Yes. Setting

"allowDuplicatePayments" : "true"

in a cart body will disable the duplicate payment checks for the cart.

Can a credit card refund be processed same day?

Yes. A refund processed same day will void a successful payment. Refunds processed after the funds have been processed by the financial institution (card issuer or bank) 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. Visibility to the user at checkout is optional. 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 pass a GL Accounting Code for the items in my Cart?

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

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).

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 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).

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. These calls will return the same response model.