Login  |  Help      
    Tuesday, December 11, 2018 9:55:53 pm MST

Secure Instant Payments (SIP) Shopping Cart Interface


API Version 2.5; Updated: 20-Jul-2018

Table of Contents



Payment Tokens

Payment tokens store card or bank information in a PCI compliant vault and can be used when processing payments using the Single Payment or Recurring Payment methods described below. This interface is used for programmatically creating these tokens. This token interface is accessed in SIP via the following URL:

All parameters are passed in POST form format with the following fields:

Merchant Information: Required
Merchant_ID Provided by SIP.
Merchant_Code Authentication provided by SIP

Credit or Bank Information: One set (card or bank) required.
Card_Name Name shown on credit or debit card
Card_Number Credit or debit card number - 13 to 16 digits with or without spaces
Card_ExpMonth 2 digits
Card_ExpYear 4 digits
Card_Street Street portion on card billing address
Card_ZIP Postal code on card billing address
Card_CVV 3 or 4 digits (used for verification but not stored)
   
Bank_AccountType 1 letter (C)hecking, (S)avings, (B)usiness checking; default: Checking
Bank_AccountName Name shown on bank account
Bank_Routing 9 digits (US banking institutions only)
Bank_Account 22 digits (may have leading zeros)

The response (success or failure) is passed back via simple comma-delimited text where the first line is:
Token,Success,Token
- Any following lines contain extra information
or
Token,Failure,
- Any following lines enumerate reasons for failure

On success, the Token returned is the unique payment token stored within the SIP system that represents the payment information provided and is available for use. In the case of card tokens, the CVV number provided is only used for verification but is not stored in the token. If the billing street address or the postal code (zip) code change a new token will need to be created for the card.


Payment Tokens from JS

Payment tokens store card or bank information in a PCI compliant vault and can be used when processing payments using the Single Payment method described below. These tokens are only valid for one payment and expire after 15 min. This interface is used for programmatically creating these tokens. This will allow you to take payments on your own site without ever seeing a credit card or bank account number if you send us the information directly via JS. This token interface is accessed in SIP via the following URL:

All parameters are passed in POST form format with the following fields:

Merchant Information: Required
APILoginKey Authentication provided by SIP that can be published in the JS

Credit or Bank Information: One set (card or bank) required.
Card_Name Name shown on credit or debit card
Card_Number Credit or debit card number - 13 to 16 digits with or without spaces
Card_ExpMonth 2 digits
Card_ExpYear 4 digits
Card_Street Street portion on card billing address
Card_ZIP Postal code on card billing address
Card_CVV 3 or 4 digits (used for verification but not stored)
   
Bank_AccountType 1 letter (C)hecking, (S)avings, (B)usiness checking; default: Checking
Bank_AccountName Name shown on bank account
Bank_Routing 9 digits (US banking institutions only)
Bank_Account 22 digits (may have leading zeros)

The response (success or failure) is passed back via simple comma-delimited text where the first line is: (CardType will be either 'F' for 'D' denoting a foreign, outsite USA, or domestic card and will not be returned for bank accounts.
Token,Success,Token,CardType
- Any following lines contain extra information
or
Token,Failure,
- Any following lines enumerate reasons for failure

On success, the Token returned is the unique payment token stored within the SIP system that represents the payment information provided and is available for use. In the case of card tokens, the CVV number provided is only used for verification but is not stored in the token. If the billing street address or the postal code (zip) code change a new token will need to be created for the card.


Sending Payments

To submit a single payment, debit or credit, or a refund use this interface. This interface is suited for programmatically entering payments from other web sites or programs. It is not optimal for processing very large numbers of payments. To process large batches, use the Mixed Record Import Interface. This single payment interface is accessed in SIP via the following URL:

The shopping cart application passes all data in via a POST form with the following fields:

Transaction Information: Required (except as specified)

Transaction_Type

For most transactions the following options suffice: "Debit", "Credit", "Refund", "PreAuth", "Capture", or "Test" (default: "Test").
Test transactions, despite possibly claiming success, do not get entered and do not process.
Refunds reverse the specified transaction to the same account as originally charged.
PreAuth transactions are only valid for the current day and, if not Captured, are deleted.

Two other transaction options, "DebitTransfer" and "CreditTransfer", allow for transferring funds from one merchant to another and should be entered as a pair, the debit to one merchant and the credit to the other. These transfer type payments will not be settled by SIP because it is assumed that the pair settle with each other.

Also, "ExternalDebit", "ExternalCredit", "ExternalDebitTransfer", and "ExternalCreditTransfer" provide a means of logging journal entries that will not actually be transacted. These are assumed to have been transacted externally.

Transaction_Amount Numeric dollar.cents amount (numeric characters and decimal point only).
For Refunds, cannot be greater than the amount in the existing payment
For Captures, cannot be greater than the amount in the pre-authorized payment
Transaction_Fee (optional) Numeric dollar.cents amount (numeric characters and decimal point only).

For Payments, Transaction_Fee is compared to the actual transaction fee and the payment will be rejected with error code E35 if the values do not match.
For Refunds, Transaction_Fee cannot be greater than the fee in the existing payment
For Captures, Transaction_Fee cannot be greater than the fee in the pre-authorized payment
Transaction_ID For new transactions: ID of transaction in merchant database (max. 50 characters)
For Refunds: the 18 character Payment_ID of the existing payment
For Captures: the 18 character Payment_ID of the original pre-authorized payment
Transaction_Category (optional) up to 50 characters, default "ShoppingCart"
Transaction_Memo (optional) up to 100 characters, default blank
Transaction_Date (optional) YYYY-MM-DD default today.
Transaction_MetaData (optional) JSON object or JSON encoded array with key value pairs that can be used in reporting

Merchant Information: Required
Merchant_ID
Provided by SIP.
Merchant_Code
Authentication provided by SIP

Credit or Bank Information: One set (token, card or bank) required for payments. Ignored on refunds.
Token Token representing credit/debit card or bank account previously defined as described above (Note: CVV values are not stored in tokens and therefore cannot be used in Merchant accounts that require the CVV for payments unless the CreditCard_CVV is passed along with the token)
   
CreditCard_Name Name shown on credit or debit card
CreditCard_Number credit or debit card number - 13 to 16 digits with or without spaces
CreditCard_ExpYear 4 digits
CreditCard_ExpMonth 2 digits
CreditCard_CVV 3 or 4 digits (may be passed with a Token if required)
CreditCard_Street Street portion on card billing address
CreditCard_ZIP Postal code on card billing address
   
Bank_AccountName Name shown on bank account
Bank_Routing 9 digits (US banking institutions only)
Bank_Account 22 digits (may have leading zeros)
Bank_AccountType 1 letter (C)hecking, (S)avings, (B)usiness checking; default: Checking

Customer Information: Optional
Customer_AID Existing customer AID
(Used to associated payment with existing user account)
Customer_Account New or existing customer account number
(required if this payment needs to be associated with other payments)
Customer_ID New or existing customer ID. May be left blank
Used to associate multiple accounts with a given customer
Customer_FirstName (optional) can also put full name in Customer_LastName field
Customer_LastName Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_OrgName (optional) Customer organization name
If Customer_LastName is not defined, this will replace the Customer_LastName and Customer_FirstName will be ignored
Customer_Address1 Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_Address2 (optional)
Customer_City Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_State (optional) 2 letter standard abbreviation
Customer_Zip (optional) 5 digits
Customer_Country (optional) - Default to "USA"
Customer_Phone (optional) 10 digits with or without "()" and dashes
Customer_Email (optional)
Customer_IPAddress (optional) IP address from which user is submitting payment
(defaults to address of server that initiated the transaction)

The response (success or failure) is passed back via simple comma-delimited text where the first line is:
Transaction_Type,Success,Transaction_ID,Transaction_Amount,Fee_Amount,Payment_ID,Token
- Any following lines contain extra information about the transaction
or
Transaction_Type,Failure,Transaction_ID,Transaction_Amount,0.00,0,
- Any following lines enumerate reasons for failure

The Payment_ID returned is the identifier within the SIP system which is 18 characters in length.


Recurring Payments

To create a recurring payment plan use this interface. To submit credits or refunds you must use the single payment interface defined above. This interface is accessed in SIP via the following URL:

The shopping cart application passes all data in via a POST form with the following fields:

Transaction Information: Required (except as specified)

Recursion_Type

Only debit transactions can be scheduled via this interface. This field defines the type of recurring payment. The available types include:

  • "Weekly" - payment processed each week starting on Start_Date.
  • "MonthlyDay" - (default) payment processed each month on a specific calendar day of the month starting on and defined by Start_Date. Payments scheduled for the 29th, 30th, or 31st will process on the last day of the month in months with less days than specified.
  • "MonthlyWeekday"- payment processed each month on the specified weekday of the month beginning with and defined by Start_Date. Start_Date must fall within the first 4 weeks of the month.
  • "Quarterly"- payment processed each quarter with a given Start_Date.
  • "Annually"- payment processed each year with a given Start_Date.
Start_Date The date on which to process the first payment in YYYY-MM-DD format. The actual processing days for ACH (e-check) payments may vary slightly due to holidays and weekends.
Payment_Count This field defines the number of payments to be processed according to the timetable defined by the Recursion_Type. The default value of 0 defines no end-date and the processing of payments will continue until the scheduled payment is canceled. Other positive integers define the actual number of payments to be processed counting the next one which is defined to be processed on the Start_Date.
Transaction_Amount Numeric dollar.cents amount (numeric characters and decimal point only)
Transaction_Fee Numeric dollar.cents amount (numeric characters and decimal point only) to be added (default: 0.00).
Transaction_ID (future) ID of transaction in merchant database (max. 50 characters)
Transaction_Category (optional) up to 50 characters, default "ShoppingCart"
Transaction_Memo (optional) up to 100 characters, default blank
Transaction_MetaData (optional) JSON object or JSON encoded array with key value pairs that can be used in reporting

Merchant Information: Required
Merchant_ID
Provided by SIP
Merchant_Code
Authentication provided by SIP

Credit or Bank Information: One set (token, card or bank) required
Token Token representing credit/debit card or bank account previously defined as described above (Note: CVV values are not stored in tokens and therefore cannot be used in Merchant accounts that require the CVV for payments unless the CreditCard_CVV is passed along with the token)
   
CreditCard_Name Name shown on card
CreditCard_Number 13 to 16 digits with or without spaces
CreditCard_ExpYear 4 digits
CreditCard_ExpMonth 2 digits
CreditCard_CVV 3 or 4 digits (may be passed with a Token if required)
CreditCard_Street Street portion on card billing address
CreditCard_ZIP Postal code on card billing address
   
Bank_AccountName Name shown on bank account
Bank_Routing 9 digits (US banking institutions only)
Bank_Account 22 digits (may have leading zeros)
Bank_AccountType 1 letter (C)hecking, (S)avings, (B)usiness checking; default: Checking.

Customer Information: Required
Customer_Account (required) New or existing customer account number
Customer_ID New or existing customer ID. May be left blank
Used to associate multiple accounts with a given customer
Customer_FirstName Can also put full name in Customer_LastName field.
Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_LastName Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_OrgName (optional) Customer organization name
If Customer_LastName is not defined, this will replace the Customer_LastName and Customer_FirstName will be ignored
Customer_Address1 Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_Address2 (optional)
Customer_City Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_State 2 letter standard abbreviation
Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_Zip 5 digits
Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_Country (optional) - Default to "USA"
Customer_Phone 10 digits with or without "()" and dashes
Required with new Customer_ID or new Customer_Account with blank Customer_ID
Customer_Email (optional)
Customer_IPAddress (optional) IP address from which user is submitting payment
(defaults to address of server that initiated the transaction)

The response (success or failure) is passed back via simple comma-delimited text where the first line is:
Recursion_Type,Success,Transaction_ID,Transaction_Amount,Fee_Amount,PaymentPlan_ID
- Any following lines contain extra information about the payment plan
or
Recursion_Type,Failure,Transaction_ID,Transaction_Amount,0.00
- Any following lines enumerate reasons for failure

The PaymentPlan_ID returned is the identifier within the SIP system which is an integer greater than zero.


To delete an existing recurring payment plan, use the following three parameters:

Transaction Information: Required

PaymentPlan_ID

Existing payment plan ID as returned from the creation call above


Merchant Information: Required
Merchant_ID
Provided by SIP
Merchant_Code
Authentication provided by SIP

The response (success or failure) is passed back via simple comma-delimited text where the first line is:

Delete,Success,PaymentPlan_ID
- Any following lines contain extra information about the action
or
Delete,Failure,PaymentPlan_ID
- Any following lines enumerate reasons for failure


AIM Interface Emulation


A subset of the Authorize.net Advanced Integration Method (AIM) is emulated via this interface. See the Authorize.net specifications for details of this interface. The emulator is limited to x_versions 3.0 and 3.1 and only the AUTH_CAPTURE, CREDIT, and VOID x_types are currently supported. The following URL provides for sending payments via this emulated interface:

The shopping cart application passes the transaction data via a POST form request with the following fields:

Authentication x_login Merchant_ID provided by SIP
x_tran_key Merchant_Code authentication provided by SIP
Miscellaneous x_allow_partial_Auth Not supported
x_delim_char Default comma
x_encap_char Default double quote
Transaction Information x_version 3.0 (default) or 3.1
x_relay_response Default 'N'
x_type AUTH_CAPTURE (default), CREDIT, or VOID, AUTH_ONLY, PRIOR_AUTH_CAPTURE
x_method ECHECK or CC (default)
x_recurring_billing not supported
x_amount Transaction amount as positive dollars and cents
x_trans_id Transaction ID
This specifies the merchants' ID for the payment for x_type=AUTH_CAPTURE and AUTH_ONLY
but is required to refund payments when the x_type is set to CREDIT, VOID, or PRIOR_AUTH_CAPTURE)
x_split_tender_id ignored
x_auth_code ignored
x_test_request Y or N (default)
x_duplicate_window ignored
Card Information x_card_num Credit card number
x_exp_date Credit card expiration date (MMYY)
x_card_code Credit card CVV code
Bank Information x_bank_aba_code Bank routing number (9 digits)
x_bank_acct_num Bank account number
x_bank_acct_type Checking, Savings, or Business Checking
x_bank_name ignored
x_bank_acct_name Name on bank account
x_echeck_type Default 'WEB'
x_bank_check_number ignored
Order Information x_invoice_num Alternate transaction ID
x_description Transaction Memo
x_line_item ignored
Customer x_first_name Customer name
x_last_name Customer name
x_company ignored
x_address Customer address
x_city Customer address
x_state Customer address
x_zip Customer address
x_country Default USA
x_phone Customer contact information
x_fax ignored
x_email Customer contact information
x_cust_id Used as both Customer_ID and Customer_Account
x_customer_ip Customer IP address
Shipping x_ship_to_first_name Not supported at this time
x_ship_to_last_name Not supported at this time
x_ship_to_company Not supported at this time
x_ship_to_address Not supported at this time
x_ship_to_city Not supported at this time
x_ship_to_state Not supported at this time
x_ship_to_zip Not supported at this time
x_ship_to_country Not supported at this time
x_tax ignored
x_freight ignored
x_duty ignored
x_tax_exempt ignored
x_po_num ignored
Miscellaneous x_authentication_indicator not supported
x_cardholder_authentication_value not supported

The emulator interface replies to transaction requests as dictated by the 3.0 or 3.1 AIM Interface Specifications using the x_delim_char and x_encap_char to build the text response string.


Reporting Processed Payments

This report produces a report containing the executed transactions in a given date range. This report will not show any scheduled recurring payments or scheduled future single payments.

The following URL provides payments report:

The shopping cart application passes all data in via a POST form request with the following fields:

Merchant Information: Required
Merchant_ID
Provided by SIP
Merchant_Code
Authentication provided by SIP
StartDate m/d/yyyy of date to start (default to 1/1/2006)
EndDate m/d/yyyy of date to end (default to current day)
Customer_Account Optional limiter
Customer_ID Optional limiter
Payment_ID Optional limiter (date range is ignored)
Transaction_Category Optional limiter
Memo Optional flag for additional output column with simple memo string
Event Optional flag for additional output columns in the form of quoted "field name"="value" pairs
Status Optional flag for filtering output based on values in Status field, ie Status=Settled

The response is passed back via simple tab-delimited text with two header records followed by detail records all between HTML <pre> tags:
  Without Memo or Event flags set With Memo and Event flags set
Header Record 1 # Transactions # Transactions
Header Record 2
(tab-separated)
Merchant_ID
Customer_Account
Transaction_ID
Payment_ID
TransactionDate
Name
Type
Amount
Fee
Total
ProcessingDate
Transaction_Category
ReturnCode
ReturnReason
CorrectionInfo
Status
Customer_ID
SettlementDate
ReturnDate
Merchant_ID
Customer_Account
Transaction_ID
Payment_ID
TransactionDate
Name
Type
Amount
Fee
Total
ProcessingDate
Transaction_Category
ReturnCode
ReturnReason\
CorrectionInfo
Status\t
Customer_ID
SettlementDate
ReturnDate
Memo
EventDetail...
Detail Records
... ...

The Status field contains one of these strings:

  • Pending
  • Processed
  • Settled
  • Returned
  • Returned (Resubmitted)
  • Returned (Duplicated)
  • Returned (Voided)
  • Reversal

Reporting All Payment Activity

This report produces a report containing all the transaction activity (Transaction entered, processed, settled, returned or corrected) in a given date range.

The following URL provides payments report:

The shopping cart application passes all data in via a POST form request with the following fields:

Merchant Information: Required
Merchant_ID
Provided by SIP
Merchant_Code
Authentication provided by SIP
StartDate m/d/yyyy [hh:mm:ss] of date to start (default to previous banking day). If time included use literal time range.
EndDate m/d/yyyy [hh:mm:ss] of date to end (default to StartDate). If time included use literal time range.
Customer_Account Optional limiter. The wildcard character, '%', can be used to request a range of values.
Customer_ID Optional limiter. The wildcard character, '%', can be used to request a range of values.
Payment_ID Optional limiter (date range is ignored). This is the ID the payment was given in the Instant Payments system. The wildcard character, '%', can be used to request a range of values.
Transaction_ID Optional limiter (date range is ignored). This is the ID given to the payment when originally submitted for processing. The wildcard character, '%', can be used to request a range of values.
Transaction_Category Optional limiter. The wildcard character, '%', can be used to request a range of values.
Ignore_Settlement Optional flag to ignore settlement dates in date range (default not set)
Display Optional flag used to visualize the data in HTML (default not set)
Include_Payout_PID Optional flag used to add the Payout PID to the return values

The response when Display is set is an HTML page with the data in an HTML table. When Display is not set, the data is passed back as simple tab-delimited text with two header records followed by detail records all between HTML <pre> tags:
With Include_Payout_PID set to 0 or default With Include_Payout_PID set to 1
Header Record 1 # Transactions # Transactions
Header Record 2
(tab-separated)
Merchant_ID
Customer_Account
Customer_ID
Transaction_ID
Category
Payment_ID
Status
TransactionDate
ProcessingDate
SettlementDate
ReturnDate
ReturnCode
ReturnReason
CorrectionDate
CorrectionCode
CorrectionAddenda
Amount
Fee
Merchant_ID
Customer_Account
Customer_ID
Transaction_ID
Category
Payment_ID
Status
TransactionDate
ProcessingDate
SettlementDate
ReturnDate
ReturnCode
ReturnReason
CorrectionDate
CorrectionCode
CorrectionAddenda
Amount
Fee
PayoutPID
Detail Records
... ...

The Status field contains one of these strings:

  • Pending
  • Processed
  • Settled
  • Returned
  • Returned (Resubmitted)
  • Returned (Duplicated)
  • Returned (Voided)

Reporting Returns

To list all returns for a given period of time use this report.

The following URL provides returns report:

The shopping cart application passes all data in via a POST form request with the following fields:

Merchant Information: Required
Merchant_ID Provided by SIP
Merchant_Code Authentication provided by SIP
ReportType 'T' by Transaction Date, 'R' by ReturnDate, 'C' Corrections (default 'R')
Category Category limit search
StartDate m/d/yyyy of date to start (default to 1/1/2006)
EndDate m/d/yyyy of date to end (default to current day)

The response is passed back via simple comma-delimited text with two header records followed by detail records all between HTML <pre> tags:
Header Record 1 # Returned Transactions
Header Record 2
by Return Date
Merchant_ID,Payment_ID,Transaction_ID,ReturnDate,ReturnCode,Correction,Reason,Category,Customer_Account
Header Record 2
by Transaction Date
or Corrections
Merchant_ID,Payment_ID,Transaction_ID,TransactionDate,ReturnCode,Correction,Reason,Category,Customer_Account
Detail Records ...


Reporting Payment Plans

To list scheduled payment plans and future single payments use this report.

The following URL provides payments report:

The shopping cart application passes all data in via a POST form request with the following fields:

Merchant Information: Required
Merchant_ID Provided by SIP
Merchant_Code Authentication provided by SIP
Customer_Account Optional limiter
Customer_ID Optional limiter
Transaction_ID Optional limiter (future)
PaymentPlan_ID Optional limiter
Transaction_Category Optional limiter
Memo Optional flag for additional output column with simple memo string
Status Optional flag for filtering output based on values in Status field, ie Status=Expired

The response is passed back via simple tab-delimited text with two header records followed by detail records all between HTML <pre> tags:
  Without Memo flag set With Memo flag set
Header Record 1 # Transactions # Transactions
Header Record 2
Merchant_ID\t
Customer_Account\t
Customer_ID\t
Transaction_ID\t
Transaction_Category\t
PaymentPlan_ID\t
Name\t
Type\t
Amount\t
Fee\t
Total\t
Period\t
PeriodDay1\t
PeriodDay2\t
Number\t
BillPayFlag\t
NextProcessingDate\t
Status\t

Merchant_ID\t
Customer_Account\t
Customer_ID\t
Transaction_ID\t
Transaction_Category\t
PaymentPlan_ID\t
Name\t
Type\t
Amount\t
Fee\t
Total\t
Period\t
PeriodDay1\t
PeriodDay2\t
Number\t
BillPayFlag\t
NextProcessingDate\t
Status\t
Memo

Detail Records
... ...

The type of scheduled payment is defined by the Period, PeriodDay1, PeriodDay2, Number, and BillPayFlag fields as follows:

  • Period - defines the frequency of the given scheduled transaction.
    • 1 - Process a one time payment
    • W - Process a payment for each week
    • B - Process a payment for every other week
    • S - Process a payment for two times each month
    • M - Process a monthly payment on a specific day of the month
    • N - Process a monthly payment on a specific weekday of the month
    • 2 - Process a payment for every other month
    • 4 - Process a payment to be paid each 4 weeks
    • 8 - Process a payment to be paid each 8 weeks
    • Q - Process a payment to be paid each three months
    • 6 - Process a payment to be paid each six months
    • A - Process a payment to be repeated each year
  • PeriodDay1 - defines the day of the month for some payment types that occur during a month.
  • PeriodDay1 - defines the day of the month for bi-monthly payment type.
  • Number - defines the number of remaining payments with 0 signifying "until canceled".
  • BillPayFlag - "BillPay" for payments defined by bill import, "Fixed" for all other payments.

The Status field contains one of these strings:

  • Normal
  • Expired - credit card has expired
  • Suspended - user account is suspended

Simple Payment

The Simple Payment (SimplePay) page is used to have the shopping cart interface request a user to make a payment. This allows your web site to determine what amount is due and have SIP ask the user for his contact and payment information and make the payment. After the user has done this, control passes back to your site with a confirmation number or reason for failure.

A shopping cart interface to submit payments or refunds for processing by SIP is provided in the following URL:

You can customize this interface with your graphics to make it look just like your own site. You can also pass in as much of the user's contact information as you already have and the form will be pre-filled in with this data. This eliminates the frustration of having your customer re-enter duplicate contact information.

The SimplePay page receives all data via a POST form request with the following fields in any order. Those marked 'Required' must be specified. All others are optional and the SimplePay page will prompt the user for them, as needed.

Merchant_ID Required Provided by SIP
Title   Text to place at top of registration form (default: "<Merchant> Registration Form").
SubTitle   Text to place below the Title.
Description   Description of payment amount. Default blank.
Amount   Positive numeric dollars.cents amount (no dollar sign) (default blank).
AmountLock   If set to any value, makes Amount not editable.
AmountMin   If greater than 0.00, limits Amount to this minimum value.
AmountMax   If greater than 0.00, limits Amount to this maximum value (Overrides AmountMin).
Memo   Notation to be included with payment.
Category   Category to identify transaction type (if set to "MerchantCategories", Category will be set to the first element in the merchant category array) (If neither Category or Categories is set and the merchant has no categories defined internally, then Category will default to "Registration")
Categories   List of categories separated by commas (set to "MerchantCategories" to include list of pre-defined categories) (if both Category and Categories are not set, defaults to "MerchantCategories")
Transaction_ID   Unique number to identify this registration (can be left blank and one will be assigned)
"TestGood" will perform a test good transaction, "TestBad" will perform a test failing transaction.
Return_Page Required Full https or http URL of page to send results (shown below) to prior to receipt page being displayed. The purpose of this page is to receive and act on the results and the output of this page is not displayed. It is called whenever the transaction is successful.
Return_Success   Defaults to Return_Page; Full https or http URL of page to jump to following receipt page (Warning: this page will never be invoked if the user does not choose to click 'OK' on the receipt page). This may also be set to 'none' to eliminate the 'OK' button option from the receipt page.
Return_Fail   Defaults to Return_Page; Full https or http URL of page to jump to with results when canceled (Warning: this page will never be invoked if the user does not choose to click 'cancel' before or after a failure).
Customer_Account   New or existing customer merchant account number.
(required if this payment needs to be associated with other payments)
Set to 'ask' if you want to have the form prompt the user for their account number.
RequireAccount   Setting this to 1 when Customer_Account is set to 'ask' will require the user to enter a value for Customer_Account, otherwise this parameter is ignored.
Customer_ID   New or existing customer ID. May be left blank.
Used to associate multiple accounts with a given customer.
Firstname   Customer first name
Lastname   Customer last name (provide Firstname and Lastname in place of OrgName)
OrgName   Organizational name (provided in place of Firstname and Lastname)
Address1   Customer address
Address2   Customer address
City   Customer city
State   Customer state (2 char abbreviation)
Zip   Customer zip code (5 digits)
RequireAddress   Setting this boolean value to 0 will not require data to be entered in the normally required fields, Address1, City, State, and Zip. When data is required to be entered into those fields, the system requires the field to not be blank but does not validate that data.
Phone   Customer phone (10 digits)
RequirePhone   Setting this boolean value to 0 will not require data to be entered in the normally required Phone field. When data is required to be entered into that field, the system requires the field to not be blank but does not validate that data.
Email   Customer email
RequireEmail   Setting this boolean value to 1 will require data to be entered in the normally not required Email field. When data is required to be entered into that field, the system requires the field to not be blank but does not validate that data.
Graphic   URL link to graphic to be placed above the registration form (default: predefined merchant logo will be used but no graphics will be used if this is set to "none".
Color1   Background color of registration form defined as RRGGBB (using hexadecimal digits) or by standard HTML color names (See w3schools).
Color2   Background color of registration form headers. (see Color1)
Footer   Set to 'none' to eliminate the standard page footer including security logos, all other values ignored.
Pay_Method   Method of payment (1 character: Checking, Savings, Business checking, Visa, Mastercard, Discover, American express).
Bank_AccountName   Name shown on bank account (only read in POST form)
Bank_Routing   9 digits (US banking institutions only) (only read in POST form)
Bank_Account   22 digits (may have leading zeros) (only read in POST form)
CreditCard_Name   Name shown on card. (only read in POST form)
CreditCard_Number   13 to 16 digits with or without spaces (only read in POST form)
CreditCard_ExpYear   4 digits (only read in POST form)
CreditCard_ExpMonth   2 digits (only read in POST form)
CreditCard_CVV   3 or 4 digits (only read in POST form)
CreditCard_Street   Street portion on billing address (only read in POST form)
CreditCard_ZIP   5 digit zip on billing address (only read in POST form)

The SimplePay page returns the results of the transaction to the given Return_Page with the following POST form fields. The output of the Return_Page is not displayed. The Return_Success and Return_Fail pages will be passed only three parameters (Transaction_ID, Code, and Status) in GET query format as control is returned to them.

Merchant_ID Copied from SimplePay call
Customer_Account Copied from SimplePay call
Category Copied from SimplePay call
Memo Copied from SimplePay call
Amount Positive numeric dollars.cents amount (no dollar sign)
Fee Amount of fee (if any) that was added to the total - this is defined by the merchant settings
Transaction_ID Copied from SimplePay call
Payment_ID Unique payment identifier assigned by SIP
Code Result - "Success" or "Failure"
Status Explanation of result

Use the following links to view some examples of the SimplePay pages:

  • Sample 1 - $20 registration for a bike-a-thon with three graphics, default colors.
  • Sample 2 - $25.46 registration for half marathon with two graphics & colors specified.
  • Sample 4 - Mortgage payment example with no graphics at all or colors specified but with registration partially pre-filled out. This could easily be placed in the frame of your web page.
  • Sample 3 - $1586.98 payment example with header graphics specified and with amount and registration mostly pre-filled out.

This is an example of PHP code that can parse the results from a SimplePay transaction. Note the use of the $_REQUEST[] array to pickup parameters that may be in POST or GET format.

<?php

// The SIP SimplePay passes all data in via a post form with the following fields:
//  Merchant_ID    - Provided by SIP
//  Customer_Account  - Customer account number provided by merchant (50 char limit)
//  Category    - Category as passed to SimplePay
//  Memo      - Memo as entered in SimplePay form
//  Amount      - Positive numeric dollars.cents amount
//  Fee      - Positive numeric dollars.cents amount
//  Transaction_ID    - unique number provided by merchant (50 char limit) as passed to SimplePay
//  Payment_ID    - unique number assigned to transaction by SIP
//  Code      - Results - "Success" or "Failure"
//  Status      - Explanation of result

// published parameters
$midp    = isset($_REQUEST['Merchant_ID'])      ? html_safe($_REQUEST['Merchant_ID'])      : '';
$account = isset($_REQUEST['Customer_Account']) ? html_safe($_REQUEST['Customer_Account']) : '';
$cat     = isset($_REQUEST['Category'])         ? html_safe($_REQUEST['Category'])         : '';
$memo    = isset($_REQUEST['Memo'])             ? html_safe($_REQUEST['Memo'])             : '';
$amount  = isset($_REQUEST['Amount'])           ? html_safe($_REQUEST['Amount'])           : '';
$fee     = isset($_REQUEST['Fee'])              ? html_safe($_REQUEST['Fee'])              : '';
$tid     = isset($_REQUEST['Transaction_ID'])   ? html_safe($_REQUEST['Transaction_ID'])   : '';
$pid     = isset($_REQUEST['Payment_ID'])       ? html_safe($_REQUEST['Payment_ID'])       : '';
$code    = isset($_REQUEST['Code'])             ? html_safe($_REQUEST['Code'])             : '';
$status  = isset($_REQUEST['Status'])           ? html_safe($_REQUEST['Status'])           : '';

echo "<table>
  <tr bgcolor=#CCCCCC><td colspan=2><b>SIP SimplePay Results Parameters</b></td></tr>
  <tr bgcolor=#CCCCCC><td><b>Parameter:</b></td>".        "<td><b>Value</b></td></tr>
  <tr><td bgcolor=#CCCCCC><b>Merchant_ID:</b></td>".      "<td>$midp</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Customer_Account:</b></td>". "<td>$account</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Category:</b></td>".         "<td>$cat</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Memo:</b></td>".             "<td>$memo</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Amount:</b></td>".           "<td>$amount</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Fee:</b></td>".              "<td>$fee</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Transaction_ID:</b></td>".   "<td>$tid</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Payment_ID:</b></td>".       "<td>$pid</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Code:</b></td>".             "<td>$code</td></tr>
  <tr><td bgcolor=#CCCCCC><b>Status:</b></td>".           "<td>$status</td></tr>
  </table>";

?>

Simple Payment Import Specification

A set of logins can be uploaded into the system to provide a group of people access to the payment they need to make. See mixed-interface for more information about the format of the upload file.


Digitzs Merchant & Payment Forms

TBD


Paystub Retrieval

Paystub information for any employee of a given merchant can be retrieved using this URL:

Note: The employer is responsible for all information retrieved by this request. Instant Payments does not calculate, verify, or alter the information in any way.

The shopping cart application receives all data in via a POST form request with the following fields:

Merchant & Employee Information: Required
1 Merchant_ID
Provided by SIP.
2 Merchant_Code
Authentication provided by SIP.
3 Employee_ID Merchant defined when Employee record was created (default to all employees).
4 PayPeriod Pay period date (m/d/yyyy) (default to most recent).
5 Format Format (PayPeriods, Text, SMS, or HTML) to return paystub (default: Text).
PayPeriods: will return a list of available pay periods.
Text: will return one tab-delimited record per paystub for each paystub requested.
SMS: will return one tab-delimited abbreviated record per paystub for each paystub with data suitable for sending in a short text message.
HTML: will display each paystub requested in an HTML page.
6 Suffix 'tsv' for tab-delimited output, 'csv' for comma-delimited output.

The PayPeriods output lists the date of each pay period for which paystub information has been uploaded. One date per line of text.

The Text format output contains one record of tab-delimited data for each pay stub requested with a header record which begins with a '#'. The fields of the file are as follows:

Field Comment
1
Merchant_ID Merchant ID
2
Merchant Merchant name
3
Merchant_Address Merchant address
4
PayPeriodStart Pay period start date (m/d/yyyy)
5
PayPeriodEnd Pay period end date (m/d/yyyy)
6
PayDay Pay day (m/d/yyyy)
7
Category  
8
Employee_ID Merchant defined when Employee record was created
9
Hours Hours paid or other string i.e. 'Salaried'
10
Currency Default USD
11
GrossPay Positive amount of gross pay
12
TaxesWithheld Positive amount of taxes withheld from pay
13
OtherWithholding Positive amount of other non-tax withholding
14
NetPay Positive amount of net pay
15
Name Employee Name
16
Address Employee address
17
Phone Employee mobile phone number
18
Email Employee email address
19
Description Begin Triplet: Description if item
20
Current Current period
21
Year2Date Year-to-date
22...
<repeat triplets> Repeat as many triplets as required to display uploaded detailed data

The SMS format output contains one abbreviated record of tab-delimited data for each pay stub requested with a header record which begins with a '#'. The fields of the file are as follows:

Field Comment
1
Merchant_ID Merchant ID
2
Mobile_Number Mobile Phone number of Employee
3
Company_Name Merchant name
4
Currency Default to USD
5
Employee_ID Merchant defined when Employee record was created
6
GrossPay Positive amount of gross pay
7
TaxesWithheld Positive amount of taxes withheld from pay
8
OtherWithholding Positive amount of other non-tax withholding
9
NetPay Positive amount of net pay
10
Hours Hours paid or other string i.e. 'Salaried'
11
PayPeriodEnd Pay period end date or issue date (m/d/yyyy)

Fee Structure

Knowing your fee structure will allow you to calculate the fees for a payment before sending it for processing. This interface is accessed in SIP via the following URL:

All parameters are passed in POST form format with the following fields:

Merchant Information: Required
Merchant_ID Provided by SIP.
Merchant_Code Authentication provided by SIP


The response is passed back via simple comma-delimited text where the format is:
Merchant Name Fee Structure:
ACH,SingleFee,RecurringFee
CC,MinFee,FixedFee,Percent,ForeignPercent
CCcalc,FeeEquation

When a Card is used the foreign percent will be added to the Percent if a foreign, outside the USA, card is used and the greater of the calculation and MinFee will be used.

Use Instant Payments to accept payments for your business.
SIP Program & Data © 2006-2018 Instant Payments All rights reserved.
~ Terms & Conditions ~ Privacy Policy ~ Contact Us ~
SIP Version 2.18; API: 2.5
RSI Security Instant Payments, Payment Processing Service, Clinton, UT Get Help