Reconciliation

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. 2026-04-02T08:40:25Z
• YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm - local time, including time zone offset
• ex. 2026-04-02T01:40:25-07:00
• YYYY-MM-DDThh:mm:ss.sss(+|-)hh:mm[IANA time zone] - local time, including time zone offset and IANA identifier
• ex. 2026-04-02T01:40:25-07:00[America/Los_Angeles]

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.