Welcome to 8-Track docs

REST API

Request Details

Request Content Type

Please use text; charset=utf-8

Auth

Auth is handled as part of the request payload, so payload is required for all requests, even ones that don't typically require it like GET or DELETE requests.

8-track uses the itssafe Python module for request unsigning. It can also be used for signing, but though it is quite simple to use, currently there are no docs, so talk to us at Mirus for instructions. For non Python environments, I will try to reverse engineer them and spell it out below in a way that one can follow the signing steps to use for a client program in most any language.

  • add a header named Auth8t with the username that we provide you with.
  • Pass time-signed json data in all requests. For requests that require no data, please use a time-signed empty json string - {}. How to time-sign json:
    • timestamp = base64 encoded seconds since 2011-01-01 (1293840000); UTC time.
    • timed_value = "{}." + timestamp
    • signature = HMAC-SHA1 encryption (with secret key that Mirus supplies) of timed_value
    • properly signed payload = "{}." + timestamp + "." + signature

Request Body Example

{
    'currency': 'US',
    'agent_state_code': '99',
    ...
}.<timestamp>.<signature>

See auth docs above for <timestamp>.<signature>

Add a payment request

POST to https://eighttrack.mirusresearch.com/paymentrequests/

Note: Currently, can only add one Payment Request at a time.

Payment Request ID in response: The response from the add will include an id property which is 8-Track's id of the payment request. We recommend that your system saves that value as it will be necessary for future edits or other potential references.

Fields

Date Format

YYYY-MM-DD, Timezone naive.

Order Id and Order Row Id

Here is what 8-Track assumes about orders and order rows: For every order that a customer makes, that order is a unique thing and should have it's own order_id. An order can have multiple line items. eg. Customer orders 2 different items (kinds of signs maybe). Each item on the order (combined with the quantity of that item) would also be a unique thing, and should have it's own unique order_row_id. The order_row_id must be absolutely unique within your organization, and not just unique within the order.

unit_price

Pretty straightforward, however in the case of subsidies it will be sub_total / quantity truncated to the penny.

Eg.:

  • sub_total = 1000.00
  • quantity = 6
  • unit_price = 166.66

sub_total Calculation

Generally unit_price * quantity

However, for the case of subsidies: product total - subsidy_amount

agent_total Calculation

sub_total + all costs (shipping_cost, installation_cost, setup_cost, rush_cost, customization_cost)

Agent Sign Program

Use item_type = 10002 or item_type = 10004 for payment requests that are part of the Agent Sign Program (ASP).

All ASP fields (asp_bill_to_dept_code, subsidy_amount, subsidy_service_charge, subsidy_shipping_cost, subsidy_installation_cost) should have values when item_type = 10004 or item_type = 10004. Zero (0.00) values are valid on amount fields.

Edit a payment request

PUT to https://eighttrack.mirusresearch.com/paymentrequest/<payment_request_id>/

The <payment_request_id> is the value from the id property that is in the response from the add request. See the note about that in the add request doc.

see Fields from add

Editing a payment request after the monthly batch

After the payment requests are sent for processing on the 28th of the month (batched), all edits will be locked out. However, there is a period where it is possible to edit them with some manual steps.

Here are those steps:

  • Notify your contact at the payment source and include the 8-Track IDs of the payment requests that need to be edited
  • Mirus will open those payment requests up for editing, and let the user know when they're ready
  • The user can edit the payment requests
  • The user notifies Mirus when they're done editing
  • Mirus re-runs the batch

Delete a payment request

DELETE to https://eighttrack.mirusresearch.com/paymentrequest/<payment_request_id>/

Deletes can only be done on payment requests that have not yet been sent for batch.

Add a Refund Request

POST to https://eighttrack.mirusresearch.com/refunds/

Refund Requests can be sent after a payment request has been sent to batch, which is on the 28th of every month. If the Payment Request has not yet been sent for batch then it needs to be edited, deleted, or use the Refund Helper.

Fields

  • payment_request - The id of the payment request to refund
  • is_full_refund - Boolean type - must be true for subsidy payment requests.
  • amount - The amount to refund. Only valid if is_full_refund is non-existing or false

Note on 3/13/18 about refunds on subsidy payment requests

Refunds are not yet available in the production system for subsidy payment requests, but will be available when downstream systems are ready to receive them.

Edit a Refund Request

PUT to https://eighttrack.mirusresearch.com/refund/<refund_request_id>/

Fields

see Fields from add

Refund Helper

As of September 20, 2017

POST to https://eighttrack.mirusresearch.com/refund-helper/<payment_request_id>/

The Refund Helper is meant for basic refund scenarios. It can be used whether or not a payment request has been sent for batch (28th each month) or not.

If the payment request has been sent for batch, then it will create the refund request. This is the simplest scenario.

The complexity lies in the case of reducing amounts of payment request that have not been sent for batch. In this case, the helper will subtract the amount given from the product amounts (sub_total, agent_total, and unit_price = new sub_total / quantity). There are scenarios where the Refund Helper will not work if the payment request has not been batched. Here they are:

  • Any ASP (Department Subsidies) on the payment request
  • amount cannot equal agent_total. In this case the client must delete the payment request.
  • The newly calculated unit_price cannot have more than 2 decimal places

Fields

  • amount - The amount to refund (subtracted from product total) - should be positive decimal value with a max of 2 decimal places