PSOnline supports an API for adding orders, billing their initial payment, and fulfilling them in realtime. Originally designed to connect to a WooCommerce-based shopping cart system on WordPress, it can be used by any client that desires to integrate its functionality into their own processes.

Endpoint URL

https://app.periodicalservices.com/api/woocommerce/v1.4/process.asp

Please note, the version number in the URL may change to support newer features, but older versions will be kept for backwards compatibility.

Request

Please submit standard name=value pairs via the POST HTTP method.

The following fields are required:

domain= The domain of the site you are submitting from

APIKey= Provided by PSOnline

MerchantID= Provided by PSOnline (v1.2 onward, specify "0" to have the system use standard MID weights if the client's system supports it)

buildorder= 0 or 1, indicating whether or not to build the order in PSOnline. Set to 0 to skip order entry and fulfillment, and only preauth the customer's card.

capture_delay= 0 or a positive integer, indicating how many days to wait to capture the payment. Providing a value of 0 will run the payment as a sale instead of a split auth/capture. Providing any other value will place the order into Waiting To IP status, awaiting an IP capture.

card_num= The customer's 15 or 16 digit credit card number

card_expm= The card's expiration month, in MM format

card_expy= The card's expiration year, in YYYY format

card_cvv= The card's 3 or 4 digit verification code

CustomerFirstName= Customer's first name

CustomerLastName= Customer's last name

BillingStreetAddress= Billing address field 1

BillingApt= Billing address field 2

BillingCity= Billing address city

BillingState= Billing address state

BillingZipCode= Billing address postal code

Email=Customer's email address

BillingHomePhone= Customer's preferred 10-digit phone number

amount= The total to bill the customer today

ProductCount= The number of line items on the order (see below)

The following fields are for the products or services purchased. In the below field names, “X” indicates an integer representing the number of the line item, starting with 1, and ending with the ProductCount you provided above:

productid_X= The unique identifier for this service in your system (In WooCommerce, this corresponds to the post ID of the product). Must be provided to PSOnline support prior to going live, as this is how we map it to the service in PSOnline.

productsku_X= The SKU of the product. Can be used instead of productid_X, but is required if this is a one-time purchase product.

productvariationid_X= Optional. If you have no variation of your product, leave this blank

productqty_X= Quantity of this product purchased in the customer's cart

producttype_X= Optional. In WooCommerce, this corresponds to "simple", "variable", etc.

productnextbilldate_X= Optional. Use if you want to override when the next bill date for the PSOnline order will be on a case-by-case basis.

Finally, the API supports additional fees/add-ons. Use this to create order notes in PSOnline for whatever you wish (for example, if you offer a free t-shirt with purchase, this is how you would provide a note with the shirt size).

feename_X= A name for the fee/add=on (i.e. "T-Shirt Size")

feeamount_X= The amount you wish to charge. This should already be included in the "amount" field you provide above. PSOnline will not bill this fee otherwise.

feevalue_X= The value of the option the customer selected (i.e. "XXL" for a t-shirt size)

The following fields are optional:

bincheck= Set to 1 to check the customer's card number against your internal list of rejected BINs prior to attempting to authorize the card. If found, a ResponseCode of code 401 will be returned, and execution will stop.

skippayment= Set to 1 to bypass the payment authorization, and jump to the order entry part of the pipeline

skipfulfillment= Set to 1 to prevent realtime fulfillment

DOB= Customer's date of birth

KeyCode= If provided, the API will check to see if the key code provided is valid in the PSOnline system, and override the key code of the order with the one provided if so. If the key code is not valid, it will be silently ignored.

Gender= M or F

FormOfPayment= "card" or "check". Defaults to "card" if not provided

BankAccountNumber= Customer's bank account number, used when formofpayment=check

BankRoutingNumber= Customer's bank routing number, used when formofpayment=check

PaidAmount= Amount that the customer has paid prior to the API call. Will create a transaction in PSOnline as the initial payment. Currently only supported when formofpayment=check

Response

Responses are provided in JSON format.

A successful response will look like this:

{
"ResponseCode": 200,
"ResponseData": "",
"AuthResult": 1,
"OrderResult": 1,
"FulfillmentResult": 1,
"FulfillmentCode": "",
"Warnings": []
}

A ResponseCode of 200 indicates success.

A ResponseCode of 400 indicates an error with the input. 400 errors are typically safe to show the customer.

A ResponseCode between 401 and 499 indicates an error with the input, but might not be something you want to show the customer (i.e. their card is on your rejected BIN list)

A ResponseCode of 500 indicates a server-side error of some kind.

For all non-200 ResponseCodes, ResponseData will contain the error message.

AuthResult indicates whether or not the card approved.

OrderResult indicates whether or not the order was entered into PSOnline successfully.

FulfillmentResult indicates whether or not the order was fulfilled to the provider successfully. If so, and if the fulfillment house supports it, FulfillmentCode will contain the unique identifier that the customer will need to use to sign up for their service.

Any warnings that did not interfere with order creation but may cause an unexpected result are noted in the Warnings array.

Other Notes

This API will process in a pipeline, starting with obtaining payment from the customer’s card. If it succeeds, it will then enter the order into PSOnline. If order entry succeeds, it will then attempt to fulfill. If any step fails, the subsequent steps will not be attempted.

All date fields are expected in MM/DD/YYYY format.

Change Log

Version 1.8

Added support for passing phone number and address to payment gateways

Version 1.7

Added in-process duplicate order check

Version 1.6

Added AuthorizationLog support for additional reporting

Version 1.5

Added support for checks as form of payment

Version 1.4

Added support for capture_delay.

Version 1.3

Added support for productsku_X.

Added support for multiple one-time purchase products to be grouped under a single order.

Added support for:

Gateways

  • BeanStream

Version 1.2

Added support for MID weight logic by passing 0 for MerchantID if supported by client system.

Added Warnings array in output.

Improved error handling.

Version 1.1

Added support for BIN suppression list checks.

Added support for KeyCode and Gender parameter.

Added support for sending confirmation emails.

Added support for productnextbilldate_X parameters.

Split 400-range ResponseCode values into safe-to-display and unsafe-to-display values.

Version 1.0

Initial release

Added support for:

Gateways

  • Authorize.Net
  • MultiPASS (TSYS)
  • Network Merchants (NMI)
  • SurePay (ePayData)

Fulfillment Houses

  • PrivacyMAXX
  • EMI Files