Introduction

Welcome to the PaySimple 4.0 API! Our API is designed to be intuitive and easy to integrate. The 4.0 API is based on a REST (Representational State Transfer) architecture inheriting all the simplicity the Web has to offer as a platform for distributed computing.

The PaySimple API uses JSON (JavaScript Object Notation) to exchange data. The structure of the “Name: Value” pairs is easily readable for developers, and allows for quick parsing within different programming languages.

This guide provides detailed instructions for integrating your web‐based system with the PaySimple 4.0 API, creating and modifying API Objects, and detailed definitions for all API Attributes.

If you need assistance with your integration, please don’t hesitate to contact our API Support Team at 800‐466‐0992 or via email at partnersupport@paysimple.com.

Sandbox Endpoint: https://sandbox-api.paysimple.com

Production Endpoint: https://api.paysimple.com

Integration

PaySimple takes security very seriously to ensure the protection of your organization’s and your clients’ sensitive information. PaySimple software is fully PCI compliant and encrypts account information once submitted. To extend this level of security, the PaySimple API only allows communications over HTTPS, utilizing SSL/TLS, and requires the API user to authenticate security credentials in order to interact with the system.

To ensure that your interface is programmed correctly, and to provide you the opportunity to test your code and learn the API prior to connecting with our Production system, PaySimple uses a two‐step certification process. You are first provided credentials to our Sandbox environment where you can develop your code. You then submit sample code for review by PaySimple. Upon our certification of your code, you are provided with credentials for the Production environment and you can use those to configure Server‐to‐Server authentication to the PaySimple API from specific IP addresses you pre‐register with us.

The following sections outline how to work in both of these environments and how to integrate with each of them. If you need PaySimple Sandbox Test Account credentials or live‐account credentials, please contact us at PartnerSupport@PaySimple.com.

Sandbox Environment

Sandbox Endpoint: https://sandbox-api.paysimple.com

The PaySimple Sandbox is a testing environment that is designed to simulate our active production environment. It is a safe environment in which to test API connectivity and functionality.

Payments processed in the Sandbox environment are routed to test authorization and capture servers which are designed to behave in the same manner as do production servers. However, none of the transactions will actually be submitted for processing, and no funds will be transferred.

Since the Sandbox mimics an active production environment, the same authentication requirements apply and you will need to obtain a PaySimple sandbox account in order to use it. To do this, contact our API Support Team at PartnerSupport@PaySimple.com with the following information:

  • The email address you would like associated with your account.
  • The type of transactions you want to process
    • Credit Card: Visa, MasterCard, American Express, and/or Discover
    • ACH: PPD, CCD, TEL, and/or WEB
  • A request to generate a Sandbox 4.0 API Key

A PaySimple API Support team member will contact you with the sandbox API Username, the sandbox API Key (a Shared Secret for Server‐to Server authentication), as well as credentials that you can use to access the API Test Tool (see Using the API Test Tool for instructions on using the tool). These credentials will also enable you to access the PaySimple Sandbox web‐based UI, from which you can view customers, payments, and schedules created via the API.

Once you receive sandbox credentials, configure your connection as described in the Integrating Your Systems with the PaySimple API section. All API communications should be made via secure HTTP communications to the Sandbox endpoint with the desired URI.

Test Account Numbers for the Sandbox Environment

The following Credit Card and ACH Account Numbers can be used for test transaction processing in the Sandbox environment. Note that you will only be able to process transaction types for which your sandbox account is enabled.

NOTE: It is against PCI rules to use live account numbers in test environments. Please be certain that you only use test account numbers in the PaySimple sandbox environment.

PaySimple Sandbox Test Credit Card Accounts

Credit Card Type Account # Expiration Date CVV2 Code
Visa 4111111111111111 12/2021 996
MasterCard 5454545454545454 12/2021 996
American Express 371449635398456 12/2021 996
Discover 6011000995504101 12/2021 996

PaySimple Sandbox Test Bank Accounts (for ACH processing)

Routing # Account # Bank Name
131111114 751111111 PaySimple Bank
307075259 751111111 PaySimple Bank
325272034 751111111 PaySimple Bank

Production Environment

Production Endpoint: https://api.paysimple.com

Once you have completed the API Certification process (see the Certification section for instructions.) you will receive credentials for a Client Account and associated production API Key (a Shared Secret for Server‐to Server authentication).

Once you have received your Production credentials, configure your connection as described in the Integrating Your Systems with the PaySimple API section. All API communications should be made via secure HTTPS to the Production endpoint with the desired URI.

NOTE: You can easily convert your Sandbox Code for the Production environment by changing the Endpoint, API Username, and API Key to the Production values.

Certification

Once you've completed your development and testing in the Sandbox, we ask that you submit your code for certification on the PaySimple API.

When you are ready to begin the certification process, please complete the following exercises and submit your code, along with the actual API Responses, and how they are handled in your system to PartnerSupport@PaySimple.com.

You must successfully complete certification in order to receive Production API Credentials.

API Certification Exercises

Customer Objects

For detailed instructions on creating Customer Objects using the PaySimple API see the Adding Customers section.

  1. Successfully Create a new Customer Object
    • Expected Result: 201 Created
  2. Attempt to create a Customer including all elements of the Billing Address except StreetAddress1.
    • Expected Result: 400 Bad Request - {"Field": "StreetAddress1", "Message": "The StreetAddress1 field is required."}
    • Provide Example of how this error is displayed in your system.

Account Objects

For detailed instructions on creating Account Objects using the PaySimple API see the Payment Accounts section.

NOTE: If you are not configured to process ACH skip the ACH items; it you are not configured to process Credit Card transactions, skip the CC items.

  1. Successfully Create an ACH account
    • Expected Result: 201 Created
  2. Attempt to create the same ACH Account
    • Expected Result: 400 Bad Request -{"Field": "", "Message": "This bank account is already attached to this customer. You cannot attach it twice.”}
    • Provide Example of how this error is displayed in your system.
  3. Successfully Create a Credit Card account
    • Expected Result: 201 Created
  4. Attempt to create Credit Card account using an invalid card number
    • Expected Result: 400 Bad Request -{"Field": "","Message": "The credit card number you entered is not valid for type Visa"}
    • Provide Example of how this error is displayed in your system.

Payment Objects

For detailed instructions on creating and modifying Payment Objects using the PaySimple API see the ts section.

NOTE: If you are not configured to process ACH skip the ACH items; it you are not configured to process Credit Card transactions, skip the CC items.

  1. Successfully Post an ACH Payment
    • Expected Result: 201 Created
      • Status = “Posted”
  2. Attempt to submit the same payment within 5 minutes.
    • Expected Result: 400 Bad Request -{"Field": "","Message": "Duplicate Transaction."}
    • Provide Example of how this error is displayed in your system.
  3. Refund a 'Settled' ACH payment.
    NOTE: ACH Payments in Sandbox settle in 2 days. Be sure to post an ACH Payment 2 days in advance of completing this exercise.
    • Expected Result: 200 OK (Success)
      • Refund (credit) Payment Status = “ReversePosted” and PaymentId= the Id for the original payment.
      • NOTE: The Response for a Refund Request is the newly created Refund (credit) Payment Object.
  4. Void a Posted ACH Payment
    • Expected Result: 200 OK (Success)
      • Status = “Voided”
  5. Successfully Post a Credit Card Payment
    • Expected Result: 201 Created
      • Status = “Authorized”
  6. Refund a 'Settled' Credit Card payment. NOTE: Credit Card Payments in Sandbox settle on the next day. Be sure to post a credit card payment at least the day before completing this exercise.
    • Expected Result: 200 OK (Success)
      • Refund (credit) Payment Status = “Authorized” and PaymentId= the Id for the original payment.
      • NOTE: The Response for a Refund Request is the newly created Refund (credit) Payment Object.
  7. Void an Authorized Credit Card Payment
    • Expected Result: 200 OK (Success)
      • Status = “Voided”
  8. Post a Credit Card Payment for over $2 million.
    • Expected Result: 400 Bad Request -{"Field": "","Message": "Payment amount cannot exceed $2,000,000.00"}
    • Provide Example of how this error is displayed in your system.
  9. Post a Credit Card Payment for $0.
    • Expected Result: 400 Bad Request -{"Field": "", "Message": "Amount must be greater than 0”}
    • Provide Example of how this error is displayed in your system.

Integrating Your Systems with the PaySimple API

PaySimple utilizes a Server Token method (the API Key or Secret Code) to enable you to integrate your back‐end services or Web Servers with the PaySimple API. This Server Token does not expire, so we use extra security measures to ensure that requests to our endpoints are valid.

We use the IP Address of your network and a netmask, which you supply during the provisioning process, to create your unique server‐to‐server API Key. This enables us to ensure that requests to our API come from a valid server address within your organization.

Your API Key will be delivered via encrypted email. Please ensure it is kept in a safe location, and never send this key over the wire to any API endpoint or via email with code samples. This is your unique password for the API and should be protected.

The API Key (secret code) is used to construct a Server Token which enables you to authenticate to the PaySimple API.

Constructing a ServerToken

Use the API Key (secret code) we provide you with to construct a Server Token using an HMAC (hash-based message authentication code) signature with an UTC time-stamp in ISO-8601 format as follows:

  1. Add an Authorization Header to your request:
    1. Create your API Signature
      1. Get UTC timestamp in ISO-8601 format.
      2. Compute HMAC with date and API Key, both encoded UTF8, using a SHA256 hashing algorithm.
      3. Base-64 Encode the HMAC.
    2. Concatenate "accessid=" + your API Username + "; timestamp=" + the ISO-8601 time-stamp defined in step a + "; signature=" + the HMAC result of step a.
    3. Create the Authorization Header using the following format: “PSSERVER” + “ “ + the result of step b.
      • Example: “Authorization: PSSERVER accessid=APIUser1000; timestamp=2012-07-20T20:45:44.0973928Z; signature=WqV47Dddgc6XqBKnQASzZbNU/UZd1tzSrFJJFVv76dw=”
  2. Call any endpoint with an API URI

Sample Authentication Code

The following examples provide sample code for creating a Server Token, authenticating with the PaySimple API, and submitting API Requests. You will need to adjust these code examples for your API integration and development environment. For example, the URI should be created and passed dynamically based on the action you want to perform.

C# PHP
using System;
using System.Net;
using System.Text;
using System.Security.Cryptography;

namespace SimpleApi {
    public partial class SimpleApi: System.Web.UI.Page {
        protected void Page_Load(object sender, EventArgs e) {
        string userName = "";
        string apiKey = "";
        string timeStamp = DateTime.Now.ToString(@"yyyy-MM-ddTHH\:mm\:sszzz");
        Uri uri = new Uri("https://api.paysimple.com/v4/customer");

        //create your token
        HMAC hasher = new HMACSHA256(Encoding.UTF8.GetBytes(superSecretCode));
        byte[] data = hasher.ComputeHash(Encoding.UTF8.GetBytes(timeStamp));
        string hmac = Convert.ToBase64String(data);

        HttpWebRequest request = WebRequest.Create(uri) as HttpWebRequest;
        string authenticationHeader = String.Format("PSSERVER AccessId = {0}; Timestamp = {1}; Signature = {2}", userName, timeStamp, hmac);
        request.Headers.Add(HttpRequestHeader.Authorization, authenticationHeader);

        HttpWebResponse response = (HttpWebResponse)request.GetResponse();
        // ... deal with response
        }
    }
}
                                
<?php
$userName = "<USER NAME HERE>";
$superSecretCode = "<CODE HERE>";
$timestamp = gmdate("c");
$hmac = hash_hmac("sha256", $timestamp, $superSecretCode, true); //note the raw output parameter
$hmac = base64_encode($hmac);
$auth = "Authorization: PSSERVER AccessId = $userName; Timestamp = $timestamp; Signature = $hmac";
$url = "https://api.paysimple.com/v4/customer";

>$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTPHEADER, array($auth));

var_dump(curl_exec($curl));
$responseCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
echo "<br>response: $responseCode <br><br>";
?>
                                

Payments

If you know the AccountId for the credit card or bank account you want to charge, processing a payment can be as simple as entering the payment amount along with that AccountId.

To create a new one-time Payment Object via the API:

  • Method = POST
  • URI = /v4/payment
  • Request = Payment Object Attributes: AccountId, Amount

Key Payment Object Response Attributes

Id: Integer -- this is the PaymentId number you will need to reference in future calls related to this transaction including void, refund, and view details.

Status: Integer -- payment Status set by the system. Enumeration: 0 = Pending; 1 = Posted; 2 = Settled; 3 = Failed; 5 = Voided; 6 = Reversed; 9 = ReversePosted; 10 = Chargeback; 12 = Authorized; 13 = Returned; 15 = ReverseNSF; 17 = Refund Settled

Expected Responses for new payments are Posted, Authorized or Failed.

NOTE: These labels do not all correspond to PaySimple Status names in the UI. Mapping is as follows: Reversed = Refunded; ReversePosted = Refund (Posted); ReverseNSF = Returned NSF

ProviderAuthCode: String -- a pass-through field that displays the authorization response for the transaction.

TraceNumber: String -- a pass-through field that displays the processor’s transaction identifier for a successful transaction or the provider’s error message for a failed transaction.

FailureData: String -- standardized system information about why a transaction failed; 4 components:
Code --a 4-digit PaySimple Error Code

Description --a description of the Error

MerchantActionText --instructions to the merchant on how to handle the error.

IsDecline" -- “true” indicates that the failure was due to the transaction being declined; “false” indicates a failure due to any other reason.

NOTE: See Data Error Co for a table containing Failure Codes and associated messages.

The above assumes you are starting with a valid AccountId, which assumes an existing Customer Object with existing Payment Account Objects attached to it. In many instances this will not be the case. The following sections cover the complete process for entering payments for completely new customers, for existing customers with existing payment accounts, and for existing customers with new payment accounts. Within each section all relevant Object Attributes are fully defined.

 

Sample Basic New Payment Object Request

JSON
{
    "AccountId": 395560,
    "Amount": 3,
}
                                

Sample New Payment Object Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Authorized",
    "RecurringScheduleId": 0,
    "PaymentType": "CC",
    "PaymentSubType": "Moto",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "406690",
    "PaymentDate": "2013-10-11T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-14T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-12T02:45:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null },
    "AccountId": 395560,
    "InvoiceId": null,
    "Amount": 7.5,
    "IsDebit": false,
    "InvoiceNumber": "123AB",
    "PurchaseOrderNumber": "77652",
    "OrderId": "AB999",
    "Description": "A one time payment for a new customer",
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1608391,
    "LastModified": "2013-10-11T22:34:07Z",
    "CreatedOn": "2013-10-11T22:34:07Z"
}
                                

Collecting a Payment for a New Customer

Collecting a payment for a new customer using the API is accomplished using three sequential steps:

  1. Creating a new Customer Object
  2. Adding a Payment Account Object to the Customer Object created in Step 1.
  3. Creating a Payment Object using the Payment Account Object created in Step 2.

Attributes for each of the Object Types are defined below, as are the Request and Response Information associated with utilizing them to create customers and process payments.

Customer Object

To create a new Customer Object via the API:

  • Method = POST
  • URI = /v4/customer
  • Request = Customer Object Attributes
  • Response Attribute Needed = “CustomerId”

Customer Object Attributes

Required Attributes

FirstName: String -- 150 characters max

LastName: String -- 150 characters max

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. Set to “false” to require ShippingAddress fields.

Sample New Customer Object Request

Optional Attributes

BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

Company: String -- 50 characters max

CustomerAccount: String -- 28 characters max. This is a non-system account number you can assign.

Phone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

AltPhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

MobilePhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Fax: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Email: String -- 100 characters max, must be a valid email address.

AltEmail: String -- 100 characters max, must be a valid email address.

Website: String -- 100 characters max, must be in URL format.

Notes: String -- 2048 characters max; an open text field.

Sample New Customer Object Response

System Attributes

These fields are required components of the Customer Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the CustomerId in the Response

LastModified: String -- set by system, any Request data will be disregarded.

CreatedOn: String -- set by system, any Request data will be disregarded.

Sample New Customer Object Request

JSON
POST /v4/customer
{
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": null,
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "testperson@abcco.com",
    "Phone": "8005551212",
}
                                

Sample New Customer Object Response

JSON
"Response": {
    "AltEmail": null,
    "AltPhone": null,
    "MobilePhone": null,
    "Fax": null,
    "Website": null,
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "testperson@abcco.com",
    "Phone": "8005551212",
    "Id": 255939,
    "LastModified": "2013-10-01T19:16:38.5061103Z",
    "CreatedOn": "2013-10-01T19:16:38.5061103Z"
}
                                

Payment Account Objects

To create a new Payment Account Object via the API:

  • Method = POST
  • URI = /v4/account/creditcard or /v4/account/ach
  • Request = Credit Card Attributes or ACH Attributes
  • Response Attribute Needed = “Account Id”

Credit Card Account Request Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.

CreditCardNumber: String -- 15 or 16 digits

ExpirationDate: String -- a valid date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

IsDefault: Boolean -- enter “true” to set the card as the default Credit Card Account for the Customer Record, otherwise enter “false.” If there are no other cards attached to the Customer Record, the field will default to “true” regardless of your entry.

Optional Attributes

BillingZipCode: String -- max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

System Attributes

These fields are required components of the Credit Card Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded.

CreatedOn: String -- set by system, any Request data will be disregarded.

ACH Account Request Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- min 4 digits, max 100 digits; the bank account number

BankName: String-- 100 characters max; the financial institution name

IsCheckingAccount: Boolean -- enter “true” to indicate a checking account or “false” to indicate a savings account. General Ledger accounts are not supported.

IsDefault: Boolean -- enter “true” to set the account as the default ACH Account for the Customer Record, otherwise enter “false.” If there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of your entry.

System Attributes

These fields are required components of the ACH Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Sample New Credit Card Account Object Request

JSON
{
    "CreditCardNumber": "4111111111111111",
    "ExpirationDate": "12/2015",
    "Issuer": "12",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New Credit Card Account Object Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36.6661404Z",
    "CreatedOn": "2013-10-11T17:41:36.6661404Z"
}
                                

Sample New ACH Account Object Request

JSON
{
    "IsCheckingAccount": "true",
    "RoutingNumber": "072000326",
    "AccountNumber": "751666666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": "true",
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New ACH Account Object Response

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56.7441402Z",
    "CreatedOn": "2013-10-11T17:54:56.7441402Z"
}
                                

Payment Object

This section covers entering a one-time payment that is submitted on the current date. (See the Scheduled Payment section for instructions on entering a one-time payment for a future date.) Note that the system determines the type of payment (ACH or Credit Card) based on the account type of the AccountId provided.

To create a new Payment Object via the API:

  • Method = POST
  • URI = /v4/payment
  • Request = Payment Object Attributes

Payment Object Request Attributes

Required Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the payment. This is the “Id” attribute from the Credit Card Object or ACH Account Object created in the previous step.

Amount: Number -- the amount to charge. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 3.129 will result in a payment Amount of 3.13.

Optional Attributes

IsDebit: Boolean-- this field defaults to “false” to indicate a payment whether or not it is included. Entering “true” will result in an error, as standalone credits are not currently supported via the API.

CVV: String-- min 3 digits, max 4 digits; the credit card security code. This field defaults to null when not included. It may be included for credit card payments and will be ignored if entered for ACH payments.

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceId: Integer-- a system invoice identifier. If included it will seat the associated system Invoice Number in the InvoiceNumber attribute, and will apply the payment to the specified Invoice ID.
NOTE: Invoice creation and management is not currently available via the API.

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the payment. If the number provided is a system Invoice Number, the associated InvoiceId will be attached to the payment and the payment will be applied to the system invoice.
NOTE: Invoice creation and management is not currently available via the API.

PurchaseOrderNumber: String-- 50 characters max; the Purchase Order Number attached to the payment.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

Description: String-- -- 2048 characters max.

Latitude: Number-- this field is not currently used in the UI, but will accept and save latitude values.

Longitude: Number-- this field is not currently used in the UI, but will accept and save longitude values.

SuccessReceiptOptions: Object -- the receipt instructions. Null means the current system default settings should be used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how payment receipts are sent:

SendToCustomer --”true” indicates that the receipt gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the receipt email is to be sent. Using brackets, enter valid email addresses separated by commas.

FailureReceiptOptions: Object -- the failure notification email instructions. Null means the current system default settings should be used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how failure notifications are sent:

SendToCustomer --”true” indicates that the notification gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the failure notification email is to be sent. Using brackets, enter valid email addresses separated by commas.

System Attributes

These fields are required components of the Payment Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the PaymentId in the Response.

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Payment Object Response Attributes

Key Attributes

Id: Integer -- this is the PaymentId number you will need to reference in future calls related to this transaction including void, refund, and view details.

Status: Integer -- payment Status set by the system. Enumeration: 0 = Pending; 1 = Posted; 2 = Settled; 3 = Failed; 5 = Voided; 6 = Reversed; 9 = ReversePosted; 10 = Chargeback; 12 = Authorized; 13 = Returned; 15 = ReverseNSF; 17 = Refund Settled

Expected Responses for new payments are Posted, Authorized or Failed.

NOTE: These labels do not all correspond to PaySimple Status names in the UI. Mapping is as follows: Reversed = Refunded; ReversePosted = Refund (Posted); ReverseNSF = Returned NSF

ProviderAuthCode: String -- a pass-through field that displays the authorization response for the transaction.

TraceNumber: String -- a pass-through field that displays the processor’s transaction identifier for a successful transaction or the provider’s error message for a failed transaction.

FailureData: String -- standardized system information about why a transaction failed; 4 components:
Code --a 4-digit PaySimple Error Code

Description --a description of the Error

MerchantActionText --instructions to the merchant on how to handle the error.

IsDecline" -- “true” indicates that the failure was due to the transaction being declined; “false” indicates a failure due to any other reason.
NOTE: See Data Error Co for a table containing Failure Codes and associated messages.

Other Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment.

CustomerFirstName: String -- the first name of the Customer associated with the payment.

CustomerLastName: String -- the last name of the Customer associated with the payment.

CustomerCompany: String -- the Company, if any, associated with the payment.

ReferenceId: Integer -- for a refunded payment, the PaymentId for the refund transaction, for a refund transaction the Payment Id for the refunded payment.This field will be “0” in all other cases.

RecurringScheduleId: Integer -- if a payment is part of a schedule, the ScheduleId. This field will be “0” in all other cases including one-time payments processed for new customers.

PaymentType: Integer -- set by the system to identify the transaction type, based on the type of account associated with the AccountId used for the payment. Enumeration: 1 = CC (credit card); 2 = ACH

PaymentSubType: Integer -- the type of Credit Card or ACH payment. It defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null. Other Values include “Swipe” for CC and “PPD,” “CCD,” and “TEL” for ACH.

PaymentDate: String -- set by the system, the date the payment was processed. This is always the current date.

ReturnDate: String -- set by the system, the date an ACH payment was Returned. This field will always be null for new transactions and will always be null for Credit Card transactions.

EstimatedSettleDate: String -- the date the system expects the transaction to be settled, based on a merchant’s funding time.

ActualSettledDate: String -- the date the system receives notification that a transaction has actually settled. This field will always be null for new transactions.

CanVoidUntil: String -- the last date on which a transaction may be voided.

AccountId: Integer -- the AccountId specified in the Payment Request.

InvoiceId: Integer -- the InvoiceId, if any, specified in the Payment Request.

Amount: Number -- the Amount specified in the Payment Request. If the Payment Request Amount included more than two decimal places, the Response Amount will be rounded to the nearest penny.

IsDebit: Boolean -- “false” for a payment or “true” for a standalone credit.

InvoiceNumber: String -- -- the InvoiceNumber, if any, specified in the Payment Request.

PurchaseOrderNumber: String -- the PurchaseOrderNumber, if any, specified in the Payment Request.

OrderId: String -- the OrderId, if any, specified in the Payment Request.

Description: String -- the Description, if any, specified in the Payment Request.

Latitude: Number -- the Latitude, if any, specified or captured in the Payment Request.

Longitude: Number -- the Longitude, if any, specified or captured in the Payment Request.

SuccessReceiptOptions: String -- the receipt instructions specified in the Payment Request. Null means the current system default settings were used.

FailureReceiptOptions: String -- the failure notification instructions specified in the Payment Request. Null means the current system default settings were used.

LastModified: String -- set by the system, the date and time the transaction record was last modified.

CreatedOn: String -- set by the system, the date and time the transaction record was created (i.e. the time and date the payment was processed.)

Sample New Payment Object Requests

JSON
Simple
{
    "AccountId": 395560,
    "Amount": 3,
}
                                

Sample New Payment Object Response

JSON
Complete
 {
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Authorized",
    "RecurringScheduleId": 0,
    "PaymentType": "CC",
    "PaymentSubType": "Moto",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "406690",
    "PaymentDate": "2013-10-11T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-14T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-12T02:45:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null
    },
    "AccountId": 395560,
    "InvoiceId": null,
    "Amount": 7.5,
    "IsDebit": false,
    "InvoiceNumber": "123AB",
    "PurchaseOrderNumber": "77652",
    "OrderId": "AB999",
    "Description": "A one time payment for a new customer",
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1608391,
    "LastModified": "2013-10-11T22:34:07Z",
    "CreatedOn": "2013-10-11T22:34:07Z"
}
                                

Collecting a Payment for an Existing Customer

Collecting a payment for an existing customer using the API is accomplished using three sequential steps:

  1. Retrieve the CustomerId
  2. Retrieve an existing AccountId or enter a new Payment Account Object.
  3. Create a Payment Object using the Payment Account created or retrieved in Step 2.

If you maintain your own database of CustomerIds and associated AccountIds you can complete steps 1 and 2 in your system, and then utilize the PaySimple API only for processing the payment (step 3.)

If you only maintain a database for CustomerId, you can begin with Step 2.

Attributes needed for each of the Object Types are defined below, as are the Request and Response Information associated with utilizing them to process payments for existing customers using new and existing payment accounts.

Retrieve the CustomerId

If you know the Customer Id for the customer you want to charge (for example if you have it stored in your own database), then you can skip this step.

If you need to retrieve the CustomerId attribute for the Customer Object you want to charge, you will need to search for the Customer Record to obtain it. To Search via the API:

  • Method = GET
  • URI = /v4/globalSearch?Query="[value]"
  • Query = {Customer Name or Company Name}
  • Response Attribute Needed = “OriginId”
    NOTE: The Search OriginId for a Customer Object is equal to its CustomerId

 

 

 

 

 

Sample Customer Search Request

JSON
URI = /v4/globalSearch?Query="ABC Company"
                                

Sample Customer Search Response

JSON
{
"Results": [{
    "OriginKey": "CUST",
    "OriginId": 255939,
    "Description": "Customer: Test Person From: ABC Company",
    "Ranking": 176
}
                                

Retrieve/Create the AccountId

When processing a payment for an existing customer you have the option of charging the default ACH or CC account, charging any non-default ACH or CC account, or entering a new ACH or CC account as part of the payment process. Each of these processes, and its associated Objects and Attributes, are described in the following sections.

Using the Default Credit Card Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve the default credit card AccountId.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/defaultcreditcard
  • Response Attribute Needed = “AccountId”

Credit Card Object Response Attributes

CreditCardNumber: String -- the last four digits of the card number
NOTE: For security purposes, full account numbers are never displayed in Responses.

ExpirationDate: String -- the expiration date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

BillingZipCode: String -- the zip code attached to the credit card if saved with the Payment Account record. If null, the ZipCode attribute for the Customer object will be used for processing the payment.

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate that you have indeed retrieved the default credit card.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the Credit Card Account Object was last changed.

CreatedOn: String -- the date the Credit Card Account Object was created.

Using the Default ACH Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve the default ACH AccountId.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/defaultach
  • Response Attribute Needed = “AccountId”

ACH Object Attributes

IsCheckingAccount: Boolean -- “true” to indicates a checking account and “false” indicates a savings account. General Ledger accounts are not supported.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- last four digits of the bank account number.
NOTE: For security purposes, full account numbers are never displayed in Responses.

BankName: String-- the financial institution name

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate that you have indeed retrieved the default ACH account.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the ACH Account Object was last changed.

CreatedOn: String -- the date the ACH Account Object was created.

Using an Existing Credit Card Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve all of the Credit Card Account Objects associated with the Customer Record, then select the AccountId of the one you want to charge.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/creditcardaccounts
  • Response Attribute Needed = “AccountId” for the account you want to charge.

Account List Credit Card Object Response Attributes

CreditCardNumber: String -- the last four digits of the card number.
NOTE: For security purposes, full account numbers are never displayed in Responses.

ExpirationDate: String -- the card expiration date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

BillingZipCode: String -- the zip code attached to the credit card if saved with the Payment Account record. If null, the ZipCode attribute for the Customer object will be used for processing the payment.

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate the default credit card and “false” for all other saved cards.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the Credit Card Account Object was last changed.

CreatedOn: String -- the date the Credit Card Account Object was created.

You will need to determine which of the returned Credit Cards you want to charge, and retrieve it’s AccountId for the next step.

Alternate Route to Obtain an Existing Credit Card AccountId

If you do not want to select from one of the saved accounts, you can treat all credit cards as new. (Follow the steps in the Account section.) The system will recognize the duplicate (and update the expiration date if necessary), and the Credit Card Object Response will contain the existing AccountId.

Using an Existing ACH Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve all of the ACH Account Objects associated with the Customer Record, then copy the AccountId of the one you want to charge.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/achaccounts
  • Response Attribute Needed = “AccountId” for the account you want to charge.

Account List ACH Object Response Attributes

IsCheckingAccount: Boolean -- “true” to indicates a checking account and “false” indicates a savings account. General Ledger accounts are not supported.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- last four digits of the bank account number
NOTE: For security purposes, full account numbers are never displayed in Responses.

BankName: String-- the financial institution name

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate the default credit card and “false” for all other saved cards.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the ACH Account Object was last changed.

CreatedOn: String -- the date the ACH Account Object was created.

You will need to determine which of the returned bank accounts you want to charge, and retrieve it’s AccountId for the next step.

NOTE: You can use the GET: /v4/{CustomerId}/accounts request to return a list of all payment accounts (ACH and Credit Card) associated with the specified CustomerID, and then select the one you would like to use for the payment.

Using a New Credit Card Account

Use the CustomerId obtained in Step 1 (or saved in your database) to attach a new Credit Card Payment Account Object via the API, then note the AccountId for the new credit card account.

  • Method = POST
  • URI = /v4/account/creditcard
  • Request = Credit Card Attributes
  • Response Attribute Needed = “Account Id”

Required Credit Card Account Object Request Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the CustomerId you retrieved from your database, or in the first step.

CreditCardNumber: String -- 15 or 16 digits

ExpirationDate: String -- a valid date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

IsDefault: Boolean -- enter “true” to set the card as the default Credit Card Account for the Customer Record, otherwise enter “false.” If there are no other cards attached to the Customer Record, the field will default to “true” regardless of your entry.

Optional Credit Card Account Object Request Attributes

BillingZipCode: String -- max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

System Credit Card Account Object Attributes

These fields are required components of the Credit Card Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Using a New ACH Account

Use the CustomerId obtained in Step 1 (or saved in your database) to attach a new ACH Payment Account Object via the API, then note the AccountId for the new credit card account.

  • Method = POST
  • URI = /v4/account/ach
  • Request = ACH Account Attributes
  • Response Attribute Needed = “AccountId”

Required ACH Account Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the CustomerId you retrieved from your database, or in the first step.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- min 4 digits, max 100 digits; the bank account number

BankName: String-- 100 characters max; the financial institution name

IsCheckingAccount: Boolean -- enter “true” to indicate a checking account or “false” to indicate a savings account. General Ledger accounts are not supported.

IsDefault: Boolean -- enter “true” to set the account as the default ACH Account for the Customer Record, otherwise enter “false.” If there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of your entry.

System ACH Account Object Attributes

These fields are required components of the ACH Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Sample Default Credit Card Request

JSON
URI = /v4/customer/255939/defaultcreditcard
                                

Sample Default Credit Card Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}
                                

Sample Default ACH Request

JSON
/v4/customer/255939/defaultach
                                

Sample Default ACH Response

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}
                                

Sample Credit Card Accounts Request

JSON
URI = /v4/customer/255939/creditcardaccounts
                                

Sample Credit Card Accounts Response

JSON
[{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}, {
    "CreditCardNumber": "************5454",
    "ExpirationDate": "08/2018",
    "Issuer": "Master",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396036,
    "LastModified": "2013-10-15T18:33:25Z",
    "CreatedOn": "2013-10-15T18:33:25Z"
}]
                                

Sample ACH Accounts Request

JSON
URI = /v4/customer/255939/achaccounts
                                

Sample ACH Accounts Response

JSON
[{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}, {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396037,
    "LastModified": "2013-10-15T18:33:56Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
}]
                                

Sample New Credit Card Account Object Request

JSON
{
    "CreditCardNumber": "4111111111111111",
    "ExpirationDate": "12/2015",
    "Issuer": 12,
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false
}
                                

Sample New Credit Card Account Object Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36.6661404Z",
    "CreatedOn": "2013-10-11T17:41:36.6661404Z"
}
                                

Sample New ACH Account Object Request

JSON
{
    "IsCheckingAccount": "true",
    "RoutingNumber": "072000326",
    "AccountNumber": "751666666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": "true"
}
                                

Sample New ACH Account Object Response

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56.7441402Z",
    "CreatedOn": "2013-10-11T17:54:56.7441402Z"
}
                                

Create a New Payment Object for an Existing Customer

This section covers entering a one-time payment that is submitted on the current date. (See the Scheduled Payment section for instructions on entering a one-time payment for a future date.) Note that the system determines the type of payment (ACH or Credit Card) based on the account type of the AccountId provided.

To create a new Payment Object via the API:

  • Method = POST
  • URI = /v4/payment
  • Request = Payment Object Attributes

Payment Object Request Attributes

Required Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the payment. This is the “Id” attribute from the Credit Card Object or ACH Account Object retrieved or created in the previous step.

Amount: Number -- the amount to charge. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 3.129 will result in a payment Amount of 3.13.

Optional Attributes

IsDebit: Boolean-- this field defaults to “false” to indicate a payment whether or not it is included. Entering “true” will result in an error, as standalone credits are not currently supported via the API.

CVV: String-- min 3 digits, max 4 digits; the credit card security code. This field defaults to null when not included. It may be included for credit card payments and will be ignored if entered for ACH payments.

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceId: Integer-- a system invoice identifier. If included it will seat the associated system Invoice Number in the InvoiceNumber attribute, and will apply the payment to the specified Invoice ID.
NOTE: Invoice creation and management is not currently available via the API.

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the payment. If the number provided is a system Invoice Number, the associated InvoiceId will be attached to the payment and the payment will be applied to the system invoice.
NOTE: Invoice creation and management is not currently available via the API.

PurchaseOrderNumber: String-- 50 characters max; the Purchase Order Number attached to the payment.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

Description: String-- -- 2048 characters max. An open text field.

Latitude: Number-- this field is not currently used in the UI, but will accept and save latitude values.

Longitude: Number-- this field is not currently used in the UI, but will accept and save longitude values.

SuccessReceiptOptions: Object -- the receipt instructions. Null means the current system default settings should be used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how payment receipts are sent:

SendToCustomer --”true” indicates that the receipt gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the receipt email is to be sent. Using brackets, enter valid email addresses separated by commas.

FailureReceiptOptions: Object -- the failure notification email instructions. Null means the current system default settings should be used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how failure notifications are sent:

SendToCustomer --”true” indicates that the notification gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the failure notification email is to be sent. Using brackets, enter valid email addresses separated by commas.

System Attributes

These fields are required components of the Payment Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the PaymentId in the Response.

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Key Attributes

Id: Integer -- this is the PaymentId number you will need to reference in future calls related to this transaction including void, refund, and view details.

Status: Integer -- payment Status set by the system. Enumeration: 0 = Pending; 1 = Posted; 2 = Settled; 3 = Failed; 5 = Voided; 6 = Reversed; 9 = ReversePosted; 10 = Chargeback; 12 = Authorized; 13 = Returned; 15 = ReverseNSF; 17 = Refund Settled

Expected Responses for new payments are Posted, Authorized or Failed.

NOTE: These labels do not all correspond to PaySimple Status names in the UI. Mapping is as follows: Reversed = Refunded; ReversePosted = Refund (Posted); ReverseNSF = Returned NSF

ProviderAuthCode: String -- a pass-through field that displays the authorization response for the transaction.

TraceNumber: String -- a pass-through field that displays the processor’s transaction identifier for a successful transaction or the provider’s error message for a failed transaction.

FailureData: String -- standardized system information about why a transaction failed; 4 components:
Code --a 4-digit PaySimple Error Code

Description --a description of the Error

MerchantActionText --instructions to the merchant on how to handle the error.

IsDecline" -- “true” indicates that the failure was due to the transaction being declined; “false” indicates a failure due to any other reason.
NOTE: See Data Error Co for a table containing Failure Codes and associated messages.

Other Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment.

CustomerFirstName: String -- the first name of the Customer associated with the payment.

CustomerLastName: String -- the last name of the Customer associated with the payment.

CustomerCompany: String -- the Company, if any, associated with the payment.

ReferenceId: Integer -- for a refunded payment, the PaymentId for the refund transaction, for a refund transaction the Payment Id for the refunded payment.This field will be “0” in all other cases.

RecurringScheduleId: Integer -- if a payment is part of a schedule, the ScheduleId. This field will be “0” in all other cases including one-time payments processed for new customers.

PaymentType: Integer -- set by the system to identify the transaction type, based on the type of account associated with the AccountId used for the payment. Enumeration: 1 = CC (credit card); 2 = ACH

PaymentSubType: Integer -- the type of Credit Card or ACH payment. It defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null. Other Values include “Swipe” for CC and “PPD,” “CCD,” and “TEL” for ACH.

PaymentDate: String -- set by the system, the date the payment was processed. This is always the current date.

ReturnDate: String -- set by the system, the date an ACH payment was Returned. This field will always be null for new transactions and will always be null for Credit Card transactions.

EstimatedSettleDate: String -- the date the system expects the transaction to be settled, based on a merchant’s funding time.

ActualSettledDate: String -- the date the system receives notification that a transaction has actually settled. This field will always be null for new transactions.

CanVoidUntil: String -- the last date on which a transaction may be voided.

AccountId: Integer -- the AccountId specified in the Payment Request.

InvoiceId: Integer -- the InvoiceId, if any, specified in the Payment Request.

Amount: Number -- the Amount specified in the Payment Request. If the Payment Request Amount included more than two decimal places, the Response Amount will be rounded to the nearest penny.

IsDebit: Boolean -- “false” for a payment or “true” for a standalone credit.

InvoiceNumber: String -- -- the InvoiceNumber, if any, specified in the Payment Request.

PurchaseOrderNumber: String -- the PurchaseOrderNumber, if any, specified in the Payment Request.

OrderId: String -- the OrderId, if any, specified in the Payment Request.

Description: String -- the Description, if any, specified in the Payment Request.

Latitude: Number -- the Latitude, if any, specified or captured in the Payment Request.

Longitude: Number -- the Longitude, if any, specified or captured in the Payment Request.

SuccessReceiptOptions: String -- the receipt instructions specified in the Payment Request. Null means the current system default settings were used.

FailureReceiptOptions: String -- the failure notification instructions specified in the Payment Request. Null means the current system default settings were used.

LastModified: String -- set by the system, the date and time the transaction record was last modified.

CreatedOn: String -- set by the system, the date and time the transaction record was created (i.e. the time and date the payment was processed.)

Sample New Payment Object Request

JSON
Simple
{
    "AccountId": 395560,
    "Amount": 3,
}
                                

Sample New Payment Object Response

JSON
Full
{
    "AccountId": 395560,
    "Amount": 7.50,
    "IsDebit": "false",
    "InvoiceNumber": "123AB",
    "PurchaseOrderNumber": "77652",
    "OrderId": "AB999",
    "Description": "A one time payment for a new customer",
    "CVV": "999",
    "PaymentSubType": "MOTO",
}
                                

Payment Object Response Attributes

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Authorized",
    "RecurringScheduleId": 0,
    "PaymentType": "CC",
    "PaymentSubType": "Moto",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "406690",
    "PaymentDate": "2013-10-11T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-14T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-12T02:45:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null
    },
    "AccountId": 395560,
    "InvoiceId": null,
    "Amount": 7.5,
    "IsDebit": false,
    "InvoiceNumber": "123AB",
    "PurchaseOrderNumber": "77652",
    "OrderId": "AB999",
    "Description": "A one time payment for a new customer",
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1608391,
    "LastModified": "2013-10-11T22:34:07Z",
    "CreatedOn": "2013-10-11T22:34:07Z"
}
                                

Void a Payment

Any successfully authorized payment that has not yet been submitted as part of an end-of-day batch can be voided. Statuses for voidable payments are:

  • Authorized -- Credit card payments and refunds that have been authorized, but not yet submitted for processing. Any credit card payment with this status can typically be voided.
  • Posted -- for ACH Payments only, and only prior to the ACH batch cut-off time. Credit Card payments with this status cannot be voided.
  • ReversePosted -- The credit transaction generated when a settled ACH transaction is refunded. (Note that this status displays as “Refund (Posted)” in the PaySimple UI.)

The “CanVoidUntil” Attribute in any Payment Object provides the date until which the transaction can be voided.

NOTE: The “CanVoidUntil” field is not included in the “lite” record response.

Credit Card transactions can typically be voided until 11PM Eastern Time on the “CanVoidUntil” date and ACH transactions can typically be voided until 5PM Eastern Time on the “CanVoidUntil” date.

To void a transaction via the 4.0 API:

NOTE: There is no Request Body for the Void call.

  • Method = PUT
  • URI = /v4/payment/{PaymentId}/void
  • Response = The Complete Payment Record with the “Status” changed to “Voided”

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Posted",
    "RecurringScheduleId": 0,
    "PaymentType": "ACH",
    "PaymentSubType": "Web",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "7cafb8cc-9413-4af5-9e67-d4789fb1499f",
    "PaymentDate": "2013-10-17T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-22T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-17T23:00:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
    },
    "AccountId": 395564,
    "InvoiceId": null,
    "Amount": 7,
    "IsDebit": false,
    "InvoiceNumber": null,
    "PurchaseOrderNumber": null,
    "OrderId": null,
    "Description": null,
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1611848,
    "LastModified": "2013-10-17T16:44:07Z",
    "CreatedOn": "2013-10-17T16:44:07Z"
}
                                

Sample Voided Transaction

JSON
Method = PUT
URI = /v4/payment/1611848/void
Response =
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Voided",
    "RecurringScheduleId": 0,
    "PaymentType": "ACH",
    "PaymentSubType": "Web",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "7cafb8cc-9413-4af5-9e67-d4789fb1499f",
    "PaymentDate": "2013-10-17T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-22T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-17T23:00:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
    },
    "AccountId": 395564,
    "InvoiceId": null,
    "Amount": 7,
    "IsDebit": false,
    "InvoiceNumber": null,
    "PurchaseOrderNumber": null,
    "OrderId": null,
    "Description": null,
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1611848,
    "LastModified": "2013-10-17T17:11:00Z",
    "CreatedOn": "2013-10-17T16:44:07Z"
}
                                

Refund a Payment

Any Settled payment can be refunded via the API. Using the refund call causes the system to perform the following actions:

  1. Change the Status of the original transaction to “Reversed” (shown as “Refunded” in the UI).
  2. Create a new credit (negative) transaction with a Status of:
    1. “Authorized” for Credit Card Refunds
    2. “ReversePosted” for ACH Refunds (shown as “Refund (Posted)” in the UI.)
  3. Set the value of the ReferenceId field for the original transaction to the PaymentId of the credit transaction.
  4. Set the value of the ReferenceID field for the credit transaction to the PaymentId of the original transaction.

To refund a payment via the 4.0 API:

NOTE: There is no Request Body for the Reverse call.

  • Method = PUT
  • URI = /v4/payment/{PaymentId}/reverse
  • Response = The credit Payment Object

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample ACH Refund

JSON
Method = PUT
URI = /v4/payment/1157575/reverse
Response =
{
    "CustomerId": 219175,
    "CustomerFirstName": "test",
    "CustomerLastName": "guy",
    "CustomerCompany": "",
    "ReferenceId": 1157575, {The PaymentId for the original payment}
    "Status": "ReversePosted", {The initial status for an ACH refund}
    "RecurringScheduleId": 0,
    "PaymentType": "ACH",
    "PaymentSubType": "Ppd",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "f542193b-3916-443a-b817-7522a57e0a47",
    "PaymentDate": "2013-10-17T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-17T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-17T23:00:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
         },
    "AccountId": 373191,
    "InvoiceId": null,
    "Amount": 10,
    "IsDebit": true, {Indicator that this is a credit (negative) transaction.}
    "InvoiceNumber": "",
    "PurchaseOrderNumber": "",
    "OrderId": null,
    "Description": "",
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1611883,	{The PaymentId for the newly created credit transaction.}
    "LastModified": "2013-10-17T17:28:27Z",
    "CreatedOn": "2013-10-17T17:28:27Z"
}
• Updated Payment Object for the original payment.
{
    "CustomerId": 219175,
    "CustomerFirstName": "test",
    "CustomerLastName": "guy",
    "CustomerCompany": "",
    "ReferenceId": 1611883,
    "Status": "Reversed",
...}
                                

Sample Credit Card Refund

JSON
Method = PUT
URI = /v4/payment/1602336/reverse
Response =
{
   "CustomerId": 255810,
    "CustomerFirstName": "Lisa",
    "CustomerLastName": "Test",
    "CustomerCompany": ""
    "ReferenceId": 1602336, {The PaymentId for the original payment}
    "Status": "Authorized", {The initial status for a credit card refund}
   "RecurringScheduleId": 0,
    "PaymentType": "CC",
    "PaymentSubType": "Moto",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "976866",
    "PaymentDate": "2013-10-17T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-21T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-18T02:45:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
       },
    "AccountId": 394098,
    "InvoiceId": null,
    "Amount": 10,
    "IsDebit": true, {Indicator that this is a credit (negative) transaction.}
   "InvoiceNumber": null,
    "PurchaseOrderNumber": null,
    "OrderId": null,
    "Description": "test payment from api",
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1611884,	{The PaymentId for the newly created credit transaction.}
    "LastModified": "2013-10-17T17:28:27Z",
    "CreatedOn": "2013-10-17T17:28:27Z"
}
• Updated Payment Object for the original payment.
{
   "CustomerId": 255810,
    "CustomerFirstName": "Lisa",
    "CustomerLastName": "Test",
    "CustomerCompany": "",
    "ReferenceId": 1611884,
    "Status": "Reversed",
...}
                                

Retrieve Payment Records

You can use the API to retrieve full transaction details for a single Payment Object, or you can retrieve a list of all payments processed in the Client Account.

Payment Objects can be displayed in two formats: Complete and Lite. Complete is the default. You can return the “lite” record by applying the “lite” filter in your GET URI Request as follows: /v4/payment?lite=true

An example of each is provided below:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Complete Payment Object

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Posted",
    "RecurringScheduleId": 0,
    "PaymentType": "ACH",
    "PaymentSubType": "Tel",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "93e36116-6f29-4a2c-9ab0-b824fcb4f735",
    "PaymentDate": "2013-10-15T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-18T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-15T23:00:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
    },
    "AccountId": 395564,
    "InvoiceId": null,
    "Amount": 9.44,
    "IsDebit": false,
    "InvoiceNumber": null,
    "PurchaseOrderNumber": null,
    "OrderId": null,
    "Description": null,
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1610692,
    "LastModified": "2013-10-15T20:37:29Z",
    "CreatedOn": "2013-10-15T20:37:29Z"
}
                                

Lite Payment Object

JSON
{
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "Status": "Posted",
    "PaymentDate": "2013-10-15T06:00:00Z",
    "Amount": 9.44,
    "Id": 1610692
}
                                

Payment Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment.

CustomerFirstName: String -- the first name of the Customer associated with the payment.

CustomerLastName: String -- the last name of the Customer associated with the payment.

CustomerCompany: String -- the Company, if any, associated with the payment.

ReferenceId: Integer -- for a refunded payment, the PaymentId for the refund transaction, for a refund transaction the Payment Id for the refunded payment. This field will be “0” in all other cases.

Status: Integer -- payment Status set by the system. Enumeration: 0 = Pending; 1 = Posted; 2 = Settled; 3 = Failed; 5 = Voided; 6 = Reversed; 9 = ReversePosted; 10 = Chargeback; 12 = Authorized; 13 = Returned; 15 = ReverseNSF; 17 = Refund Settled

Expected Responses for new payments are Posted, Authorized or Failed.

NOTE: These labels do not all correspond to PaySimple Status names in the UI. Mapping is as follows: Reversed = Refunded; ReversePosted = Refund (Posted); ReverseNSF = Returned NSF

RecurringScheduleId: Integer -- if a payment is part of a schedule, the ScheduleId. This field will be “0” in all other cases.

PaymentType: Integer -- set by the system to identify the transaction type, based on the type of account associated with the AccountId used for the payment. Enumeration: 1 = CC (credit card); 2 = ACH

PaymentSubType: Integer -- the type of Credit Card or ACH payment. It defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null. Other Values include “Swipe” for CC and “PPD,” “CCD,” and “TEL” for ACH.

ProviderAuthCode: String -- a pass-through field that displays the authorization response for the transaction.

TraceNumber: String -- a pass-through field that displays the processor’s transaction identifier for a successful transaction or the provider’s error message for a failed transaction.

PaymentDate: String -- set by the system, the date the payment was processed. This is always the current date.

ReturnDate: String -- set by the system, the date an ACH payment was Returned. This field will always be null for new transactions and will always be null for Credit Card transactions.

EstimatedSettleDate: String -- the date the system expects the transaction to be settled, based on a merchant’s funding time.

ActualSettledDate: String -- the date the system receives notification that a transaction has actually settled. This field will always be null for new transactions.

CanVoidUntil: String -- the last date on which a transaction may be voided.

FailureData: String -- standardized system information about why a transaction failed; 3 components:
Code --a 4-digit PaySimple Error Code

Description --a description of the Error

MerchantActionText --instructions to the merchant on how to handle the error.

"IsDecline" -- “true” indicates that the failure was due to the transaction being declined; “false” indicates a failure due to any other reason.
NOTE: See Appendix A for a table containing Failure Codes and associated messages.

AccountId: Integer -- the AccountId specified in the Payment Request.

InvoiceId: Integer -- the InvoiceId, if any, specified in the Payment Request.

Amount: Number -- the Amount specified in the Payment Request. If the Payment Request Amount included more than two decimal places, the Response Amount will be rounded to the nearest penny.

IsDebit: Boolean -- “false” for a payment or “true” for a standalone credit.

InvoiceNumber: String -- -- the InvoiceNumber, if any, specified in the Payment Request.

PurchaseOrderNumber: String -- the PurchaseOrderNumber, if any, specified in the Payment Request.

OrderId: String -- the OrderId, if any, specified in the Payment Request.

Description: String -- the Description, if any, specified in the Payment Request.

Latitude: Number -- the Latitude value, if any, specified or captured in the Payment Request.

Longitude: Number -- the Longitude value, if any, specified or captured in the Payment Request.

SuccessReceiptOptions: String -- the receipt instructions specified in the Payment Request. Null means the current system default settings were used.

FailureReceiptOptions: String -- the failure notification instructions specified in the Payment Request. Null means the current system default settings were used.

Id: Integer -- this is the PaymentId number you will need to reference in future calls related to this transaction including void, refund, and view details.

LastModified: String -- set by the system, the date and time the transaction record was last modified.

CreatedOn: String -- set by the system, the date and time the transaction record was created (i.e. the time and date the payment was processed.)

Retrieve a Single Payment Record

Single Payment Objects can only be retrieved in complete form, the “lite” version is not available. To retrieve a complete Payment Object via the API:

 

  • Method = GET
  • URI = /v4/payment/{PaymentId}
  • Query = Id for the Payment Object you want to retrieve

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request

JSON
/v4/payment/1611188
                                

Sample Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Posted",
    "RecurringScheduleId": 0,
    "PaymentType": "ACH",
    "PaymentSubType": "Tel",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "ec99cbe9-17fb-43cb-bf20-962c417f166d",
    "PaymentDate": "2013-10-16T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-21T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-16T23:00:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
    },
    "AccountId": 395564,
    "InvoiceId": null,
    "Amount": 10,
    "IsDebit": false,
    "InvoiceNumber": null,
    "PurchaseOrderNumber": null,
    "OrderId": null,
    "Description": null,
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1611188,
    "LastModified": "2013-10-16T16:56:07Z",
    "CreatedOn": "2013-10-16T16:56:07Z"
}
                                

Retrieve a List of All Payments

The API can be used to return a list of all payments processed for a particular Client account. The generated list can be in complete format or “lite” format, which is ideal for creating summary tables and snapshots.

Because the full list of transactions can grow quite large and unwieldy, the API uses paging to limit the number of results returned from a single Request. The default is to show the most recent 200 transactions. You can use Pagination filters to govern both the number of results returned in the Response as well as the Response page you would like to retrieve.

Pagination Filters

These filters are used as part of the GET URI Request to return a list of transactions:

  • Page = the set of results you want to return. “1” returns the first page, “2” the second, etc. If this filter is not included, the Request defaults to “1.”
  • Pagesize = the number of payment records per page. If this filter is not included, the Request defaults to “200.”

The “Meta” section of the response echoes the Request and displays the total number of records, the page of results returned, and the number of results returned per page.

Status Filter

When returning a list of transactions, you can filter that list by status. You can generate lists that include transactions of a single status, or a group of one or more statuses. The default is to return transactions of all statuses.

The following are used as part of the GET URI Request with the “status” filter to return a list of transactions:

  • Authorized -- Credit card payments and refunds that have been authorized, but not yet submitted for processing.
  • ChargeBack -- An ACH payment being disputed by the customer.
  • Failed -- Attempted transactions that were never authorized or completed.
  • Pending -- The initial stage for every transaction sent for authorization. The system assigns this status while waiting for an authorization response. In some rare cases, if communication is disrupted before the system gets a response, the transaction will remain in the “Pending” status.
  • Posted -- Credit Card and ACH payments that have been entered in the system, but not yet settled. This is the initial status for an authorized but unsettled ACH transaction.
  • RefundSettled -- A settled Credit Card or ACH refund transaction.
  • Returned -- ACH payments that were initially posted but ultimately unsuccessful for any reason other than non-sufficient funds or chargeback.
  • Reversed -- A transaction that has been reversed (refunded). When a settled transaction is refunded, the status of that transaction changes to “Reversed.”
    NOTE: This status displays as “Refunded” in the PaySimple UI.
  • ReverseNSF -- An ACH transaction that failed because the customer had insufficient funds in the account to cover the payment.
    NOTE: This status displays as “ReturnedNSF” in the PaySimple UI.
  • ReversePosted -- The credit transaction generated when a settled ACH transaction is refunded. When the refund settles, the status changes to “RefundSettled.”
    NOTE: This status displays as “Refund (Posted)” in the PaySimple UI.
  • Settled -- A settled ACH or Credit Card payment.
  • Voided -- A voided ACH or Credit Card transaction.

The “Meta” section of the response displays the number of transactions that match the status filter, as well as any pagination filters applied as part of the query.

Date Filters

When requesting a transaction list you can use date filters to return transactions for a given date range. The default is to return all transactions, regardless of date.

The Date Format for URI Requests is: YYYY-MM-DD

These filters are used as part of the GET URI Request to return a list of transactions:

  • startdate = set this filter to return all transactions processed on or after the given date.
  • enddate= set this filter to return all transactions processed on or before the given date.

The “Meta” section of the response displays the number of transactions that match the date filter, as well as any pagination filters applied as part of the query.

Payment List Sorting

When returning a list of transactions in complete or “lite” form you can use sorting calls to control the Attribute by which the list is sorted, and whether the sort is in ascending or descending order. The default sort is Descending by PaymentId. This results in listing the most recent transactions first.

A sort instruction is comprised of two calls, the first determines the field by which the transactions are sorted and the second determines whether the sort is high-to-low or low-to-high.

The secondary sort is always ascending PaymentId. Thus, if more than one payment has the same value for the “sortby” field, they will be listed in ascending order by PaymentId, which effectively means from oldest-to-newest.

These calls are used as part of the GET URI Request to designate the sort parameters:

  • sortby = the Attribute by which to sort.
  • ReturnDate -- sort by the date an ACH transaction was updated to “Returned” or “Returned NSF.”
  • EstimatedSettleDate -- sort by the estimated settle date.
  • ActualSettledDate -- sort by the actual settle date.
  • PaymentDate -- sort by the date the transaction was entered.
  • PaymentType-- sort by the type of payment. This groups ACH transactions and CC transactions.
  • PaymentSubType-- sort by the payment sub type. This will group by ACH - CCD, ACH-PPD, ACH-TEL, ACH-WEB, CC-MOTO, and CC-SWIPE.
  • Amount -- sort by transaction amount.
  • direction = the order by which to sort.
  • ASC -- Ascending, sort low-to-high / A-to-Z. When this direction is selected “null” values will appear first in the list.
  • DESC-- Descending, sort high-to low / Z-to-A. when this direction is selected “null” values will appear last in the list.

The “Meta” section of the response displays the number of transactions that match the date filter, as well as the pagination filters applied as part of the query.

NOTE: The default Pagination filter of 200 records per page will be applied unless an alternate pagination filter is included in the URI. (See Filters for instructions.)

Sample Sorting Calls

  • Sort by Transaction date and list in descending order (newest-to-oldest)

    Method: GET
    URI: /v4/payment?sortby=paymentdate&direction=desc
  • List all ACH transactions and then all Credit Card transactions

    Method: GET
    URI: /v4/payment?sortby=paymenttype&direction=ascending
  • List all ACH Returns first then list all other transactions.

    Method: GET
    URI: /v4/payment?sortby=returndate&direction=descending
  • List all settled transactions first from newest to oldest.

    Method: GET
    URI: /v4/payment?sortby=ActualSettledDate&direction=desc

Payment List Request Examples

Payment list sorting, filtering, and paging can be combined to create any type of response you require. Additionally all payment lists can return either complete or “lite” records, though a single response cannot contain both. The following are representative samples of compound Payment List Requests and the associated Responses.

NOTE: These examples purposely use small page sizes in order to keep the Response displays readable.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Payment List Example 1: Default Payment List Response (200 most recent transactions)

JSON
Request: Method = GET
URI = /v4/payment
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4524,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Payment List Example 2: 500 Record Payment List Response (500 most recent transactions)

JSON
Request: Method = GET
URI = /v4/payment?pagesize=500
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4524,
        "Page": 1,
        "ItemsPerPage": 500
}
                                

Payment List Example 3: Default Payment List Page Two Response (second most recent 200 transactions)

JSON
Request: Method = GET
URI = /v4/payment?page=2
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4524,
        "Page": 2,
        "ItemsPerPage": 200
}
                                

Payment List Example 4: 10 Payments per Page, Page 3 Response (the third most recent 10 transactions)

JSON
Request: Method = GET
URI = /v4/payment?page=3&pagesize=10
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4524,
        "Page": 3,
        "ItemsPerPage": 10
}
                                

Sample Default Payment List Response with Page and Page Size Filters Applied

JSON
Request: Method = GET
URI = /v4/payment?page=3&pagesize=2
Response:

{
"Meta": {
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4524,
        "Page": 2,
        "ItemsPerPage": 2
    }
},
"Response": [{
    "CustomerId": 94274,
    "CustomerFirstName": "Sam",
    "CustomerLastName": "Pell",
    "CustomerCompany": "",
    "ReferenceId": 0,
    "Status": "Authorized",
    "RecurringScheduleId": 5471,
    "PaymentType": "CC",
    "PaymentSubType": "Moto",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "699339",
    "PaymentDate": "2013-10-16T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-18T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-17T02:45:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
    },
    "AccountId": 56365,
    "InvoiceId": null,
    "Amount": 5,
    "IsDebit": false,
    "InvoiceNumber": "",
    "PurchaseOrderNumber": "",
    "OrderId": null,
    "Description": "",
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1611042,
    "LastModified": "2013-10-16T07:30:42Z",
    "CreatedOn": "2013-10-16T07:30:42Z"
}, {
    "CustomerId": 180379,
    "CustomerFirstName": "Sam",
    "CustomerLastName": "Pell",
    "CustomerCompany": "",
    "ReferenceId": 0,
    "Status": "Authorized",
    "RecurringScheduleId": 92298,
    "PaymentType": "CC",
    "PaymentSubType": "Moto",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "936374",
    "PaymentDate": "2013-10-16T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-18T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-17T02:45:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null,
        "IsDecline": false
    },
    "AccountId": 285900,
    "InvoiceId": null,
    "Amount": 10,
    "IsDebit": false,
    "InvoiceNumber": "",
    "PurchaseOrderNumber": "",
    "OrderId": null,
    "Description": "",
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1610854,
    "LastModified": "2013-10-16T07:30:23Z",
    "CreatedOn": "2013-10-16T07:30:23Z"
}]
                                

Sample Lite Payment List Response with Page and Page Size Filters Applied

JSON
Request: Method = GET
URI = /v4/payment?page=3&pagesize=2&lite=true
Response:

{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 4524,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "Status": "Authorized",
        "PaymentDate": "2013-10-16T06:00:00Z",
        "Amount": 5,
        "Id": 1611042
    }, {
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "Status": "Authorized",
        "PaymentDate": "2013-10-16T06:00:00Z",
        "Amount": 10,
        "Id": 1610854
    }]
}
                                

Date Filter Example 1: Default Payment List Response

JSON
Request: Method = GET
URI = /v4/payment
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4524,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Date Filter Example 2: All Transactions On or After October 1, 2013

JSON
Request: Method = GET
URI = /v4/payment?startdate=2013-10-01
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 152,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Date Filter Example 3: All Transactions On or Before January 1, 2013

JSON
Request: Method = GET
URI = /v4/payment?enddate=2013-01-01
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 2205,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Date Filter Example 4: All Transactions Between January 1, 2013 and October 1, 2013

JSON
Request: Method = GET
URI = /v4/payment?startdate=startdate=2013-01-01&enddate=2013-10-01
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 2187,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Sample Lite Payment List Response with Start and End Date Filters Applied

JSON
Request: Method = GET
URI = /v4/payment?startdate=2013-10-01&enddate=2013-10-05&lite=true
Response:

{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerFirstName": "Lisa",
        "CustomerLastName": "Test",
        "Status": "Settled",
        "PaymentDate": "2013-10-01T06:00:00Z",
        "Amount": 10,
        "Id": 1602336
    }, {
        "CustomerFirstName": "Lisa",
        "CustomerLastName": "Test",
        "Status": "Settled",
        "PaymentDate": "2013-10-01T06:00:00Z",
        "Amount": 20,
        "Id": 1602283
    }, {
        "CustomerFirstName": "Lisa",
        "CustomerLastName": "Test",
        "Status": "Settled",
        "PaymentDate": "2013-10-01T06:00:00Z",
        "Amount": 10,
        "Id": 1602282
    }]
}
                                

Status Filter Example 1: Default Payment List Response including all Statuses

JSON
Request: Method = GET
URI = /v4/payment
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4524,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Status Filter Example 2: All Authorized Payments

JSON
Request: Method = GET
URI = /v4/payment?status=authorized
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 6,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Status Filter Example 3: All Returned ACH Transactions (Status = Returned and ReverseNSF)

JSON
Request: Method = GET
URI = /v4/payment?status=returned,reversensf
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Status Filter Example 4: All Transactions Involved in Refunds (Status = Reversed and ReversePosted and RefundSettled)

JSON
Request: Method = GET
URI = /v4/payment?status=reversed,reverseposted,refundsettled
Response Meta

{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 146,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Sample Lite Payment List Response with “Failed” Status Filter Applied

JSON
Request: Method = GET
URI = /v4/payment?status=failed&lite=true
Response:

{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Failed",
        "PaymentDate": "2013-10-15T06:00:00Z",
        "Amount": 9.44,
        "Id": 1610692
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Failed",
        "PaymentDate": "2013-10-15T06:00:00Z",
        "Amount": 8.44,
        "Id": 1610691
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Failed",
        "PaymentDate": "2013-10-15T06:00:00Z",
        "Amount": 4.44,
        "Id": 1610684
      }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Failed",
        "PaymentDate": "2013-10-11T06:00:00Z",
        "Amount": 7.25,
        "Id": 1608327
    }]
}
                                

All Settled Payments Processed in October, 2013; Sorted by Amount in Descending Order, Lite Record, 2 Payment Records per page, show page 1.

JSON
Request: Method = GET
URI = /v4/payment?status=settled&startdate=2013-10-01&enddate=2013-10-31 &sortby=Amount&direction=DESC&lite=true&page=1&pagesize=2
Response:

{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 22,
            "Page": 1,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-10-11T06:00:00Z",
        "Amount": 48,
        "Id": 1608315
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-10-11T06:00:00Z",
        "Amount": 48,
        "Id": 1608316
    }]
}
                                

All Payments Processed in Q1, 2013; Sorted by Settle Date, oldest-to-newest, 2 Payment Records per page, show page 2.

JSON
Request: Method = GET
URI = /v4/payment?startdate=2013-01-01&enddate=2013-03-31 &sortby=ActualSettledDate&
direction=ASC&page=2&pagesize=2 Response: { "Meta": { "Errors": null, "HttpStatus": "OK", "HttpStatusCode": 200, "PagingDetails": { "TotalItems": 2325, "Page": 2, "ItemsPerPage": 2 } }, "Response": [{ "CustomerId": 94659, "CustomerFirstName": "Rose", "CustomerLastName": "Tyler", "CustomerCompany": "", "ReferenceId": 0, "Status": "Settled", "RecurringScheduleId": 4698, "PaymentType": "CC", "PaymentSubType": "Moto", "ProviderAuthCode": "Approved", "TraceNumber": "TAS110", "PaymentDate": "2013-01-22T07:00:00Z", "ReturnDate": null, "EstimatedSettleDate": "2013-01-24T07:00:00Z", "ActualSettledDate": null, "CanVoidUntil": "2013-01-23T03:45:00Z", "FailureData": { "Code": null, "Description": null, "MerchantActionText": null, "IsDecline": false }, "AccountId": 298301, "InvoiceId": null, "Amount": 120, "IsDebit": false, "InvoiceNumber": "", "PurchaseOrderNumber": "", "OrderId": null, "Description": "", "Latitude": null, "Longitude": null, "SuccessReceiptOptions": null, "FailureReceiptOptions": null, "Id": 935887, "LastModified": "2013-01-23T00:07:28Z", "CreatedOn": "2013-01-22T15:51:44Z" }, { "CustomerId": 180379, "CustomerFirstName": "Sam", "CustomerLastName": "Pell", "CustomerCompany": "", "ReferenceId": 0, "Status": "Settled”, "RecurringScheduleId": 92301,” "PaymentType": "CC", "PaymentSubType": "Moto", "ProviderAuthCode": "Approved", "TraceNumber": "TAS399", "PaymentDate": "2013-01-23T07:00:00Z", "ReturnDate": null, "EstimatedSettleDate": "2013-01-25T07:00:00Z", "ActualSettledDate": null, "CanVoidUntil": "2013-01-24T03:45:00Z", "FailureData": { "Code": null, "Description": null, "MerchantActionText": null, "IsDecline": false }, "AccountId": 285900, "InvoiceId": null, "Amount": 10, "IsDebit": false, "InvoiceNumber": "", "PurchaseOrderNumber": "", "OrderId": null, "Description": "", "Latitude": null, "Longitude": null, "SuccessReceiptOptions": null, "FailureReceiptOptions": null, "Id": 937823, "LastModified": "2013-01-23T18:31:05Z", "CreatedOn": "2013-01-23T15:33:55Z" }] }

All transactions entered on the current date sorted by ascending expected settle date, 2 Records per page, show page 3.

JSON
Request: Method = GET
URI = /v4/payment?startdate=2013-10-17&enddate=2013-10-17 &sortby=EstimatedSettleDate& direction=ASC&page=3&pagesize=2
Response:

{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 6,
            "Page": 3,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerId": 94274,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "CustomerCompany": "",
        "ReferenceId": 0,
        "Status": "Authorized",
        "RecurringScheduleId": 6063,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "Approved",
        "TraceNumber": "525632",
        "PaymentDate": "2013-10-17T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-10-21T06:00:00Z",
        "ActualSettledDate": null,
        "CanVoidUntil": "2013-10-18T02:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null,
            "IsDecline": false
        },
        "AccountId": 54576,
        "InvoiceId": null,
        "Amount": 100,
        "IsDebit": false,
        "InvoiceNumber": "",
        "PurchaseOrderNumber": "",
        "OrderId": null,
        "Description": "",
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1611522,
        "LastModified": "2013-10-17T07:30:31Z",
        "CreatedOn": "2013-10-17T07:30:31Z"
    }, {
        "CustomerId": 94274,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "CustomerCompany": "",
        "ReferenceId": 0,
        "Status": "Authorized",
        "RecurringScheduleId": 5471,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "Approved",
        "TraceNumber": "681924",
        "PaymentDate": "2013-10-17T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-10-22T06:00:00Z",
        "ActualSettledDate": null,
        "CanVoidUntil": "2013-10-18T02:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null,
            "IsDecline": false
        },
        "AccountId": 56365,
        "InvoiceId": null,
        "Amount": 5,
        "IsDebit": false,
        "InvoiceNumber": "",
        "PurchaseOrderNumber": "",
        "OrderId": null,
        "Description": "",
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1611594,
        "LastModified": "2013-10-17T07:30:39Z",
        "CreatedOn": "2013-10-17T07:30:39Z"
    }]
}
                                

Payment Schedules

Payment Schedule Basics

Payment Schedule Basics

There are two types of payment schedules:

Recurring Payments: Schedules configured to charge a set amount for a set period of time, or indefinitely.

Payment Plans: Schedule configured to discharge a set amount via a set number of payments.

Each of the above uses a distinct Schedule Object as follows:

Recurring Payment Schedule = recurringpayment

Payment Plan Schedule = paymentplan

When creating a new schedule, be certain to use the correct object type. When generating lists of schedules you can use the GET /v4/paymentschedule route to return a list of all schedules, but it will return abbreviated records that do not include all schedule fields. If you want your list to include all fields, you will need separate calls for each schedule type, as there is no way to use a single call to return complete objects of both types.

Also note that there is currently no way to configure settings for new schedule notification emails, transaction receipt emails, transaction failure emails, and pre-notification emails for schedules entered via the API. All schedules created via the API will use the default email configuration settings for the Client account.

The following sections provide basic examples for creating Recurring Payment and Payment Plan schedules.

Recurring Payment Schedule Basics

If you know the AccountId for the credit card or bank account you want to charge, entering a recurring payment schedule via the 4.0 API can be as simple as entering the payment amount, start date, and frequency along with that AccountId.

To create a new Recurring Payment Object via the API:

  • Method = POST
  • URI = /v4/recurringpayment
  • Request = Recurring Payment Object Attributes: AccountId, Amount, StartDate,ExecutionFrequencyType, and ExecutionFrequencyParameter if required.

Key Recurring Payment Object Response Attributes

Id: Integer -- this is the ScheduleId number you will need to reference in future calls related to this schedule including pause, suspend, resume, and view details.

ScheduleStatus: Integer -- schedule Status set by the system.
Enumeration: 1 = Active; 3 = Expired; 4 = Suspended

Expected Response for new schedule is “Active.”

PaymentAmount: Number-- the amount of each scheduled payment, as specified in the Recurring Payment Request. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 23.129 will result in a PaymentAmount of 23.13.

StartDate: String -- the date on which the schedule will start running, not necessarily the date it will generate its first payment, as specified in the Recurring Payment Request. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

NOTE: To make schedule management easier, it is strongly recommended that you set the schedule StartDate to the first day it will generate a payment.

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)


NOTE: If you configured the schedule to start on the current day the StartDate will be the current date and the NextScheduleDate will be the future date of the second scheduled payment. If the schedule was configured to start on the future date of its first scheduled payment, StartDate and NextSchduleDate will be the same future date.

The above assumes you are starting with a valid AccountId, which assumes an existing Customer Object with existing Payment Account Objects attached to it. In many instances this will not be the case. The following sections cover the complete process for entering recurring payment schedules for completely new customers, for existing customers with existing payment accounts, and for existing customers with new payment accounts. Within each section all relevant Object Attributes are fully defined.

Sample Basic New Recurring Payment Object Request

JSON
{
    "PaymentAmount": 12,
    "AccountId":  395560,
    "StartDate": "2013-10-28",
    "ExecutionFrequencyType": 4 (enumeration for “First of Month”)
}
                                

Sample New Recurring Payment Object Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-01T06:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 0,
    "NumberOfPaymentsMade": 0,
    "EndDate": null,
    "PaymentAmount": 12,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "FirstofMonth",
    "ExecutionFrequencyParameter": 1,
    "Description": null,
    "Id": 118169,
    "LastModified": "2013-10-28T21:42:19.5051617Z",
    "CreatedOn": "2013-10-28T21:42:19.5051617Z"
}
                                

Payment Plan Schedule Basics

If you know the AccountId for the credit card or bank account you want to charge, entering a payment plan schedule via the 4.0 API can be as simple as entering the schedule amount, start date, number of payments, and frequency along with that AccountId. To create a new Payment Plan Object via the API: • Method = POST • URI = /v4/paymentplan • Request = Payment Object Attributes: AccountId, TotalDueAmount, TotalNumberOfPayments, StartDate,ExecutionFrequencyType and ExecutionFrequencyParameter, if required.

Key Payment Plan Object Response Attributes

Id: Integer -- this is the ScheduleId number you will need to reference in future calls related to this schedule including pause, suspend, resume, and view details.

ScheduleStatus: Integer -- schedule Status set by the system.
Enumeration: 1 = Active; 3 = Expired; 4 = Suspended

Expected Response for new schedule is “Active.”

PaymentAmount: Number -- the system calculated amount of each scheduled payment
PaymentAmount = (TotalAmountDue - CustomFirstPaymentAmount) / NumberofPayments.

StartDate: String -- the date on which the schedule will start running, not necessarily the date it will generate its first payment. Date format YYYY-MM-DD

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DD.

NOTE: If you configured the schedule to start on the current day the StartDate will be the current date and the NextScheduleDate will be a future date. If the schedule was configured to start on a future date, StartDate and NextSchduleDatewill be the same future date.

The above assumes you are starting with a valid AccountId, which assumes an existing Customer Object with existing Payment Account Objects attached to it. In many instances this will not be the case. The following sections cover the complete process for entering payment plan schedules for completely new customers, for existing customers with existing payment accounts, and for existing customers with new payment accounts. Within each section all relevant Object Attributes are fully defined.

 

 

 

 

 

 

Sample Basic New Payment Plan Object Request

JSON
{
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "AccountId": 395560,
    "StartDate": "2013-10-28",
    "ExecutionFrequencyType": 6 (enumeration for last of month)
}
                                

Sample New Payment Plan Object Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-10-31T06:00:00Z",
    "BalanceRemaining": 0,
    "NumberOfPaymentsRemaining": 5,
    "PauseUntilDate": null,
    "PaymentAmount": 20,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 0,
    "NumberOfPaymentsMade": 0,
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "LastofMonth",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118171,
    "LastModified": "2013-10-28T21:59:00.280007Z",
    "CreatedOn": "2013-10-28T21:59:00.280007Z"
}
                                

Entering a Recurring Payment Schedule for a New Customer

Entering a Recurring Payment schedule for a new customer using the API is accomplished using three sequential steps:

  1. Creating a new Customer Object
  2. Adding a Payment Account Object to the Customer Object created in Step 1.
  3. Creating a Recurring Payment Object using the Payment Account Object created in Step 2.

Attributes for each of the Object Types are defined below, as are the Request and Response Information associated with utilizing them to create customers and enter schedules.

Customer Object

To create a new Customer Object via the API:

  • Method = POST
  • URI = /v4/customer
  • Request = Customer Object Attributes
  • Response Attribute Needed = “CustomerId”

Customer Object Attributes

Required Attributes

FirstName: String -- 150 characters max

LastName: String -- 150 characters max

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. Set to “false” to require ShippingAddress fields.

Optional Attributes

BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

Company: String -- 50 characters max

CustomerAccount: String -- 28 characters max. This is a non-system account number you can assign.

Phone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

AltPhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

MobilePhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Fax: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Email: String -- 100 characters max, must be a valid email address.

AltEmail: String -- 100 characters max, must be a valid email address.

Website: String -- 100 characters max, must be in URL format.

Notes: String -- 2048 characters max; an open text field.

System Attributes

These fields are required components of the Customer Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the CustomerId in the Response

LastModified: String -- set by system, any Request data will be disregarded.

CreatedOn: String -- set by system, any Request data will be disregarded.

Sample New Customer Object Request

JSON
POST /v4/customer
{
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": null,
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "testperson@abcco.com",
    "Phone": "8005551212",
}
                                

Payment Account Objects

Credit Card Account Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.

CreditCardNumber: String -- 15 or 16 digits

ExpirationDate: String -- a valid date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

IsDefault: Boolean -- enter “true” to set the card as the default Credit Card Account for the Customer Record, otherwise enter “false.” If there are no other cards attached to the Customer Record, the field will default to “true” regardless of your entry.

Optional Attributes

BillingZipCode: String -- max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

System Attributes

These fields are required components of the Credit Card Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded.

CreatedOn: String -- set by system, any Request data will be disregarded.

Sample New Credit Card Account Object Request

JSON
{
    "CreditCardNumber": "4111111111111111",
    "ExpirationDate": "12/2015",
    "Issuer": "12",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New Credit Card Account Object Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36.6661404Z",
    "CreatedOn": "2013-10-11T17:41:36.6661404Z"
}
                                

ACH Account Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- min 4 digits, max 100 digits; the bank account number

BankName: String-- 100 characters max; the financial institution name

IsCheckingAccount: Boolean -- enter “true” to indicate a checking account or “false” to indicate a savings account. General Ledger accounts are not supported.

IsDefault: Boolean -- enter “true” to set the account as the default ACH Account for the Customer Record, otherwise enter “false.” If there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of your entry.

System Attributes

These fields are required components of the ACH Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

 

 

Sample New ACH Account Object Request

JSON
{
    "IsCheckingAccount": "true",
    "RoutingNumber": "072000326",
    "AccountNumber": "751666666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": "true",
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New ACH Account Object Response

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56.7441402Z",
    "CreatedOn": "2013-10-11T17:54:56.7441402Z"
}
                                

Recurring Payment Object

This section covers entering a recurring payment schedule. Note that the system determines the type of payment (ACH or Credit Card) based on the account type of the AccountId provided.

To create a new Recurring Payment Object via the API:

  • Method = POST
  • URI = /v4/recurringpayment
  • Request = Recurring Payment Object Attributes

Recurring Payment Object Request Attributes

Required Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule. This is the “Id” attribute from the Credit Card Object or ACH Account Object created in the previous step. The Customer Object associated with the AccountId will be associated with the schedule.

PaymentAmount: Number -- the scheduled payment amount. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 3.129 will result in a PaymentAmount of 3.13.

StartDate: String -- the date on which the schedule will start running, not necessarily the date it will generate its first payment. Date format YYYY-MM-DD.
NOTE: To make schedule management easier, it is strongly recommended that you set the schedule StartDate to the first day it will generate a payment.

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments.

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

Optional Attributes</p>

EndDate: String-- the date the schedule is to stop generating payments. If not included or left null, the schedule will default to running until manually disabled. Date format: YYYY-MM-DD.

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.

NOTE: To ensure that you do not collect more than the amount due for the system invoice it is better to use a Payment Plan schedule (instead of a recurring billing schedule) to discharge a system invoice.

NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31

NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

Description: String-- -- 2048 characters max.

System Attributes

These fields are required components of the Recurring Payment Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the ScheduleId in the Response.

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Recurring Payment Object Response Attributes

Key Attributes

Id: Integer -- this is the ScheduleId number you will need to reference in future calls related to this schedule including pause, suspend, resume, and view details.

ScheduleStatus: Integer -- schedule Status set by the system.
Enumeration: 1 = Active; 3 = Expired; 4 = Suspended

Expected Response for new schedule is “Active.”

PaymentAmount: Number-- the amount of each scheduled payment, as specified in the Recurring Payment Request.

StartDate: String -- the date on which the schedule will start running, not necessarily the date it will generate its first payment, as specified in the Recurring Payment Request. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

NOTE: If you configured the schedule to start on the current day the StartDate will be the current date and the NextScheduleDate will be the future date of the second scheduled payment. If the schedule was configured to start on the future date of its first scheduled payment, StartDate and NextSchduleDate will be the same future date.

Other Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment.

CustomerFirstName: String -- the first name of the Customer associated with the payment.

CustomerLastName: String -- the last name of the Customer associated with the payment.

CustomerCompany: String -- the Company, if any, associated with the payment.

PauseUntilDate: String -- the date a paused schedule is or was set to resume. If the schedule status is “suspended” this is the date it will automatically resume. If the schedule status is “Active” or “Expired” and this field has a value, it is the most recent date on which the schedule resumed. For schedules that have never been paused, this value will be null.

NOTE: The PauseUntilDate field does not re-set to “null” once a paused schedule resumes. This field will always contain the date on which the schedule was last re-activated.

FirstPaymentDone: Boolean-- if any payment (either the custom first payment or the first scheduled payment) has been generated by the schedule this attribute will be “true” and the schedule can no longer be deleted. If no payment activity has been generated by the schedule, this attribute will be “false.” This is a read-only system field.

DateOfLastPaymentMade: String-- a read only system field indicating the last date a scheduled payment (not a custom first payment) was generated by the schedule. If the schedule has not yet generated a payment this field will be null.

TotalAmountPaid: Number-- a read only system field indicating the sum of all payments, including any custom first payment, generated by the schedule.

NumberOfPaymentsMade: Integer-- a read only system field indicating the number of regular payments (not including any custom first payment) generated by the schedule.

EndDate: String-- the date specified in the Recurring Payment Request for the schedule to stop generating payments (status changes to “Expired”). If the schedule is programmed to run indefinitely, this field will be null. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

PaymentSubType: Integer -- the type of Credit Card or ACH payment. It defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null. Other Values include “Swipe” for CC and “PPD,” “CCD,” and “TEL” for ACH.

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule, as specified in the Recurring Payment Request.

InvoiceNumber: String -- -- the InvoiceNumber, if any, specified in the Recurring Payment Request.

OrderId: String -- the OrderId, if any, specified in the Recurring Payment Request.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. The value specified in the Recurring Payment Request, rounded to 2 decimal places, is displayed here. If no custom first payment was configured, this field will be null.

FirstPaymentDate: String-- the date the custom first payment is to be processed. The value specified in the Recurring Payment Request. If no custom first payment was configured, this field will be null. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments, as specified in the Recurring Payment Request. (The Response displays the text not the integer.)

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

ExecutionFrequencyParameter: Integer --  the day of month for a Specific Day of Month schedule or the day of the week for a weekly or bi-weekly schedule, as specified in the Recurring Payment Request.For all other Frequency Types this field will be 0.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: An integer from 1 -31

Description: String -- the Description, if any, specified in the Recurring Payment Request.

LastModified: String -- set by the system, the date and time the schedule object was last modified.

CreatedOn: String -- set by the system, the date and time the schedule object was created.

Sample New Recurring Payment Object Requests

JSON
Simple
{
    "AccountId": 395564,
    "Amount": 21,
    "StartDate": "2013-11-01",
    "ExecutionFrequencyType": 4

   }
Full
{
    "EndDate": "2014-10-31",
    "PaymentAmount": 21,
    "PaymentSubType": "PPD",
    "AccountId": 395564,
    "InvoiceNumber": "123A",
    "OrderId": null,
    "FirstPaymentAmount": 25,
    "FirstPaymentDate": "2013-10-29",
    "StartDate": "2013-11-04",
    "ExecutionFrequencyType": 5,
    "ExecutionFrequencyParameter": 4,
    "Description": "This is a recurring payment schedule entered via the API
}
                                

Sample New Recurring Payment Object Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-04T07:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": true,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 25,
    "NumberOfPaymentsMade": 0,
    "EndDate": "2014-10-31T06:00:00Z",
    "PaymentAmount": 21,
    "PaymentSubType": "Ppd",
    "AccountId": 395564,
    "InvoiceNumber": "123A",
    "OrderId": null,
    "FirstPaymentAmount": 25,
    "FirstPaymentDate": "2013-10-29T06:00:00Z",
    "StartDate": "2013-11-04T07:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "SpecificDayofMonth",
    "ExecutionFrequencyParameter": 4,
    "Description": "This is a recurring payment schedule entered via the API.",
    "Id": 118215,
    "LastModified": "2013-10-29T16:49:21.7538167Z",
    "CreatedOn": "2013-10-29T16:49:21.7538167Z"
}
                                

Entering a Recurring Payment Schedule for an Existing Customer

Entering a recurring payment schedule for an existing customer using the API is accomplished using three sequential steps:

  1. Retrieve the CustomerId
  2. Retrieve an existing AccountId or create a new Payment Account Object.
  3. Create a Recurring Payment Object using the Payment Account created or retrieved in Step 2.

If you maintain your own database of CustomerIds and associated AccountIds you can complete steps 1 and 2 in your system, and then utilize the PaySimple API only for creating the recurring payment schedule (step 3).

If you only maintain a database for CustomerId, you can begin with Step 2.

Attributes needed for each of the Object Types are defined below, as are the Request and Response Information associated with utilizing them to enter recurring payment schedules for existing customers using new and existing payment accounts.

Retrieve the CustomerId

If you know the CustomerId for the customer you want to charge (for example if you have it stored in your own database), then you can skip this step.

If you need to retrieve the CustomerId attribute for the Customer Object you want to charge, you will need to search for the Customer Record to obtain it. To Search via the API:

  • Method = GET
  • URI = /v4/globalSearch?Query="[value]"
  • Query = {Customer Name or Company Name}
  • Response Attribute Needed = “OriginId”
    NOTE: The Search OriginId for a Customer Object is equal to its CustomerId

 

 

 

 

 

Sample Customer Search Request

JSON
URI = /v4/globalSearch?Query="ABC Company"
                                

Sample Customer Search Response

JSON
{
    "Results": [{
        "OriginKey": "CUST",
        "OriginId": 255939,
        "Description": "Customer: Test Person From: ABC Company",
        "Ranking": 176
}
                                

Create the AccountId

When entering a recurring payment schedule for an existing customer you have the option of charging the default ACH or CC account, charging any non-default ACH or CC account, or entering a new ACH or CC account as part of the schedule entry process. Each of these processes, and its associated Objects and Attributes, are described in the following sections.

Using the Default Credit Card Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve the default credit card AccountId.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/defaultcreditcard
  • Response Attribute Needed = “AccountId”

Credit Card Object Response Attributes

CreditCardNumber: String -- the last four digits of the card number

NOTE: For security purposes, full account numbers are never displayed in Responses.

ExpirationDate: String -- the expiration date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

BillingZipCode: String -- the zip code attached to the credit card if saved with the Payment Account record. If null, the ZipCode attribute for the Customer object will be used for processing the payment.

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate that you have indeed retrieved the default credit card.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the Credit Card Account Object was last changed.

CreatedOn: String -- the date the Credit Card Account Object was created.

Using the Default ACH Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve the default ACH AccountId.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/defaultach
  • Response Attribute Needed = “AccountId”

ACH Object Attributes

IsCheckingAccount: Boolean -- “true” to indicates a checking account and “false” indicates a savings account. General Ledger accounts are not supported.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- last four digits of the bank account number.
                               

NOTE: For security purposes, full account numbers are never displayed in Responses.

BankName: String-- the financial institution name

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate that you have indeed retrieved the default ACH account.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the ACH Account Object was last changed.

CreatedOn: String -- the date the ACH Account Object was created.

Using an Existing Credit Card Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve all of the Credit Card Account Objects associated with the Customer Record, then copy the AccountId of the one you want to use for the schedule.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/creditcardaccounts
  • Response Attribute Needed = “AccountId” for the account you want to charge.

Account List Credit Card Object Response Attributes

CreditCardNumber: String -- the last four digits of the card number

NOTE: For security purposes, full account numbers are never displayed in Responses.

ExpirationDate: String -- the expiration date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

BillingZipCode: String -- the zip code attached to the credit card if saved with the Payment Account record. If null, the ZipCode attribute for the Customer object will be used for processing the payment.

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate that you have indeed retrieved the default credit card.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the Credit Card Account Object was last changed.

CreatedOn: String -- the date the Credit Card Account Object was created.

You will need to determine which of the returned Credit Cards you want to use for the schedule, and retrieve it’s AccountId for the next step.

Alternate Route to Obtain an Existing Credit Card AccountId

If you do not want to select from one of the saved accounts, you can treat all credit cards as new. (Follow the steps in the Using a New Credit Card Account section.) The system will recognize the duplicate (and update the expiration date if necessary), and the Credit Card Object Response will contain the existing AccountId.

Using an Existing ACH Payment Account

Use the CustomerId obtained in Step 1 (or saved in your database) to retrieve all of the ACH Account Objects associated with the Customer Record, then copy the AccountId of the one you want to use for the schedule.

  • Method = GET
  • URI = /v4/customer/{CustomerId}/achaccounts
  • Response Attribute Needed = “AccountId” for the account you want to charge.

Account List ACH Object Response Attributes

IsCheckingAccount: Boolean -- “true” to indicates a checking account and “false” indicates a savings account. General Ledger accounts are not supported.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- last four digits of the bank account number.

NOTE: For security purposes, full account numbers are never displayed in Responses.

BankName: String-- the financial institution name

CustomerId: Integer -- the system identifier for the Customer Record to which the card is attached. This is the “CustomerId” attribute you entered in the URI.

IsDefault: Boolean -- this will be “true” to indicate that you have indeed retrieved the default ACH account.

Id: Integer -- This is the AccountId you need for the next step.

LastModified: String -- the date the ACH Account Object was last changed.

CreatedOn: String -- the date the ACH Account Object was created.

You will need to determine which of the returned bank accounts you want to use for the schedule, and retrieve it’s AccountId for the next step.

Using a New Credit Card Account

Use the CustomerId obtained in Step 1 (or saved in your database) to attach a new Credit Card Payment Account Object via the API, then note the AccountId for the new credit card account.

  • Method = POST
  • URI = /v4/account/creditcard
  • Request = Credit Card Attributes
  • Response Attribute Needed = “Account Id”

Required Credit Card Account Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the CustomerId you retrieved from your database, or in the first step.

CreditCardNumber: String -- 15 or 16 digits

ExpirationDate: String -- a valid date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

IsDefault: Boolean -- enter “true” to set the card as the default Credit Card Account for the Customer Record, otherwise enter “false.” If there are no other cards attached to the Customer Record, the field will default to “true” regardless of your entry.

Optional Credit Card Account Object Request Attributes

BillingZipCode: String -- max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

System Credit Card Account Object Attributes

These fields are required components of the Credit Card Account Object that are populated by the system-- you do not need to include them in your requests.

 

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Using a New ACH Account

Use the CustomerId obtained in Step 1 (or saved in your database) to attach a new ACH Payment Account Object via the API, then note the AccountId for the new bank account.

  • Method = POST
  • URI = /v4/account/ach
  • Request = ACH Account Attributes
  • Response Attribute Needed = “AccountId”

Required ACH Account Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the CustomerId you retrieved from your database, or in the first step.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- min 4 digits, max 100 digits; the bank account number

BankName: String-- 100 characters max; the financial institution name

IsCheckingAccount: Boolean -- enter “true” to indicate a checking account or “false” to indicate a savings account. General Ledger accounts are not supported.

IsDefault: Boolean -- enter “true” to set the account as the default ACH Account for the Customer Record, otherwise enter “false.” If there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of your entry.

System ACH Account Object Attributes

These fields are required components of the ACH Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response.

LastModified: String -- set by system, any Request data will be disregarded.

CreatedOn: String -- set by system, any Request data will be disregarded.

Sample Default Credit Card Request

JSON
URI = /v4/customer/255939/defaultcreditcard
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}
                                

Sample New Credit Card Account Object Request

JSON
{
    "CreditCardNumber": "4111111111111111",
    "ExpirationDate": "12/2015",
    "Issuer": 12,
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New Credit Card Account Object Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36.6661404Z",
    "CreatedOn": "2013-10-11T17:41:36.6661404Z"
}
                                

Sample Default ACH Request

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}
                                

Sample Credit Card Accounts Request

JSON
URI = /v4/customer/255939/creditcardaccounts
                                

Sample Credit Card Accounts Response

JSON
[{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}, {
    "CreditCardNumber": "************5454",
    "ExpirationDate": "08/2018",
    "Issuer": "Master",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396036,
    "LastModified": "2013-10-15T18:33:25Z",
    "CreatedOn": "2013-10-15T18:33:25Z"
}]
                                

Sample ACH Accounts Request

JSON
URI = /v4/customer/255939/achaccounts
                                

Sample ACH Accounts Response

JSON
[{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}, {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396037,
    "LastModified": "2013-10-15T18:33:56Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
}]
                                

Sample New ACH Account Object Request

JSON
{
    "IsCheckingAccount": "true",
    "RoutingNumber": "072000326",
    "AccountNumber": "751666666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": "true",
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New ACH Account Object Response

JSON
{
    "IsCheckingAccount": "true",
    "RoutingNumber": "072000326",
    "AccountNumber": "751666666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": "true",
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Create a New Recurring Payment Object

Entering a Payment Plan Schedule for a New Customer

Entering a Payment Plan schedule for a new customer using the API is accomplished using three sequential steps:

  1. Creating a new Customer Object
  2. Adding a Payment Account Object to the Customer Object created in Step 1.
  3. Creating a Payment Plan Object using the Payment Account Object created in Step 2.

Attributes for each of the Object Types are defined below, as are the Request and Response Information associated with utilizing them to create customers and enter schedules.

Customer Object

To create a new Customer Object via the API:

  • Method = POST
  • URI = /v4/customer
  • Request = Customer Object Attributes
  • Response Attribute Needed = “CustomerId”

Customer Object Attributes

Required Attributes

FirstName: String -- 150 characters max

LastName: String -- 150 characters max

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. Set to “false” to require ShippingAddress fields.

Optional Attributes

BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

Company: String -- 50 characters max

CustomerAccount: String -- 28 characters max. This is a non-system account number you can assign.

Phone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

AltPhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

MobilePhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Fax: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Email: String -- 100 characters max, must be a valid email address.

AltEmail: String -- 100 characters max, must be a valid email address.

Website: String -- 100 characters max, must be in URL format.

Notes: String -- 2048 characters max; an open text field.

System Attributes

These fields are required components of the Customer Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the CustomerId in the Response

LastModified: String -- set by system, any Request data will be disregarded.

CreatedOn: String -- set by system, any Request data will be disregarded.

Sample New Customer Object Request

JSON
POST /v4/customer
{
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": null,
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "testperson@abcco.com",
    "Phone": "8005551212",
}
                                

Sample New Customer Object Response

JSON
"Response": {
    "AltEmail": null,
    "AltPhone": null,
    "MobilePhone": null,
    "Fax": null,
    "Website": null,
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "testperson@abcco.com",
    "Phone": "8005551212",
    "Id": 255939,
    "LastModified": "2013-10-01T19:16:38.5061103Z",
    "CreatedOn": "2013-10-01T19:16:38.5061103Z"
}
                                

Payment Account Objects

To create a new Payment Account Object via the API:

  • Method = POST
  • URI = /v4/account/creditcard or /v4/account/ach
  • Request = Credit Card Attributes or ACH Attributes
  • Response Attribute Needed = “Account Id”

Credit Card Account Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.

CreditCardNumber: String -- 15 or 16 digits

ExpirationDate: String -- a valid date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

IsDefault: Boolean -- enter “true” to set the card as the default Credit Card Account for the Customer Record, otherwise enter “false.” If there are no other cards attached to the Customer Record, the field will default to “true” regardless of your entry.

Optional Attributes

BillingZipCode: String -- max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

System Attributes

These fields are required components of the Credit Card Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded.

CreatedOn: String -- set by system, any Request data will be disregarded.

ACH Account Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- min 4 digits, max 100 digits; the bank account number

BankName: String-- 100 characters max; the financial institution name

IsCheckingAccount: Boolean -- enter “true” to indicate a checking account or “false” to indicate a savings account. General Ledger accounts are not supported.

IsDefault: Boolean -- enter “true” to set the account as the default ACH Account for the Customer Record, otherwise enter “false.” If there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of your entry.

System Attributes

These fields are required components of the ACH Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Sample New Credit Card Account Object Request

JSON
{
    "CreditCardNumber": "4111111111111111",
    "ExpirationDate": "12/2015",
    "Issuer": "12",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New Credit Card Account Object Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36.6661404Z",
    "CreatedOn": "2013-10-11T17:41:36.6661404Z"
}
                                

Sample New ACH Account Object Request

JSON
{
    "IsCheckingAccount": "true",
    "RoutingNumber": "072000326",
    "AccountNumber": "751666666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": "true",
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New ACH Account Object Response

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56.7441402Z",
    "CreatedOn": "2013-10-11T17:54:56.7441402Z"
}
                                

Payment Plan Object

This section covers entering a Payment Plan schedule. Note that the system determines the type of payment (ACH or Credit Card) based on the account type of the AccountId provided.

  • To create a new Payment Plan Object via the API:
  • Method = POST
  • URI = /v4/paymentplan
  • Request = Payment Plan Object Attributes

Payment Plan Object Request Attributes

Required Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule. This is the “Id” attribute from the Credit Card Object or ACH Account Object created in the previous step. The Customer Object associated with the AccountId will be associated with the schedule.

TotalDueAmount: Number -- the total amount to be collected for the schedule. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 300.129 will result in a TotalDueAmount of 300.13.

TotalNumberOfPayments: Integer -- the total number of schedule payments. Enter any integer between 1 and 99.

StartDate: String -- the date on which the schedule will start running, not necessarily the date it will generate its first payment. Date format YYYY-MM-DD.  Date format: YYYY-MM-DD.

NOTE: To make schedule management easier, it is strongly recommended that you set the schedule StartDate to the first day it will generate a payment.

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments.

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

Optional Attributes

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.

NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13. This amount is subtracted from the TotalDueAmount when the system calculates the schedule PaymentAmount.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31
NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

Description: String-- -- 2048 characters max.

System Attributes

These fields are required components of the Recurring Payment Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the ScheduleId in the Response.

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Payment Plan Object Response Attributes

Key Attributes

Id: Integer -- this is the ScheduleId number you will need to reference in future calls related to this schedule including pause, suspend, resume, and view details.

ScheduleStatus: Integer -- schedule Status set by the system.
Enumeration: 1 = Active; 3 = Expired; 4 = Suspended

Expected Response for new schedule is “Active.”

PaymentAmount: Number -- the system calculated amount of each scheduled payment, rounded to the nearest penny.     PaymentAmount = (TotalAmountDue - CustomFirstPaymentAmount) / NumberofPayments.

StartDate: String -- the date on which the schedule will start running, not necessarily the date it will generate its first payment, as specified in the Payment Plan Request. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

NOTE: If you configured the schedule to start on the current day the StartDate will be the current date and the NextScheduleDate will be the future date of the second scheduled payment. If the schedule was configured to start on the future date of its first scheduled payment, StartDate and NextSchduleDate will be the same future date.

Other Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment.

CustomerFirstName: String -- the first name of the Customer associated with the payment.

CustomerLastName: String -- the last name of the Customer associated with the payment.

CustomerCompany: String -- the Company, if any, associated with the payment.

BalanceRemaining: Number-- a read-only system field indicating the total amount still to be collected as part of the schedule. (TotalDueAmount - TotalAmountPaid = BalanceRemaining)

NumberOfPaymentsRemaining: Integer -- a read-only system field indicating the number of payments left to be generated on the schedule. If the schedule has yet to generate a payment, it will be equal to TotalNumberofPayments.

PauseUntilDate: String -- the date a paused schedule is or was set to resume. If the schedule status is “suspended” this is the date it will automatically resume. If the schedule status is “Active” or “Expired” and this field has a value, it is the most recent date on which the schedule resumed. For schedules that have never been paused, this value will be null.

NOTE: The PauseUntilDate field does not re-set to “null” once a paused schedule resumes. This field will always contain the date on which the schedule was last re-activated.

FirstPaymentDone: Boolean-- if any payment (either the custom first payment or the first scheduled payment) has been generated by the schedule this attribute will be “true” and the schedule can no longer be deleted. If no payment activity has been generated by the schedule, this attribute will be “false.” This is a read-only system field.

DateOfLastPaymentMade: String-- a read only system field indicating the last date a scheduled payment (not a custom first payment) was generated by the schedule. If the schedule has not yet generated a payment this field will be null.

TotalAmountPaid: Number-- a read only system field indicating the sum of all payments, including any custom first payment, generated by the schedule.

NumberOfPaymentsMade: Integer-- a read only system field indicating the number of regular payments (not including any custom first payment) generated by the schedule.

TotalDueAmount: Number -- the total amount to be collected for the schedule, as specified in the Payment Plan Request.

TotalNumberOfPayments: Integer -- the total number of schedule payments, as specified in the Payment Plan Request.

PaymentSubType: Integer -- the type of Credit Card or ACH payment. It defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null. Other Values include “Swipe” for CC and “PPD,” “CCD,” and “TEL” for ACH.

AccountID: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule, as specified in the Payment Plan Request.

InvoiceNumber: String -- -- the InvoiceNumber, if any, specified in the Payment Plan Request.

OrderId: String -- the OrderId, if any, specified in the Payment Plan Request.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. The value specified in the Payment Plan Request, rounded to 2 decimal places, is displayed here. If no custom first payment was configured, this field will be null.

FirstPaymentDate: String-- the date the custom first payment is to be processed. The value specified in the Payment Plan Request. If no custom first payment was configured, this field will be null. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments, as specified in the Payment Plan Request. (The Response displays the text not the integer.)

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

ExecutionFrequencyParameter: Integer -- the day of month for a Specific Day of Month schedule or the day of the week for a weekly or bi-weekly schedule, as specified in the Payment Plan Request.For all other Frequency Types this field will be 0.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: An integer from 1 -31

Description: String -- the Description, if any, specified in the Payment Plan Request.

LastModified: String -- set by the system, the date and time the Payment Plan object was last modified.

CreatedOn: String -- set by the system, the date and time the Payment Plan object was created.

Sample New Payment Plan Object Requests

JSON
Simple
{
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "AccountId": 395564,
    "StartDate": "2013-11-01",
    "ExecutionFrequencyType": 4
}

Full
{
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "PaymentSubType": "CCD",
    "AccountId": 395564,
    "InvoiceNumber": "AA777",
    "FirstPaymentAmount": 10,
    "FirstPaymentDate": "2013-10-29",
    "StartDate": "2013-11-04",
    "ExecutionFrequencyType": 2,
    "ExecutionFrequencyParameter": 2,
    "Description": "This is a payment plan entered via the API"
}
                                

Sample New Payment Object Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-04T07:00:00Z",
    "BalanceRemaining": 90,
    "NumberOfPaymentsRemaining": 5,
    "PauseUntilDate": null,
    "PaymentAmount": 18,
    "FirstPaymentDone": true,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 10,
    "NumberOfPaymentsMade": 0,
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "PaymentSubType": "Ccd",
    "AccountId": 395564,
    "InvoiceNumber": "AA777",
    "OrderId": null,
    "FirstPaymentAmount": 10,
    "FirstPaymentDate": "2013-10-29T06:00:00Z",
    "StartDate": "2013-11-04T07:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "Weekly",
    "ExecutionFrequencyParameter": 2,
    "Description": "This is a payment plan entered via the API",
    "Id": 118239,
    "LastModified": "2013-10-29T22:07:43.8697581Z",
    "CreatedOn": "2013-10-29T22:07:43.8697581Z"
}
                                

Entering a Payment Plan Schedule for an Existing Customer

Entering a recurring payment schedule for an existing customer using the API is accomplished using three sequential steps:

1.      Retrieve the CustomerId

2.      Retrieve an existing AccountId or create a new Payment Account Object.

3.      Create a Recurring Payment Object using the Payment Account created or retrieved in Step 2.

If you maintain your own database of CustomerIds and associated AccountIds you can complete steps 1 and 2 in your system, and then utilize the PaySimple API only for creating the recurring payment schedule (step 3).

 If you only maintain a database for CustomerId, you can begin with Step 2.

Attributes needed for each of the Object Types are defined below, as are the Request and Response Information associated with utilizing them to enter recurring payment schedules for existing customers using new and existing payment accounts.

Retrieve the CustomerId

If you know the CustomerId for the customer you want to charge (for example if you have it stored in your own database), then you can skip this step.

If you need to retrieve the CustomerId attribute for the Customer Object you want to charge, you will need to search for the Customer Record to obtain it. To Search via the API:

       Method = GET

       URI = /v4/globalSearch?Query="[value]"

       Query = {Customer Name or Company Name}

       Response Attribute Needed = “OriginId”


NOTE: The Search OriginId for a Customer Object is equal to its CustomerId

 

 

 

Sample Customer Search Request

JSON
URI = /v4/globalSearch?Query="ABC Company"
                                

Sample Customer Search Response

JSON
{
"Results": [{
    "OriginKey": "CUST",
    "OriginId": 255939,
    "Description": "Customer: Test Person From: ABC Company",
    "Ranking": 176
}
                                

Create the AccountId

Create a New Recurring Payment Object

Entering a One time Payment for a Future Date

Entering a one-time payment to be executed on a future date is done by creating a recurring billing schedule and setting the start date to the payment date, the frequency to annual, and the end date to the day after the payment date.

For detailed instructions on entering recurring billing schedules via the API see:

  • Schedule for a New Customer
  • Schedule for an Existing Customer

To create a new Recurring Payment Object for a one-time payment on a future date using an AccountId obtained through one of the methods described in the above sections:

  • Method = POST
  • URI = /v4/recurringpayment
  • Request = Recurring Payment Object Attributes:
  • AccountId = the account you want to charge
  • Amount = the amount you want to charge
  • StartDate = the date you want the payment to process
  • EndDate = the day after the StartDate
  • ExecutionFrequencyType = 9 (enumeration for Annually)

Key Recurring Payment Object Response Attributes for a One-time Payment to be Processed on a Future Date:

Id: Integer -- this is the ScheduleId number you will need to reference in future calls related to this schedule including pause, suspend, resume, and view details.

ScheduleStatus: Integer -- schedule Status set by the system.
Enumeration: 1 = Active; 3 = Expired; 4 = Suspended
Expected Response for new schedule is “Active.”

PaymentAmount: Number-- the amount of the scheduled payment, as specified in the Recurring Payment Request.

StartDate: String -- the date on which the schedule will start running, as specified in the Recurring Payment Request. In this case the date the payment is scheduled to process.

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency and StartDate as specified in the Recurring Payment Request. For one-time payments scheduled for a future date, the NextScheduleDate should always be equal to the StartDate.

EndDate: String-- the date specified in the Recurring Payment Request for the schedule to stop generating payments. For one-time payments scheduled for a future date, the EndDate should always be the day after the StartDate.

FirstPaymentDone: Boolean-- indicates whether any payments have yet been made via the schedule. For one-time payments scheduled for a future date, this value should always be “false.”

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments, as specified in the Recurring Payment Request. For one-time payments scheduled for a future date, this value should always be “Annually.”

CreatedOn: String -- set by the system, the date and time the recurring payment object was created (the date on which the one-time future payment was entered, not when it will be executed).

Sample Recurring Payment Object Request for a One-time Payment to be Processed on a Future Date:

JSON
In the following example, the payment is entered on October 30, 2013 and will be processed on November 4, 2013:
{
    "EndDate": "2013-11-05",
    "PaymentAmount": 10,
    "AccountId": 395560,
    "StartDate": "2013-11-04",
    "ExecutionFrequencyType": 9
}
                                

Sample Recurring Payment Object Response for a One-time Payment to be Processed on a Future Date:

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-04T07:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 0,
    "NumberOfPaymentsMade": 0,
    "EndDate": "2013-11-05T07:00:00Z",
    "PaymentAmount": 10,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-11-04T07:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "Annually",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118275,
    "LastModified": "2013-10-30T17:07:24.9581759Z",
    "CreatedOn": "2013-10-30T17:07:24.9581759Z"
}
                                

Retrieve a Payment Schedule

You can use the API to retrieve full schedule details for a single Recurring Payment Object or Payment Plan Object. Instructions for each of these are provided below:

To Retrieve a Recurring Payment Object:

  • Method = GET
  • URI = /v4/recurringpayment/{ScheduleId}
  • Query = Id for the Recurring Payment Object you want to retrieve

To Retrieve a Payment Plan Object:

  • Method = GET
  • URI = /v4/paymentplan/{ScheduleId}
  • Query = Id for the Payment Plan Object you want to retrieve

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request

JSON
/v4/recurringpayment/118162
                                

Sample Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-10-31T06:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-30T06:00:00Z",
    "TotalAmountPaid": 48,
    "NumberOfPaymentsMade": 3,
    "EndDate": null,
    "PaymentAmount": 16,
    "PaymentSubType": "Moto",
    "AccountId": 396036,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "Daily",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118162,
    "LastModified": "2013-10-30T07:30:18Z",
    "CreatedOn": "2013-10-28T19:55:02Z"
}
                                

Sample Request

JSON
/v4/paymentplan/118171
                                

Sample Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-10-31T06:00:00Z",
    "BalanceRemaining": 0,
    "NumberOfPaymentsRemaining": 5,
    "PauseUntilDate": null,
    "PaymentAmount": 20,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 0,
    "NumberOfPaymentsMade": 0,
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "LastofMonth",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118171,
    "LastModified": "2013-10-30T17:44:30Z",
    "CreatedOn": "2013-10-28T21:59:00Z"
}
                                

Recurring Payment Response Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the schedule.This value is assigned based on the Customer Object to which the designated Payment Account Object for the schedule is attached.

CustomerFirstName: String -- the first name of the Customer associated with the schedule.

CustomerLastName: String -- the last name of the Customer associated with the schedule.

CustomerCompany: String -- the Company, if any, associated with the schedule.

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule. The Customer Object associated with the AccountId will be associated with the schedule.

PaymentAmount: Number -- the scheduled payment amount. An integer or a decimal. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 3.129 will result in a PaymentAmount of 3.13.

StartDate: String -- the date on which the schedule will start (or did start) running, not necessarily the date it will (or did) generate its first payment. If a future date is used, it can be edited prior to the schedule starting. After the first payment is actually generated the field becomes read-only. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

ExecutionFrequencyType: Integer-- the primary frequency on which the schedule executes payments. (The Response displays the text not the integer.)

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

EndDate: String-- the date the schedule will stop generating payments (status changes to “Expired”). If the schedule is programmed to run indefinitely, this field will be null. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.

NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. Enter a number only, do not include the $. An integer or a decimal. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31

NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

Description: String-- -- 2048 characters max. An open text field.

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

PauseUntilDate: String -- the date a paused schedule is or was set to resume. If the schedule status is “suspended” this is the date it will automatically resume. If the schedule status is “Active” or “Expired” and this field has a value, it is the most recent date on which the schedule resumed. For schedules that have never been paused, this value will be null.

NOTE: The PauseUntilDate field does not re-set to “null” once a paused schedule resumes. This field will always contain the date on which the schedule was last re-activated.

NOTE: See Payment Schedule for instructions on how to set a pause and a resume date via the API.

FirstPaymentDone: Boolean-- if any payment (either the custom first payment or the first scheduled payment) has been generated by the schedule this attribute will be “true” and the schedule can no longer be deleted. If no payment activity has been generated by the schedule, this attribute will be “false.”

DateOfLastPaymentMade: String-- a read only system field indicating the last date a scheduled payment (not a custom first payment) was generated by the schedule. If the schedule has not yet generated a payment this field will be null.

TotalAmountPaid: Number-- a read only system field indicating the sum of all payments, including any custom first payment, generated by the schedule.

NumberOfPaymentsMade: Integer-- a read only system field indicating the number of regular payments (not including any custom first payment) generated by the schedule.

ScheduleStatus: Integer -- the current schedule Status.
Enumeration: 1 = Active; 2 = PauseUntil; 3 = Expired; 4 = Suspended

NOTE: Schedule Status is changed via URI Status Change requests, not by modifying the value of this field via a URI PUT request. See Payment Schedule, Payment Schedule, and Payment Schedule for detailed instructions.

Id: Integer -- this is the ScheduleId number you will need to reference in calls related to this schedule including pause, suspend, resume, and view details.

LastModified: String -- set by the system, the date and time the recurring payment object was last modified.

CreatedOn: String -- set by the system, the date and time the recurring payment object was created.

Payment Plan Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the schedule.This value is assigned based on the Customer Object to which the designated Payment Account Object for the schedule is attached.

CustomerFirstName: String -- the first name of the Customer associated with the schedule.

CustomerLastName: String -- the last name of the Customer associated with the schedule.

CustomerCompany: String -- the Company, if any, associated with the schedule.

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule.

TotalDueAmount: Number -- the total amount to be collected for the schedule. An integer or a decimal, without the $ is used. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 300.129 will result in a TotalDueAmount of 300.13.

TotalNumberOfPayments: Integer -- the total number of schedule payments. An integer between 1 and 99.

StartDate: String -- the date on which the schedule will start (or did start) running, not necessarily the date it will (or did) generate its first payment. If a future date is used, it can be edited prior to the schedule starting. After the first payment is actually generated the field becomes read-only. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

ExecutionFrequencyType: Integer-- the primary frequency on which the schedule executes payments. (The Response displays the text not the integer.)

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31

NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.
NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. An integer or a decimal, without the $ is used. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

Description: String-- -- 2048 characters max.

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

BalanceRemaining: Number-- a read-only system field indicating the total amount still to be collected as part of the schedule. (TotalDueAmount - TotalAmountPaid = BalanceRemaining)

NumberOfPaymentsRemaining: Integer -- a read-only system field indicating the number of payments left to be generated on the schedule. If the schedule has yet to generate a payment, it will be equal to TotalNumberofPayments.

PauseUntilDate: String -- the date a paused schedule is or was set to resume. If the schedule status is “suspended” this is the date it will automatically resume. If the schedule status is “Active” or “Expired” and this field has a value, it is the most recent date on which the schedule resumed. For schedules that have never been paused, this value will be null.

NOTE: The PauseUntilDate field does not re-set to “null” once a paused schedule resumes. This field will always contain the date on which the schedule was last re-activated.

NOTE: See Payment Schedule for instructions on how to set a pause and a resume date via the API.

PaymentAmount: Number -- the system calculated amount of each scheduled payment.
PaymentAmount = (TotalAmountDue - CustomFirstPaymentAmount) / NumberofPayments.

FirstPaymentDone: Boolean-- if any payment (either the custom first payment or the first scheduled payment) has been generated by the schedule this attribute will be “true” and the schedule can no longer be deleted. If no payment activity has been generated by the schedule, this attribute will be “false.”

DateOfLastPaymentMade: String-- a read only system field indicating the last date a scheduled payment (not a custom first payment) was generated by the schedule. If the schedule has not yet generated a payment this field will be null.

TotalAmountPaid: Number-- a read only system field indicating the sum of all payments, including any custom first payment, generated by the schedule.

NumberOfPaymentsMade: Integer-- a read only system field indicating the number of regular payments (not including any custom first payment) generated by the schedule.

ScheduleStatus: Integer -- the current schedule Status.
Enumeration: 1 = Active; 2 = PauseUntil; 3 = Expired; 4 = Suspended

NOTE: Schedule Status is changed via URI Status Change requests, not by modifying the value of this field via a URI PUT request. See Payment Schedule, Payment Schedule, and Payment Schedule for detailed instructions.

Id: Integer -- this is the ScheduleId number you will need to reference in calls related to this schedule including pause, suspend, resume, and view details.

LastModified: String -- set by the system, the date and time the recurring payment object was last modified.

CreatedOn: String -- set by the system, the date and time the recurring payment object was created.

Suspend a Payment Schedule

Suspending a schedule stops it from generating payments until it is manually resumed (see Payment Schedule for instructions). Any schedule (Recurring Payment or Payment Plan) with a Status of “Active” can be suspended via the API. Additionally, when the Suspend request is used with a paused schedule (see Payment Schedule), it will set the PauseUntilDate to null.

These is no Request Body required or Response Body provided for a schedule suspend URI instruction. Methods for suspending a Recurring Payment and a Payment Plan schedule are provided below”

To Suspend a Recurring Payment via the API:

  • Method = PUT
  • URI = /v4/recurringpayment/{ScheduleId}/suspend

To Suspend a Payment Plan via the API:

  • Method = PUT
  • URI = /v4/paymentplan/{ScheduleId}/suspend

To confirm that a schedule has been suspended, retrieve the schedule object (recurring payment or payment plan), and check the Status field. Suspended schedules will have a status of “Suspended.”

NOTE: See Payment Schedule for instructions.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Active Schedule Object (Recurring Payment Example)

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-04T07:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-28T06:00:00Z",
    "TotalAmountPaid": 15,
    "NumberOfPaymentsMade": 1,
    "EndDate": null,
    "PaymentAmount": 15,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "Weekly",
    "ExecutionFrequencyParameter": 2,
    "Description": null,
    "Id": 118161,
    "LastModified": "2013-10-28T19:48:09Z",
    "CreatedOn": "2013-10-28T19:48:09Z"
}
                                

Suspended Schedule Object (Recurring Payment Example)

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "0001-01-01T07:00:00Z", (NOTE: The NextScheduleDate for a suspended schedule will always be “0001-01-01”
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-28T06:00:00Z",
    "TotalAmountPaid": 15,
    "NumberOfPaymentsMade": 1,
    "EndDate": null,
    "PaymentAmount": 15,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Suspended",
    "ExecutionFrequencyType": "Weekly",
    "ExecutionFrequencyParameter": 2,
    "Description": null,
    "Id": 118161,
    "LastModified": "2013-10-30T18:32:38Z",
    "CreatedOn": "2013-10-28T19:48:09Z"
}
                                

Pause a Payment Schedule

Pausing a schedule stops it from generating payments until the date you specify. On the specified date the schedule returns to “Active” status and will generate a payment on the next scheduled date, based on the schedule frequency.

For example, if a schedule with a First of Month frequency is paused until December 15, 2013 it will next process a payment on January 1, 2014.

Any schedule (Recurring Payment or Payment Plan) with a Status of “Active” can be paused via the API.

NOTE: A paused schedule can be manually resumed at any time by using the schedule resume feature (see Payment Schedule), and can also be suspended indefinitely using the schedule suspend feature (see Payment Schedule.)

These is no Request Body required nor Response Body provided for a schedule pause URI instruction. Methods for pausing a Recurring Payment and a Payment Plan schedule are provided below”

To Pause a Recurring Payment via the API:

  • Method = PUT
  • URI = /v4/recurringpayment/{ScheduleId}/pause?enddate={date}
  • Enddate= the date on which you want the schedule to resume. (Date format YYYY-MM-DD)

To Pause a Payment Plan via the API:

  • Method = PUT
  • URI = /v4/paymentplan/{ScheduleId}/pause?enddate={date}
  • Enddate= the date on which you want the schedule to resume. (Date format YYYY-MM-DD)

To confirm that a schedule has been paused, retrieve the schedule object (recurring payment or payment plan), and check the Status field. Paused schedules will have a ScheduleStatus of “Suspended” and the PauseUntil field will reflect the date entered in your request.

NOTE: See Payment Schedule for instructions.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Active Schedule Object (Recurring Payment Example)

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-04T07:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-28T06:00:00Z",
    "TotalAmountPaid": 15,
    "NumberOfPaymentsMade": 1,
    "EndDate": null,
    "PaymentAmount": 15,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "Weekly",
    "ExecutionFrequencyParameter": 2,
    "Description": null,
    "Id": 118161,
    "LastModified": "2013-10-28T19:48:09Z",
    "CreatedOn": "2013-10-28T19:48:09Z"
}
                                

Suspended Schedule Object (Recurring Payment Example)

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-12-02T07:00:00Z", (The next date, based on frequency, that a payment will occur.)
    "PauseUntilDate": "2013-12-01T07:00:00Z", (The date on which the schedule status will (or did) return to “Active.”  A future date in this field indicates a paused schedule.)
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-28T06:00:00Z",
    "TotalAmountPaid": 15,
    "NumberOfPaymentsMade": 1,
    "EndDate": null,
    "PaymentAmount": 15,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Suspended",
    "ExecutionFrequencyType": "Weekly",
    "ExecutionFrequencyParameter": 2,
    "Description": null,
    "Id": 118161,
    "LastModified": "2013-10-30T19:33:33Z",
    "CreatedOn": "2013-10-28T19:48:09Z"
}
                                

Resume a Payment Schedule

You can resume any “Suspended” schedule, whether suspended indefinitely or paused until a specific date, using the resume schedule feature.

These is no Request Body required nor Response Body provided for a schedule resume URI instruction. Methods for resuming a Recurring Payment and a Payment Plan schedule are provided below.

To Resume a Recurring Payment via the API:

  • Method = PUT
  • URI = /v4/recurringpayment/{ScheduleId}/resume

To Resume a Payment Plan via the API:

  • Method = PUT
  • URI = /v4/paymentplan/{ScheduleId}/resume

To confirm that a schedule has been resumed, retrieve the schedule object (recurring payment or payment plan), and check the Status field. The schedule should have a ScheduleStatus of “Active” and the “PauseUntil” field should be “Null.”

NOTE: See Payment Schedule for instructions.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Paused Schedule Object (Payment Plan Example)

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2014-02-28T07:00:00Z",
    "BalanceRemaining": 0,
    "NumberOfPaymentsRemaining": 5,
    "PauseUntilDate": "2014-02-01T07:00:00Z",
    "PaymentAmount": 20,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 0,
    "NumberOfPaymentsMade": 0,
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Suspended",
    "ExecutionFrequencyType": "LastofMonth",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118171,
    "LastModified": "2013-10-30T21:57:56Z",
    "CreatedOn": "2013-10-28T21:59:00Z"
}
                                

Suspended Schedule Object (Payment Plan Example)

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-10-31T06:00:00Z",
    "BalanceRemaining": 0,
    "NumberOfPaymentsRemaining": 5,
    "PauseUntilDate": null,
    "PaymentAmount": 20,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 0,
    "NumberOfPaymentsMade": 0,
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "LastofMonth",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118171,
    "LastModified": "2013-10-30T21:59:52Z",
    "CreatedOn": "2013-10-28T21:59:00Z"
}
                                

Delete a Payment Schedule

You can delete any payment schedule (Recurring Payment or Payment Plan) that has not yet started and does not have a transaction attached to it. This means that neither the custom first payment nor any regularly scheduled payments have yet been generated by the schedule, and that the schedule StartDate is not in the past. (Schedules with a StartDate on the current date can be deleted.)

There is no Request Body required nor Response Body provided for a schedule delete URI instruction. Methods for deleting a Recurring Payment and a Payment Plan schedule are provided below.

To Delete a Recurring Payment via the API:

  • Method = DELETE
  • URI = /v4/recurringpayment/{ScheduleId}

To Delete a Payment Plan via the API:

  • Method = DELETE
  • URI = /v4/paymentplan/{ScheduleId}

To confirm that a schedule has been deleted, retrieve the schedule object (recurring payment or payment plan), and check Response Information.

NOTE: See Payment Schedule for instructions.

Deleted Schedule Objects will return a “203 - Non-Authoritative Information” response. (The HttpStatus field in the Meta section of the Response will be “NonAuthoritativeInformation” and the HttpStatusCode will be “203” as shown below”

Delete Error Message

If you send a URI Delete request for a schedule that cannot be deleted (either because it has a StartDate in the past or has a transaction attached to it), you will see the error message below:

JSON
"Meta": {
    "Errors": null,
    "HttpStatus": "NonAuthoritativeInformation",
    "HttpStatusCode": 203,
    "PagingDetails": null
}
                                

400 - Bad Request

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Payment schedules that have started cannot be deleted, only suspended"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Edit a Recurring Payment Schedule

You can use the API to make changes to Recurring Payment Schedules. The API does not support editing Payment Plan Schedules.

NOTE: For Payment Plans that have not yet started (StartDate is in the future) changes can be made via the UI. After a Payment Plan StartDate, changes are no longer permitted.

You can use the API to make changes to the following Recurring Payment Schedule fields:

PaymentAmount: Number -- the scheduled payment amount. You can change this to any other number.

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule. You can enter any other AccountId associated with the Customer Record here. If you change from Credit Card to ACH, or vice versa, and do not specify a new PaymentSubType the system will update the schedule with the default sub-type for the account type (for CC this is “Moto” and for ACH this is “Web”).

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null. You can manually enter a new value for this field or omit it (or set it to null) and let the system assign the default sub-type for the AccountId.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

StartDate: String-- the date the schedule is configured to start running. If this date is in the future you can change it to the current date or any other future date. If this date has passed, then this field is read-only and cannot be changed. Date format: YYYY-MM-DD.

EndDate: String-- the date the schedule is to stop generating payments. You can change this date to any other future date, or set it to “null” to run the schedule indefinitely. Date format: YYYY-MM-DD.

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments. You can change this to any frequency.

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

NOTE: If Quarterly, Semi-Annually, or Annually are used the schedule will execute the next payment on the Start Date (if the schedule has not yet started), or will calculate the next scheduled payment based on the date of the previous payment. For example, if you have a first of month schedule with a start date of January 1, 2013 that last generated a payment on September 1, 2013 and you change it to an Annual schedule, the next scheduled payment will be generated on September 1, 2014.

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule. You can change this field whether or not you change the ExecutionFrequencyType, however the value used must be appropriate for the frequency type.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31

NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. You can only change this amount if the FirstPaymentDate is in the future. Once the payment has been generated this field becomes read-only.

FirstPaymentDate: String-- the date the custom first payment is to be processed. You can only change this if the existing date is in the future, and you can change it to the current date or any other future date. Once the payment has been generated this field becomes read-only. Date format: YYYY-MM-DD.

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

Description: String-- -- 2048 characters max. An open text field.

NOTE: If changes are entered for any other fields, the system will ignore them and retain existing values.

You must include the following Recurring Payment Object Required fields in your URI Request, whether or not you are changing their values:

  • Id: Integer -- The ScheduleId for the Recurring Payment Object you are editing.
  • PaymentAmount
  • AccountId
  • StartDate
  • ExecutionFrequencyType (and ExecutionFrequencyParameter if required by the selected Type)

To edit a Recurring Payment Schedule via the API:

  • Method = PUT
  • URI = /v4/recurringpayment
  • Request = Required Recurring Payment Object Attributes and Optional Attributes to be changed.

Original Recurring Payment Object

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-30T07:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-31T06:00:00Z",
    "TotalAmountPaid": 20,
    "NumberOfPaymentsMade": 1,
    "EndDate": null,
    "PaymentAmount": 20,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-31T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "LastofMonth",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118328,
    "LastModified": "2013-10-31T17:57:29.6842513Z",
    "CreatedOn": "2013-10-31T17:57:29.6842513Z"
}
                                

Sample Recurring Payment Edit Request

JSON
(Change Payment Amount from $20 to $50, change End Date from “Null” to “December 1, 2014, and change Payment Account from a credit card to a bank account.)
{
    "Id": 118328,
    "EndDate": "2014-12-01",
    "PaymentAmount": 50,
    "AccountId": 395564,
    "StartDate": "2013-10-31",
    "ExecutionFrequencyType": 6
}
                                

Sample Recurring Payment Edit Response

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-30T07:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-31T06:00:00Z",
    "TotalAmountPaid": 20,
    "NumberOfPaymentsMade": 1,
     "EndDate": "2014-12-01T07:00:00Z"
    "PaymentAmount": 50,
     "PaymentSubType": "Web",
    "AccountId": 395564,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-31T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "LastofMonth",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118328,
    "LastModified": "2013-10-31T18:01:11.1617104Z",
    "CreatedOn": "2013-10-31T17:57:29Z"
}
                                

List Payments for a Payment Schedule

You can use the API to retrieve a list of payments generated by any Recurring Billing or Payment Plan schedule, regardless of schedule status. Instructions for each of these are provided below:

To Retrieve Payments for a Recurring Payment Object:

  • Method = GET
  • URI = /v4/recurringpayment/{ScheduleId}/payments
  • Query = Id for the Recurring Payment Object for which you want to retrieve payments.

NOTE: This Request only returns the complete payment record. You cannot retrieve payments in “Lite” format.

NOTE: For a detailed description of the fields in the Response, see Object Attributes.

To Retrieve Payments for a Payment Plan Object:

  • Method = GET
  • URI = /v4/paymentplan/{ScheduleId}/payments
  • Query = Id for the Payment Plan Object for which you want to retrieve payments.

NOTE: For a detailed description of the fields in the Response, see Object Attributes.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request for a Recurring Payment Object

JSON
/v4/recurringpayment/118163/payments
                                

Sample Response for a Recurring Payment Object

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "ReferenceId": 0,
        "Status": "Settled",
        "RecurringScheduleId": 118163,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "",
        "TraceNumber": "487718",
        "PaymentDate": "2013-10-28T19:56:38Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-10-30T06:00:00Z",
        "ActualSettledDate": "2013-10-29T10:00:01Z",
        "CanVoidUntil": "2013-10-29T02:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 396036,
        "InvoiceId": null,
        "Amount": 10,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1618094,
        "LastModified": "2013-10-29T10:00:01Z",
        "CreatedOn": "2013-10-28T19:56:38Z"
    }, 
       {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "ReferenceId": 0,
        "Status": "Settled",
        "RecurringScheduleId": 118163,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "",
        "TraceNumber": "816446",
        "PaymentDate": "2013-10-30T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-11-01T06:00:00Z",
        "ActualSettledDate": "2013-10-31T10:00:00Z",
        "CanVoidUntil": "2013-10-31T02:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 396036,
        "InvoiceId": null,
        "Amount": 16,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1618939,
        "LastModified": "2013-10-31T10:00:00Z",
        "CreatedOn": "2013-10-30T07:30:18Z"
    }, 
        {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "ReferenceId": 0,
        "Status": "Authorized",
        "RecurringScheduleId": 118163,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "Approved",
        "TraceNumber": "335251",
        "PaymentDate": "2013-10-31T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-11-04T07:00:00Z",
        "ActualSettledDate": null,
        "CanVoidUntil": "2013-11-01T02:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 396036,
        "InvoiceId": null,
        "Amount": 16,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1619533,
        "LastModified": "2013-10-31T07:30:18Z",
        "CreatedOn": "2013-10-31T07:30:18Z"
    }]
}
                                

Sample Request for a Payment Plan Object

JSON
/v4/paymentplan/115042/payments
                                

Sample Response for a Payment Plan Object

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 2,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 248352,
        "CustomerFirstName": "Eddie",
        "CustomerLastName": "Example",
        "CustomerCompany": "Example Company",
        "ReferenceId": 0,
        "Status": "Settled",
        "RecurringScheduleId": 115042,
        "PaymentType": "ACH",
        "PaymentSubType": "Web",
        "ProviderAuthCode": "",
        "TraceNumber": "4b7af052-09d9-4c74-87f1-17a21aeeec2f",
        "PaymentDate": "2013-08-22T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-08-27T06:00:00Z",
        "ActualSettledDate": "2013-08-23T10:00:00Z",
        "CanVoidUntil": "2013-08-22T23:00:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 386548,
        "InvoiceId": null,
        "Amount": 10,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1435338,
        "LastModified": "2013-08-23T10:00:00Z",
        "CreatedOn": "2013-08-22T17:15:08Z"
    }, {
        "CustomerId": 248352,
        "CustomerFirstName": "Eddie",
        "CustomerLastName": "Example",
        "CustomerCompany": "Example Company",
        "ReferenceId": 0,
        "Status": "Settled",
        "RecurringScheduleId": 115042,
        "PaymentType": "ACH",
        "PaymentSubType": "Web",
        "ProviderAuthCode": "",
        "TraceNumber": "f5a5d3a7-e5ef-4356-af38-e019f954e613",
        "PaymentDate": "2013-08-24T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-08-28T06:00:00Z",
        "ActualSettledDate": "2013-08-25T10:00:00Z",
        "CanVoidUntil": "2013-08-24T12:00:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 386548,
        "InvoiceId": null,
        "Amount": 10,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1436342,
        "LastModified": "2013-08-25T10:00:00Z",
        "CreatedOn": "2013-08-24T07:30:23Z"
     }]
}
                                

List Payment Schedules

You can use the API to retrieve all payment schedules for a Client account, or you can retrieve a list of all Recurring Payment Schedules or all Payment Plan Schedules.

When returning a list of all schedules, the system provides high-level details for each schedule, not the complete schedule record. This response includes a PaymentScheduleType field that indicates whether the object is a Recurring Payment or a Payment Plan.

Recurring Payment Objects and Payment Plan Objects can be displayed in two formats: Complete and Lite. Complete is the default. You can return the “lite” record by applying the “lite” filter in your GET URI Request.

The following sections provide examples of Requests and Responses available for obtaining schedule lists.

List All Schedules

The following Requests and Responses are used with the “paymentschedule” route to return abbreviated records for all schedules (including expired and suspended schedules) associated with a client account. The default is to list schedules from oldest to newest.

If you want the detail record for one of the schedules, note its type and ID, and then retrieve the full schedule. (See Payment Schedule for instructions.)

To Retrieve a List of All Schedule Objects:

  • Method = GET
  • URI = /v4/paymentschedule

Object Attributes Included in the Payment Schedule List Response

PaymentScheduleType: String-- “RecurringPayment” for a Recurring Payment schedule or “PaymentPlan for a Payment Plan schedule.

CustomerFirstName: String -- the first name of the Customer associated with the payment.

CustomerLastName: String -- the last name of the Customer associated with the payment.

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment.

ScheduleStatus: Integer -- the current schedule Status.
Enumeration: 1 = Active; 3 = Expired; 4 = Suspended

NextPaymentDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

PaymentAmount: Number-- the amount of each scheduled payment.

Id: Integer -- this is the ScheduleId number you will need to reference in future calls related to this schedule including pause, suspend, resume, and view details.

LastModified: String -- set by the system, the date and time the schedule was last modified.

CreatedOn: String -- set by the system, the date and time the schedule object was created.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample List Payment Schedules Request

JSON
GET
/v4/paymentschedule
                                

Sample List Payment Schedules Response

JSON
{
"Meta": {
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 4,
        "Page": 1,
        "ItemsPerPage": 200
    }
},
"Response": [{
    "PaymentScheduleType": "RecurringPayment",
    "CustomerFirstName": "test",
    "CustomerLastName": "guy",
    "CustomerId": 219175,
    "ScheduleStatus": "Expired", Note that this schedule is expired and does not have a next payment date.
    "NextPaymentDate": "0001-01-01T07:00:00Z",
    "PaymentAmount": 90,
    "Id": 110165,
    "LastModified": "2013-08-31T17:11:15Z",
    "CreatedOn": "2013-05-24T19:25:26Z"
}, {
    "PaymentScheduleType": "RecurringPayment",
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerId": 255939,
    "ScheduleStatus": "Suspended", Note that this schedule is paused with a next payment date of Dec 2, 2013.
    "NextPaymentDate": "2013-12-02T07:00:00Z",
    "PaymentAmount": 15,
    "Id": 118161,
    "LastModified": "2013-10-30T19:33:33Z",
    "CreatedOn": "2013-10-28T19:48:09Z"
}, {
    "PaymentScheduleType": "RecurringPayment",
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerId": 255939,
    "ScheduleStatus": "Active",
    "NextPaymentDate": "2013-11-04T07:00:00Z",
    "PaymentAmount": 22,
    "Id": 118216,
    "LastModified": "2013-10-29T17:12:33Z",
    "CreatedOn": "2013-10-29T17:12:33Z"
},  {
    "PaymentScheduleType": "PaymentPlan",
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerId": 255939,
    "ScheduleStatus": "Active",
    "NextPaymentDate": "2013-11-04T07:00:00Z",
    "PaymentAmount": 25,
    "Id": 118323,
    "LastModified": "2013-10-31T16:28:11Z",
    "CreatedOn": "2013-10-31T16:28:11Z"
     }]
}
                                

List Recurring Payment Schedules

Use the “recurringpayment” route to return a list of all recurring payment schedules for a Client account as shown below.

To Retrieve a List of All Recurring Payment Objects:

  • Method = GET
  • URI = /v4/recurringpayment

Recurring Payment Objects can be displayed in two formats: Complete and Lite. Complete is the default. You can return the “lite” record by applying the “lite” filter in your GET URI Request as follows:

  • Method = GET
  • URI = /v4/recurringpayment?lite=true

An example of each is provided below:

NOTE: See Response Object Attributes for definitions of the above fields.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Complete Recurring Payment Object

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-01T06:00:00Z",
    "PauseUntilDate": null,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": null,
    "TotalAmountPaid": 0,
    "NumberOfPaymentsMade": 0,
    "EndDate": null,
    "PaymentAmount": 12,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": "",
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-28T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "FirstofMonth",
    "ExecutionFrequencyParameter": 1,
    "Description": "",
    "Id": 118169,
    "LastModified": "2013-10-28T22:40:17Z",
    "CreatedOn": "2013-10-28T21:42:19Z"
}
                                

Lite Recurring Payment Object

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "NextScheduleDate": "2013-11-01T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "FirstofMonth",
    "ExecutionFrequencyParameter": 1,
    "Id": 118169
}
                                

Sample Recurring Payment List Request (using lite records)

JSON
GET
/v4/recurringpayment?lite=true
                                

Sample Recurring Payment List Response (using lite records)

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 5,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Id": 110165
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-01T06:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "FirstofMonth",
        "ExecutionFrequencyParameter": 1,
        "Id": 118169
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-04T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "SpecificDayofMonth",
        "ExecutionFrequencyParameter": 4,
        "Id": 118216
    },, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-04T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "Quarterly",
        "ExecutionFrequencyParameter": 0,
        "Id": 118324
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-30T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "LastofMonth",
        "ExecutionFrequencyParameter": 0,
        "Id": 118328
    }]
}
                                

List Payment Plan Schedules

Use the “paymentplan” route to return a list of all recurring payment schedules for a Client account as shown below.

To Retrieve a List of All Payment Plan Objects:

  • Method = GET
  • URI = /v4/paymentplan

Payment Plan Objects can be displayed in two formats: Complete and Lite. Complete is the default. You can return the “lite” record by applying the “lite” filter in your GET URI Request as follows:

  • Method = GET
  • URI = /v4/paymentplan?lite=true

An example of each is provided below:

NOTE: See Response Object Attributes for definitions of the above fields.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Complete Payment Plan Object

JSON
{ 
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "NextScheduleDate": "2013-11-01T06:00:00Z",
    "BalanceRemaining": 40,
    "NumberOfPaymentsRemaining": 2,
    "PauseUntilDate": null,
    "PaymentAmount": 20,
    "FirstPaymentDone": false,
    "DateOfLastPaymentMade": "2013-10-31T06:00:00Z",
    "TotalAmountPaid": 60,
    "NumberOfPaymentsMade": 3,
    "TotalDueAmount": 100,
    "TotalNumberOfPayments": 5,
    "PaymentSubType": "Moto",
    "AccountId": 395560,
    "InvoiceNumber": null,
    "OrderId": null,
    "FirstPaymentAmount": 0,
    "FirstPaymentDate": null,
    "StartDate": "2013-10-29T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "Daily",
    "ExecutionFrequencyParameter": 0,
    "Description": null,
    "Id": 118234,
    "LastModified": "2013-10-31T07:30:17Z",
    "CreatedOn": "2013-10-29T20:00:03Z"
}
                                

Lite Payment Plan Object

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "NextScheduleDate": "2013-11-01T06:00:00Z",
    "ScheduleStatus": "Active",
    "ExecutionFrequencyType": "Daily",
    "ExecutionFrequencyParameter": 0,
    "Id": 118234
}
                                

Sample Payment Plan List Request (using lite records)

JSON
GET
/v4/paymentplan?lite=true
                                

Sample Payment Plan List Response (using lite records)

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems":3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-30T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "LastofMonth",
        "ExecutionFrequencyParameter": 0,
        "Id": 118171
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-01T06:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Id": 118234
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-04T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 2,
        "Id": 118239
    }]
}
                                

Filtering Schedule Lists

Because the full list of schedules can grow quite large and unwieldy, the API uses paging to limit the number of results returned from a single Request. The default is to show the most recent 200 schedules. You can use Pagination filters to govern both the number of results returned in the Response as well as the Response page you would like to retrieve.

You can also use filters to create lists based on schedule status.

These schedule list filtering and sorting options are detailed in the following sections.

Pagination Filters for Schedule Lists

These filters are used as part of the GET URI Request to return a list of schedules:

  • Page = the set of results you want to return. “1” returns the first page, “2” the second, etc. If this filter is not included, the Request defaults to “1.”
  • Pagesize = the number of schedule records per page. If this filter is not included, the Request defaults to “200.”

The “Meta” section of the response echoes the Request and displays the total number of records, the page of results returned, and the number of results returned per page.

The above examples use the “paymentschedule” route to return a list of both Recurring Payment and Payment Plan schedules. You can also use the “recurringpayment” route and/or the “paymentplan” route with pagination filters. In the above examples replacing “paymentschedule” with an alternate route would return a list with complete Recurring Payment Object lists or Payment Plan object lists.

With the “recurringpayment” and “paymentplan” routes, you can also specify a “lite” record response. Examples of “lite” requests are provided below.

Date Filters

When requesting a schedule list you can use date filters to return schedules with a Start Date in a given date range. The default is to return all schedules, regardless of start date.

NOTE: This filter works on the StartDate field. It does not consider the schedule CreatedOn field, or the date of the actual first payment generated by the schedule.

The Date Format for URI Requests is: YYYY-MM-DD

These filters are used as part of the GET URI Request to return a list of transactions:

  • startdate = set this filter for the earliest schedule StartDate you want to return.
  • enddate= set this filter for the latest schedule StartDate you want to return.

Date filters can be used with the GET paymentschedule, GET recurringpayment, and GET paymentplan routes. For recurringpayment and paymentplan the default is to return complete schedule records, however you can use the “lite” filter in conjunction with the date filter to return abbreviated schedule records.

The “Meta” section of the response displays the number of transactions that match the date filter, as well as any pagination filters applied as part of the query.

Status Filter

When returning a list of schedules, you can filter that list by status. You can generate lists that include schedules of a single status, or a group of one or more statuses. The default is to return schedules of all statuses.

The following are used as part of the GET URI Request with the “status” filter to return a list of schedules:

  • Active -- schedules that are currently live and generating payments.
  • Suspended -- schedules that are currently paused or suspended indefinitely. If a schedule is suspended indefinitely, there will be a zero value in the NextPaymentDate field, if paused the NextPaymentDate field will indicate the date the schedule will resume generating payments.
  • Expired -- a schedule no longer generating payments. For Recurring Billing schedules, this means the End Date has passed. For Payment Plan schedules, this means all of the scheduled payments have been processed.

Status filters can be used with the GET paymentschedule, GET recurringpayment, and GET paymentplan routes. For recurringpayment and paymentplan the default is to return complete schedule records, however you can use the “lite” filter in conjunction with the status filter to return abbreviated schedule records.

The “Meta” section of the response displays the number of schedules that match the status filter, as well as any pagination filters applied as part of the query. Schedules are always listed from oldest-to-newest.

Schedule List Sorting

When returning a list of schedules in complete or “lite” form you can use sorting calls to control the Attribute by which the list is sorted, and whether the sort is in ascending or descending order. The default sort is Ascending Id. This results in listing the oldest schedules first.

A sort instruction is comprised of two calls, the first determines the field by which the schedules are sorted and the second determines whether the sort is high-to-low or low-to-high.

The secondary sort is always ascending Id. Thus, if more than one schedule has the same value for the “sortby” field, they will be listed in ascending order by Id, which effectively means from oldest-to-newest.

These calls are used as part of the GET URI Request to designate the sort parameters:

  • sortby = the Attribute by which to sort.
  • StartDate-- sort by the schedule start date.
  • EndDate -- sort by the schedule end date. (‘Null” is considered low, and will appear first in ascending sorts.)
  • NextPaymentDate-- sort by the schedule’s next payment date.(Schedules that are expired or paused indefinitely will appear first in ascending sorts and last in descending sorts.)
    NOTE: For the GET recurringpayment and GET paymentplan routes, this field is called “NextScheduleDate.” However, you should use “NextPaymentDate” in your query.
  • PaymentAmount -- sort by the scheduled payment amount.
  • ScheduleStatus -- sort by the schedule status. (Ascending: Active - Expired - Suspended)
  • Id-- sort by the schedule Id. (This is the same as sorting by schedule creation date.)
  • ExecutionFrequencyType-- sort by the schedule frequency. (Note this sort will group like frequencies together, but cannot be relied upon for true ascending and descending sorting.)
  • CustomerLastName -- sort alphabetically by the customer’s last name.
  • CustomerFirstName-- sort alphabetically by the customer’s first name.
  • PaymentScheduleType-- sort by schedule type. Used with the “GET paymentschedule” route only, this sort is used to group recurring payments and payment plans. Payment Plan is considered low.
  • direction = the order by which to sort.
  • ASC -- Ascending, sort low-to-high / A-to-Z. When this direction is selected “null” values will appear first in the list.
  • DESC-- Descending, sort high-to low / Z-to-A. when this direction is selected “null” values will appear last in the list.

NOTE: The default Pagination filter of 200 records per page will be applied unless an alternate pagination filter is included in the URI.

Sample Sorting Calls

  • Return all schedules and sort by next payment date in ascending order (present-future)
    Method: GET
    URI: /v4/paymentschedule?sortby=nextpaymentdate&direction=asc
  • List all Payment Plan schedules and then all Recurring Payment Schedules
    Method: GET
    URI: /v4/paymentschedule?sortby=paymentscheduletype&direction=asc
  • List all schedules in descending order by payment amount.
    Method: GET
    URI: /v4/paymentschedule?sortby=paymentamount&direction=descending
  • List all Recurring Payment schedules sorted A-to-Z by customer last name.
    Method: GET
    URI: /v4/recurringpayment?sortby=customerlastname&direction=ascending
  • List all Payment Plan schedules sorted by creation date, newest-to-oldest.
    Method:GET
    URI: /v4/paymentplan?sortby=Id&direction=descending

Schedule List Request Examples

Schedule list sorting, filtering, and paging can be combined to create any type of response you require. Additionally all recurring payment and payment plan schedule lists can return either complete or “lite” records, though a single response cannot contain both. The following are representative samples of compound Schedule List Requests and the associated Responses.

NOTE: These examples purposely use small page sizes in order to keep the Response displays readable.

All Active Schedules Started after October 1, 2013, Sorted by Payment Amount in Descending Order,
2 Schedule Records per page, show page 1.

NOTE: Start Date is not included in the “paymentschedule” list response, however you can still use it to sort the list.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Schedule List Example 1: Default Payment List Response (200 most recent schedules)

JSON
Request: Method = GET
URI = /v4/paymentschedule
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 166,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Schedule List Example 2: 50 Record Schedule List Response (50 oldest schedules)

JSON
Request: Method = GET
URI = /v4/paymentschedule?pagesize=50
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 166,
    "Page": 1,
    "ItemsPerPage": 50
}
                                

Payment List Example 3: 10 Payments per Page, Page 3 Response (the third oldest 10 schedules)

JSON
Request: Method = GET
URI = /v4/paymentschedule?page=3&pagesize=10
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 166,
    "Page": 3,
    "ItemsPerPage": 10
}
                                

Sample Default Schedule List Response with Page and Page Size Filters Applied

JSON
Request: Method = GET
URI = /v4/paymentschedule?page=2&pagesize=2
Response Meta
{
"Meta": {
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 166,
        "Page": 2,
        "ItemsPerPage": 2
    }
},
"Response": [{
    "PaymentScheduleType": "RecurringPayment",
    "CustomerFirstName": "Sam",
    "CustomerLastName": "Pell",
    "CustomerId": 94274,
    "ScheduleStatus": "Expired",
    "NextPaymentDate": "0001-01-01T07:00:00Z",
    "PaymentAmount": 10,
    "Id": 4330,
    "LastModified": "2010-05-25T14:21:35Z",
    "CreatedOn": "2010-05-04T18:07:32Z"
}, {
    "PaymentScheduleType": "RecurringPayment",
    "CustomerFirstName": "Sam",
    "CustomerLastName": "Pell",
    "CustomerId": 94274,
    "ScheduleStatus": "Expired",
    "NextPaymentDate": "0001-01-01T07:00:00Z",
    "PaymentAmount": 13,
    "Id": 4331,
    "LastModified": "2010-08-03T14:22:25Z",
    "CreatedOn": "2010-05-04T18:10:02Z"
}]
                                

Sample Lite Recurring Payment List Response with Page and Page Size Filters Applied

JSON
Request: Method = GET
URI = /v4/recurringpayment?page=2&pagesize=2&lite=true
Response Meta
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 119,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerId": 94274,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 3,
        "Id": 4330
    }, {
        "CustomerId": 94274,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 3,
        "Id": 4331
    }]
}
                                

Sample Lite Payment Plan List Response with Page and Page Size Filters Applied

JSON
Request: Method = GET
URI = /v4/paymentplan?page=2&pagesize=2&lite=true
Response Meta
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 50,
            "Page": 2,
            "ItemsPerPage": 2
        }    },
    "Response": [{
        "CustomerId": 94661,
        "CustomerFirstName": "Jack",
        "CustomerLastName": "Box",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "SpecificDayofMonth",
        "ExecutionFrequencyParameter": 5,
        "Id": 4562
    }, {
        "CustomerId": 103029,
        "CustomerFirstName": "Macavity",
        "CustomerLastName": "Mystery-Cat",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 6,
        "Id": 5598
    }]
}
                                

Date Filter Example 1: Default Schedule List Response

JSON
Request: Method = GET
URI = /v4/paymentschedule
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 166,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Date Filter Example 2: All Schedules with a StartDate between June 1, 2013 and August 1, 2013

JSON
Request: Method = GET
URI = /v4/paymentschedule?startdate=2013-06-01&enddate=2013-08-01
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 8,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Date Filter Example 3: All Schedules with a StartDate On or After April 1, 2013

JSON
Request: Method = GET
URI = /v4/paymentschedule?startdate=2013-04-01&enddate={currentdate}
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 33,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Date Filter Example 4: All Recurring Payment Schedules with a StartDate between April 1, 2013 and July 15, 2013

JSON
Request: Method = GET
URI = /v4/recurringpayment?startdate=2013-04-01&enddate=2013-07-15
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 7,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Date Filter Example 5: All Payment Plan Schedules with a StartDate between August 20, 2013 and October 15, 2013

JSON
Request: Method = GET
URI = /v4/paymentplan?startdate=2013-08-20&enddate=2013-10-15
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 4,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Sample Lite Payment Plan List Response with Start and End Date Filters Applied

JSON
Request: Method = GET
URI =/v4/paymentplan?startdate=2013-08-20&enddate=2013-10-15&lite=true
Response Meta
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 94278,
        "CustomerFirstName": "Pooh",
        "CustomerLastName": "Bear",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 3,
        "Id": 114745
    }, {
        "CustomerId": 248352,
        "CustomerFirstName": "Eddie",
        "CustomerLastName": "Example",
        "NextScheduleDate": "2013-11-24T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "SpecificDayofMonth",
        "ExecutionFrequencyParameter": 24,
        "Id": 115042
    }, {
        "CustomerId": 248352,
        "CustomerFirstName": "Eddie",
        "CustomerLastName": "Example",
        "NextScheduleDate": "2013-11-04T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 2,
        "Id": 115799
    }]
}
                                

Status Filter Example 1: Default Schedule List Response

JSON
Request: Method = GET
URI = /v4/paymentschedule
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 166,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Status Filter Example 2: All Active Schedules

JSON
Request: Method = GET
URI = /v4/paymentschedule?status=active
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 54,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Status Filter Example 3: All Suspended Schedules

JSON
Request: Method = GET
URI = /v4/paymentschedule?status=suspended
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems": 19,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Status Filter Example 4: All Expired Schedules

JSON
Request: Method = GET
URI = /v4/paymentschedule?status=expired
Response Meta
{
"Errors": null,
"HttpStatus": "OK",
"HttpStatusCode": 200,
"PagingDetails": {
    "TotalItems":93,
    "Page": 1,
    "ItemsPerPage": 200
}
                                

Sample Schedule List with Suspended Status Filter Applied

JSON
Request: Method = GET
URI = /v4/paymentschedule?status=suspended
Response Meta
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 2,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "Rose",
        "CustomerLastName": "Tyler",
        "CustomerId": 94659,
        "ScheduleStatus": "Suspended", (Schedule is suspended indefinitely)
        "NextPaymentDate": "0001-01-01T07:00:00Z",
        "PaymentAmount": 11,
        "Id": 4336,
        "LastModified": "2013-02-08T17:35:30Z",
        "CreatedOn": "2010-05-04T20:10:41Z"
    },{
        "PaymentScheduleType": "PaymentPlan",
        "CustomerFirstName": "Eddie",
        "CustomerLastName": "Example",
        "CustomerId": 248352,
        "ScheduleStatus": "Suspended",
        "NextPaymentDate": "2014-01-06T07:00:00Z", (Schedule is paused until January 6, 2014)
        "PaymentAmount": 40,
        "Id": 115799,
        "LastModified": "2013-11-01T17:47:07Z",
        "CreatedOn": "2013-09-05T16:59:33Z"
    }]
}
                                

Sample Lite Recurring Payment Schedule List Response with “Expired” Status Filter Applied

JSON
Request: Method = GET
URI = /v4/recurringpayment?status=expired&lite=true
Response Meta
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 2,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 94274,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Id": 4226
    }, {
        "CustomerId": 94274,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 7,
        "Id": 4326
      }]
}
                                

Sample Lite Payment Plan Schedule List Response with “Active” Status Filter Applied

JSON
Request: Method = GET
URI = /v4/paymentplan?status=active&lite=true
Response Meta
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 103830,
        "CustomerFirstName": "Zack",
        "CustomerLastName": "Apple",
        "NextScheduleDate": "2013-11-30T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "LastofMonth",
        "ExecutionFrequencyParameter": 0,
        "Id": 81871
    }, {
        "CustomerId": 180379,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "NextScheduleDate": "2013-11-06T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 4,
        "Id": 92301
    }, {
        "CustomerId": 201946,
        "CustomerFirstName": "Somother",
        "CustomerLastName": "Guye",
        "NextScheduleDate": "2013-12-01T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "FirstofMonth",
        "ExecutionFrequencyParameter": 1,
        "Id": 98921
      }]
}
                                

All Expired Recurring Payment Schedules; Lite Schedule Record; Sorted by schedule End Date, newest-to-oldest; 2 Schedule Records per page, show page 2

JSON
NOTE: End Date is not included in the “lite” response, however you can still use it to sort the list.
Request: Method = GET
URI = /v4/recurringpayment?status=expired&sortby=EndDate&direction=desc&pagesize=2&page=2&lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 48,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerId": 248020,
        "CustomerFirstName": "",
        "CustomerLastName": "GLOBAL PAYMENTS TEST CARD",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 3,
        "Id": 114479
    }, {
        "CustomerId": 94274,
        "CustomerFirstName": "Sam",
        "CustomerLastName": "Pell",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Weekly",
        "ExecutionFrequencyParameter": 3,
        "Id": 6388
    }]
}
                                

All Suspended Schedules; Sorted by Next Payment Date, from present-to-future; 2 records per page, show page 3

JSON
Request: Method = GET
URI = /v4/paymentschedule?status=suspended&sortby=NextPaymentDate&direction=ASC&page=3&pagesize=2
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 19,
            "Page": 3,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "Sally",
        "CustomerLastName": "Sample",
        "CustomerId": 94699,
        "ScheduleStatus": "Suspended",
        "NextPaymentDate": "2013-12-01T07:00:00Z",
        "PaymentAmount": 20,
        "Id": 26773,
        "LastModified": "2011-11-18T20:31:39Z",
        "CreatedOn": "2011-11-18T20:30:38Z"
    }, {
        "PaymentScheduleType": "PaymentPlan",
        "CustomerFirstName": "Pooh",
        "CustomerLastName": "Testbear",
        "CustomerId": 96093,
        "ScheduleStatus": "Suspended",
        "NextPaymentDate": "2014-01-05T07:00:00Z",
        "PaymentAmount": 5,
        "Id": 98830,
        "LastModified": "2013-02-01T19:06:51Z",
        "CreatedOn": "2013-02-01T19:05:57Z"
    }]
}
                                

Payment Plan Schedules Started in Q2 2013, Listed in the order they were created (oldest-to-newest); 2 records per page, show page 1; Complete Schedule Record

JSON
Request: Method = GET
URI = /v4/paymentplan?startdate=2013-04-01&enddate=2013-06-30&sortby=Id&direction=asc &pagesize=2&page=1&lite=false
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems":4,
            "Page": 1,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerId": 179643,
        "CustomerFirstName": "Donald",
        "CustomerLastName": "Duck",
        "CustomerCompany": "",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "BalanceRemaining": 0,
        "NumberOfPaymentsRemaining": 1,
        "PauseUntilDate": null,
        "PaymentAmount": 10,
        "FirstPaymentDone": false,
        "DateOfLastPaymentMade": "2013-05-24T06:00:00Z",
        "TotalAmountPaid": 0,
        "NumberOfPaymentsMade": 1,
        "TotalDueAmount": 10,
        "TotalNumberOfPayments": 1,
        "PaymentSubType": "Web",
        "AccountId": 358385,
        "InvoiceNumber": null,
        "OrderId": null,
        "FirstPaymentAmount": 0,
        "FirstPaymentDate": null,
        "StartDate": "2013-05-24T06:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Description": null,
        "Id": 110085,
        "LastModified": "2013-05-24T07:30:39Z",
        "CreatedOn": "2013-05-23T18:55:21Z"
    }, {
        "CustomerId": 103830,
        "CustomerFirstName": "Zack",
        "CustomerLastName": "Apple",
        "CustomerCompany": "XYZ Company",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "BalanceRemaining": 0,
        "NumberOfPaymentsRemaining": 0,
        "PauseUntilDate": null,
        "PaymentAmount": 10,
        "FirstPaymentDone": false,
        "DateOfLastPaymentMade": "2013-05-24T06:00:00Z",
        "TotalAmountPaid": 10,
        "NumberOfPaymentsMade": 1,
        "TotalDueAmount": 10,
        "TotalNumberOfPayments": 1,
        "PaymentSubType": "Web",
        "AccountId": 149989,
        "InvoiceNumber": null,
        "OrderId": null,
        "FirstPaymentAmount": 0,
        "FirstPaymentDate": null,
        "StartDate": "2013-05-24T06:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Description": null,
        "Id": 110087,
        "LastModified": "2013-05-24T07:30:39Z",
        "CreatedOn": "2013-05-23T19:21:29Z"
    }]
}
                                

Customers

Customer Records can be created, viewed, and managed via the API. The API can also be used to view and manage Customer Records created via the web-based UI or via Web Payment Pages. The following functions are supported, and are detailed in this section:

  • Adding Customers
  • Managing Customer Payment Accounts
  • Retrieving Customer Records
  • Retrieving a Customer List
  • Editing Customer Records
  • Listing Customer Payments
  • Listing Customer Payment Schedules
  • Deleting Customer Records

Adding Customers

In order to process payments and enter schedules you must first create a Customer Record. Once this record is created, you can attach credit card accounts and bank accounts to it (see Adding Payment Accounts). When processing payments and schedules, you specify the “Id” for the payment account, which instructs the system to attach the payment/schedule to the associated Customer Record.

The following sections provide detailed instructions for adding new Customer Records, and provide detailed definitions for all Customer Object Attributes.

Customer Object

To create a new Customer Object via the API:

  • Method = POST
  • URI = /v4/customer
  • Request = Customer Object Attributes

Customer Object Attributes

Required Attributes


FirstName: String -- 150 characters max
LastName: String -- 150 characters max
ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. Set to “false” to require ShippingAddress fields.

Optional Attributes


BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max
StreetAddress2: String -- optional, 250 characters max
City: String -- 100 characters max
StateCode: String -- valid 2 character State or Territory code in the US or Canada
ZipCode: String -- up to 10 characters
Country: String -- optional, defaults to “US,” max 3 characters.

ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max
StreetAddress2: String -- optional, 250 characters max
City: String -- 100 characters max
StateCode: String -- valid 2 character State or Territory code in the US or Canada
ZipCode: String -- up to 10 characters
Country: String -- optional, defaults to “US,” max 3 characters.

Company: String -- 50 characters max
CustomerAccount: String -- 28 characters max. This is a non-system account number you can assign.
Phone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.
AltPhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.
MobilePhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.
Fax: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.
Email: String -- 100 characters max, must be a valid email address.
AltEmail: String -- 100 characters max, must be a valid email address.
Website: String -- 100 characters max, must be in URL format.
Notes: String -- 2048 characters max; an open text field.

System Attributes

Id: Integer -- defaults to “0” for new requests, and is populated with the CustomerId in the Response
LastModified: String -- set by system, any Request data will be disregarded.
CreatedOn: String -- set by system, any Request data will be disregarded.

Customer Object Response Attributes

NOTE: These are listed in the order they appear in the Response, which is no indication of importance.

AltEmail: String -- the secondary email address for the customer. (100 characters max, must be a valid email address).
AltPhone: String -- the secondary phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)
MobilePhone: String -- the mobile phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)
Fax: String -- the fax number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)
Website: String -- a website associated with the customer. (100 characters max, must be in URL format.)
BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- first line of billing street address (250 characters max)
StreetAddress2: String -- second line of billing street address. (Optional, 250 characters max)
City: String -- billing city (100 characters max)
StateCode: String -- billing state; valid 2 character State or Territory code in the US or Canada
ZipCode: String -- billing postal code; up to 10 characters
Country: String -- billing Country (optional, defaults to “US,” max 3 characters.)

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. If “true” the system will set shipping field values equal to their corresponding billing address fields. If set to “false” ShippingAddress fields are not linked to billing address fields.
ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- primary shipping address line (250 characters max)
StreetAddress2: String -- second shipping address line (Optional, 250 characters max)
City: String -- the shipping city (100 characters max)
StateCode: String -- the shipping state; valid 2 character State or Territory code in the US or Canada
ZipCode: String -- the shipping postal code; up to 10 characters
Country: String -- the shipping country (Optional, defaults to “US,” max 3 characters.)

Company: String -- the Company name for the customer (50 characters max)
Notes: String -- an open text area. (2048 characters max)
CustomerAccount: String -- the Account Number the User entered for the customer (28 characters max)
FirstName: String -- the customer’s last name (150 characters max)
LastName: String -- the customer’s first name (150 characters max)
Email: String -- the primary email address for the customer. (100 characters max, must be a valid email address.)
Phone: String -- the primary phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)
Id: Integer -- assigned by the system, the CustomerId for the record. This is the Id referenced for this customer in all other API objects. It defaults to “0” for new requests, and is populated with the CustomerId in the Response.
LastModified: String -- set by the system, the last time and date on which the record was changed, any Request data will be disregarded
CreatedOn: String -- set by system, the time and date the record was created, any Request data will be disregarded

Sample New Customer Object Post

PHP
<?php
$userName = "<USER NAME HERE>";
$superSecretCode = "<CODE HERE>";
$timestamp = gmdate("c");
$hmac = hash_hmac("sha256", $timestamp, $superSecretCode, true);
$hmac = base64_encode($hmac);
$auth = "Authorization: PSSERVER AccessId = $userName; Timestamp = $timestamp; Signature = $hmac";
$url = "https://sandbox-api.paysimple.com/v4/customer";

$post_args = json_encode(array('FirstName' => 'Frank','LastName' => 'Frankman'));
$headers = array($auth, "Content-Type: application/json; charset=utf-8");

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post_args);

var_dump(curl_exec($curl));
$responseCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
echo "<br>response: $responseCode <br>";
?>
                                

Sample New Customer Object Request

JSON
POST /v4/customer
{
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": null,
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "testperson@abcco.com",
    "Phone": "8005551212",
}
                                

Sample New Customer Object Response

JSON
"Response": {
    "AltEmail": null,
    "AltPhone": null,
    "MobilePhone": null,
    "Fax": null,
    "Website": null,
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": null,
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": null
    },
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "testperson@abcco.com",
    "Phone": "8005551212",
    "Id": 255939, {This is the CustomerId that identifies this record in all other API Objects)
    "LastModified": "2013-10-01T19:16:38.5061103Z",
    "CreatedOn": "2013-10-01T19:16:38.5061103Z"
}
                                

Managing Customer Payment Accounts

Each Customer Object can have multiple Payment Account Objects attached to it. The 4.0 API supports two Payment Object Types-- Credit Card and ACH.

The Payment Account Objects are used when creating payments and payment schedules. The Customer Object associated with the Payment Account Object specified in the New Payment or New Schedule Request is associated with the newly created Payment or Schedule Object.

For Example:

  • Credit Card Object with AccountId 12345 is associated with Customer Object with CustomerId 6789
  • A Payment Request is Posted for AccountId 12345
  • The Resulting Payment Object is associated with both AccountId 12345 and CustomerId 6789

For each Customer Object, one credit card account can be set as the default Credit Card Object and one bank account can be set at the default ACH object. Default accounts enable more direct routes for processing payments and entering schedules, as they remove the need to select one of several saved payment accounts prior to processing a payment.

The API can be used to enter new credit card and ACH (bank account) Objects, as well as to view saved accounts, edit saved accounts, delete saved accounts, manage default accounts, and list all accounts associated with an individual Customer Object.

The following sections cover these functions in detail.

Adding Payment Accounts

The PaySimple 4.0 API supports two types of Payment Account Object: Credit Card and ACH (bank account).
To create a new Payment Account Object via the API:

  • Method = POST
  • URI = /v4/account/creditcard or /v4/account/ach
  • Request = Credit Card Attributes or ACH Attributes

Each type of Payment Account has its own set of attributes, which are detailed in the next sections.

Credit Card Account Request Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.
CreditCardNumber: String -- 15 or 16 digits
ExpirationDate: String -- a valid date in the format of MM/YYYY
Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover
IsDefault: Boolean -- enter “true” to set the card as the default Credit Card Account for the Customer Record, otherwise enter “false.” If there are no other cards attached to the Customer Record, the field will default to “true” regardless of your entry.

Optional Attributes

BillingZipCode: String -- max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

System Attributes

These fields are required components of the Credit Card Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response
LastModified: String -- set by system, any Request data will be disregarded.
CreatedOn: String -- set by system, any Request data will be disregarded.

ACH Account Request Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from the Customer Object created in the previous step.
RoutingNumber: String -- 9 digit bank routing number
AccountNumber: String -- min 4 digits, max 100 digits; the bank account number
BankName: String-- 100 characters max; the financial institution name
IsCheckingAccount: Boolean -- enter “true” to indicate a checking account or “false” to indicate a savings account. General Ledger accounts are not supported.
IsDefault: Boolean -- enter “true” to set the account as the default ACH Account for the Customer Record, otherwise enter “false.” If there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of your entry.

System Attributes

These fields are required components of the ACH Account Object that are populated by the system-- you do not need to include them in your requests.
Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response
LastModified: String -- set by system, any Request data will be disregarded
CreatedOn: String -- set by system, any Request data will be disregarded

Sample New Credit Card Account Object Request

JSON
{
    "CreditCardNumber": "4111111111111111",
    "ExpirationDate": "12/2015",
    "Issuer": "12",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New Credit Card Account Object Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36.6661404Z",
    "CreatedOn": "2013-10-11T17:41:36.6661404Z"
}
                                

Sample New ACH Account Object Request

JSON
{
    "IsCheckingAccount": "true",
    "RoutingNumber": "072000326",
    "AccountNumber": "751666666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": "true",
    "Id": 0,
    "LastModified": "0001-01-01T07:00:00Z",
    "CreatedOn": "0001-01-01T07:00:00Z"
}
                                

Sample New ACH Account Object Response

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56.7441402Z",
    "CreatedOn": "2013-10-11T17:54:56.7441402Z"
}
                                

Updating Payment Accounts

The PaySimple 4.0 API supports making limited changes to saved credit card and ACH account objects. For credit cards, the expiration date and billing zip code can be changed; for bank accounts only the account type (checking/savings) can be changed.

Each time you make a change to a saved Payment Account, the LastModified field is updated by the system to record the time and date of the change.

To change the default payment account, use the Setting Default Payment Accounts Customer route. Making a change to the isDefault field is not supported under the Account route.
To make any other change to a saved account, you must enter the new account information as a new payment account object and then delete the old payment account object.

Updating Credit Card Account Objects

To update a Credit Card Account Object:

  • Method = PUT
  • URI = /v4/account/creditcard 
  • Request = All Required Credit Card Attributes

Updating ACH Account Objects

To update an ACH Account Object:

  • Method = PUT
  • URI = /v4/account/ach
  • Request = All Required ACH Attributes

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Original Credit Card Object

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}
                                

Credit Card Update Request - Change Expiration date and change billing zip code

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2019",
    "Issuer": "Visa",
    "BillingZipCode": "80433",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
}
                                

Credit Card Update Response (Updated Credit Card Object)

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2019",
    "Issuer": "Visa",
    "BillingZipCode": "80433",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-11-07T22:11:08.8272Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}
                                

Original ACH Object

JSON
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396037,
    "LastModified": "2013-11-07T19:22:08Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
}
                                

ACH Update Request - Change to a savings account.

JSON
NOTE: This would only be necessary if the original setting for account type was incorrect.
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2019",
    "Issuer": "Visa",
    "BillingZipCode": "80433",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
}
                                

ACH Update Response (Updated ACH Object)

JSON
{
    "IsCheckingAccount": false,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396037,
    "LastModified": "2013-11-07T22:17:07.8681045Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
}
                                

Setting Default Payment Accounts

Default payment accounts are used to quickly process new payments and enter new schedules without requiring a selection from a list of all available payment accounts. See Using the Default Credit Card Payment Account and Using the Default ACH Payment Account for instructions on entering payments using default accounts.

Default credit card and ACH accounts are changed via the Customer route, not the Account route. When making the change, you always set the new default account; you never un-designate the existing default account.

The default designation can be assigned for a NEW payment account when it is entered (Method = POST), by setting the IsDefault field to “true.” However, it cannot be changed by changing the value of the IsDefault field for an existing payment account object (Method = PUT).

If you delete the existing default Credit Card or ACH Account, the system will automatically designate the oldest remaining account of the deleted type as the new default. For Example:

  • Credit Card AccountID 1234 was CreatedOn 12/1/2013 and set as the default credit card.
  • Credit Card AccountId 789 was CreatedOn 11/1/2013
  • Credit Card AccountId 456 was CreatedOn 10/1/2013
  • Credit Card AccoutId 1234 is Deleted
  • The system will set Credit Card AccountId 456 as the new default credit card.

If you would like a different account set as default, you will need to use the route described in this section to change it.

To set a Credit Card or ACH Account as the default:

  • Method = PUT
  • URI = /v4/customer/{CustomerId}/{AccountId}
    • CustomerId = the Customer Record ID with which the account is associated
    • AccountId = the Id for the account you want to set as a default.

The system will determine whether the provided AccountId is for a credit card or an ACH object, and will make the default account change as applicable. There is no Response body for a set default Request. You will simply see the 204 Response Header.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request to Set a New Default ACH Account

JSON
Current ACH Set for CustomerId 255939
{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 395564,
    "LastModified": "2013-11-08T18:38:55Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}, {
    "IsCheckingAccount": false,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396037,
    "LastModified": "2013-11-08T18:38:55Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
}, {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****4999",
    "BankName": "Test Bank 9",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 399738,
    "LastModified": "2013-11-08T18:38:55Z",
    "CreatedOn": "2013-11-08T18:38:15Z"
}
                                

Request to Change AccountId 396037 to Default

JSON
PUT /v4/customer/255939/396037
Updated ACH Set for CustomerId 255939
{
    "IsCheckingAccount": false,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 396037,
    "LastModified": "2013-11-08T18:48:53Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
}, {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****4999",
    "BankName": "Test Bank 9",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 399738,
    "LastModified": "2013-11-08T18:48:53Z",
    "CreatedOn": "2013-11-08T18:38:15Z"
}, {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 395564,
    "LastModified": "2013-11-08T18:48:53Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}
                                

Sample Request to Set a New Default Credit Card

JSON
Current Credit Card Set for CustomerId 255939
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2019",
    "Issuer": "Visa",
    "BillingZipCode": "80433",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-11-07T22:11:08Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}, {
    "CreditCardNumber": "************5454",
    "ExpirationDate": "08/2018",
    "Issuer": "Master",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396036,
    "LastModified": "2013-11-07T22:11:08Z",
    "CreatedOn": "2013-10-15T18:33:25Z"
}
                                

Request to Change AccountId 396036 to Default

JSON
PUT   /v4/customer/255939/396036
Updated Credit Card Set for CustomerId 255939
{
    "CreditCardNumber": "************5454",
    "ExpirationDate": "08/2018",
    "Issuer": "Master",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 396036,
    "LastModified": "2013-11-07T22:11:08Z",
    "CreatedOn": "2013-10-15T18:33:25Z"
}
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2019",
    "Issuer": "Visa",
    "BillingZipCode": "80433",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 395560,
    "LastModified": "2013-11-07T22:11:08Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
},
                                

Retrieving Default Payment Accounts

Default payment accounts are used to quickly process new payments and enter new schedules without requiring a selection from a list of all available payment accounts. See Using the Default Credit Card Payment Account and Using the Default ACH Payment Account for instructions on entering payments using default accounts.

Instructions for Setting Default Payment Accounts is provided in the previous section. The following sections provide instructions for retrieving the AccountId for the default credit card and the default ACH account associated with a particular Customer Object.

Retrieving the Default Credit Card

For any CustomerID, to retrieve the default credit card AccountId:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/defaultcreditcard
  • Response Attribute Needed = “AccountId”

Retrieving the Default ACH Account

For any CustomerID, to retrieve the default ACH AccountId:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/defaultach
  • Response Attribute Needed = “AccountId”

Sample Default Credit Card Request

JSON
URI = /v4/customer/255939/defaultcreditcard
                                

Sample Default Credit Card Response

JSON
{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}
                                

Listing Payment Accounts

You can use the API to generate a list of all payment accounts attached to a single Customer Object. (You cannot generate a list all payment accounts under a Client account.) You can generate a list that includes all of a Customer’s saved payment accounts, or you can create lists of only Credit Card Accounts or only ACH Accounts.

You can use this list to select the AccountId you would like to use when creating a new payment or payment schedule.

There is no “lite” version of a payment account object. All lists contain a complete set of Credit Card or ACH Account Object elements. (See ACH Account Response Object Attributes and Credit Card Account Response Object Attributes for detailed description of payment account object attributes.)

The following sections detail how to generate these lists.

List All Credit Card Accounts for a Customer

To retrieve all of the Credit Card Account Objects associated with a Customer Record:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/creditcardaccounts
  • CustomerId = the Id of the Customer whose credit card accounts you want to list

List All ACH Accounts for a Customer

To retrieve all of the ACH Account Objects associated with a Customer Record:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/achaccounts
  • CustomerId = the Id of the Customer whose credit card accounts you want to list

List All Payment Accounts for a Customer

To retrieve all of the Payment Account Objects associated with a Customer Record:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/accounts
  • CustomerId = the Id of the Customer whose credit card accounts you want to list

NOTE: Credit Cards are always listed ahead of ACH Accounts.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Credit Card Accounts Request

JSON
URI = /v4/customer/255939/creditcardaccounts
                                

Sample Credit Card Accounts Responsee

JSON
[{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}, {
    "CreditCardNumber": "************5454",
    "ExpirationDate": "08/2018",
    "Issuer": "Master",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396036,
    "LastModified": "2013-10-15T18:33:25Z",
    "CreatedOn": "2013-10-15T18:33:25Z"
}]
                                

Sample ACH Accounts Request

JSON
URI = /v4/customer/255939/achaccounts
                                

Sample ACH Accounts Responsee

JSON
[{
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}, {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396037,
    "LastModified": "2013-10-15T18:33:56Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
}]
                                

Sample All Payment Accounts Request

JSON
URI = /v4/customer/255939/accounts
                                

Sample All Payment Accounts Responsee

JSON
[{
    "CreditCardNumber": "************1111",
    "ExpirationDate": "12/2015",
    "Issuer": "Visa",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395560,
    "LastModified": "2013-10-11T17:41:36Z",
    "CreatedOn": "2013-10-11T17:41:36Z"
}, {
    "CreditCardNumber": "************5454",
    "ExpirationDate": "08/2018",
    "Issuer": "Master",
    "BillingZipCode": "80202",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396036,
    "LastModified": "2013-10-15T18:33:25Z",
    "CreatedOn": "2013-10-15T18:33:25Z"
}  {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****6666",
    "BankName": "Test Bank",
    "CustomerId": 255939,
    "IsDefault": true,
    "Id": 395564,
    "LastModified": "2013-10-11T17:54:56Z",
    "CreatedOn": "2013-10-11T17:54:56Z"
}, {
    "IsCheckingAccount": true,
    "RoutingNumber": "072000326",
    "AccountNumber": "*****8888",
    "BankName": "Bank Two",
    "CustomerId": 255939,
    "IsDefault": false,
    "Id": 396037,
    "LastModified": "2013-10-15T18:33:56Z",
    "CreatedOn": "2013-10-15T18:33:56Z"
 }]
                                

Retrieving Customer Records

You can use the API to retrieve full details for a single Customer Object, or you can retrieve a list of all Customer Records saved in the Client Account.

Customer Objects can be displayed in two formats: Complete and Lite. Complete is the default. You can return the “lite” record by applying the “lite” filter in your GET URI Request as follows: /v4/customer?lite=true

An example of each is provided below:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Complete Customer Object

JSON
{
    "AltEmail": "",
    "AltPhone": "",
    "MobilePhone": null,
    "Fax": "",
    "Website": "",
    "BillingAddress": {
        "StreetAddress1": "123 any st",
        "StreetAddress2": "",
        "City": "denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 any st",
        "StreetAddress2": "",
        "City": "denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "Company": "",
    "Notes": "",
    "CustomerAccount": "",
    "FirstName": "test",
    "LastName": "guy",
    "Email": "lisa@paysimple.com",
    "Phone": "",
    "Id": 219175,
    "LastModified": "2013-10-31T17:07:13Z",
    "CreatedOn": "2013-05-24T19:24:11Z"
}
                                

Lite Customer Object

JSON
{
    "Company": null,
    "FirstName": "test",
    "LastName": "guy",
    "Id": 219175
}
                                

Customer Object Attributes

NOTE: These are listed in the order they appear in the Response, which is no indication of importance.

AltEmail: String -- the secondary email address for the customer. (100 characters max, must be a valid email address).

AltPhone: String -- the secondary phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

MobilePhone: String -- the mobile phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

Fax: String -- the fax number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

Website: String -- a website associated with the customer. (100 characters max, must be in URL format.)

BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- first line of billing street address (250 characters max)

StreetAddress2: String -- second line of billing street address. (Optional, 250 characters max)

City: String -- billing city (100 characters max)

StateCode: String -- billing state; valid 2 character State or Territory code in the US or Canada

ZipCode: String -- billing postal code; up to 10 characters

Country: String -- billing Country (optional, defaults to “US,” max 3 characters.)

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. If “true” the system will set shipping field values equal to their corresponding billing address fields. If set to “false” ShippingAddress fields are not linked to billing address fields.

ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- primary shipping address line (250 characters max)

StreetAddress2: String -- second shipping address line (Optional, 250 characters max)

City: String -- the shipping city (100 characters max)

StateCode: String -- the shipping state; valid 2 character State or Territory code in the US or Canada

ZipCode: String -- the shipping postal code; up to 10 characters

Country: String -- the shipping country (Optional, defaults to “US,” max 3 characters.)

Company: String -- the Company name for the customer (50 characters max)

Notes: String -- an open text area. (2048 characters max)

CustomerAccount: String -- the Account Number the User entered for the customer (28 characters max)

FirstName: String -- the customer’s last name (150 characters max)

LastName: String -- the customer’s first name (150 characters max)

Email: String -- the primary email address for the customer. (100 characters max, must be a valid email address.)

Phone: String -- the primary phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

Id: Integer -- assigned by the system, the CustomerId for the record. This is the Id referenced for this customer in all other API objects. It defaults to “0” for new requests, and is populated with the CustomerId in the Response.

LastModified: String -- set by the system, the last time and date on which the record was changed, any Request data will be disregarded

CreatedOn: String -- set by system, the time and date the record was created, any Request data will be disregarded

Retrieving a Single Customer Record

Single Customer Objects can only be retrieved in complete form, the “lite” version is not available. To retrieve a complete Customer Object via the API:

  • Method = GET
  • URI = /v4/customer/{CustomerId}
  • Query = Id for the Customer Object you want to retrieve

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request

JSON
/v4/customer/255939
                                

Sample Response

JSON
{
    "AltEmail": "",
    "AltPhone": "",
    "MobilePhone": null,
    "Fax": "",
    "Website": "",
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "Company": "ABC Company",
    "Notes": "This is a note about ABC Company.",
    "CustomerAccount": "TP-117",
    "FirstName": "Test",
    "LastName": "Person",
    "Email": "lisa@paysimple.com",
    "Phone": "8005551212",
    "Id": 255939,
    "LastModified": "2013-10-11T18:12:26Z",
    "CreatedOn": "2013-10-01T19:16:38Z"
}
                                

Retrieving a Customer List

The API can be used to return a list of all Customer Records saved for a particular Client account. The generated list can be in complete format or “lite” format, which is ideal for creating summary tables and snapshots.

Because the full list of customers can grow quite large and unwieldy, the API uses paging to limit the number of results returned from a single Request. The default is to show the oldest 200 customers. You can use Pagination filters to govern both the number of results returned in the Response as well as the Response page you would like to retrieve.

Pagination Filters

These filters are used as part of the GET URI Request to return a list of customers:

  • Page = the set of results you want to return. “1” returns the first page, “2” the second, etc. If this filter is not included, the Request defaults to “1.”
  • Pagesize = the number of customer records per page. If this filter is not included, the Request defaults to “200.”

The “Meta” section of the response echoes the Request and displays the total number of records, the page of results returned, and the number of results returned per page.

Customer List Sorting

When returning a list of customers in complete or “lite” form you can use sorting calls to control the Attribute by which the list is sorted, and whether the sort is in ascending or descending order. The default sort is Ascending by CustomerId. This results in listing the oldest customers first.

A sort instruction is comprised of two calls, the first determines the field by which the customers are sorted and the second determines whether the sort is high-to-low or low-to-high.

These calls are used as part of the GET URI Request to designate the sort parameters:

  • sortby = the Attribute by which to sort.
  • FirstName-- sort alphabetically by the customer’s first name.
  • LastName-- sort alphabetically by the customer’s last name.
  • Company-- sort alphabetically by the customer’s company name.
  • BillingAddress.City-- sort alphabetically by the customer’s billing city name.
  • BillingAddress.State-- sort alphabetically by the customer’s billing State/Province abbreviation.
  • BillingAddress.Zip-- sort alpha-numerically by the customer’s billing postal code. Canadian Postal Codes beginning with a letter are considered higher than US Postal Codes beginning with a number. Thus a descending sort would be Z-to-0, and an ascending sort 0-Z.
  • BillingAddress.Country-- sort alphabetically by the customer’s billing country.
  • ShippingAddress.City-- sort alphabetically by the customer’s shipping city name.
  • ShippingAddress.State-- sort alphabetically by the customer’s shipping State/Province abbreviation.
  • ShippingAddress.Zip-- sort alpha-numerically by the customer’s shipping postal code. Canadian Postal Codes beginning with a letter are considered higher than US Postal Codes beginning with a number. Thus a descending sort would be Z-to-0, and an ascending sort 0-Z.
  • ShippingAddress.Country-- sort alphabetically by the customer’s shipping country.
  • direction = the order by which to sort.
  • ASC -- Ascending, sort low-to-high / A-to-Z. When this direction is selected “null” values will appear first in the list.
  • DESC-- Descending, sort high-to low / Z-to-A. when this direction is selected “null” values will appear last in the list.

The “Meta” section of the response displays the number of customers that match the pagination filters applied as part of the query.

NOTE: The default Pagination filter of 200 records per page will be applied unless an alternate pagination filter is included in the URI.

Sample Sorting Calls

  • Sort by Customer Last Name and list in ascending order (A-to-Z)

    Method: GET
    URI: /v4/customer?sortby=lastname&direction=asc
  • List all US Customers and then all Canadian Customers

    Method: GET
    URI: /v4/customer?sortby=billingaddress.country&direction=desc

Sort by Company Name and list in ascending order (A-to-Z).

Method: GET
URI: /v4/customer?sortby=company&direction=asc

Customer List Request Examples

Customer list sorting and paging can be combined to create any type of response you require. Additionally all customer lists can return either complete or “lite” records, though a single response cannot contain both. The following are representative samples of compound Customer List Requests and the associated Responses.

NOTE: These examples purposely use small page sizes in order to keep the Response displays readable.

NOTE: If you use a “sortby” field that is not included in the Lite record, the sort will still be used when generating the list of “lite” records, even though the “sortby” field will not appear in the Response.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Customer List Example 1: Default Customer List Response (200 oldest customers)

JSON
Method = Get
URI = /v4/customer
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 138,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Customer List Example 2: 50 Record Customer List Response (50 oldest customers)

JSON
Method = Get
URI = /v4/customer?pagesize=50
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 138,
        "Page": 1,
        "ItemsPerPage": 50
}
                                

Customer List Example 3: 50 Record Customer List Page Two Response (second oldest 50 customers)

JSON
Method = Get
URI = /v4/customer?pagesize=50&page=2
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 138,
        "Page": 2,
        "ItemsPerPage": 50
}
                                

Sample Customer List Response with Page and Page Size Filters Applied

JSON
Method = Get
URI = /v4/customer?page=3&pagesize=2
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 138,
            "Page": 3,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "AltEmail": "",
        "AltPhone": "",
        "MobilePhone": null,
        "Fax": "",
        "Website": "",
        "BillingAddress": {
            "StreetAddress1": "22 Tardis Trail",
            "StreetAddress2": "",
            "City": "Teaneck",
            "StateCode": "NJ",
            "ZipCode": "07666",
            "Country": "US"
        },
        "ShippingSameAsBilling": true,
        "ShippingAddress": {
            "StreetAddress1": "22 Tardis Trail",
            "StreetAddress2": "",
            "City": "Teaneck",
            "StateCode": "NJ",
            "ZipCode": "07666",
            "Country": "US"
        },
        "Company": "Bad Wolf Corporation ",
        "Notes": "",
        "CustomerAccount": "",
        "FirstName": "Rose",
        "LastName": "Tyler",
        "Email": "lisa@paysimple.com",
        "Phone": "",
        "Id": 94659,
        "LastModified": "2013-02-05T21:44:22Z",
        "CreatedOn": "2010-05-03T17:13:13Z"
    }, {
        "AltEmail": "",
        "AltPhone": "",
        "MobilePhone": null,
        "Fax": "",
        "Website": "",
        "BillingAddress": {
            "StreetAddress1": "123 Any St.",
            "StreetAddress2": "",
            "City": "Denver",
            "StateCode": "CO",
            "ZipCode": "80202",
            "Country": "US"
        },
        "ShippingSameAsBilling": false,
        "ShippingAddress": {
            "StreetAddress1": null,
            "StreetAddress2": null,
            "City": null,
            "StateCode": null,
            "ZipCode": null,
            "Country": "US"
        },
        "Company": "",
        "Notes": "",
        "CustomerAccount": "",
        "FirstName": "Sarah Jane",
        "LastName": "Smith",
        "Email": "ssmith@drwho.com",
        "Phone": "",
        "Id": 94660,
        "LastModified": "2010-05-03T17:13:44Z",
        "CreatedOn": "2010-05-03T17:13:44Z"
      }]
}
                                

Sample Lite Customer List Response with Page and Page Size Filters Applied

JSON
Method = Get
URI = /v4/payment?page=3&pagesize=2&lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 138,
            "Page": 3,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "Company": "Bad Wolf Corporation ",
        "FirstName": "Rose",
        "LastName": "Tyler",
        "Id": 94659
    }, {
        "Company": "",
        "FirstName": "Sarah Jane",
        "LastName": "Smith",
        "Id": 94660
    }]
}
                                

All Customers, Sorted A-to-Z by Last Name, Lite Record, 2 Customer Records per page, show page 2

JSON
Method = Get
URI = /v4/customer?sortby=lastname&direction=asc&pagesize=2&page=2&lite=true
Response Meta
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 11,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "Company": null,
        "FirstName": "Test",
        "LastName": "Gal",
        "Id": 255932
    }, {
        "Company": "Canada Co",
        "FirstName": "Canada",
        "LastName": "Girl",
        "Id": 260236
    }]
}
                                

All Customers, Sorted Z-to-A by Company Name, 2 Customer Records per page, show page 3

JSON
Method = Get
URI = /v4/customer?sortby=company&direction=desc&pagesize=2&page=3
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 11,
            "Page": 3,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "AltEmail": null,
        "AltPhone": null,
        "MobilePhone": null,
        "Fax": null,
        "Website": null,
        "BillingAddress": {
            "StreetAddress1": "999 Any Which Way",
            "StreetAddress2": "Suite 700",
            "City": "Denver",
            "StateCode": "CO",
            "ZipCode": "80202",
            "Country": "US"
        },
        "ShippingSameAsBilling": true,
        "ShippingAddress": {
            "StreetAddress1": "999 Any Which Way",
            "StreetAddress2": "Suite 700",
            "City": "Denver",
            "StateCode": "CO",
            "ZipCode": "80202",
            "Country": "US"
        },
        "Company": "Any Company",
        "Notes": null,
        "CustomerAccount": null,
        "FirstName": "Any",
        "LastName": "One",
        "Email": "anyone@anyco.com",
        "Phone": "8005556789",
        "Id": 260234,
        "LastModified": "2013-11-06T19:22:50Z",
        "CreatedOn": "2013-11-06T19:22:50Z"
    }, {
        "AltEmail": "",
        "AltPhone": "",
        "MobilePhone": null,
        "Fax": "",
        "Website": "",
        "BillingAddress": {
            "StreetAddress1": "123 Some St",
            "StreetAddress2": "",
            "City": "Denver",
            "StateCode": "CO",
            "ZipCode": "80202",
            "Country": "US"
        },
        "ShippingSameAsBilling": true,
        "ShippingAddress": {
            "StreetAddress1": "123 Some St",
            "StreetAddress2": "",
            "City": "Denver",
            "StateCode": "CO",
            "ZipCode": "80202",
            "Country": "US"
        },
        "Company": "ABC Company",
        "Notes": "This is a note about ABC Company.",
        "CustomerAccount": "TP-117",
        "FirstName": "Test",
        "LastName": "Person",
        "Email": "lisa@paysimple.com",
        "Phone": "8005551212",
        "Id": 255939,
        "LastModified": "2013-10-11T18:12:26Z",
        "CreatedOn": "2013-10-01T19:16:38Z"
    }]
}
                                

Editing Customer Records

You can use the API to make changes to the following Customer Object Attributes

AltEmail: String -- can be changed to any valid email address or set to null.

AltPhone: String -- can be changed to any other 10 digit string or set to null.

MobilePhone: String -- can be changed to any other 10 digit string or set to null.

Fax: String -- can be changed to any other 10 digit string or set to null.

Website: String -- 100 characters max, must be in URL format. Can be changed to any other URL or set to null.

BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- first line of billing street address can be changed as required.

StreetAddress2: String -- second line of billing street address can be changed as required or set to null.

City: String -- can be changed as required.

StateCode: String -- valid 2 character State or Territory code in the US or Canada can be changed as required.

ZipCode: String -- billing postal code, up to 10 characters. Can be changed as required.

Country: String -- defaults to “US,” max 3 characters. Can be changed to “US” or “CAN.”

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. If “true” the system will set shipping field values equal to their corresponding billing address fields. If set to “false” ShippingAddress fields are not linked to billing address fields and may be entered separately.

ShippingAddress: Object -- shipping address fields for the customer record. If ShippingSameAsBilling is “true” these fields are linked to their corresponding billing fields and cannot be individually changed. Otherwise the values are independent of billing address and may be changed or set to null. If one Shipping Address field is used, then all are required except StreetAddress2, StateCode, and Country.

StreetAddress1: String -- primary shipping address line can be changed as required.

StreetAddress2: String -- second shipping address line can be changed as required or set to null.

City: String -- can be changed as required.

StateCode: String -- valid 2 character State or Territory code in the US or Canada can be changed as required.

ZipCode: String -- the shipping postal-code, up to 10 characters. Can be changed as required.

Country: String -- defaults to “US,” max 3 characters. Can be changed to “US” or “CAN.”

Company: String -- the Company name for the customer can be changed as desired.

Notes: String -- an open descriptive field can be changed as required.

CustomerAccount: String -- the Account Number you assigned to the Customer. Can be changed as required.

FirstName: String -- the customer’s last name can be changed as required.

LastName: String -- the customer’s first name can be changed as required.

Email: String -- 100 characters max, must be a valid email address. Can be changed as required.

Phone: String -- 10 characters max, a numeric string without parenthesis or dashes. Can be changed as required.

NOTE: If changes are entered for any other fields, the system will ignore them and retain existing values.

You must include the entire set of Customer Object Attributes in your change request, even if you are changing just one of the fields. Failure to do this will result in any non-included fields being set to null.

NOTE: If you know a field is set to null, and you want to keep it that way, you do not need to include it in the Request.

To edit a Customer Record via the API:

  • Method = PUT
  • URI = /v4/customer
  • Request = All Customer Object Attributes. The Id specified here will identify the Customer Record to be updated.

 

 

 

 

 

 

 

 

 

 

 

 

Original Customer Object

JSON
{
    "AltEmail": null, These field are all null and may be, but are not required to be, left out of the edit request.
    "AltPhone": null,
    "MobilePhone": null,
    "Fax":null,
    "Website": null,
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "Company": "Lisa's New Test Company",
    "Notes": null,
    "CustomerAccount": null,
    "FirstName": "Lisa",
    "LastName": "Test",
    "Email": "lisa@testco.com",
    "Phone": "3035551212",
    "Id": 255888,
    "LastModified": "2013-11-01T23:30:12.1201165Z",
    "CreatedOn": "2013-10-01T18:22:47Z"
}
                                

Sample Customer Record Edit Request

JSON
(Change Company Name and Add a Note about the company name change.)
{
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "Company": "Lisa's Company Name Changed",
    "Notes": "Company name changed on November 6 2013.",
    "FirstName": "Lisa",
    "LastName": "Test",
    "Email": "lisa@testco.com",
    "Phone": "3035551212",
    "Id": 255888
}
                                

Sample Customer Object Edit Response

JSON
{
    "AltEmail": null,
    "AltPhone": null,
    "MobilePhone": null,
    "Fax": null,
    "Website": null,
    "BillingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "ShippingSameAsBilling": true,
    "ShippingAddress": {
        "StreetAddress1": "123 Some St",
        "StreetAddress2": "",
        "City": "Denver",
        "StateCode": "CO",
        "ZipCode": "80202",
        "Country": "US"
    },
    "Company": "Lisa's Company Name Changed",
    "Notes": "Company name changed on November 6 2013.",
    "CustomerAccount": null,
    "FirstName": "Lisa",
    "LastName": "Test",
    "Email": "lisa@testco.com",
    "Phone": "3035551212",
    "Id": 255888,
    "LastModified": "2013-11-06T23:43:58.3091828Z",
    "CreatedOn": "2013-10-01T18:22:47Z"
}
                                

Listing Customer Payments

The API can be used to return a list of all payments processed for a particular Customer. The generated list can be in complete format or “lite” format, which is ideal for creating summary tables and snapshots.

Because the full list of transactions can grow quite large and unwieldy, the API uses paging to limit the number of results returned from a single Request. The default is to show the most recent 200 transactions. You can use Pagination filters to govern both the number of results returned in the Response as well as the Response page you would like to retrieve.

You can also filter the list of payments by date and/or status, and can sort the resulting list by name, company, name, amount, date, status and more.

NOTE: If you already know the PaymentId for the payment you want to look at, you can retrieve it directly by using the method described in Retrieve Payment Records above. Use the Customer route described here to generate a payment list.

To retrieve a full list of payments associated with a single Customer:

  • Method = GET
  • URI = /v4/Customer/ {CustomerId}/payments
  • CustomerId = the Id associated with the Customer Object for which you would like to retrieve payments.

Sample Requests

  • GET Full Payment Objects
    GET /v4/Customer/ 255939/payments
  • GET “lite” Payment Objects
    /v4/Customer/ 255939/payments?lite=true

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Complete Payment Object

JSON
{
    "CustomerId": 255939,
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "CustomerCompany": "ABC Company",
    "ReferenceId": 0,
    "Status": "Posted",
    "RecurringScheduleId": 0,
    "PaymentType": "ACH",
    "PaymentSubType": "Tel",
    "ProviderAuthCode": "Approved",
    "TraceNumber": "93e36116-6f29-4a2c-9ab0-b824fcb4f735",
    "PaymentDate": "2013-10-15T06:00:00Z",
    "ReturnDate": null,
    "EstimatedSettleDate": "2013-10-18T06:00:00Z",
    "ActualSettledDate": null,
    "CanVoidUntil": "2013-10-15T23:00:00Z",
    "FailureData": {
        "Code": null,
        "Description": null,
        "MerchantActionText": null
    },
    "AccountId": 395564,
    "InvoiceId": null,
    "Amount": 9.44,
    "IsDebit": false,
    "InvoiceNumber": null,
    "PurchaseOrderNumber": null,
    "OrderId": null,
    "Description": null,
    "Latitude": null,
    "Longitude": null,
    "SuccessReceiptOptions": null,
    "FailureReceiptOptions": null,
    "Id": 1610692,
    "LastModified": "2013-10-15T20:37:29Z",
    "CreatedOn": "2013-10-15T20:37:29Z"
}
                                

Lite Payment Object

JSON
{
    "CustomerFirstName": "Test",
    "CustomerLastName": "Person",
    "Status": "Posted",
    "PaymentDate": "2013-10-15T06:00:00Z",
    "Amount": 9.44,
    "Id": 1610692
}
                                

Pagination Filters for a Customer Payments List

These filters are used as part of the GET URI Request to return a list of transactions for a specific customer:

  • Page = the set of results you want to return. "1" returns the first page, "2" the second, etc. If this filter is not included, the Request defaults to "1."
  • Pagesize = the number of payment records per page. If this filter is not included, the Request defaults to "200."

The "Meta" section of the response echoes the Request and displays the total number of records, the page of results returned, and the number of results returned per page.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Payment List Example 1: Default Customer Payment List Response (200 most recent transactions)

JSON
Method = GET
URI = /v4/Customer/ 255939/payments
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 98,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Payment List Example 2: 50 Record Customer Payment List Response (50 most recent transactions)

JSON
Method = GET
URI =  /v4/Customer/ 255939/payments?pagesize=50
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 98,
        "Page": 1,
        "ItemsPerPage": 50
}
                                

Payment List Example 3: Customer Payment List; 10 Payments per Page; Page 3 Response (the third most recent 10 transactions)

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?page=3&pagesize=10
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 98,
        "Page": 3,
        "ItemsPerPage": 10
}
                                

Sample Customer Payment List Response with Page and Page Size Filters Applied

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?page=2&pagesize=2
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 98,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "ReferenceId": 0,
        "Status": "Settled",
        "RecurringScheduleId": 118163,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "",
        "TraceNumber": "728528",
        "PaymentDate": "2013-11-07T07:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-11-11T07:00:00Z",
        "ActualSettledDate": "2013-11-08T11:00:00Z",
        "CanVoidUntil": "2013-11-08T03:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 396036,
        "InvoiceId": null,
        "Amount": 16,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1690752,
        "LastModified": "2013-11-08T11:00:00Z",
        "CreatedOn": "2013-11-07T08:30:22Z"
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "ReferenceId": 0,
        "Status": "Settled",
        "RecurringScheduleId": 118173,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "",
        "TraceNumber": "932611",
        "PaymentDate": "2013-11-07T07:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-11-11T07:00:00Z",
        "ActualSettledDate": "2013-11-08T11:00:00Z",
        "CanVoidUntil": "2013-11-08T03:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 395560,
        "InvoiceId": null,
        "Amount": 5,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1690750,
        "LastModified": "2013-11-08T11:00:00Z",
        "CreatedOn": "2013-11-07T08:30:22Z"
    }]
}
                                

Sample Lite Customer Payment List Response with Page and Page Size Filters Applied

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?page=2&pagesize=2&lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 98,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-11-07T07:00:00Z",
        "Amount": 16,
        "Id": 1690752
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-11-07T07:00:00Z",
        "Amount": 5,
        "Id": 1690750
    }]
}
                                

Date Filters for a Customer Payment List

When requesting a transaction list as part of a Customer Payments Request, you can use date filters to return transactions for a given date range. The default is to return all transactions, regardless of date.

The date format for URI Requests is: YYYY-MM-DD

These filters are used as part of the GET URI Request to return a list of transactions for an individual customer:

  • startdate = set this filter to return all transactions processed on or after the given date.
  • enddate = set this filter to return all transactions processed on or before the given date.

The "Meta" section of the response displays the number of transactions that match the date filter, as well as any pagination filters applied as part of the query.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Date Filter Example 1: Default Payment List Response

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?startdate=2013-10-30
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 98,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Date Filter Example 2: All Transactions On or After October 30, 2013

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?startdate=2013-10-30
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 41,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Date Filter Example 3: All Transactions On or Before October 15, 2013

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?enddate=2013-10-15
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 15,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Date Filter Example 4: All Customer Transactions Between October 1, 2013 and October 31, 2013

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?startdate=2013-10-01&enddate=2013-10-31
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 70,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Sample Lite Customer Payment List Response with Start and End Date Filters Applied

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?startdate=2013-11-02&enddate=2013-11-03&lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 5,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-11-03T06:00:00Z",
        "Amount": 16,
        "Id": 1688152
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-11-03T06:00:00Z",
        "Amount": 5,
        "Id": 1688150
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-11-02T06:00:00Z",
        "Amount": 16,
        "Id": 1687606
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-11-02T06:00:00Z",
        "Amount": 5,
        "Id": 1687605
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-11-02T06:00:00Z",
        "Amount": 20,
        "Id": 1687602
    }]
}
                                

Status Filter for a Customer Payment List

When returning a list of payments associated with a particular Customer, you can filter that list by status. You can generate lists that include payments of a single status, or a group of one or more statuses. The default is to return payments of all statuses.

The following are used as part of the GET URI Request with the “status” filter to return a list of Customer Payments:

  • Authorized -- Credit card payments and refunds that have been authorized, but not yet submitted for processing.
  • ChargeBack -- An ACH payment being disputed by the customer.
  • Failed -- Attempted transactions that were never authorized or completed.
  • Pending -- The initial stage for every transaction sent for authorization. The system assigns this status while waiting for an authorization response. In some rare cases, if communication is disrupted before the system gets a response, the transaction will remain in the "Pending" status
  • Posted -- Credit Card and ACH payments that have been entered in the system, but not yet settled. This is the initial status for an authorized but unsettled ACH transaction.
  • RefundSettled -- A settled Credit Card or ACH refund transaction.
  • Returned -- ACH payments that were unsuccessful for any reason other than non-sufficient funds or chargeback.
  • Reversed -- A transaction that has been reversed (refunded). When a settled transaction is refunded, the status of that transaction changes to "Reversed." (Note that this status displays as "Refunded" in the PaySimple UI.)
  • ReverseNSF -- An ACH transaction that failed because the customer had insufficient funds in the account to cover the payment (Note that this status displays as "ReturnedNSF" in the PaySimple UI.)
  • ReversePosted -- The credit transaction generated when a settled ACH transaction is refunded. When the refund settles, the status changes to "RefundSettled." (Note that this status displays as "Refund (Posted)" in the PaySimple UI.)
  • Settled -- A settled ACH or Credit Card payment.
  • Voided -- A voided ACH or Credit Card transaction.
  • The "Meta" section of the response displays the number of transactions that match the status filter, as well as any pagination filters applied as part of the query.

The "Meta" section of the response displays the number of transactions that match the status filter, as well as any pagination filters applied as part of the query.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Status Filter Example 1: Default Customer Payment List Response

JSON
Method = GET
URI =  /v4/Customer/ 255939/payments
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 98,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Status Filter Example 2: All Authorized Payments for the Customer

JSON
Method = GET
URI =  /v4/Customer/ 255939/payments?status=authorized
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 3,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Status Filter Example 3: All Returned ACH Transactions for the Customer (Status = Returned and ReverseNSF)

JSON
Method = GET
URI =  /v4/Customer/ 255939/payments?status=returned,reversensf
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 2,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Status Filter Example 4: All Transactions Involved in Refunds (Status = Reversed and ReversePosted and RefundSettled)

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?status=reversed,reverseposted,refundsettled
Response
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 5,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Sample Lite Customer Payment List Response with "Reversed" Status Filter Applied (All the Customer’s Refunded Payments)

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?status=reversed&lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Reversed",
        "PaymentDate": "2013-11-06T07:00:00Z",
        "Amount": 25,
        "Id": 1690207
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Reversed",
        "PaymentDate": "2013-11-04T07:00:00Z",
        "Amount": 22,
        "Id": 1688913
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Reversed",
        "PaymentDate": "2013-10-11T06:00:00Z",
        "Amount": 12,
        "Id": 1608311
    }]
}
                                

Customer Payment List Sorting

When returning a list of Customer payments in complete or “lite” form you can use sorting calls to control the Attribute by which the list is sorted, and whether the sort is in ascending or descending order. The default sort is Decending PaymentId. This results in listing the Customer’s most recent transactions first.

A sort instruction is comprised of two calls, the first determines the field by which the payments are sorted and the second determines whether the sort is high-to-low or low-to-high.

The secondary sort is always ascending PaymentId. Thus, if more than one payment has the same value for the "sortby" field, they will be listed in ascending order by PaymentId, which effectively means from oldest-to-newest.

These calls are used as part of the GET URI Request to designate the sort parameters:

  • sortby = the Attribute by which to sort.
    • ReturnDate -- sort by the date an ACH transaction was updated to "Returned" or "Returned NSF."
    • EstimatedSettleDate -- sort by the estimated settle date.
    • ActualSettledDate -- sort by the actual settle date.
    • PaymentDate -- sort by the date the transaction was entered.
    • PaymentType -- sort by the type of payment. This groups ACH transactions and CC transactions.
    • PaymentSubType -- sort by the payment sub type. This will group by ACH - CCD, ACH-PPD, ACH-TEL, ACH-WEB, CC-MOTO, and CC-SWIPE.
    • Amount -- sort by transaction amount.
  • direction = the order by which to sort.
    • ASC -- Ascending, sort low-to-high / A-to-Z. When this direction is selected "null" values will appear first in the list.
    • DESC -- Descending, sort high-to low / Z-to-A. when this direction is selected “null” values will appear last in the list.

Sample Sorting Calls

  • Sort by Payment date and list in descending order (newest-to-oldest)
    Method: GET
    URI: /v4/Customer/ 255939/payments?sortby=paymentdate&direction=desc
  • List all ACH payments and then all Credit Card payments
    Method: GET
    URI: /v4/Customer/ 255939/payments?sortby=paymenttype&direction=asc
  • List all ACH Returns first then list all other payments.
    Method: GET
    URI: /v4/Customer/ 255939/payments?sortby=returndate&direction=desc
  • List all settled payments first from newest to oldest.
    Method: GET
    URI: /v4/Customer/ 255939/payments?sortby=ActualSettledDate&direction=desc

Customer Payment List Request Examples

Payment list sorting, filtering, and paging can be combined to create any type of response you require. Additionally all Customer payment lists can return either complete or “lite” records, though a single response cannot contain both. The following are representative samples of compound Customer Payment List Requests and the associated Responses.

NOTE: These examples purposely use small page sizes in order to keep the Response displays readable.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

All A Customer’s Settled Payments Processed in October, 2013; Sorted by Amount in Descending Order, Lite Record; 2 Payment Records per page, show page 1

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?status=settled&startdate=2013-10-01&enddate=2013-10-31 &sortby=Amount&direction=DESC&lite=true&page=1&pagesize=2
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 71,
            "Page": 1,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-10-29T19:49:15Z",
        "Amount": 100,
        "Id": 1618760
    }, {
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "Status": "Settled",
        "PaymentDate": "2013-10-29T19:57:12Z",
        "Amount": 50,
        "Id": 1618762
    }]
}
                                

All payments entered for the Customer on the current date sorted by ascending expected settle date, 2 Records per page, show page 3

JSON
Method = GET
URI = /v4/Customer/ 255939/payments?startdate=2013-10-17&enddate=2013-10-17 &sortby=EstimatedSettleDate& direction=ASC&page=3&pagesize=2
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 8,
            "Page": 3,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "ReferenceId": 0,
        "Status": "Voided",
        "RecurringScheduleId": 0,
        "PaymentType": "CC",
        "PaymentSubType": "Moto",
        "ProviderAuthCode": "Approved",
        "TraceNumber": "419977",
        "PaymentDate": "2013-10-17T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-10-21T06:00:00Z",
        "ActualSettledDate": null,
        "CanVoidUntil": "2013-10-18T02:45:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 395560,
        "InvoiceId": null,
        "Amount": 13,
        "IsDebit": true,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1611881,
        "LastModified": "2013-10-17T17:16:41Z",
        "CreatedOn": "2013-10-17T17:15:23Z"
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "ReferenceId": 0,
        "Status": "Voided",
        "RecurringScheduleId": 0,
        "PaymentType": "ACH",
        "PaymentSubType": "Web",
        "ProviderAuthCode": "Approved",
        "TraceNumber": "7cafb8cc-9413-4af5-9e67-d4789fb1499f",
        "PaymentDate": "2013-10-17T06:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-10-22T06:00:00Z",
        "ActualSettledDate": null,
        "CanVoidUntil": "2013-10-17T23:00:00Z",
        "FailureData": {
            "Code": null,
            "Description": null,
            "MerchantActionText": null
        },
        "AccountId": 395564,
        "InvoiceId": null,
        "Amount": 7,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "Latitude": null,
        "Longitude": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1611848,
        "LastModified": "2013-10-17T17:11:00Z",
        "CreatedOn": "2013-10-17T16:44:07Z"
    }]
}
                                

Listing Customer Payment Schedules

The API can be used to return a list of all payment schedules attached to an individual Customer Object. It can also be used to return a list of just Recurring Payment Schedules or just Payment Plan Schedules attached to a Customer. The generated lists can be in complete format or “lite” format, which is ideal for creating summary tables and snapshots.

Because the full list of schedules can grow quite large and unwieldy, the API uses paging to limit the number of results returned from a single Request. The default is to show the most recent 200 schedules. You can use Pagination filters to govern both the number of results returned in the Response as well as the Response page you would like to retrieve.

You can also filter the list of schedules by start date and/or status, and can sort the resulting list by name, company, name, amount, date, status, frequency, schedule type, and more.

NOTE: If you already know the ScheduleId for the schedule you want to look at, you can retrieve it directly by using the method described in Retrieve a Payment Schedule above. Use the Customer route described here to generate a schedules list.

Listing All Schedules for a Customer

Use the "paymentschedules" route with a CustomerId to return the set of schedules attached to a single customer record. This list can be returned in either full or “lite” format. For detailed descriptions of schedule object attributes see Payment Schedule Response Object Attributes, Recurring Payment Response Object Attributes and Payment Plan Response Object Attributes.

NOTE: The "lite" payment schedule record is the only one that contains the schedule Payment Amount. (Amount is not an included field for either “recurringpayment” or “paymentplan” lite records.) Thus, if you would like to use a lite record to display a list of schedules that includes payment amount, you should always use the “paymentschedules” route to generate it.

NOTE: Schedules in a Lite list generated using the “paymentschedules” route are listed from oldest-to-newest by default.

To Retrieve a List of All Schedules for a Customer:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/paymentschedules
  • CustomerId = the Id associated with the Customer Object for which you would like to retrieve schedules.

To Retrieve a List of All Schedules for a Customer Using Lite Records:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/paymentschedules?lite=true
  • CustomerId = the Id associated with the Customer Object for which you would like to retrieve schedules.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request:

JSON
GET
/v4/customer/219175/paymentschedules
                                

Sample Response:

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": {
        "PaymentPlans": [{ Payment Plans Are Always Listed First for Full Records
            "CustomerId": 219175,
            "CustomerFirstName": "test",
            "CustomerLastName": "guy",
            "CustomerCompany": "",
            "NextScheduleDate": "2013-12-01T07:00:00Z",
            "BalanceRemaining": 0,
            "NumberOfPaymentsRemaining": 5,
            "PauseUntilDate": null,
            "PaymentAmount": 20,
            "FirstPaymentDone": false,
            "DateOfLastPaymentMade": null,
            "TotalAmountPaid": 0,
            "NumberOfPaymentsMade": 0,
            "TotalDueAmount": 100,
            "TotalNumberOfPayments": 5,
            "PaymentSubType": "Web",
            "AccountId": 373191,
            "InvoiceNumber": null,
            "OrderId": null,
            "FirstPaymentAmount": 0,
            "FirstPaymentDate": null,
            "SwipeData": null,
            "StartDate": "2013-12-01T07:00:00Z",
            "ScheduleStatus": "Active",
            "ExecutionFrequencyType": "FirstofMonth",
            "ExecutionFrequencyParameter": 1,
            "Description": null,
            "Id": 118830,
            "LastModified": "2013-11-11T19:55:42Z",
            "CreatedOn": "2013-11-11T19:55:42Z"
        }],
        "RecurringPayments": [{ Recurring Payments Are Grouped and Listed Second.
            "CustomerId": 219175,
            "CustomerFirstName": "test",
            "CustomerLastName": "guy",
            "CustomerCompany": "",
            "NextScheduleDate": "0001-01-01T07:00:00Z",
            "PauseUntilDate": null,
            "FirstPaymentDone": false,
            "DateOfLastPaymentMade": "2013-05-31T06:00:00Z",
            "TotalAmountPaid": 160,
            "NumberOfPaymentsMade": 8,
            "EndDate": "2013-12-01T07:00:00Z",
            "PaymentAmount": 90,
            "PaymentSubType": "Ppd",
            "AccountId": 373191,
            "InvoiceNumber": "",
            "OrderId": null,
            "FirstPaymentAmount": 0,
            "FirstPaymentDate": null,
            "SwipeData": null,
            "StartDate": "2013-05-24T06:00:00Z",
            "ScheduleStatus": "Expired",
            "ExecutionFrequencyType": "Daily",
            "ExecutionFrequencyParameter": 0,
            "Description": "",
            "Id": 110165,
            "LastModified": "2013-10-31T17:11:15Z",
            "CreatedOn": "2013-05-24T19:25:26Z"
        }, {
            "CustomerId": 219175,
            "CustomerFirstName": "test",
            "CustomerLastName": "guy",
            "CustomerCompany": "",
            "NextScheduleDate": "2013-12-01T07:00:00Z",
            "PauseUntilDate": null,
            "FirstPaymentDone": false,
            "DateOfLastPaymentMade": null,
            "TotalAmountPaid": 0,
            "NumberOfPaymentsMade": 0,
            "EndDate": null,
            "PaymentAmount": 12,
            "PaymentSubType": "Web",
            "AccountId": 373191,
            "InvoiceNumber": null,
            "OrderId": null,
            "FirstPaymentAmount": 0,
            "FirstPaymentDate": null,
            "SwipeData": null,
            "StartDate": "2013-11-15T07:00:00Z",
            "ScheduleStatus": "Active",
            "ExecutionFrequencyType": "FirstofMonth",
            "ExecutionFrequencyParameter": 1,
            "Description": null,
            "Id": 118829,
            "LastModified": "2013-11-11T19:54:27Z",
            "CreatedOn": "2013-11-11T19:54:27Z"
        }]
    }
}
                                

Sample Request:

JSON
GET
/v4/customer/219175/paymentschedules?lite=true
                                

Sample Response:

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "CustomerId": 219175,
        "ScheduleStatus": "Expired",
        "NextPaymentDate": "0001-01-01T07:00:00Z",
        "PaymentAmount": 90,
        "Id": 110165,
        "LastModified": "2013-10-31T17:11:15Z",
        "CreatedOn": "2013-05-24T19:25:26Z"
    }, {
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "CustomerId": 219175,
        "ScheduleStatus": "Active",
        "NextPaymentDate": "2013-12-01T07:00:00Z",
        "PaymentAmount": 12,
        "Id": 118829,
        "LastModified": "2013-11-11T19:54:27Z",
        "CreatedOn": "2013-11-11T19:54:27Z"
    }, {
        "PaymentScheduleType": "PaymentPlan",
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "CustomerId": 219175,
        "ScheduleStatus": "Active",
        "NextPaymentDate": "2013-12-01T07:00:00Z",
        "PaymentAmount": 20,
        "Id": 118830,
        "LastModified": "2013-11-11T19:55:42Z",
        "CreatedOn": "2013-11-11T19:55:42Z"
    }]
}
                                

Listing All Recurring Payment Schedules for a Customer

Use this route to return a list of recurring payment schedules attached to a single customer record. This list can be returned in either complete or “lite” format. For detailed descriptions of schedule object attributes see Recurring Payment Response Object Attributes.

To Retrieve a List of All Recurring Payment Objects for a Customer:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/recurringpayments
  • CustomerId = the Id associated with the Customer Object for which you would like to retrieve schedules.

To Retrieve a List of All Recurring Payment Objects for a Customer Using Lite Records:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/recurringpayments?lite=true
  • CustomerId = the Id associated with the Customer Object for which you would like to retrieve schedules.

NOTE: Lite Recurring Payment Schedule Records do not include Schedule Payment Amount.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request:

JSON
GET
/v4/customer/219175/recurringpayments
                                

Sample Response:

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 2,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "CustomerCompany": "",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "PauseUntilDate": null,
        "FirstPaymentDone": false,
        "DateOfLastPaymentMade": "2013-05-31T06:00:00Z",
        "TotalAmountPaid": 160,
        "NumberOfPaymentsMade": 8,
        "EndDate": "2013-12-01T07:00:00Z",
        "PaymentAmount": 90,
        "PaymentSubType": "Ppd",
        "AccountId": 373191,
        "InvoiceNumber": "",
        "OrderId": null,
        "FirstPaymentAmount": 0,
        "FirstPaymentDate": null,
        "SwipeData": null,
        "StartDate": "2013-05-24T06:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Description": "",
        "Id": 110165,
        "LastModified": "2013-10-31T17:11:15Z",
        "CreatedOn": "2013-05-24T19:25:26Z"
    }, {
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "CustomerCompany": "",
        "NextScheduleDate": "2013-12-01T07:00:00Z",
        "PauseUntilDate": null,
        "FirstPaymentDone": false,
        "DateOfLastPaymentMade": null,
        "TotalAmountPaid": 0,
        "NumberOfPaymentsMade": 0,
        "EndDate": null,
        "PaymentAmount": 12,
        "PaymentSubType": "Web",
        "AccountId": 373191,
        "InvoiceNumber": null,
        "OrderId": null,
        "FirstPaymentAmount": 0,
        "FirstPaymentDate": null,
        "SwipeData": null,
        "StartDate": "2013-11-15T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "FirstofMonth",
        "ExecutionFrequencyParameter": 1,
        "Description": null,
        "Id": 118829,
        "LastModified": "2013-11-11T19:54:27Z",
        "CreatedOn": "2013-11-11T19:54:27Z"
    }]
}
                                

Sample Request:

JSON
GET
/v4/customer/219175/recurringpayments?lite=true
                                

Sample Response:

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 2,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "NextScheduleDate": "0001-01-01T07:00:00Z",
        "ScheduleStatus": "Expired",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Id": 110165
    }, {
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "NextScheduleDate": "2013-12-01T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "FirstofMonth",
        "ExecutionFrequencyParameter": 1,
        "Id": 118829
    }]
}
                                

Listing All Payment Plan Schedules for a Customer

Use this route to return the set of payment plan schedules attached to a single customer record. This list can be returned in either full or “lite” format. For detailed descriptions of schedule object attributes s Payment Plan Response Object Attributes.

To Retrieve a List of All Payment Plan Objects for a Customer:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/paymentplans
  • CustomerId = the Id associated with the Customer Object for which you would like to retrieve schedules.

To Retrieve a List of All Payment Plan Objects for a Customer Using Lite Records:

  • Method = GET
  • URI = /v4/customer/{CustomerId}/paymentplans?lite=true
  • CustomerId = the Id associated with the Customer Object for which you would like to retrieve schedules.

NOTE: Lite Payment Plan Schedule Records do not include Schedule Payment Amount.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sample Request:

JSON
GET
/v4/customer/219175/paymentplans
                                

Sample Response:

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 1,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "CustomerCompany": "",
        "NextScheduleDate": "2013-12-01T07:00:00Z",
        "BalanceRemaining": 0,
        "NumberOfPaymentsRemaining": 5,
        "PauseUntilDate": null,
        "PaymentAmount": 20,
        "FirstPaymentDone": false,
        "DateOfLastPaymentMade": null,
        "TotalAmountPaid": 0,
        "NumberOfPaymentsMade": 0,
        "TotalDueAmount": 100,
        "TotalNumberOfPayments": 5,
        "PaymentSubType": "Web",
        "AccountId": 373191,
        "InvoiceNumber": null,
        "OrderId": null,
        "FirstPaymentAmount": 0,
        "FirstPaymentDate": null,
        "SwipeData": null,
        "StartDate": "2013-12-01T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "FirstofMonth",
        "ExecutionFrequencyParameter": 1,
        "Description": null,
        "Id": 118830,
        "LastModified": "2013-11-11T19:55:42Z",
        "CreatedOn": "2013-11-11T19:55:42Z"
    }]
}
                                

Sample Request:

JSON
GET
/v4/customer/219175/paymentplans?lite=true
                                

Sample Response:

JSON
{{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 1,
            "Page": 1,
            "ItemsPerPage": 200
        }
    },
    "Response": [{
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "NextScheduleDate": "2013-12-01T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "FirstofMonth",
        "ExecutionFrequencyParameter": 1,
        "Id": 118830
    }]
}
                                

Filtering Customer Schedule Lists

The API uses paging to control the number of results returned from a single Customer Schedule List Request. The default is to show the most recent 200 schedules. You can use Pagination filters to govern both the number of results returned in the Response as well as the Response page you would like to retrieve.

You can also use filters to create Customer schedule lists based on schedule status and start date.

These schedule list filtering options are detailed in the following sections.

Customer Schedule List Pagination Filters

These filters are used as part of the GET URI Request to return a list of schedules for a specific customer:

  • Page = the set of results you want to return. "1" returns the first page, "2" the second, etc. If this filter is not included, the Request defaults to "1"
  • Pagesize = the number of schedule records per page. If this filter is not included, the Request defaults to "200"

The "Meta" section of the response echoes the Request and displays the total number of records, the page of results returned, and the number of results returned per page.

The above examples use the “paymentschedules” route to return a list of both Recurring Payment and Payment Plan schedules for the specified customer. You can also use the “recurringpayments” route and/or the “paymentplans” route with pagination filters. In the above examples replacing “paymentschedules” with an alternate route would return a Recurring Payment Object list for the customer or a Payment Plan Object list for the customer.

Date Filters

When requesting a customer schedule list you can use date filters to return schedules with a Start Date in a given date range. The default is to return all schedules, regardless of start date.

NOTE: This filter works on the StartDate field. It does not consider the schedule CreatedOn field, or the date of the actual first payment generated by the schedule.

The date format for URI Requests is: YYYY-MM-DD

These filters are used as part of the GET URI Request to return a list of schedules

  • startdate = set this filter for the earliest schedule StartDate you want to return.
  • enddate= set this filter for the latest schedule StartDate you want to return

Date filters can be used with the GET paymentschedules, GET recurringpayments, and GET paymentplans customer routes. The default is to return complete schedule records, however you can use the “lite” filter in conjunction with the date filter to return abbreviated schedule records.

The “Meta” section of the response displays the number of schedules that match the date filter, as well as any pagination filters applied as part of the query.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Customer Schedule List Example 1: Default All Schedules List Response (200 most recent schedules)

JSON
Request: Method = GET
URI = /v4/customer/219175/paymentschedules
Response Meta:
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 3,
        "Page": 1,
        "ItemsPerPage": 200
}
                                

Customer Schedule List Example 2: Two Record All Schedule List Response (2 oldest schedules)

JSON
Request: Method = GET
URI = /v4/customer/219175/paymentschedules?pagesize=2
Response Meta:
{
    "Errors": null,
    "HttpStatus": "OK",
    "HttpStatusCode": 200,
    "PagingDetails": {
        "TotalItems": 3,
        "Page": 1,
        "ItemsPerPage": 2
}
                                

Sample Default Customer Schedule List Response with Page and Page Size Filters Applied

JSON
Request: Method = GET
URI = /v4/customer/255939/paymentschedules?pagesize=2&page=2
Response Meta:
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems":8,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": {
        "PaymentPlans": [],
        "RecurringPayments": [{
            "CustomerId": 255939,
            "CustomerFirstName": "test",
            "CustomerLastName": "guy",
            "CustomerCompany": "",
            "NextScheduleDate": "0001-01-01T07:00:00Z",
            "PauseUntilDate": null,
            "FirstPaymentDone": false,
            "DateOfLastPaymentMade": "2013-05-31T06:00:00Z",
            "TotalAmountPaid": 160,
            "NumberOfPaymentsMade": 8,
            "EndDate": "2013-12-01T07:00:00Z",
            "PaymentAmount": 90,
            "PaymentSubType": "Ppd",
            "AccountId": 373191,
            "InvoiceNumber": "",
            "OrderId": null,
            "FirstPaymentAmount": 0,
            "FirstPaymentDate": null,
            "SwipeData": null,
            "StartDate": "2013-05-24T06:00:00Z",
            "ScheduleStatus": "Expired",
            "ExecutionFrequencyType": "Daily",
            "ExecutionFrequencyParameter": 0,
            "Description": "",
            "Id": 110165,
            "LastModified": "2013-10-31T17:11:15Z",
            "CreatedOn": "2013-05-24T19:25:26Z"
        }, {
            "CustomerId": 255939,
            "CustomerFirstName": "test",
            "CustomerLastName": "guy",
            "CustomerCompany": "",
            "NextScheduleDate": "2013-12-01T07:00:00Z",
            "PauseUntilDate": null,
            "FirstPaymentDone": false,
            "DateOfLastPaymentMade": null,
            "TotalAmountPaid": 0,
            "NumberOfPaymentsMade": 0,
            "EndDate": null,
            "PaymentAmount": 12,
            "PaymentSubType": "Web",
            "AccountId": 373191,
            "InvoiceNumber": null,
            "OrderId": null,
            "FirstPaymentAmount": 0,
            "FirstPaymentDate": null,
            "SwipeData": null,
            "StartDate": "2013-11-15T07:00:00Z",
            "ScheduleStatus": "Active",
            "ExecutionFrequencyType": "FirstofMonth",
            "ExecutionFrequencyParameter": 1,
            "Description": null,
            "Id": 118829,
            "LastModified": "2013-11-11T19:54:27Z",
            "CreatedOn": "2013-11-11T19:54:27Z"
        }]
}
                                

Sample Lite Customer Schedule List Response with Page and Page Size Filters Applied

JSON
Request: Method = GET
URI = /v4/customer/255939/paymentschedules?pagesize=2&page=2
Response Meta:
{{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 18,
            "Page": 2,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerId": 255939,
        "ScheduleStatus": "Active",
        "NextPaymentDate": "2013-11-12T07:00:00Z",
        "PaymentAmount": 16,
        "Id": 118163,
        "LastModified": "2013-11-11T08:30:18Z",
        "CreatedOn": "2013-10-28T19:56:38Z"
    }, {
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerId": 255939,
        "ScheduleStatus": "Active",
        "NextPaymentDate": "2013-12-01T07:00:00Z",
        "PaymentAmount": 12,
        "Id": 118169,
        "LastModified": "2013-11-01T07:30:37Z",
        "CreatedOn": "2013-10-28T21:42:19Z"
    }]
}
                                

Customer Schedule List Sorting

When returning a list of customer schedules in complete or “lite” form you can use sorting calls to control the Attribute by which the list is sorted, and whether the sort is in ascending or descending order. The default sort is Ascending Id. This results in listing the oldest schedules first.

NOTE: When using “paymentschedules” to return a list including both schedule types, Payment Plans are listed first and Recurring Payment Schedules second. Within the schedule type sort, schedules are listed from oldest-to-newest.

A sort instruction is comprised of two calls, the first determines the field by which the schedules are sorted and the second determines whether the sort is high-to-low or low-to-high.

The secondary sort is always ascending Id. Thus, if more than one schedule has the same value for the "sortby" field, they will be listed in ascending order by Id, which effectively means from oldest-to-newest.

These calls are used as part of the GET URI Request to designate the sort parameters:

  • sortby = the Attribute by which to sort.
    • StartDate-- sort by the schedule start date.
    • EndDate -- sort by the schedule end date. (‘Null” is considered low, and will appear first in ascending sorts.)
    • NextPaymentDate -- sort by the schedule’s next payment date.(Schedules that are expired or paused indefinitely will appear first in ascending sorts and last in descending sorts.) NOTE: For the GET recurringpayment and GET paymentplan routes, this field is called “NextScheduleDate.” However, you should use “NextPaymentDate” in your query.
    • PaymentAmount -- sort by the scheduled payment amount.
    • ScheduleStatus -- sort by the schedule status. (Ascending: Active - Expired - Suspended)
    • Id-- sort by the schedule Id. (This is the same as sorting by schedule creation date.)
    • ExecutionFrequencyType-- sort by the schedule frequency. (Note this sort will group like frequencies together, but cannot be relied upon for true ascending and descending sorting.)
    • PaymentScheduleType-- sort by schedule type. Used with the “GET paymentschedule” route only, this sort is used to group recurring payments and payment plans. Payment Plan is considered low.
  • direction = the order by which to sort
    • ASC -- Ascending, sort low-to-high / A-to-Z. When this direction is selected “null” values will appear first in the list.
    • DESC-- Descending, sort high-to low / Z-to-A. when this direction is selected “null” values will appear last in the list.

NOTE: The default Pagination filter of 200 records per page will be applied unless an alternate pagination filter is included in the URI.

Sample Sorting Calls

  • Return all schedules for a specific customer and sort by next payment date in ascending order (present-future)
    Method: Get
    URI: /v4/customer/255939/paymentschedule?sortby=nextpaymentdate&direction=asc
  • List all Payment Plan schedules for a specific customer and sort by End Date in descending order.
    Method: GET
    URI:/v4/customer/255939/paymentplans?sortby=EndDate&direction=desc
  • List all schedules for a specific customer in descending order by payment amount.
    Method: GET
    URI: /v4/customer/255939/paymentschedule?sortby=paymentamount&direction=desc
  • List all Recurring Payment schedules for a specific customer and sort by creation date, newest-to-oldest.
    Method: GET
    URI: /v4/customer/255939/paymentplans?sortby=Id&direction=desc

Customer Schedule List Request Examples

Schedule list sorting, filtering, and paging can be combined to create any type of response you require. Additionally all schedule lists generated for a specific customer can return either complete or “lite” records, though a single response cannot contain both. The following are representative samples of compound Schedule List Requests for Specific Customers and the associated Responses.

NOTE: These examples purposely use small page sizes in order to keep the Response displays readable.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

All Active Schedules for the Specified Customer Started after November 1, 2013, Lite Records, Sorted by Payment Amount in Descending Order, 2 Schedule Records per page, show page 1

JSON
NOTE: Start Date is not included in the “paymentschedule” lite response, however you can still use it to sort the list.

Method = GET
URI = /v4/customer/255939/paymentschedules?status=active&startdate=2013-11-01 &sortby=PaymentAmount&direction=desc&page=1&pagesize=2&lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 5,
            "Page": 1,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerId": 255939,
        "ScheduleStatus": "Active",
        "NextPaymentDate": "2013-12-04T07:00:00Z",
        "PaymentAmount": 21,
        "Id": 118215,
        "LastModified": "2013-11-04T08:30:20Z",
        "CreatedOn": "2013-10-29T16:49:21Z"
    }, {
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerId": 255939,
        "ScheduleStatus": "Active",
        "NextPaymentDate": "2013-12-04T07:00:00Z",
        "PaymentAmount": 22,
        "Id": 118216,
        "LastModified": "2013-11-04T08:30:20Z",
        "CreatedOn": "2013-10-29T17:12:33Z"
    }]
}
                                

All Expired Recurring Payment Schedules for a specific Customer; Sorted by schedule End Date, newest-to-oldest; 2 Schedule Records per page, show page 2

JSON
NOTE: End Date is not included in the “lite” response, however you can still use it to sort the list.

Method = GET
URI = /v4/customer/255939/paymentschedules?status=expired&sortby=EndDate &direction=desc &pagesize=2&page=2
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 2,
            "ItemsPerPage": 2 Note that as there are 3 matches, page 2 contains only 1 record.
        }
    },
    "Response": {
        "PaymentPlans": [{
            "CustomerId": 255939,
            "CustomerFirstName": "Test",
            "CustomerLastName": "Person",
            "CustomerCompany": "ABC Company",
            "NextScheduleDate": "0001-01-01T07:00:00Z",
            "BalanceRemaining": 0,
            "NumberOfPaymentsRemaining": 0,
            "PauseUntilDate": null,
            "PaymentAmount": 25,
            "FirstPaymentDone": false,
            "DateOfLastPaymentMade": "2013-11-07T07:00:00Z",
            "TotalAmountPaid": 100,
            "NumberOfPaymentsMade": 4,
            "TotalDueAmount": 100,
            "TotalNumberOfPayments": 4,
            "PaymentSubType": "Moto",
            "AccountId": 395560,
            "InvoiceNumber": null,
            "OrderId": null,
            "FirstPaymentAmount": 0,
            "FirstPaymentDate": null,
            "SwipeData": null,
            "StartDate": "2013-11-04T07:00:00Z",
            "ScheduleStatus": "Expired",
            "ExecutionFrequencyType": "Daily",
            "ExecutionFrequencyParameter": 0,
            "Description": null,
            "Id": 118323,
            "LastModified": "2013-11-07T08:30:22Z",
            "CreatedOn": "2013-10-31T16:28:11Z"
        }],
        "RecurringPayments": []
    }
}
                                

All Suspended Schedules for a specific customer; Lite Record; Sorted by Next Payment Date, from present-to-future; 2 records per page, show page 1

JSON
Method = GET
URI = /v4/customer/255939/paymentschedules?status=suspended&sortby=NextPaymentDate &direction=ASC&page=1&pagesize=2&lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 3,
            "Page": 1,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "PaymentScheduleType": "RecurringPayment",
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerId": 255939,
        "ScheduleStatus": "Suspended",
        "NextPaymentDate": "2013-12-02T07:00:00Z",
        "PaymentAmount": 15,
        "Id": 118161,
        "LastModified": "2013-10-30T19:33:33Z",
        "CreatedOn": "2013-10-28T19:48:09Z"
    }, {
        "PaymentScheduleType": "PaymentPlan",
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerId": 255939,
        "ScheduleStatus": "Suspended",
        "NextPaymentDate": "2014-01-31T07:00:00Z",
        "PaymentAmount": 10,
        "Id": 118229,
        "LastModified": "2013-11-11T23:19:38Z",
        "CreatedOn": "2013-10-29T19:57:12Z"
    }]
}
                                

Payment Plan Schedules for a Specific Customer Started in Q4 2013 Listed in the order they were created (oldest-to-newest); 2 records per page, show page 1; Complete Schedule Record

JSON
Method = GET
URI = /v4/customer/255939/paymentplans?startdate=2013-10-01&enddate=2013-12-31&sortby=Id&direction=asc &pagesize=2&page=1&lite=false
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 2,
            "Page": 1,
            "ItemsPerPage": 2
        }
    },
    "Response": [{
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "NextScheduleDate": "2013-11-30T07:00:00Z",
        "BalanceRemaining": 80,
        "NumberOfPaymentsRemaining": 4,
        "PauseUntilDate": null,
        "PaymentAmount": 20,
        "FirstPaymentDone": false,
        "DateOfLastPaymentMade": "2013-10-31T06:00:00Z",
        "TotalAmountPaid": 20,
        "NumberOfPaymentsMade": 1,
        "TotalDueAmount": 100,
        "TotalNumberOfPayments": 5,
        "PaymentSubType": "Moto",
        "AccountId": 395560,
        "InvoiceNumber": null,
        "OrderId": null,
        "FirstPaymentAmount": 0,
        "FirstPaymentDate": null,
        "SwipeData": null,
        "StartDate": "2013-10-28T06:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "LastofMonth",
        "ExecutionFrequencyParameter": 0,
        "Description": null,
        "Id": 118171,
        "LastModified": "2013-10-31T07:30:18Z",
        "CreatedOn": "2013-10-28T21:59:00Z"
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "CustomerCompany": "ABC Company",
        "NextScheduleDate": "2013-11-30T07:00:00Z",
        "BalanceRemaining": 95,
        "NumberOfPaymentsRemaining": 19,
        "PauseUntilDate": null,
        "PaymentAmount": 5,
        "FirstPaymentDone": false,
        "DateOfLastPaymentMade": "2013-10-31T06:00:00Z",
        "TotalAmountPaid": 5,
        "NumberOfPaymentsMade": 1,
        "TotalDueAmount": 100,
        "TotalNumberOfPayments": 20,
        "PaymentSubType": "Moto",
        "AccountId": 395560,
        "InvoiceNumber": null,
        "OrderId": null,
        "FirstPaymentAmount": 0,
        "FirstPaymentDate": null,
        "SwipeData": null,
        "StartDate": "2013-10-28T06:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "LastofMonth",
        "ExecutionFrequencyParameter": 0,
        "Description": null,
        "Id": 118172,
        "LastModified": "2013-10-31T07:30:18Z",
        "CreatedOn": "2013-10-28T22:42:50Z"
    }]
}
                                

Active Recurring Payment Schedules for a Specific Customer Grouped by Frequency Type; Lite Records; 5 Records per page, show page 1

JSON
Method = GET
URI = /v4/customer/255939/recurringpayments?sortby=ScheduleStatus&pagesize=5 &page=1 &lite=true
Response
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "OK",
        "HttpStatusCode": 200,
        "PagingDetails": {
            "TotalItems": 18,
            "Page": 1,
            "ItemsPerPage": 5
        }
    },
    "Response": [{
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2014-10-31T06:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "Annually",
        "ExecutionFrequencyParameter": 0,
        "Id": 118162
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-11-12T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "Daily",
        "ExecutionFrequencyParameter": 0,
        "Id": 118163
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-12-01T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "FirstofMonth",
        "ExecutionFrequencyParameter": 1,
        "Id": 118169
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-12-04T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "SpecificDayofMonth",
        "ExecutionFrequencyParameter": 4,
        "Id": 118215
    }, {
        "CustomerId": 255939,
        "CustomerFirstName": "Test",
        "CustomerLastName": "Person",
        "NextScheduleDate": "2013-12-04T07:00:00Z",
        "ScheduleStatus": "Active",
        "ExecutionFrequencyType": "SpecificDayofMonth",
        "ExecutionFrequencyParameter": 4,
        "Id": 118216
    },
    }]
}
                                

Deleting Customer Records

You can delete any Customer Object as long as there are no active payment schedules or unsettled payments associated with it. All deletes performed via the API are soft deletes that simply flag a record as deleted. Deleted Customer objects are not included in any list Responses obtained via the API.

There is no Request Body required nor Response Body provided for a customer delete URI instruction.

To Delete a Customer Object via the API:

  • Method = DELETE
  • URI = /v4/customer/{CustomerId}

All data associated with a deleted Customer object remains saved in the database, and can be accessed via the API when the Object ID is used as part of the Request. The Response code “203 - Non Authoritative Information” is used to designate a deleted object. (The HttpStatus field in the Meta section of the Response will be "NonAuthoritativeInformation" and the HttpStatusCode will be “203” as shown below)

To confirm that a customer has been deleted, retrieve the customer object and check Response Information.

NOTE: See Retrieving Customer Records for instructions.

Delete Error Message

If you send a URI Delete request for a customer that cannot be deleted (either because it has an active schedule or has an unsettled payment associated with it), you will see the error message below:

 

 

JSON
"Meta": {
    "Errors": null,
    "HttpStatus": "NonAuthoritativeInformation",
    "HttpStatusCode": 203,
    "PagingDetails": null
}
                                

400 - Bad Request

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "There are still unsettled transactions outstanding for this Customer.  It cannot be deleted."
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

API HTTP Responses

All HTTP responses from the PaySimple 4.0 API will be a wrapped JSON response with the following format:

The “Meta:” section of the Wrapped JSON response will provide the HTTP response code as a numeric and text representation. If the response has information about paging or errors, then the respective object will contain additional information; otherwise, the object will be null.

Common HTTP responses from the PaySimple API are:

Status Code Status What It Means
200 OK Successful Request
201 Created New Object was successfully created
203 Non-authoritative Information The response is showing information for a deleted object
204 No Content Successfully processed request with no response body
400 Bad Request Error for Invalid Input - ErrorCode and ErrorMessage are provided to detail required information or error reason
401 Unauthorized Error getting an API token. Check your authentication credentials and resubmit. NOTE: A JSON response will not be returned only the HTTP header will be shown.
403 Forbidden Permission is denied to perform this action
404 Not Found The requested information cannot be found. It may not exist or may have been deleted.
405 Method Not Allowed The requested method is not allowed or supported for the specified object.
500 Internal Server Error System Error - Try again. If the error persists, contact PaySimple Customer Care for assistance.
JSON
{
    “Meta": {
        “HttpStatus":  … ,
        “HttpStatusCode":  … ,
        “Errors": {
            ...ErrorCode and ErrorMessages…
        }
        “PagingDetails": {
            …TotalItems, Page and ItemsPerPage…
        }
    },
    “Response": {
        …results…
    }
}
                                

Common API Errors

When errors occur, the top portion of the Response Meta will contain a detailed explanation of the error. Each error is comprised of an ErrorCode and an ErrorMessage. The former identifies the error type and the latter provides specific information about the error.

NOTE: If a Request contains multiple errors of a single type a single ErrorCode will be used in conjunction with multiple ErrorMessages.

NOTE: Creating a log to capture any API errors is strongly recommended. It will be extremely helpful when you work with our API Support Team to troubleshoot errors.

Error Codes

The following ErrorCode values are used:

Error Code What It Means
InvalidInput This is the most common error type, and occurs if there is a problem with the data entered in the Request. The ErrorMessage provided for this ErrorCode details the problem, and provides a text explanation that can be displayed directly to the User.
InvalidPermissions Permission is denied to perform this action.
NotFound The requested information cannot be found. It may not exist or may have been deleted.
UnexpectedError System Error - Check for coding errors and then try again. If the error persists, note the Trace Code included in the error and provide it to PaySimple Customer Care for assistance.

Error Messages

The ErrorMessage contains two components:

  • Field-- indicates the field containing the error. If the error is not field related, this section will be blank.
  • Message-- provides detailed information about the error and how to correct it. These message are suitable for direct display to the User. If a Trace Error is associated with the error, it will be displayed here so that the User can reference it when requesting assistance.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The following is an example of a Successful Request response for Posting a New Payment:

JSON
{
    "Meta": {
        "Errors": null,
        "HttpStatus": "Created",
        "HttpStatusCode": 201,
        "PagingDetails": null
    },
    "Response": {
        "CustomerId": 219175,
        "CustomerFirstName": "test",
        "CustomerLastName": "guy",
        "CustomerCompany": "",
        "ReferenceId": 0,
        "Status": "Posted",
        "RecurringScheduleId": 0,
        "PaymentType": "ACH",
        "PaymentSubType": "Web",
        "ProviderAuthCode": "Approved",
        "TraceNumber": "2ecf8cbd-89f9-4027-ac15-b092fad02c3b",
        "PaymentDate": "2013-12-04T07:00:00Z",
        "ReturnDate": null,
        "EstimatedSettleDate": "2013-12-09T07:00:00Z",
        "ActualSettledDate": null,
        "CanVoidUntil": "2013-12-05T00:00:00Z",
        "FailureData": null,
        "AccountId": 373191,
        "InvoiceId": null,
        "Amount": 10,
        "IsDebit": false,
        "InvoiceNumber": null,
        "PurchaseOrderNumber": null,
        "OrderId": null,
        "Description": null,
        "SuccessReceiptOptions": null,
        "FailureReceiptOptions": null,
        "Id": 1776260,
        "LastModified": "2013-12-04T20:32:00Z",
        "CreatedOn": "2013-12-04T20:32:00Z"
    }
}
                                

The following is an example of a Bad Request response for Posting a New Payment:

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Amount must be greater than 0"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

The following is an example of an error in which a Customer Object POST Request did not include first or last name:

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "FirstName",
                "Message": "The FirstName field is required."
            }, {
                "Field": "LastName",
                "Message": "The LastName field is required."
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Missing or Improper Field Values

This type of error typically occurs when you have failed to include a required field in a Customer, Payment, or Schedule Object Request.

  • ErrorCode: InvalidInput
  • ErrorMessage:
    • Field "{Name of the missing field}
    • Message "{Display-ready detailed error message}"

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Error Message Example 1: Customer Edit (PUT) request that does not contain the ShippingSameAsBilling field

JSON
NOTE: If ShippingSameasBilling is omitted it defaults to “false” and thus ShippingAddress must be included.
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "ShippingAddress",
                "Message": "ShippingAddress is required when ShippingSameAsBilling is false"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 2: New Payment Posted without an Amount

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Amount must be greater than 0"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 3: New Payment Plan Posted Without a Billing Frequency

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "ExecutionFrequencyType",
                "Message": "Invalid Billing Frequency"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 4: New Weekly Recurring Payment Schedule Posted Without a Billing Frequency Parameter

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Weekly schedules must have Billing Frequency Parameter set between 1 and 7."
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 5: Routing Number Entered for an ACH Account Is Not Valid

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "RoutingNumber",
                "Message": "Invalid Routing Number."
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 6: CCD ACH Payment Attempted for a Consumer (Customer Record does not have a Company Name saved)

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Company Name is required for all CCD transactions."
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Object ID Reference Errors

This type of error typically occurs when you attempt a Request that includes a Customer, Account, Payment, or Schedule Id that does not exist for the Client Account.

  • ErrorCode: InvalidInput
  • ErrorMessage:
    • Field "" (empty)
    • Message "{Display-ready detailed error message}"

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Error Message Example 1: Attempt to Process a Payment for a Non-existent Account

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Specified Customer Account Id is not valid"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 2: Attempt to View a Customer Object That Does Not Belong to Your Client

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Customer with ID 219175 does not belong to client"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 3: Attempt to Process a Payment for a Deleted Payment Account

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Account with ID 394099 has been deleted"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Customer Not Found Errors

This type of error occurs when you attempt to edit a deleted Customer Object.

  • ErrorCode: NotFound
  • ErrorMessage:
    • Field "" (empty)
    • Message "{Display-ready detailed error message}"

 

 

 

 

 

 

 

Example Customer Not Found Error Message

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "NotFound",
            "ErrorMessages": [{
                "Field": null,
                "Message": "Customer 260860 was not found, or has been deleted"
            }],
            "TraceCode": null
        },
        "HttpStatus": "NotFound",
        "HttpStatusCode": 404,
        "PagingDetails": null
    },
    "Response": null
}
                                

Unavailable Functions

This type of error occurs when you attempt a function that cannot be completed. For example, you’ll see this error type if you attempt to delete a payment account attached to an active schedule or attempt to delete a Customer associated with unsettled payments.

  • ErrorCode: InvalidInput
  • ErrorMessage:
    • Field "" (empty)
    • Message "{Display-ready detailed error message}"

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Error Message Example 1: Attempt to Delete a Payment Account Attached to an Active Schedule

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "NotFound",
            "ErrorMessages": [{
                "Field": null,
                "Message": "Customer 260860 was not found, or has been deleted"
            }],
            "TraceCode": null
        },
        "HttpStatus": "NotFound",
        "HttpStatusCode": 404,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 2: Attempt to Delete a Customer with Unsettled Payments

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "There are still unsettled transactions outstanding for this Customer. It cannot be deleted.”
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Error Message Example 3: Attempt to Delete a Schedule that has Started

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "Payments have been made on this schedule. Payment schedules that have started cannot be deleted, only suspended.”
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Improper Methods

This type of error occurs when you attempt a Route not supported by the API, such as attempting to delete a Payment Object; or when the system detects that you are using an incorrect method, such as using the “POST” method when trying to update an Object instead of the “PUT” method.

When using an unsupported Route, the Response Body will contain an error message describing the problem.

When the system detects what it identifies as an incorrect method, you will see a full error message:

  • ErrorCode: InvalidInput
  • ErrorMessage
    • Field "Id"
    • Message "Id cannot have a value, did you mean to execute a PUT operation?"

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Error Message Example 1: Attempt to Delete a Payment

JSON
{
    "Message": "The requested resource does not support http method 'DELETE'."
}
                                

Error Message Example 2: Attempt to Modify a Payment

JSON
{
    "Message": "The requested resource does not support http method 'PUT'."
}

                                

Error Message Example 3: Use the POST Method to Modify a Customer

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "Id",
                "Message": "Id cannot have a value, did you mean to execute a PUT operation?"
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Trace Errors

When an error occurs and the system cannot immediately identify the cause it creates a Trace Record that developers can look at to help troubleshoot the problem. This Trace Record is identified by a Trace Number that is returned as part of an API error message.

In some cases, typically when the error is due to an unexpected User input, this Trace Number is displayed in the ErrorMessage field so that it can be passed along to the User. The User can then call customer support and provide the Trace Code so that the problem can be investigated.

In other cases, typically when the error is at the system level, the Trace Number is provided in the TraceCode field included in the error message. An example of each case is provided below.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Trace Number in TraceCode Field

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "InvalidInput",
            "ErrorMessages": [{
                "Field": "",
                "Message": "CM-003: An unknown error occurred while processing your request. Please contact customer service. Trace number is '8D0AE88CCB92CF0'."
            }],
            "TraceCode": null
        },
        "HttpStatus": "BadRequest",
        "HttpStatusCode": 400,
        "PagingDetails": null
    },
    "Response": null
}
                                

Trace Number in Error Message

JSON
{
    "Meta": {
        "Errors": {
            "ErrorCode": "UnexpectedError",
            "ErrorMessages": [],
            "TraceCode": "API8D0AE891FE42F3D"
        },
        "HttpStatus": "InternalServerError",
        "HttpStatusCode": 500,
        "PagingDetails": null
    },
    "Response": null
}
                                

Using the API Test Tool

The API Test Tool is a powerful programming tool designed to give you a quick and easy way to interact with the PaySimple 4.0 API to test available routes and visually review an API response with JSON. This tool is designed to help you understand the HTTP communications that will be sent from and received by your application. As long as your application supports HTTP communications, you should be able to use the routes documented in this guide to interface with the PaySimple API.

The API Test Tool is accessed from the PaySimple Developer Website at:

When used with the correct method, route, and applicable JSON request, the API Test Tool will show you the response you can expect from the PaySimple API along with the corresponding JSON payload or data pack. You may also log into the PaySimple Sandbox Website using your Username and Password to see the result of your actions in PaySimple's standard user interface.

Getting Started Creating and Testing your Code

The API Test Tool is accessed from the PaySimple Developer Website at:
https://sandbox-api.paysimple.com/v4/help

The API Test Tool contains five main sections as described below:

Username and password fields -- API Authentication

When you register as a Developer with PaySimple, you are provided with a sandbox environment in which to test your code. This sandbox environment is used with the API Test Tool. You enter the User ID and Password used to login to the UI version of your Sandbox into the corresponding fields in the API Test Tool. This instructs the tool to obtain the API Key associated with your sandbox account for use in processing the JSON requests entered into the tool.

NOTE: When your sandbox environment was created, you should have received two emails: one with your user name and one with a temporary password. You will need to reset the password upon first login. Go to the PaySimple Sandbox Website Application to reset the password. After resetting your password, you may use the username and password here as a means to authenticate your API credentials via the API Test Tool..

Method Drop-Down Box

The Method drop-down box allows you to select the action you would like to take. These are the HTTP request types that follow the CRUD methods:

  • Create = Post
  • Retrieve = Get
  • Update = Put
  • Delete = Delete

URI Field

The URI is the field where you specify the endpoint for the method. You may find that the endpoint is the same across different methods. For example, the URI "/v4/customer" can accept the following methods: POST, PUT, and GET.

Request Information Section

Some API calls, such as PUT and POST, require a Request Body which may include a JSON string of the object to create or update. Not all fields in an object are required and the Schema Reference section documents all Objects and their attributes.

Response Information Section

Once a Request is submitted, you will see the HTTP Response Code in the Response Information section along with the Response Header. This is the information that will also be present in the HTTP Header when you receive the response from the PaySimple API. The Response Content section will contain the wrapped response object which includes Meta Data with paging information or error information if applicable, and the HTTP response in numeric code and text.

The wrapped object will also include the response JSON which will show a newly created object, requested object or collection, or updated object in full detail.

NOTE: If no response body is provided, a 204 response will be returned. In the API Test Tool, the response body section will say null. If you requested an object that has been deleted, you will receive a 203 response with the object in the Response Content section.

API Test Tool Example: Collecting a Payment for a New Customer

Create a Customer

  1. Enter Username and Password in the appropriate fields.
  2. Select "GET" in the Method drop-down box.
  3. Enter "/v4/new/customer" in the URI field to obtain the schema for a new Customer Object.
  4. Click the Submit button
  5. The empty Customer object code is displayed in the Response Content text box. All attributes are set to null. This is a request object that you can use as a template to create a new Customer.

    NOTE: The sample object is going to return all applicable Customer fields. You only need to complete required fields as defined in Customer Object Attributes

  6. Copy the Customer object from the Response Content section, selecting the curly brace after the "Response" to the curly brace after the "Created on" date.
  7. Paste the copied Customer object into the Request Body text box (or into an external text editor).
  8. Edit the Customer object attributes in the Request Body section (or external text editor-- paste into the Request Body section when done editing) replacing 'null' with actual customer information. Please enter values in double quotes for required and desired fields.

    NOTE: Make sure that the JSON code you paste into the Request Body field is valid. If it is not valid, the API will provide an error indicating 'Invalid JSON.'

    NOTE: A JSON Validator is available here:http://jsonformatter.curiousconcept.com/

  9. Create the New Customer by selecting "POST" from the Method drop-down box, entering "/v4/customer" in the URI field and clicking the "Submit" button.
  10. Once submitted, the Response Content textbox will refresh and display the wrapped response, including a 201 Success message in the Meta section along with the created object in the Response section. The Response Header box will also contain a success message with the object header as shown below.
  11. Locate and copy the numerical Customer ID for use in the next step.

    NOTE: To save the Customer ID, paste the copied ID into a text editor or write it down.

Add an Account

  1. Select "GET" in the Method drop-down box.
  2. Enter "/v4/new/account/creditcard" in the URI field to obtain a schema for a new payment account object.

    NOTE: If you are not collecting payments via credit card, please replace 'creditcard' with 'ach' in the account route.

  3. Click the Submit button.
  4. The empty Account object code is displayed in the Response Content text box. All attributes are set to null. This is a request object that you can use as a template to create a new Account.
  5. Copy the Account object from the Response Content section, selecting the curly brace after the "Response:" to the curly brace after the "Created on:" date.
  6. Paste the copied Account object into the Request Body text box.
  7. Edit the Account object attributes in the Request Bodysection (or external text editor- and paste back into the Request Body area) replacing 'null' with actual Account information values. Remember to Include the Customer ID saved from the previous step and ensure any other attribute values are in double quotes.

    NOTE: See Test Account Numbers for the Sandbox Environment for bank account and credit card information to use in the Sandbox.

  8. Create the New Account by selecting "POST" from the Method drop-down box and entering "/v4/account/creditcard" in the URI field.
  9. Click the Submit button.
  10. Once submitted the Response Content text box will refresh and display the wrapped response, including a 201 Success message in the Meta section along with the created object in the Response section.
  11. Locate and copy the numerical Account ID from the Response Content for the next step. Save this ID for the next step.

    NOTE: To save the Account ID, paste the copied ID into a text editor or write it down.

Collect a Payment

  1. Select "GET" in the Method drop-down box.
  2. Enter "/v4/new/payment" in the URI field to obtain to obtain a schema for a new Payment Object.
  3. Click the Submit button.
  4. The empty Payment object code is displayed in the Response Content textbox. All attributes are set to null. This is a request object that you can use as a template to create a new Payment.

    NOTE: Not all fields are required. See Payment Request Object Attributes for required fields.

  5. Copy the Payment object from the Response Content section, selecting the curly brace after the "Response:" to the curly brace after the "Created on:" date.
  6. Paste the copied Payment object into the Request Body text box (or into an external text editor).

  7. Edit the Payment object attributes in the Response Content section (or external text editor-- paste into the Response Content section when done editing) replacing 'null' with actual Payment information values. Enter required information, including the Account ID saved from the previous step and Amount, along with any other pertinent information such as payment subtype, description, invoice number or order number.

    NOTE: The CVV attribute applies to credit card payments and refers to the credit card security code. This is not a required field for a credit card payment. However, by providing the CVV, the credit card processor is aware that you or the customer had the credit card in hand at the time of the payment.

  8. Create the new Payment by selecting "POST" from the Method drop-down box and enter "/v4/payment" in the URI field.
  9. Click the Submit button.
  10. Once submitted the Response Content text box will refresh and display the wrapped response, including a 201 Success message in the Meta section along with the created object in the Response section.
  11. Locate and copy the numerical Payment ID from the Response Content.
  12. At this point you have collected a payment through API calls. You may log into the PaySimple Website Application and view the payment in the PaySimple's user interface.

Schema Reference

A schema displays object attributes, including those which are required, optional, and system managed. It also details any other applicable data constraints, such as minLength and/or maxLength or the pattern for the regular expression (regex) that applies to the attribute. This information serves as a reference for the required information to create an object assisting you in designing a user interface to validate any data constraints.

The Schema are metadata representations for each system object presented in easy to read JSON format. There are two object types: Request objects and Response objects

Request objects

A Request object shows only the attributes available to create an object. You are not required to provide values for all Request object attributes in order to create or edit an object.

Response objects

The Response object includes the attributes, optional and required, from the Request object along with the system-managed attributes and immutable object attributes. The schema provides detailed descriptions of each field, so you may understand how to use system fields as display fields in your application.

The following sections provide detailed definitions for all PaySimple 4.0 API Objects and their associated attributes.

Customer Object Attributes

The following sections detail Customer Request and Response Objects. For more information on using the API to manage Customer Objects, see the Customers section.

Customer Request Object Attributes

Required Attributes

FirstName: String -- 150 characters max

LastName: String -- 150 characters max

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. Set to “false” to require ShippingAddress fields.

Optional Attributes

BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- 250 characters max

StreetAddress2: String -- optional, 250 characters max

City: String -- 100 characters max

StateCode: String -- valid 2 character State or Territory code in the US or Canada

ZipCode: String -- up to 10 characters

Country: String -- optional, defaults to “US,” max 3 characters.

Company: String -- 50 characters max

CustomerAccount: String -- 28 characters max

Phone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

AltPhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

MobilePhone: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Fax: String -- 10 characters max, enter as a numeric string; do not include parenthesis or dashes.

Email: String -- 100 characters max, must be a valid email address.

AltEmail: String -- 100 characters max, must be a valid email address.

Website: String -- 100 characters max, must be in URL format.

Notes: String -- 2048 characters max

System Attributes

These fields are required components of the Customer Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the CustomerId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Customer Response Object Attributes

FirstName: String -- the customer’s last name (150 characters max)

LastName: String -- the customer’s first name (150 characters max)

ShippingSameAsBilling: Boolean -- Set to “true” to indicate that there is no separate shipping address, even if you are not including a billing address. If “true” the system will set shipping field values equal to their corresponding billing address fields. If set to “false” ShippingAddress fields are not linked to billing address fields.

BillingAddress: Object -- billing address is not required, but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- first line of billing street address (250 characters max)

StreetAddress2: String -- second line of billing street address. (Optional, 250 characters max)

City: String -- billing city (100 characters max)

StateCode: String -- billing state; valid 2 character State or Territory code in the US or Canada

ZipCode: String -- billing postal code; up to 10 characters

Country: String -- billing Country (optional, defaults to “US,” max 3 characters.)

ShippingAddress: Object -- not required if ShippingSameAsBilling is set to “true,” but if included all its attributes are required except “StreetAddress2,” “StateCode,” and “Country.” Up to 10 characters of any type is valid for “ZipCode.”

StreetAddress1: String -- primary shipping address line (250 characters max)

StreetAddress2: String -- second shipping address line (Optional, 250 characters max)

City: String -- the shipping city (100 characters max)

StateCode: String -- the shipping state; valid 2 character State or Territory code in the US or Canada

ZipCode: String -- the shipping postal code; up to 10 characters

Country: String -- the shipping country (Optional, defaults to “US,” max 3 characters.)

Company: String -- the Company name for the customer (50 characters max)

CustomerAccount: String -- the Account Number the User entered for the customer (28 characters max)

Phone: String -- the primary phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

AltPhone: String -- the secondary phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

MobilePhone: String -- the mobile phone number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

Fax: String -- the fax number for the customer (10 characters max, enter as a numeric string; do not include parenthesis or dashes.)

Email: String -- the primary email address for the customer. (100 characters max, must be a valid email address.)

AltEmail: String -- the secondary email address for the customer. (100 characters max, must be a valid email address).

Website: String -- a website associated with the customer. (100 characters max, must be in URL format.)

Notes: String -- an open text area. (2048 characters max)

Id: Integer -- assigned by the system, the CustomerId for the record. This is the Id referenced for this customer in all other API objects. It defaults to “0” for new requests, and is populated with the CustomerId in the Response.

LastModified: String -- set by the system, the last time and date on which the record was changed, any Request data will be disregarded

CreatedOn: String -- set by system, the time and date the record was created, any Request data will be disregarded

Account Object Attributes

The PaySimple 4.0 API supports two types of Account: ACH and Credit Card. Each of these Account Objects has its own set of attributes. There is no separate schema for an “account” that includes attributes from both types. When returning a list of accounts for a specific Customer Record, the Response will list all Credit Card Accounts first and then all ACH Accounts.

The following sections provide attribute definitions for Credit Card and ACH Accounts.

ACH Account Objects Attributes

The following sections detail ACH Account Request and Response Objects. For more information on using the API to manage ACH Account Objects, see the Managing Customer Payment Accounts section.

ACH Account Request Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from a previously created Customer Object.

RoutingNumber: String -- 9 digit bank routing number

AccountNumber: String -- min 4 digits, max 100 digits; the bank account number

BankName: String-- 100 characters max; the financial institution name

IsCheckingAccount: Boolean -- enter “true” to indicate a checking account or “false” to indicate a savings account. General Ledger accounts are not supported.

IsDefault: Boolean -- enter “true” to set the account as the default ACH Account for the Customer Record, otherwise enter “false.” If there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of your entry.

System Attributes

These fields are required components of the ACH Account Object that are populated by the system-- you do not need to include them in your requests.

 

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

ACH Account Response Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record with which the account is associated. This is the “Id” attribute from a previously created Customer Object.

RoutingNumber: String -- 9 digit bank routing number.

AccountNumber: String -- the bank account number (min 4 digits, max 100 digits)

BankName: String-- the financial institution name (100 characters max)

IsCheckingAccount: Boolean -- “true” indicates a checking account and “false” indicates a savings account. General Ledger accounts are not supported.

IsDefault: Boolean -- “true” indicates that the account is the default ACH Account for the Customer Record; “false” indicates that it is not the default. When adding new accounts, if there are no other ACH Accounts attached to the Customer Record, the field will default to “true” regardless of the value provided in the Request

Id: Integer -- assigned by the system, the AccountId for the record. This is the Id referenced for this account in all other API objects. It defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by the system, the last time and date on which the record was changed, any Request data will be disregarded

CreatedOn: String -- set by system, the time and date the record was created, any Request data will be disregarded

Credit Card Account Object Attributes

The following sections detail Credit Card Account Request and Response Objects. For more information on using the API to manage Credit Card Account Objects, see the Managing Customer Payment Accounts section.

Credit Card Account Request Object Attributes

Required Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added. This is the “Id” attribute from a previously created Customer Object.

CreditCardNumber: String -- 15 or 16 digits

ExpirationDate: String -- a valid date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

IsDefault: Boolean -- enter “true” to set the card as the default Credit Card Account for the Customer Record, otherwise enter “false.” If there are no other cards attached to the Customer Record, the field will default to “true” regardless of your entry.

Optional Attributes

BillingZipCode: String -- max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

System Attributes

These fields are required components of the Credit Card Account Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Credit Card Account Response Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record to which the card is being added.This is the “Id” attribute from a previously created Customer Object.

CreditCardNumber: String -- 15 or 16 digit credit card number.

ExpirationDate: String -- a valid credit card expiration date in the format of MM/YYYY

Issuer: Integer-- enumeration: 12 = Visa; 13 = Master (MasterCard); 14= Amex (American Express); 15 = Discover

IsDefault: Boolean -- “true” indicates that the account is the default Credit Card Account for the Customer Record; “false” indicates that it is not the default. When adding new accounts, if there are no other Credit Card Accounts attached to the Customer Record, the field will default to “true” regardless of the value provided in the Request.

BillingZipCode: String -- the billing postal code associated with the credit card; max 10 characters. If left blank, system will use the Billing Zip code (ZipCode attribute for the Customer object) when processing a payment, and the BillingZipCode attribute will be null. Up to 10 characters of any type is valid.

Id: Integer -- assigned by the system, the AccountId for the record. This is the Id referenced for this account in all other API objects. It defaults to “0” for new requests, and is populated with the AccountId in the Response

LastModified: String -- set by system, the last date the Credit Card object was changed, any Request data will be disregarded.

CreatedOn: String -- set by system, the date the Credit Card Object was created, any Request data will be disregarded

Payment Object Attributes

The following sections detail Payment Request and Response Objects. For more information on using the API to manage Payment Objects, see the Payments section.

Payment Request Object Attributes

Required Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the payment. This is the “Id” attribute from the Credit Card Object or ACH Account Object created in the previous step.

Amount: Number -- the amount to charge. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 3.129 will result in a payment Amount of 3.13.

Optional Attributes

IsDebit: Boolean-- this field defaults to “false” to indicate a payment whether or not it is included. Entering “true” will result in an error, as standalone credits are not currently supported via the API.

CVV: String-- min 3 digits, max 4 digits; the credit card security code. This field defaults to null when not included. It may be included for credit card payments and will be ignored if entered for ACH payments.

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceId: Integer-- a system invoice identifier. If included it will seat the associated system Invoice Number in the InvoiceNumber attribute, and will apply the payment to the specified Invoice ID.

NOTE: Invoice creation and management is not available via the API.

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the payment. If the number provided is a system Invoice Number, the associated InvoiceId will be attached to the payment and the payment will be applied to the system invoice.
NOTE: Invoice creation and management is not available via the API.

PurchaseOrderNumber: String-- 50 characters max; the Purchase Order Number attached to the payment.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

Description: String-- -- 2048 characters max.

Latitude: Number-- this field is not currently used in the UI, but will accept and save latitude values.

Longitude: Number-- this field is not currently used in the UI, but will accept and save longitude values.

SuccessReceiptOptions: Object -- the receipt instructions. Null means the current system default settings should be used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how payment receipts are sent:

SendToCustomer --”true” indicates that the receipt gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the receipt email is to be sent. Using brackets, enter valid email addresses separated by commas.

FailureReceiptOptions: Object -- the failure notification email instructions. Null means the current system default settings should be used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how failure notifications are sent:

SendToCustomer --”true” indicates that the notification gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the failure notification email is to be sent. Using brackets, enter valid email addresses separated by commas.

System Attributes

These fields are required components of the Payment Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the PaymentId in the Response.

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Payment Response Object Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the payment. This is the “Id” attribute from a previously created Credit Card Object or ACH Account Object.

Amount: Number -- the payment Amount. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 3.129 will result in a payment Amount of 3.13.

IsDebit: Boolean-- “false” for a payment or “true” for a standalone credit. This field defaults to “false” to indicate a payment whether or not it is included in the Request. Entering “true” in the Request Body will result in an error, as standalone credits are not currently supported via the API.

PaymentSubType: String-- the type of Credit Card or ACH payment. It defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceId: Integer-- the InvoiceId from a PaySimple system invoice, if any, associated with the Payment. If included it will seat the associated system Invoice Number in the InvoiceNumber attribute, and will apply the payment to the specified Invoice ID.
NOTE: Invoice creation and management is not available via the API.

InvoiceNumber: String-- the Invoice Number attached to the payment. If the number provided is a system Invoice Number, the associated InvoiceId will be attached to the payment and the payment will be applied to the system invoice. (50 characters max)
NOTE: Invoice creation and management is not available via the API.

PurchaseOrderNumber: String-- the Purchase Order Number, if any, entered with the Payment. (50 characters max).

OrderId: String-- a back-end transaction identifier that may be included for the payment. It is not visible in the PaySimple UI. (50 characters max)

Description: String-- an open text field used to provide a description of the goods and/or services being paid for. This field is included in payment receipt templates to meet the processing requirement that a description of goods and services be included on receipts. (2048 characters max.)

Latitude: Number-- this field is not currently used, but will accept and save latitude values.

Longitude: Number-- this field is not currently used, but will accept and save longitude values.

SuccessReceiptOptions: Object -- the receipt instructions specified in the Payment Request. Null means the current system default settings were used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how payment receipts are sent:

SendToCustomer --”true” indicates that the receipt gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the receipt email is sent. Using brackets, enter valid email addresses separated by commas.

FailureReceiptOptions: Object -- the failure notification email instructions specified in the Payment Request. Null means the current system default settings were used. (If not included, null is the default.) The following additional fields can be used to override defaults and direct how failure notifications are sent:

SendToCustomer --”true” indicates that the notification gets sent to the email address attached to the Customer Record; “false” indicates that it does not.

SendToOtherAddresses-- a specific email address (or addresses) to which the failure notification email is sent. Using brackets, enter valid email addresses separated by commas.

Id: Integer -- assigned by the system, the PaymentId for the record. This is the Id referenced for this payment in future calls related to the transaction including void, refund, and view details. It defaults to “0” for new requests, and is populated with the PaymentId in the Response.

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment. (The system identifies the CustomerId with which the AccountId is associated.)

CustomerFirstName: String -- the first name of the Customer associated with the payment. The system populates this field based on the AccountId (and the associated CustomerId) supplied in the Request.

CustomerLastName: String -- the last name of the Customer associated with the payment. The system populates this field based on the AccountId (and the associated CustomerId) supplied in the Request.

CustomerCompany: String -- the Company, if any, associated with the payment. The system populates this field based on the AccountId (and the associated CustomerId) supplied in the Request.

ReferenceId: Integer -- for a refunded payment, the PaymentId for the refund transaction, for a refund transaction the Payment Id for the refunded payment.This field will be “0” in all other cases.

Status: Integer -- payment Status set by the system. Enumeration: 0 = Pending; 1 = Posted; 2 = Settled; 3 = Failed; 5 = Voided; 6 = Reversed; 9 = ReversePosted; 10 = Chargeback; 12 = Authorized; 13 = Returned; 15 = ReverseNSF; 17 = Refund Settled

Expected Responses for new payments are Posted, Authorized or Failed.

These labels do not all correspond to PaySimple Status names in the UI. Mapping is as follows:
Reversed = Refunded; ReversePosted = Refund (Posted); ReverseNSF = Returned NSF

RecurringScheduleId: Integer -- if a payment is part of a schedule, the ScheduleId. This field will be “0” in all other cases.

PaymentType: Integer -- set by the system to identify the transaction type, based on the type of account associated with the AccountId used for the payment. Enumeration: 1 = CC (credit card); 2 = ACH

ProviderAuthCode: String -- a pass-through field that displays the authorization response for the transaction.

TraceNumber: String -- a pass-through field that displays the processor’s transaction identifier for a successful transaction or the provider’s error message for a failed transaction.

PaymentDate: String -- set by the system, the date the payment was processed. When entering new one-time payments, this field is set to the current date. Date format YYYY-MM-DDT00:00:00Z.

ReturnDate: String -- set by the system, the date an ACH payment was Returned. This field will always be null for new transactions and will always be null for Credit Card transactions. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

EstimatedSettleDate: String -- the date the system expects the transaction to be settled, based on a merchant’s funding time. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

ActualSettledDate: String -- the date the system receives notification that a transaction has actually settled. This field will always be null for new transactions. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

CanVoidUntil: String -- the last date on which a transaction may be voided.

FailureData: String -- standardized system information about why a transaction failed; 4 components:
Code --a 4-digit PaySimple Error Code

Description --a description of the Error

MerchantActionText --instructions to the merchant on how to handle the error.

"IsDecline" -- “true” indicates that the failure was due to the transaction being declined; “false” indicates a failure due to any other reason.

NOTE: See Appendix A for a table containing Failure Codes and associated messages.

LastModified: String -- set by the system, the date and time the transaction record was last modified. Date format YYYY-MM-DDT00:00:00Z.

CreatedOn: String -- set by the system, the date and time the transaction record was created (i.e. the time and date the payment was processed). Date format YYYY-MM-DDT00:00:00Z.

Schedule Object Attributes

The PaySimple 4.0 API supports two types of Schedule: Recurring Payment and Payment Plan. Each of these Schedule Objects has its own set of Request and Response Object attributes. There is a separate abbreviated schema for a “PaymentSchedule” that is a condensed Response Object including a set of attributes shared by both schedule types, along with a schedule attribute that indicates schedule type.

The following sections provide attribute definitions for PaymentSchedule, RecurringPayment and PaymentPlan. For more information on using the API to manage Schedules, see the Payment Schedules section.

Payment Schedule Response Object Attributes

The PaymentSchedule Response Object is designed for creating lists of schedules. There is not a corresponding Request Object for entering new schedule objects, or for modifying existing schedule objects. The following attributes are available:

PaymentScheduleType: String -- “RecurringPayment for a Recurring Payment Schedule or “PaymentPlan” for a Payment Plan Schedule.

CustomerFirstName: String -- the first name of the Customer associated with the schedule.

CustomerLastName: String -- the last name of the Customer associated with the schedule.

CustomerId: Integer -- the system identifier for the Customer Record associated with the payment.

ScheduleStatus: Integer -- the current schedule Status.
Enumeration: 1 = Active; 2 = PauseUntil; 3 = Expired; 4 = Suspended

NextPaymentDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

NOTE: This attribute is called “NextScheduleDate” in RecurringPayment and PaymentPlan Objects.

PaymentAmount: Number-- the amount of each scheduled payment.

Id: Integer -- assigned by the system, the ScheduleId number referenced in calls related to this schedule including pause, suspend, resume, and view details.

LastModified: String -- set by the system, the date and time the schedule object was last modified.

CreatedOn: String -- set by the system, the date and time the schedule object was created.

Recurring Payment Object Attributes

The following sections detail Recurring Payment Request and Response Objects. For more information on using the API to manage Recurring Payment Objects, see the Payment Schedules section.

Recurring Payment Request Object Attributes

Required Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule. The Customer Object associated with the AccountId will be associated with the schedule.

PaymentAmount: Number -- the scheduled payment amount. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 3.129 will result in a PaymentAmount of 3.13.

StartDate: String-- the date on which the schedule will start (or did start) running, not necessarily the date it will generate its first payment. If a future date is used, it can be edited prior to the schedule starting. After the first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

NOTE: To make schedule management easier, it is strongly recommended that you set the schedule StartDate to the first day it will generate a payment.

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments.

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

Optional Attributes

EndDate: String-- the date the schedule is to stop generating payments. If not included or left null, the schedule will default to running until manually disabled.Date format: YYYY-MM-DD.

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.

NOTE: To ensure that you do not collect more than the amount due for the system invoice it is better to use a Payment Plan schedule (instead of a recurring billing schedule) to discharge a system invoice.

NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31
NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

Description: String-- -- 2048 characters max.

System Attributes

These fields are required components of the Recurring Payment Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the ScheduleId in the Response.

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Recurring Payment Response Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the schedule.This value is assigned based on the Customer Object to which the designated Payment Account Object for the schedule is attached.

CustomerFirstName: String -- the first name of the Customer associated with the schedule.

CustomerLastName: String -- the last name of the Customer associated with the schedule.

CustomerCompany: String -- the Company, if any, associated with the schedule.

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule. The Customer Object associated with the AccountId will be associated with the schedule.

PaymentAmount: Number -- the scheduled payment amount. An integer or a decimal. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 3.129 will result in a PaymentAmount of 3.13.

StartDate: String -- the date on which the schedule will start (or did start) running, not necessarily the date it will (or did) generate its first payment. If a future date is used, it can be edited prior to the schedule starting. After the first payment is actually generated the field becomes read-only. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

ExecutionFrequencyType: Integer-- the primary frequency on which the schedule executes payments. (The Response displays the text not the integer.)

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

EndDate: String-- the date the schedule will stop generating payments (status changes to “Expired”). If the schedule is programmed to run indefinitely, this field will be null. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.
NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. Enter a number only, do not include the $. An integer or a decimal. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31
NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

Description: String-- -- 2048 characters max. An open text field.

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

PauseUntilDate: String -- the date a paused schedule is or was set to resume. If the schedule status is “suspended” this is the date it will automatically resume. If the schedule status is “Active” or “Expired” and this field has a value, it is the most recent date on which the schedule resumed. For schedules that have never been paused, this value will be null.

NOTE: The PauseUntilDate field does not re-set to “null” once a paused schedule resumes. This field will always contain the date on which the schedule was last re-activated.

NOTE: See
Pause a Payment Schedule for instructions on how to set a pause and a resume date via the API.

FirstPaymentDone: Boolean-- if any payment (either the custom first payment or the first scheduled payment) has been generated by the schedule this attribute will be “true” and the schedule can no longer be deleted. If no payment activity has been generated by the schedule, this attribute will be “false.”

DateOfLastPaymentMade: String-- a read only system field indicating the last date a scheduled payment (not a custom first payment) was generated by the schedule. If the schedule has not yet generated a payment this field will be null.

TotalAmountPaid: Number-- a read only system field indicating the sum of all payments, including any custom first payment, generated by the schedule.

NumberOfPaymentsMade: Integer-- a read only system field indicating the number of regular payments (not including any custom first payment) generated by the schedule.

ScheduleStatus: Integer -- the current schedule Status.
Enumeration: 1 = Active; 2 = PauseUntil; 3 = Expired; 4 = Suspended
NOTE: Schedule Status is changed via URI Status Change requests, not by modifying the value of this field via a URI PUT request. See
Suspend a Payment Schedule, Pause a Payment Schedule, and Resume a Payment Schedule for detailed instructions.

Id: Integer -- this is the ScheduleId number you will need to reference in calls related to this schedule including pause, suspend, resume, and view details.

LastModified: String -- set by the system, the date and time the recurring payment object was last modified.

CreatedOn: String -- set by the system, the date and time the recurring payment object was created.

Payment Plan Object Attributes

The following sections detail Payment Plan Request and Response Objects. For more information on using the API to manage Payment Plan Objects, see the Schedules section.

Payment Plan Request Object Attributes

Required Attributes

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule. This is the “Id” attribute from the Credit Card Object or ACH Account Object to be used for the schedule. The Customer Object associated with the AccountId will be associated with the schedule.

TotalDueAmount: Number -- the total amount to be collected for the schedule. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 300.129 will result in a TotalDueAmount of 300.13.

TotalNumberOfPayments: Integer -- the total number of schedule payments. Enter any integer between 1 and 99.

StartDate: String-- the first date the schedule will generate a payment based on the configured frequency. This can be the current date, or any future date. If a future date is used, it can be edited prior to the schedule starting. After the first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.
NOTE: To make schedule management easier, it is strongly recommended that you set the schedule StartDate to the first day it will generate a payment.

ExecutionFrequencyType: Integer-- the primary frequency on which to execute scheduled payments.

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

Optional Attributes

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.
NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. Enter a number only, do not include the $. You can enter an integer or a decimal. If you use more than 2 decimal places, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13. This amount is subtracted from the TotalDueAmount when the system calculates the schedule PaymentAmount.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31
NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

Description: String-- -- 2048 characters max. An open text field.

System Attributes

These fields are required components of the Recurring Payment Object that are populated by the system-- you do not need to include them in your requests.

Id: Integer -- defaults to “0” for new requests, and is populated with the ScheduleId in the Response.

LastModified: String -- set by system, any Request data will be disregarded

CreatedOn: String -- set by system, any Request data will be disregarded

Payment Plan Response Object Attributes

CustomerId: Integer -- the system identifier for the Customer Record associated with the schedule.This value is assigned based on the Customer Object to which the designated Payment Account Object for the schedule is attached.

CustomerFirstName: String -- the first name of the Customer associated with the schedule.

CustomerLastName: String -- the last name of the Customer associated with the schedule.

CustomerCompany: String -- the Company, if any, associated with the schedule.

AccountId: Integer -- the system identifier for the Credit Card Account or ACH Account used for the schedule.

TotalDueAmount: Number -- the total amount to be collected for the schedule. An integer or a decimal, without the $ is used. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 300.129 will result in a TotalDueAmount of 300.13.

TotalNumberOfPayments: Integer -- the total number of schedule payments. An integer between 1 and 99.

StartDate: String -- the date on which the schedule will start (or did start) running, not necessarily the date it will (or did) generate its first payment. If a future date is used, it can be edited prior to the schedule starting. After the first payment is actually generated the field becomes read-only. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

ExecutionFrequencyType: Integer-- the primary frequency on which the schedule executes payments. (The Response displays the text not the integer.)

enumeration: 1 = Daily, 2 = Weekly, 3 = BiWeekley, 4 = First of Month, 5 = Specific Day of Month,
6 = Last of Month, 7 = Quarterly, 8 = Semi-Annually, 9 = Annually

ExecutionFrequencyParameter: Integer -- used to specify the day of month for a Specific Day of Month schedule or to specify the day of the week for a weekly or bi-weekly schedule.

enumeration (Weekly/Bi-Weekly): 1=Sunday; 2=Monday; 3=Tuesday; 4=Wednesday; 5=Thursday
6=Friday; 7=Saturday

Monthly: Enter an integer from 1 -31
NOTE: To avoid confusion, if you want to bill on the 30th or 31st, use a “Last Day of Month” Frequency Type instead of the “Specific Day of Month” Frequency Type.

PaymentSubType: String-- this field defaults to “MOTO” for credit card payments and “WEB” for ACH payments if not included or left null.

enumeration (ACH): 4 = WEB; 5 = TEL; 6 = PPD; 7= CCD

enumeration (CC): 10 = SWIPE; 11 = MOTO

InvoiceNumber: String-- 50 characters max; the Invoice Number attached to the schedule. If the number provided is a system Invoice Number, the associated system InvoiceId will be attached to the schedule and the scheduled payments will be applied to the system invoice.
NOTE: Invoice creation and management is not available via the API.

OrderId: String-- 50 characters max; a back-end transaction identifier not included in the UI.

FirstPaymentAmount: Number-- a custom payment amount that is executed prior to the start of the schedule. An integer or a decimal, without the $ is used. If more than 2 decimal places are entered, the system will round to the nearest penny-- i.e. entering 23.129 will result in a FirstPaymentAmount of 23.13.

FirstPaymentDate: String-- the date the custom first payment is to be processed. This can be the current date, or any future date, but must be prior to the schedule StartDate. If a future date is used, it can be edited prior to the custom first payment being generated. After the custom first payment is actually generated the field becomes read-only. Date format: YYYY-MM-DD.

Description: String-- -- 2048 characters max.

NextScheduleDate: String -- the next date on which the schedule will generate a payment, based on the schedule frequency. Date format YYYY-MM-DDT00:00:00Z. (You can ignore the time portion of this date.)

BalanceRemaining: Number-- a read-only system field indicating the total amount still to be collected as part of the schedule. (TotalDueAmount - TotalAmountPaid = BalanceRemaining)

NumberOfPaymentsRemaining: Integer -- a read-only system field indicating the number of payments left to be generated on the schedule. If the schedule has yet to generate a payment, it will be equal to TotalNumberofPayments.

PauseUntilDate: String -- the date a paused schedule is or was set to resume. If the schedule status is “suspended” this is the date it will automatically resume. If the schedule status is “Active” or “Expired” and this field has a value, it is the most recent date on which the schedule resumed. For schedules that have never been paused, this value will be null.
NOTE: The PauseUntilDate field does not re-set to “null” once a paused schedule resumes. This field will always contain the date on which the schedule was last re-activated.

NOTE: See Pause a Payment Schedule for instructions on how to set a pause and a resume date via the API.

PaymentAmount: Number -- the system calculated amount of each scheduled payment.
PaymentAmount = (TotalAmountDue - CustomFirstPaymentAmount) / NumberofPayments.

FirstPaymentDone: Boolean-- if any payment (either the custom first payment or the first scheduled payment) has been generated by the schedule this attribute will be “true” and the schedule can no longer be deleted. If no payment activity has been generated by the schedule, this attribute will be “false.”

DateOfLastPaymentMade: String-- a read only system field indicating the last date a scheduled payment (not a custom first payment) was generated by the schedule. If the schedule has not yet generated a payment this field will be null.

TotalAmountPaid: Number-- a read only system field indicating the sum of all payments, including any custom first payment, generated by the schedule.

NumberOfPaymentsMade: Integer-- a read only system field indicating the number of regular payments (not including any custom first payment) generated by the schedule.

ScheduleStatus: Integer -- the current schedule Status.
Enumeration: 1 = Active; 2 = PauseUntil; 3 = Expired; 4 = Suspended
NOTE: Schedule Status is changed via URI Status Change requests, not by modifying the value of this field via a URI PUT request. See Suspend a Payment Schedule, Pause a Payment Schedule, and Resume a Payment Schedule for detailed instructions.

Id: Integer -- this is the ScheduleId number you will need to reference in calls related to this schedule including pause, suspend, resume, and view details.

LastModified: String -- set by the system, the date and time the recurring payment object was last modified.

CreatedOn: String -- set by the system, the date and time the recurring payment object was created.

Appendix A: API Quick Reference

The following tables provide commonly used routes and endpoints for the PaySimple 4.0 API

PaySimple 4.0 API Endpoints

Environment Endpoint
PaySimple Production https://api.paysimple.com
PaySimple Sandbox https://sandbox-api.paysimple.com

API Test Tool URL

https://sandbox-api.paysimple.com/v4/Help/Test

URI Request Building Tools

GET URI Function

/v4/new/{object}

where “object” =

  • Customer
  • ACH
  • Creditcard
  • Payment
  • RecurringPayment
  • PaymentPlan            

/v4/lookup

Returns an empty object of the specified type.

An informational URI detailing the system enumerations for statuses, payment types, invoice actions, and payment schedule frequencies. This also includes valid State and U.S. territory codes.

Customer Routes

Method URI Description
GET /v4/customer Returns a list of Customer records
GET /v4/customer/{customerId} Returns a Customer record for the specified Id
GET /v4/customer/{customerId}/payments Returns a list of Payment records for the specified Id
GET /v4/customer/{customerId}/paymentschedules Returns a collection of Payment Schedule records (both Recurring Payment Schedules and Payment Plan Schedules) in abbreviated list format, for the specified CustomerId.
GET /v4/customer/{customerId}/accounts Returns a list of all payment accounts (both credit card and ACH bank accounts) associated with the specified CustomerId.
GET /v4/customer/{customerId}/achaccounts Returns a list of all ACH Accounts (bank accounts) associated with the specified CustomerId.
GET /v4/customer/{customerId}/creditcardaccounts Returns a list of all Credit Card accounts associated with the specified CustomerId.
GET /v4/customer/{customerId}/defaultach Returns the Default ACH Account (bank account) associated with the specified CustomerId.
GET /v4/customer/{customerId}/defaultcreditcard Returns the Default Credit Card account associated with the specified CustomerId.
POST /v4/customer Creates a new Customer Record from the Customer Object Request Body content.
PUT /v4/customer Updates the Customer Record for the CustomerId specified in the Request Body, using values from any fields included in the Request.
PUT /v4/customer/{customerId}/{accountId} Sets the default ACH or Credit Card using the CustomerId and AccountId specified in the request.
DELETE /v4/customer/{customerId} Deletes the Customer Record for the specified CustomerID.

Payment Account Routes

Method URI Description
GET /v4/account/creditcard/{accountId} Returns a the Credit Card Record for the specified Id.
GET /v4/account/ach/{accountId} Returns a the ACH Record for the specified Id.
POST /v4/account/creditcard Creates a new Credit Card Record from the Credit Card Object Request Body content. (The ID for the Customer with which the account is to be associated is specified in the CustomerId field in the Body.)
POST /v4/account/ach Creates a new ACH Record from the ACH Object Request Body content. (The ID for the Customer with which the account is to be associated is specified in the CustomerId field in the Body.)
PUT /v4/account/creditcard Updates the Credit Card Record for the AccountId specified in the Request Body, using values from any fields included in the Request.

NOTE: Only Expiration Date and Billing Zip can be changed; changed to other fields will be ignored.

PUT /v4/account/ach Updates the ACH Record for the AccountId specified in the Request Body, using values from any fields included in the Request.

NOTE: Only Account Type (IsCheckingAccount) can be changed; changed to other fields will be ignored.

DELETE /v4/account/creditcard/{accountId} Deletes the Credit Card Record for the specified accountId.
DELETE /v4/account/ach/{accountId} Deletes the ACH Record for the specified accountId.

Payment Routes

Method URI Description
GET /v4/payment Returns a list of all Payment Records.
GET /v4/payment/{paymentId} Returns a the Payment Record for the specified Id.
POST /v4/payment Creates a new Payment Record from the Payment Object Request Body content. (The ID for the Customer to be charged is specified in the CustomerId field in the Body.)
PUT /v4/payment/{paymentId}/reverse Reverses the settled Payment of the specified Id

NOTE: A body is not required for this request.

PUT /v4/payment/{paymentId}/void Voids the Payment of the specified Id

NOTE: A body is not required for this request.

Payment Schedule Routes

Method URI Description
GET /v4/paymentschedule Returns a collection of Payment Schedule Records (both Payment Plan and Recurring Payment), using an abbreviated record list format.
GET /v4/recurringpayment Returns a collection of Recurring Payment Schedule Records.
GET /v4/paymentplan Returns a collection of Payment Plan Schedule Records.
GET /v4/recurringpayment/{scheduleId} Returns the Recurring Payment Schedule Record for the specified scheduleId.
GET /v4/paymentplan/{scheduleId} Returns a the Payment Plan Schedule Record for the specified scheduleId.
GET /v4/recurringpayment/{scheduleId}/payments Returns a list of payments associated with the specified scheduleId. (The Payment Records for the payments generated by the schedule.)
GET /v4/paymentplan/{scheduleId}/payments Returns a list of payments associated with the specified scheduleId. (The Payment Records for the payments generated by the schedule.)
POST /v4/recurringpayment Creates a new Recurring Payment Record from the Recurring Payment Object Request Body content. (The ID for the Customer to be charged is specified in the CustomerId field in the Body.)
POST /v4/paymentplan Creates a new Payment Plan Record from the Recurring Payment Object Request Body content. (The ID for the Customer to be charged is specified in the CustomerId field in the Body.)
PUT /v4/recurringpayment Updates the Recurring Payment Schedule Record for the scheduleId specified in the Request Body, using values from any fields included in the Request.
PUT /v4/recurringpayment/{scheduleId}/pause?endDate={iso8601 Date} Pauses the specified Recurring Payment Schedule until the specified endDate.
PUT /v4/paymentplan/{scheduleId}/pause?endDate={iso8601 Date} Pauses the specified Payment Plan Schedule until the specified endDate.
PUT /v4/recurringpayment/{scheduleId}/suspend Suspends the specified Recurring Payment Schedule indefinitely.
PUT /v4/paymentplan/{scheduleId}/suspend Suspends the specified Payment Plan Schedule indefinitely.
PUT /v4/recurringpayment/{scheduleId}/resume Immediately resumes the specified paused or suspended Recurring Payment Schedule.
PUT /v4/paymentplan/{scheduleId}/resume Immediately resumes the specified paused or suspended Payment Plan Schedule.
DELETE /v4/recurringpayment/{scheduleId} Deletes the specified Recurring Payment Schedule Record.
DELETE /v4/paymentplan/{scheduleId} Deletes the specified Payment Plan Schedule Record.

Filtering and Sorting Request Parameters

Parameter GET URI Values Supported GET Routes Description
Lite true false (default) /v4/customer /v4/payment /v4/paymentschedule /v4/paymentplan /v4/recurringpayment /v4/customer/{id}/payments /v4/customer/{id}/paymentschedules /v4/customer/{id}/paymentplans /v4/customer/{id}/recurringpayments Returns a “lite” or abbreviated record, ideal for creating lists and tables, for the specified Object type. The default is to return the complete record (Lite= false), to return the abbreviated record specify “lite = true” in the URI request.
Pagesize Any Integer, 1 or higher. All The API returns collections of data in defined groups called pages. The default page size is 200 records. You can use this parameter to set your page size to any number of records you like.
Page Any Integer, 1 or higher. All The API returns collections of data in defined groups called pages. The default is to return the first page of results. The first page will contain the number of records specified with the Pagesize parameter, page 2 the second set of records, etc.) You can use this parameter to specify the page of results you would like to return. For example, using the default Pagesize of 200, if Page = 1 records 1-200 are returned, if Page = 2 records 201-400 are returned.
startDate Any valid date using format YYYY-MM-DD /v4/payment /v4/paymentschedule /v4/customer/{id}/payments /v4/customer/{id}/paymentschedules The default is to return all payments and schedules regardless of date. For Payments, startDate filters based on the date the payment was created (PaymentDate). Use it to generate a list of payments entered on or after the specified date. For schedules, startDate filters based on the schedule StartDate. Use it to generate a list of schedules that were or will be activated on or after the specified date.
endDate Any valid date using format YYYY-MM-DD /v4/payment /v4/paymentschedule /v4/customer/{id}/payments /v4/customer/{id}/paymentschedules The default is to return all payments and schedules regardless of date. For Payments, endDate filters based on the date the payment was created (PaymentDate). Use it to generate a list of payments entered on or before the specified date. For schedules, endDate filters based on the schedule StartDate. Use it to generate a list of schedules that were or will be activated on or before the specified date.
status Payment Values Authorized ChargeBack Failed Pending Posted RefundSettled Returned Reversed ReverseNSF ReversePosted Settled Voided Schedule Values Active Suspended /v4/payment /v4/paymentschedule /v4/paymentplan /v4/recurringpayment /v4/customer/{id}/payments /v4/customer/{id}/paymentschedules /v4/customer/{id}/paymentplans /v4/customer/{id}/recurringpayments The default is to return all payments and schedules regardless of status. Use the status filter to specify the payment or schedule status (es) you would like to return. You can specify multiple statuses separated by commas.
sortBy Customer Fields FirstName LastName Company BillingAddress.City BillingAddress.State BillingAddress.Zip BillingAddress.Country ShippingAddress.City ShippingAddress.State ShippingAddress.Zip ShippingAddress.Country Payment Fields ReturnDate EstimatedSettleDate ActualSettledDate PaymentDate PaymentType PaymentSubType Amount /v4/customer /v4/customer/{id}/payments /v4/payment The default Customer Record sort is oldest-to-newest. The default Payment Record sort is newest-to-oldest. Use the sortBy filter to specify the field by which to sort the Customer Record or Payment Record collection, in conjunction with the direction filter to specify the sort direction.
direction ASC Sorts oldest-to-newest or A-to-Z DESC sorts newest-to-oldest or Z-to-A

NOTE: Null values appear first in ASC sorts and last in DESC sorts.

/v4/customer /v4/customer/{id}/payments /v4/payment The direction filter is used in conjunction with the sortBy filter to designate the sort order based on the specified field. If a sortBy filter is specified, and no direction filter is specified, ascending sorting will be used.

Appendix B: Failure Data Error Codes and Messages

When a payment fails (is submitted for processing but is not authorized), the FailureData Object is used to provide the actual failure code passed by the processor as well as information about why the payment failed and instructions that can be passed directly to the merchant for how to handle the error.

For all successful payments, the FailureData field will be null.

The four attributes of the FailureData Object are:

  • Code --a 4-digit PaySimple Error Code
  • Description --a description of the Error
  • MerchantActionText --instructions to be passed to the merchant on how to handle the error.
    NOTE: You can substitute your own instructions for the system ones, if you like.
  • "IsDecline" -- “true” indicates that the failure was due to the transaction being declined; “false” indicates a failure due to any other reason.

Depending on the type of payment (ACH or Credit Card), and the processing pipe used to submit payments for authorizations, different error codes and messages are used. The following tables provide the error codes you can expect, by payment type and processor.

Credit Card Processing

PaySimple supports credit card processing via TSYS and Global Payments. If you are unsure of the pipe used for your (or your customers’) credit card merchant processing accounts, ask your Partner Support representative.

TSYS Processing Pipe

CODE DESCRIPTION MERCHANT ACTION TEXT isDECLINE AMOUNT
4001 Refer to Issuer Try a different payment method. 9999.11
4002 Refer to Issuer - Special Condition Try a different payment method.
4004 Pick up Card (no Fraud) Try a different payment method. true
4005 Do Not Honor Try a different payment method. true 9999.01
4006 General Error Try again, if the problem persists contact customer service.
4006 Error response text from check service Try again, if the problem persists contact customer service.
4007 Pick up card, special condition (fraud account) Try a different payment method. true 9999.02
4012 Invalid transaction Verify you have selected the proper payment type and retry.
4013 Invalid amount Re-enter payment amount and try again.
4014 Invalid card number Re-enter the payment information or try a different payment method. 9999.03
4015 No such issuer Re-enter the payment information or try a different payment method. 9999.13
4019 Re-enter transaction Re-enter the payment information or try a different payment method.
4021 Unable to back out transaction Try again, if the problem persists contact customer service.
4028 File is temporarily unavailable Try again, if the problem persists contact customer service.
4039 No credit account Try again, if the problem persists contact customer service.
4041 Lost card, pick up (fraud account) Try a different payment method. true 9999.05
4043 Stolen card, pick up (fraud account) Try a different payment method. true
4051 Insufficient funds Try a different payment method. true
4052 No checking account Try a different payment method. 9999.12
4053 No savings account Try a different payment method.
4054 Invalid Expiration Date Re-enter the payment information or try a different payment method. 9999.04
4057 Transaction not permitted-Card Try a different payment method.
4058 Transaction not permitted-Terminal Try a different payment method.
4061 Exceeds withdrawal limit Try a different payment method. true
4062 Invalid service code, restricted Try a different payment method.
4063 Security violation Re-enter the payment information or try a different payment method.
4065 Activity limit exceeded Try a different payment method. true
4075 PIN tries exceeded Try a different payment method.
4076 Unable to locate, no match Try a different payment method.
4077 Inconsistent data, rev., or repeat Try a different payment method.
4078 No account Try a different payment method. 9999.09
4079 Already reversed by switch Contact customer service.
4080 Invalid date Re-enter the payment information or try a different payment method.
4081 Encryption Error Try again, if the problem persists contact customer service.
4083 Cannot verify PIN Try a different payment method.
4086 Cannot verify PIN Try a different payment method.
4091 Issuer or switch is unavailable Try again, if the problem persists contact customer service.
4092 Destination not found Try a different payment method.
4093 Violation, cannot complete Try a different payment method. true
4201 Account length error Re-enter the payment information or try a different payment method.
4202 Cash back service is not available Contact customer service.
4203 Verification error Re-enter the payment information or try a different payment method.
4204 Verification error Re-enter the payment information or try a different payment method.
4205 Exceeds issuer withdrawal limit Try a different payment method. true
4206 Velocity limit exceeded Try a different payment method.
4207 Invalid Merchant Account Contact customer service.
4208 Configuration Try a different payment method. 9999.08
4209 Surcharge amount not permitted on Visa cards or EBT food stamps Contact customer service.
4210 Surcharge amount not supported by debit network issuer Contact customer service.
4211 Customer requested stop of specific recurring payment Contact the customer. 9999.10
4213 Check is OK but cannot be converted - declined transaction Contact customer service.
4214 Invalid ABA number, not an ACH participant Re-enter the payment information or try a different payment method.
4215 Amount greater than the limit Re-enter payment amount and try again.
4216 Unpaid Items on Customer's Account Try a different payment method.
4217 Duplicate check number Re-enter the payment information or try a different payment method.
4218 MICR error Try again, if the problem persists contact customer service.
4219 Too many checks (over merchant or bank limit) Try a different payment method.
4220 CVV2 Value supplied is invalid Re-enter the CVV2 information or try a different payment method.
4221 Customer has blocked all recurring payments. Contact the customer.
4222 LRC content is not consistent. Possible network error has occurred.
4223 Supplied postal code does not appear to be valid Re-enter the payment information or try a different payment method.
4224 Error reading processor response Try again, if the problem persists contact customer service.
4225 Received bad bin response from processor, possible configuration error. Contact customer service. 9999.07
4880 Exact match, nine-character numeric ZIP
4881 Exact match, five-character numeric ZIP
4882 Address match only
4883 Nine-character numeric ZIP match only
4884 Five-character numeric ZIP match only
4885 No address or ZIP match
4886 Address unavailable
4887 Non-U.S. Issuer does not participate
4888 Issuer system unavailable Try again, if the problem persists contact customer service.
4889 Not a mail/phone order
4890 Service not supported

Global Processing Pipe

CODE DESCRIPTION MERCHANT ACTION TEXT isDECLINE AMOUNT
4002 Refer to Issuer - Special Condition Try a different payment method. 9999.13
4003 Invalid Merchant ID Contact customer service. 9999.04
4004 Pick up Card (no Fraud) Try a different payment method. true 9999.02
4005 Do Not Honor Try a different payment method. true 9999.01
4012 Invalid transaction Verify you have selected the proper payment type and retry.
4013 Invalid amount Re-enter payment amount and try again.
4014 Invalid card type. Verify card type selected is correct or try a different payment method.
4014 Invalid CID Re-enter the CID information or try a different payment method. 9999.07
4019 Re-enter transaction Re-enter the payment information or try a different payment method.
4054 Invalid PIN number Re-enter the payment information or try a different payment method. 9999.1
4055 Invalid PIN number Retry PIN or try another payment method. 9999.16
4058 Transaction not permitted-Terminal Try a different payment method. 9999.06
4220 CVV2 Value supplied is invalid Re-enter the CVV2 information or try a different payment method. 9999.08
4221 Customer has blocked all recurring payments. Contact the customer. 9999.14
4226 There is an error with your account configuration. Contact customer service. 9999.05
4227 Account not set up to accept Debit cards Contact customer service.
4228 Exceeds withdrawal amount limit Try a different payment method.
4229 Exceeds withdrawal amount limit Try a different payment method.
4230 The item number entered for a void or adjustment transaction is incorrect Contact customer service.
4231 An adjustment or item review was attempted on a transaction previously voided. Contact customer service.
4232 Override transaction is attempted on a non-duplicated transaction. Contact customer service.
4233 Format of the transaction is incorrect. Try again, if the problem persists contact customer service.
4234 Reversal transaction is attempted on a transaction that is not in the open batch on the host. Contact customer service.
4235 Maximum PIN number entry attempts exceeded Contact customer service.
4236 The amount entered for a void or adjustment transaction does not match the amount stored in the host for that item. Contact customer service.
4237 Originating device has not been balanced within time specified in the Global Payments Merchant Master File for this merchant, but merchant is set up to perform extra transactions before balancing. Contact customer service.
4294 Transaction entered is a duplicate Contact customer service.
7000 Processor Unavailable Please try again later.

Credit Card Mock Results

<?xml version="1.0" encoding="utf-8" ?>
<mocks>
	<mock>
		<amount>9999.01</amount>
		<providerauthcode>DECLINE</providerauthcode>
		<status>Failed</status>
		<tracenumber>05</tracenumber>
	</mock>
	<mock>
		<amount>9999.02</amount>
		<providerauthcode>CVV2 MISMATCH</providerauthcode>
		<status>Failed</status>
		<tracenumber>07</tracenumber>
	</mock>
	<mock>
		<amount>9999.03</amount>
		<providerauthcode>CARD NO. ERROR</providerauthcode>
		<status>Failed</status>
		<tracenumber>14</tracenumber>
	</mock>
	<mock>
		<amount>9999.04</amount>
		<providerauthcode>EXPIRED CARD</providerauthcode>
		<status>Failed</status>
		<tracenumber>54</tracenumber>
	</mock>
	<mock>
		<amount>9999.05</amount>
		<providerauthcode>HOLD-CALL</providerauthcode>
		<status>Failed</status>
		<tracenumber>41</tracenumber>
	</mock>
	<mock>
		<amount>9999.06</amount>
		<providerauthcode>SERV NOT ALLOWED</providerauthcode>
		<status>Failed</status>
		<tracenumber>41</tracenumber>
	</mock>
	<mock>
		<amount>9999.07</amount>
		<providerauthcode>Received bad bin response from processor, possible configuration error.</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.08</amount>
		<providerauthcode>FAILURE CV</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.09</amount>
		<providerauthcode>NO ACCOUNT</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.10</amount>
		<providerauthcode>STOP RECURRING</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.11</amount>
		<providerauthcode>CALL</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.12</amount>
		<providerauthcode>NO CHECK ACCOUNT</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.13</amount>
		<providerauthcode>NO SUCH ISSUER</providerauthcode>
		<status>Failed</status>
	</mock>
</mocks>
                        

ACH Processing

PaySimple supports ACH processing via Forte, Payliance, ProfitStars, and Vericheck. If you are unsure of the ACH Processor you (or your customers’) are using, ask your Partner Support representative.

Forte

CODE DESCRIPTION MERCHANT ACTION TEXT isDECLINE AMOUNT
4014 Invalid Card Number Re-enter the payment information or try a different payment method.
4501 Account ABA number is invalid. Re-enter the payment information or try a different payment method. 9999.07
4502 Merchant's maximum transaction amount exceeded Contact customer service. 9999.05
4503 Merchant monthly limit exceeded (EFT only). 9999.03
4504 Merchant's daily limit exceeded Contact customer service. 9999.01
4506 Duplicate transaction Contact customer service. 9999.04
4507 Customer account is in the "known bad" account list. Try a different payment method. 9999.02
4508 Merchant is not "live". Contact customer service. 9999.11
4509 Invalid Field Value. Re-enter payment amount and try again. If problem persists contact customer service 9999.1
4510 Invalid Merchant ID or Password Contact customer service. 9999.06
4511 Invalid Routing Number or Account Number Re-enter the payment information or try a different payment method. 9999.09
7000 Processor Unavailable Please try again later. 9999.08

Payliance

CODE DESCRIPTION MERCHANT ACTION TEXT isDECLINE
4502
4504 Merchant's maximum transaction amount exceeded Contact customer service.
4510 Invalid Merchant ID or Password Contact customer service.
4513 Invalid Routing Number Re-enter the payment information or try a different payment method.
4516 Unauthorized SEC type Contact customer service.

ProfitStars

CODE DESCRIPTION MERCHANT ACTION TEXT isDECLINE AMOUNT
4505 Velocity amount exceeded 9999.04
4506 Duplicate transaction Contact customer service.
4513 Invalid Routing Number Re-enter the payment information or try a different payment method. 9999.02
4517 Not subscribed Contact customer service. 9999.03
7000 Processor Unavailable Please try again later. 9999.01

Vericheck

CODE DESCRIPTION MERCHANT ACTION TEXT isDECLINE AMOUNT
4055 Invalid PIN number Retry PIN or try another payment method.
4502 Merchant's maximum transaction amount exceeded Contact customer service. 9999.08
4506 Duplicate transaction Contact customer service. 9999.01
4510 Invalid Merchant ID or Password Contact customer service.
4511 Invalid Routing Number or Account Number Re-enter the payment information or try a different payment method.
4512 Invalid Account Number Re-enter the payment information or try a different payment method. 9999.06
4513 Invalid Routing Number Re-enter the payment information or try a different payment method. 9999.05
4514 Federal ID does match records Contact customer service.
4515 Inactive merchant Contact customer service.

ACH Mock Results

<?xml version="1.0" encoding="utf-8" ?>
<mocks>
	<mock>
		<amount>9999.01</amount>
		<responsecode>U03</responsecode>
		<failurereason>DailyLimit</failurereason>
		<providerauthcode>ACHP-003: Merchant daily limit exceeded (EFT only).</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.02</amount>
		<responsecode>U02</responsecode>
		<failurereason>None</failurereason>
		<providerauthcode>ACHP-002: Customer account is in the ACH Direct "known bad" account list (EFT only).</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.03</amount>
		<responsecode>U04</responsecode>
		<failurereason>MonthlyLimit</failurereason>
		<providerauthcode>ACHP-004: Merchant monthly limit exceeded (EFT only).</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.04</amount>
		<responsecode>U10</responsecode>
		<failurereason>None</failurereason>
		<providerauthcode>ACHP-008: Transaction has the same attributes as another transaction within the time set by the merchant.</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.05</amount>
		<responsecode>U53</responsecode>
		<failurereason>SingleTransactionLimit</failurereason>
		<providerauthcode>ACHP-025: Transaction amount exceeds merchant’s per transaction limit (EFTs only).</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.06</amount>
		<responsecode>E10</responsecode>
		<failurereason>None</failurereason>
		<providerauthcode> We're sorry!  This transaction cannot be processed because your Merchant Processing Key or Password is incorrect.  Please contact your Account Executive to correct this error.</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.07</amount>
		<responsecode>U19</responsecode>
		<failurereason>None</failurereason>
		<providerauthcode>ACHP-016: Account ABA number is invalid.</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.08</amount>
		<failurereason>None</failurereason>
		<providerauthcode>Communication failure with ACH Direct</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.09</amount>
		<responsecode>F01</responsecode>
		<failurereason>None</failurereason>
		<providerauthcode> The Routing # and/or Account # entered are not valid.</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.10</amount>
		<responsecode>F04</responsecode>
		<failurereason>None</failurereason>
		<providerauthcode> Invalid Field Value.</providerauthcode>
		<status>Failed</status>
	</mock>
	<mock>
		<amount>9999.11</amount>
		<responsecode>U51</responsecode>
		<failurereason>None</failurereason>
		<providerauthcode>ACHP-023: Merchant is not "live".</providerauthcode>
		<status>Failed</status>
	</mock>
</mocks>