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