Mock Payment Processing

Your account is currently hooked up to the mock processor, meaning transactions will not move real money. To process a transaction, you should issue a POST against the /txns endpoint. Click here for a sample.

The best way to handle the transaction processing is to process the transaction and check the status field of the response. If the status is Pending or Settled, that means the transaction was successful.

Test Credit Cards

Use any expiration date in the future! Use any 4-digit security code for American Express and any 3-digit security code for all others.

Brand Number
Visa 4111 1111 1111 1111
Visa 4800 0000 0000 4444
MasterCard 5454 5454 5454 5454
MasterCard 5000 0000 0003 4321
MasterCard 5000 0000 0005 1234
Discover 6767 6767 6767 6767
Discover 6900 0000 0000 6666
Am Ex 3111 1111 1111 1113

Trigger Amounts

Amount Status Result
$*.10 DECLINED Test decline
$*.11 DECLINED Technical failure (declined)
$*.12 ERROR Technical failure (error)
$*.97 UNKNOWN Test unknown status
$*.02 SETTLED Test direct-to-settled status
All others PENDING Normal txn

To trigger declines, we use a value look up table. Simply process a transaction for these dollar amounts, and you will get the response you desire. Please note that partial authorizations, while simulated by the API, are disabled at our live processor and cannot happen in the real world. Also note that in the real world, transactions will go into Pending until they’re batched out at midnight, however, the default behavior is to move straight to Settled, so that programmers reporting tools will usually work without the developer having to wait a day.

If you need to do end-to-end reconciling, You will schedule a daily call to a report process that loops through the transactions for the day and matches them up with your system.

Test Magnetic Stripes

Copy the below stripe. Click “Swipe Card”. CTRL+V to paste in the stripe.




ACH Testing

Routing Number: 111111118

Account Number: any integer longer than 5 digits


UTF-8 Encoding

Every string passed to and from the API needs to be UTF­8 encoded. For maximum compatibility, normalize to Unicode Normalization Form C (NFC) before UTF-­8 encoding.

Date Format

SchoolPay’s API’s use two date formats, we apologize in advance for the confusion, we are upgrading our standards over time!

Old Format New Format
2010­-10­-21 22:31:20 2010­-10­-22T03:31:20Z

When no time zone identifier is attached (naive, old format) the date’s time zone is America/Chicago.

Error Handling

Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON­-formatted. Error codes not listed here are in the REST API methods listed below.

Remove non-ASCII characters from JSON

SchoolPay utilizes a framework that cannot handle extended characters in JSON. While this is annoying, it is easy enough to fix by preconditioning your API. You must escape all non-ascii characters in your JSON payloads or you will receive a 500 error.

asciiJSON.escapeNonAsciis = function(text) {
  var chars, code, i;

  chars = [];
  i = 0;
  while (i < text.length) {
    code = text.charCodeAt(i);
    if (code < 128) {
    } else {
      if (code < 256) {
      } else if (code < 4096) {
      } else {
  return chars.join('');

Standard API Errors

Code Description
400 Bad input parameter. Error message should indicate which one and why.
401 Not authorized
404 File or folder not found at the specified path.
405 Request method not expected (generally should be GET or POST).
500 Server Error


function hmac_sha1(string $key, string $string) {
    $data = utf8_encode($string);
    $blocksize = 64;
    $hashfunc = 'sha1';
    if (strlen($key) > $blocksize) {
        $key = pack('H*', $hashfunc($key));
    $key = str_pad($key, $blocksize, chr(0x00));
    $ipad = str_repeat(chr(0x36), $blocksize);
    $opad = str_repeat(chr(0x5c), $blocksize);
    $hmac = pack('H*', $hashfunc(($key^$opad) . pack('H*', $hashfunc( ($key^$ipad) . $data))));
    $hexData = bin2hex($hmac);

    $raw = '';
    for ( $i = 0; $i < strlen($hexData); $i += 2) {
        $raw .= chr(hexdec(substr($hexData, $i, 2)));
    return base64_encode($raw);

Data Dictionaries

Item Object

Variable Type Req’d Description
code String Yes Identifier to look up the base item in the SchoolPay system.
amount Currency Amount Yes The amount of the item being purchased. This is a base price, and does not include fees, tax, or shipping values.
title String Yes Distinctive name to give the item.
description HTML No A description to give the item
convenience_fee Currency Amount No An additional fee to add to the price of the item.
tax Currency Amount No An additional amount to add to the price of the item described as tax.
shipping Currency Amount No An additional amount to add to the price of the item described as shipping.
chart_of_accounts_number String No The number for the associated chart of accounts account (GL ledger)
chart_of_accounts_label String No The label for the associated chart of accounts account (GL ledger)
student_id String No The ID of the student to associate with the transaction.
student_name String No The name of the student to associate with the transaction. Helpful for identifying problems with the integration.
custom_fields Object No JSON-encoded object of additional custom fields. It is of the format

Bank Account Object

The bank account information can be validated by using an object of type

Name Type Notes
routing_number string Validation
account_number string Validation

Batch Object

Name Type Notes
id string Batch identifier. Assigned by our processor after transaction deposit date.
payee int The payee of the batch.
date Date The date the batch is submitted to the processor.
payment_method ACH, CC, Cash, PhysicalCheck The payment method of the batch
total_amount amount The sum of all authorization amounts in the batch. This is the amount of the deposit in a non­split­settlement set up.
fees_amount amount The sum of all convenience fees in the batch.
partial_amount amount The total amount of the batch minus the fees amount of the batch. This is the amount of the deposit in a split­settlement set
total_count int The count of transactions in the batch.

Credit Card Object

Name Type Notes
brand Visa, MasterCard, AmericanExpress, Discover Validation
pan string Validation
expires string Validation
security_code string Validation

ErrorBody Object

Name Type Notes
error string
message string

GLAccount Object

Name Type Notes
id string Unique Identifier
label string Validation
number string Validation

GLBatch Object

Name Type Notes
gl_batch_identifier string A unique identifier for the SchoolPay GL batch​.
date Date The date of the batch.
batch_id int The batch ID for this batch which is assigned by our payment processor.
payee_id int The ID of the payee of the transactions in the batch.
gl_account GLAccount The GL account of the transactions in the batch.
amount decimal The total amount of all transactions in the batch.
amount_without_fees decimal The total amount of all transactions in the batch minus and amounts designated as “fees”.
count int The number of items sold in the batch.

PagedList of T

Name Type Notes
offset int
limit int
objects T[ ]


Name Type Notes
name string Required, length > 1
merchant_id string Required, length > 1


Name Type Notes
name string Minimum pattern of [a­zA­Z]* [a­zA­Z]* (at least two names separated by a space with minimum length 1 each)
address string Maximum length of 20, minimum length > 1
address2 string not required
email string Must be an email address
phone string Must be numeric, minimum length 10.
ip inet_addr Must be a valid ipv4 internet address
city string minimum length > 1
state string 2-­letter code. Must be in file data/states.php IFF country = USA, otherwise, optional.
postal_code string Must be numeric, minimum length 10.
country string 3-­letter code. Must be in file data/coutries.php


Name Type Notes
id int Returns the unique ID of a transaction.
order_id int Returns a unique identifier for the order that the transaction was a part of.
payer Payer
payment_method ACH, CC, Cash, PhysicalCheck Must be ACH, CC, Cash, PhysicalCheck
credit_card CreditCard required if payment_method is CC
bank_account BankAccount required if payment_method is ACH
stored_card_retrieval_token string minimum length > 1
gl_account GLAccount Do not validate.
amount decimal must be a valid formatted string between 1 and 100,000 and must contain two decimal places (4.00)
amount_refunded decimal Do not validate
convenience_fee decimal Same validation as “amount”
tax decimal Same validation as “amount”
shipping decimal Same validation as “amount”
payee int Must be a company_id in the database.
status Error / Pending / Settled / Refunded / Returned Do not validate
status_message string Do not validate
batch int Do not validate
data string Anything you want!
store_card bool If set to true, the card will be stored and a token will be returned.
stored_card_retrieval_token string This is a randomly­generated token used to look up the card used to pay for a previous transaction.
items PurchasedItem[ ] Specifies the item/receipt­level details to be associated with the transaction, visible on item­level SchoolPay reports.

Transaction Status Details

Name Type Notes
Error A technical problem prevented us from processing this payment.
Pending The processor approved the transaction and it will settle at midnight.
Settled Money has moved from payer to payee for this transaction.
Voided The authorization was canceled. It will not settle. Can only happen when transaction is pending
Refunded Money has been moved from payee to payer for this transaction. can only happen after funds settle.
Returned The check was returned by the bank, much like with paper currency.
Unknown The payment processor sent an unclear response or timed out, and we cannot determine the status of this transaction at this time. It may have
Declined The payment was declined by the issuer


Name Type Notes
id int Unique identifier for the item change.
item_id int
user_id int Anything you want!
date date
undoes int


Name Type Notes
id int Unique identifier for the item.
company_id int The owner/controller of the item.
payee_id int The payee who would take payment for the item.
is_valid bool Whether or not this item is valid.
title string The tile of the item
description string Requires the “description” expansion This is an HTML­compatible field that allows the description of an item to be input.
item_type string The item type of the item. Valid values are Simple, Recurring, Food Service, and Multi.
sold_count int The number of payments made against this item minus the number of reversals made against this item.
created_on date The time at which the item was created.
updated_on date The last time a field on this item was changed, with the exception of sold_count.
active_state enum The state of the general availability of the item. Options are yes, no, yes_between_dates
is_parent_center bool Determines if an item should be visible to parents using the parent center software.
can_be_purcahsed bool Determines if an item can be purchased. It is a combination of active_state, active_before, active_after, and the current time.
active_after date
active_before date
category int Category
gl_account int GL Account
recurring Recurring Holds details pertaining to the recurring nature of this item.
multi Multi Requires the “multi” expansion Holds details pertaining to the multi­item nature of this item.
amounts Amounts Holds details pertaining to the amounts of this item.


Name Type Notes
number string Holds the district­unique student number.
district_id int
name string The student’s name.


Name Type Notes
id string A unique identifier for the purchasd item.
item_name string The name of the item purchased.
amount decimal The amount of the item purchased.
gl_account GLAccount The GL account associated with the item purchased.
student Student The student associated with the item purchased.
custom_fields Map Returns a key/value map of the “custom fields” purchased with this item.
Go Live