# Customer and Recurring API

## Overview 

The Sola Recurring API, designed in the RESTful architectural style, lets you process recurring transactions through the Sola gateway based on customized schedules. You can create recurring schedules along with customers and payment methods. Additionally, you can process single transactions for a customer and change a merchant's settings for recurring schedule reports.

### Authorization

Include your Sola API key in the `Authorization` header for all requests. You can generate an API key in the [Key Management section](https://portal.solapayments.com/settings/gateway-settings/key-management) of the Sola Portal.

### Versioning

Customer and Recurring API V2 is versioned to allow stability for integrators and flexibility for Sola to continue making improvements.

#### **Major Version**

The URL contains the major version number parameter. This version number would only be changed if there has been a major change that overhauls the entire API.

*Example:* <https://api.cardknox.com/v2>

#### **Minor Version**

This version number is incremented when a breaking change to the existing API is implemented (for example, a change to how requests are processed or how responses are sent back).&#x20;

The minor version is passed in the X-Recurring-Api-Version header: `X-Recurring-Api-Version = 2.1`

### Request Method

Method: ![](https://cardknox.atlassian.net/wiki/plugins/servlet/status-macro/placeholder?title=POST\&colour=Green)

The Sola gateway requires the POST method to be used for enhanced security.

We do not support the GET method.

### Base URL

The base URL for all requests is [**https://api.cardknox.com/v2**](https://api.cardknox.com/v2)

## Customer Endpoints

### /CreateCustomer

Add a new customer record, which can then be linked to payment methods and schedules.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="200.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>CustomerNumber</td><td>No</td><td>string</td><td>Merchant's internal customer identifier.</td></tr><tr><td>CustomerNotes</td><td>No</td><td>string</td><td>Notes pertaining to the customer.</td></tr><tr><td>Email</td><td>No</td><td>string</td><td>Customer's email address.</td></tr><tr><td>Fax</td><td>No</td><td>string</td><td>Customer's fax number.</td></tr><tr><td>BillFirstName</td><td>Yes*</td><td>string</td><td><p>Customer's first name for their billing profile.</p><p>*Required if <code>BillLastName</code> and <code>BillCompany</code> are not passed in.</p></td></tr><tr><td>BillMiddleName</td><td>No</td><td>string</td><td>Customer's middle name or middle initial for their billing profile.</td></tr><tr><td>BillLastName</td><td>Yes*</td><td>string</td><td><p>Customer's last name or family name for their billing profile.</p><p>*Required if <code>BillFirstName</code> and <code>BillCompany</code> are not passed in.</p></td></tr><tr><td>BillCompany</td><td>Yes*</td><td>string</td><td><p>Customer's company name for their billing profile.</p><p>*Required if <code>BillFirstName</code> and <code>BillLastName</code> are not passed in.</p></td></tr><tr><td>BillStreet</td><td>No</td><td>string</td><td>Customer's street address for their billing profile.</td></tr><tr><td>BillStreet2</td><td>No</td><td>string</td><td>Customer's street address second line for their billing profile.</td></tr><tr><td>BillCity</td><td>No</td><td>string</td><td>Customer's city for their billing profile.</td></tr><tr><td>BillState</td><td>No</td><td>string</td><td>Customer's state for their billing profile.</td></tr><tr><td>BillZip</td><td>No</td><td>string</td><td>Customer's ZIP code or postal code for their billing profile.</td></tr><tr><td>BillCountry</td><td>No</td><td>string</td><td>Customer's country for their billing profile.</td></tr><tr><td>BillPhone</td><td>No</td><td>string</td><td>Customer's phone number for their billing profile.</td></tr><tr><td>BillMobile</td><td>No</td><td>string</td><td>Customer's mobile number for their billing profile.</td></tr><tr><td>ShipFirstName</td><td>No</td><td>string</td><td>Customer’s first name for their shipping profile.</td></tr><tr><td>ShipMiddleName</td><td>No</td><td>string</td><td>Customer’s middle name or initial for their shipping profile.</td></tr><tr><td>ShipLastName</td><td>No</td><td>string</td><td>Customer’s last/family name for their shipping profile.</td></tr><tr><td>ShipCompany</td><td>No</td><td>string</td><td>Customer’s company name for their shipping profile.</td></tr><tr><td>ShipStreet</td><td>No</td><td>string</td><td>Customer’s street address for their shipping profile.</td></tr><tr><td>ShipStreet2</td><td>No</td><td>string</td><td>Customer’s street address second line for their shipping profile.</td></tr><tr><td>ShipCity</td><td>No</td><td>string</td><td>Customer’s city for their shipping profile.</td></tr><tr><td>ShipState</td><td>No</td><td>string</td><td>Customer’s state for their shipping profile.</td></tr><tr><td>ShipZip</td><td>No</td><td>string</td><td>Customer’s ZIP code for their shipping profile.</td></tr><tr><td>ShipCountry</td><td>No</td><td>string</td><td>Customer’s country for their shipping profile.</td></tr><tr><td>ShipPhone</td><td>No</td><td>string</td><td>Customer’s phone number for their shipping profile.</td></tr><tr><td>ShipMobile</td><td>No</td><td>string</td><td>Customer’s mobile number for their shipping profile.</td></tr><tr><td>ShipEmail</td><td>No</td><td>string</td><td>Customer’s shipping email address for their shipping profile.</td></tr><tr><td>CustomerCustomXX</td><td>No</td><td>string</td><td>Custom fields (20 available) used for custom data such as customer comments and so forth. Use <code>CustomerCustom01</code> through <code>CustomerCustom20</code>.</td></tr></tbody></table>

#### **Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerNumber" : "123456",
    "CustomerNotes" : "Vip Customer",
    "Email" : "sample@example.com",
    "Fax" : "",
    "BillFirstName" : "John",
    "BillMiddleName" : "G",
    "BillLastName" : "Doe",
    "BillCompany" : "ACME Inc.",
    "BillStreet" : "123 Main Street",
    "BillStreet2" : "STE 1",
    "BillCity" : "AnyTown",
    "BillState" : "NY",
    "BillCountry" : "USA",
    "BillZip" : "11218",
    "BillPhone" : "",
    "BillMobile" : "",
    "ShipFirstName" : "John",
    "ShipMiddleName" : "G",
    "ShipLastName" : "Doe",
    "ShipCompany" : "ACME Inc.",
    "ShipStreet" : "123 Main Street",
    "ShipStreet2" : "STE 1",
    "ShipCity" : "AnyTown",
    "ShipState" : "NY",
    "ShipCountry" : "USA",
    "ShipZip" : "11218",
    "ShipPhone" : "",
    "ShipMobile" : "",
    "ShipEmail" : "sample@example.com",
    "CustomerCustom01" : "MyCustomValue",
    "CustomerCustom02" : "MyCustomValue2",
    "CustomerCustom03" : "MyCustomValue3"
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="181">Parameter</th><th width="150">Type</th><th width="214.6511627906977">Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>CustomerId</td><td>integer</td><td>The created customer ID.</td><td></td></tr></tbody></table>

**Sample Response**

```json
{ 
"RefNum": "r1234567890",
"Result": "S",
"Error": "",
"CustomerId": "c1234567890"
}
```

### /UpdateCustomer

Update existing customer information.

**Note:** All fields with values must be passed in (even fields that are not being updated). Any fields not passed in are treated as being set to blank.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>Revision</td><td>Yes</td><td>integer</td><td>The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.</td></tr><tr><td>CustomerId</td><td>Yes</td><td>string</td><td>The ID of the customer to update.</td></tr><tr><td>CustomerNumber</td><td>No</td><td>string</td><td>Merchant's internal customer identifier.</td></tr><tr><td>CustomerNotes</td><td>No</td><td>string</td><td>Notes pertaining to the customer.</td></tr><tr><td>DefaultPaymentMethodId</td><td>Yes</td><td>string</td><td>The ID of the created payment method.</td></tr><tr><td>Email</td><td>No</td><td>string</td><td>Customer's email address.</td></tr><tr><td>Fax</td><td>No</td><td>string</td><td>Customer's fax number.</td></tr><tr><td>BillFirstName</td><td>Yes*</td><td>string</td><td><p>Customer's first name for their billing profile.</p><p>*Required if <code>BillLastName</code> and <code>BillCompany</code> are not passed in.</p></td></tr><tr><td>BillMiddleName</td><td>No</td><td>string</td><td>Customer's middle name or middle initial for their billing profile.</td></tr><tr><td>BillLastName</td><td>Yes*</td><td>string</td><td><p>Customer's last/family name for their billing profile.</p><p>*Required if <code>BillFirstName</code> and <code>BillCompany</code> are not passed in.</p></td></tr><tr><td>BillCompany</td><td>Yes*</td><td>string</td><td><p>Customer's company name for their billing profile.</p><p>*Required if <code>BillFirstName</code> and <code>BillLastName</code> are not passed in.</p></td></tr><tr><td>BillStreet</td><td>No</td><td>string</td><td>Customer's street address for their billing profile.</td></tr><tr><td>BillStreet2</td><td>No</td><td>string</td><td>Customer's street address second line for their billing profile.</td></tr><tr><td>BillCity</td><td>No</td><td>string</td><td>Customer's city for their billing profile.</td></tr><tr><td>BillState</td><td>No</td><td>string</td><td>Customer's state for their billing profile.</td></tr><tr><td>BillZip</td><td>No</td><td>string</td><td>Customer's ZIP code or postal code for their billing profile.</td></tr><tr><td>BillCountry</td><td>No</td><td>string</td><td>Customer's country for their billing profile.</td></tr><tr><td>BillPhone</td><td>No</td><td>string</td><td>Customer's phone number for their billing profile.</td></tr><tr><td>BillMobile</td><td>No</td><td>string</td><td>Customer's mobile number for their billing profile.</td></tr><tr><td>ShipFirstName</td><td>No</td><td>string</td><td>Customer’s first name for their shipping profile.</td></tr><tr><td>ShipMiddleName</td><td>No</td><td>string</td><td>Customer’s middle name or initial for their shipping profile.</td></tr><tr><td>ShipLastName</td><td>No</td><td>string</td><td>Customer’s last/family name for their shipping profile.</td></tr><tr><td>ShipCompany</td><td>No</td><td>string</td><td>Customer’s company name for their shipping profile.</td></tr><tr><td>ShipStreet</td><td>No</td><td>string</td><td>Customer’s street address for their shipping profile.</td></tr><tr><td>ShipStreet2</td><td>No</td><td>string</td><td>Customer’s street address second line for their shipping profile.</td></tr><tr><td>ShipCity</td><td>No</td><td>string</td><td>Customer’s city for their shipping profile.</td></tr><tr><td>ShipState</td><td>No</td><td>string</td><td>Customer’s state for their shipping profile.</td></tr><tr><td>ShipZip</td><td>No</td><td>string</td><td>Customer’s ZIP code for their shipping profile.</td></tr><tr><td>ShipCountry</td><td>No</td><td>string</td><td>Customer’s country for their shipping profile.</td></tr><tr><td>ShipPhone</td><td>No</td><td>string</td><td>Customer’s phone number for their shipping profile.</td></tr><tr><td>ShipMobile</td><td>No</td><td>string</td><td>Customer’s mobile number for their shipping profile.</td></tr><tr><td>ShipEmail</td><td>No</td><td>string</td><td>Customer’s shipping email address for their shipping profile.</td></tr><tr><td>CustomerCustomXX</td><td>No</td><td>string</td><td>Custom fields (20 available) used for custom data such as customer comments and so forth. Use <code>CustomerCustom01</code> through <code>CustomerCustom20</code>.</td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
	"Revision" : 1,
    "CustomerId" : "c123456",
    "CustomerNumber" : "123456",
    "CustomerNotes" : "Vip Customer",
    "Email" : "sample@example.com",
    "Fax" : "",
    "BillFirstName" : "John",
    "BillMiddleName" : "G",
    "BillLastName" : "Doe",
    "BillCompany" : "ACME Inc.",
    "BillStreet" : "123 Main Street",
    "BillStreet2" : "STE 1",
    "BillCity" : "AnyTown",
    "BillState" : "NY",
    "BillCountry" : "USA",
    "BillZip" : "11218",
    "BillPhone" : "",
    "BillMobile" : "",
    "ShipFirstName" : "John",
    "ShipMiddleName" : "G",
    "ShipLastName" : "Doe",
    "ShipCompany" : "ACME Inc.",
    "ShipStreet" : "123 Main Street",
    "ShipStreet2" : "STE 1",
    "ShipCity" : "AnyTown",
    "ShipState" : "NY",
    "ShipCountry" : "USA",
    "ShipZip" : "11218",
    "ShipPhone" : "",
    "ShipMobile" : "",
    "ShipEmail" : "sample@example.com",
    "CustomerCustom01" : "MyCustomValue",
    "CustomerCustom02" : "MyCustomValue2",
    "CustomerCustom03" : "MyCustomValue3"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Type</th><th width="232">Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. S represents success, E represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /GetCustomer

Retrieves the details of a specific customer.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>CustomerId</td><td>Yes</td><td>string</td><td>The ID of the customer to retrieve.</td></tr><tr><td>ShowDeleted</td><td>No</td><td>boolean</td><td>A flag that can be set to retrieve deleted items. If set to <strong>true</strong>, only deleted items can be retrieved (i.e. customers that are not deleted will not be returned).</td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerId" : "c1234567890",
    "ShowDeleted" : false
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="186">Parameter</th><th width="150">Type</th><th width="220.26086956521738">Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>Revision</td><td>integer</td><td>The revision number of the customer record.</td><td></td></tr><tr><td>CreatedDate</td><td>string</td><td>The date and time the customer was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).</td><td></td></tr><tr><td>CustomerId</td><td>string</td><td>The ID of the customer to update.</td><td></td></tr><tr><td>CustomerNumber</td><td>string</td><td>Merchant's internal customer identifier.</td><td></td></tr><tr><td>CustomerNotes</td><td>string</td><td>Notes pertaining to the customer.</td><td></td></tr><tr><td>Email</td><td>string</td><td>Customer's email address.</td><td></td></tr><tr><td>Fax</td><td>string</td><td>Customer's fax number.</td><td></td></tr><tr><td>BillFirstName</td><td>string</td><td>Customer's first name for their billing profile.</td><td></td></tr><tr><td>BillMiddleName</td><td>string</td><td>Customer's middle name or initial for their billing profile.</td><td></td></tr><tr><td>BillLastName</td><td>string</td><td>Customer's last/family name for their billing profile.</td><td></td></tr><tr><td>BillCompany</td><td>string</td><td>Customer's company name for their billing profile.</td><td></td></tr><tr><td>BillStreet</td><td>string</td><td>Customer's street address for their billing profile.</td><td></td></tr><tr><td>BillStreet2</td><td>string</td><td>Customer's street address second line for their billing profile.</td><td></td></tr><tr><td>BillCity</td><td>string</td><td>Customer's city for their billing profile.</td><td></td></tr><tr><td>BillState</td><td>string</td><td>Customer's state for their billing profile.</td><td></td></tr><tr><td>BillZip</td><td>string</td><td>Customer's ZIP code or postal code for their billing profile.</td><td></td></tr><tr><td>BillCountry</td><td>string</td><td>Customer's country for their billing profile.</td><td></td></tr><tr><td>BillPhone</td><td>string</td><td>Customer's phone number for their billing profile.</td><td></td></tr><tr><td>BillMobile</td><td>string</td><td>Customer's mobile number for their billing profile.</td><td></td></tr><tr><td>ShipFirstName</td><td>string</td><td>Customer’s first name for their shipping profile.</td><td></td></tr><tr><td>ShipMiddleName</td><td>string</td><td>Customer’s middle name or initial for their shipping profile.</td><td></td></tr><tr><td>ShipLastName</td><td>string</td><td>Customer’s last/family name for their shipping profile.</td><td></td></tr><tr><td>ShipCompany</td><td>string</td><td>Customer’s company name for their shipping profile.</td><td></td></tr><tr><td>ShipStreet</td><td>string</td><td>Customer’s street address for their shipping profile.</td><td></td></tr><tr><td>ShipStreet2</td><td>string</td><td>Customer’s street address second line for their shipping profile.</td><td></td></tr><tr><td>ShipCity</td><td>string</td><td>Customer’s city for their shipping profile.</td><td></td></tr><tr><td>ShipState</td><td>string</td><td>Customer’s state for their shipping profile.</td><td></td></tr><tr><td>ShipZip</td><td>string</td><td>Customer’s ZIP code for their shipping profile.</td><td></td></tr><tr><td>ShipCountry</td><td>string</td><td>Customer’s country for their shipping profile.</td><td></td></tr><tr><td>ShipPhone</td><td>string</td><td>Customer’s phone number for their shipping profile.</td><td></td></tr><tr><td>ShipMobile</td><td>string</td><td>Customer’s mobile number for their shipping profile.</td><td></td></tr><tr><td>ShipEmail</td><td>string</td><td>Customer’s shipping email address for their shipping profile.</td><td></td></tr><tr><td>CustomerCustomXX</td><td>string</td><td>Custom fields (20 available) used for custom data such as customer comments and so forth. Use <code>CustomerCustom01</code> through <code>CustomerCustom20</code>.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "CustomerId": "c123456",
    "Revision": 1,
    "CustomerNotes": "Vip Customer",
    "CustomerNumber": "123456",
    "DefaultPaymentMethodId": "",
    "CreatedDate": "2019-08-20 14:30:57.578",
    "Email": "sample@example.com",
    "BillFirstName": "John",
    "BillMiddleName": "G",
    "BillLastName": "Doe",
    "BillCompany": "ACME Inc.",
    "BillStreet": "123 Main Street",
    "BillStreet2": "STE 1",
    "BillCity": "AnyTown",
    "BillState": "NY",
    "BillZip": "11218",
    "BillCountry": "USA",
    "ShipFirstName": "John",
    "ShipMiddleName": "G",
    "ShipLastName": "Doe",
    "ShipCompany": "ACME Inc.",
    "ShipStreet": "123 Main Street",
    "ShipStreet2": "STE 1",
    "ShipCity": "AnyTown",
    "ShipState": "NY",
    "ShipZip": "11218",
    "ShipCountry": "USA",
    "ShipEmail": "sample@example.com",
    "CustomerCustom01": "MyCustomValue",
    "CustomerCustom02": "MyCustomValue2",
    "CustomerCustom03": "MyCustomValue3"
}
```

### /DeleteCustomer

Deletes a customer record. You cannot delete a customer who has an active recurring schedule.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>CustomerId</td><td>Yes</td><td>string</td><td>The ID of the customer to update.</td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerId" : "c123456"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="150">Parameter</th><th width="150">Type</th><th width="242.7142857142857">Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents  error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /ListCustomers

Lists customers created by a merchant.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="185">Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td><td>Valid Values</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td><td></td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td><td></td></tr><tr><td>PageSize</td><td>No</td><td>integer</td><td>100</td><td>The maximum number of items to retrieve for this request.</td><td></td></tr><tr><td>NextToken</td><td>No</td><td>string</td><td></td><td>A token that can be sent in to the following request to get the next set of customers.</td><td></td></tr><tr><td>SortOrder</td><td>No</td><td>string</td><td>Ascending</td><td>The list order. Order is determined by customer creation date.</td><td>Ascending, Descending</td></tr><tr><td>Filters</td><td>No</td><td>object</td><td><p>{</p><p>    "IsDeleted" : false</p><p>}</p></td><td><p>Filters that can be applied to limit the result set.</p><p>Filters will remove any items that do not contain the string for that filter value. If there are multiple filters applied, the item must match all of them.</p><p>Available filters:</p><ul><li>CustomerId</li><li>CustomerNumber</li><li>IsDeleted</li><li>Email</li><li>BillName</li><li>BillFirstName</li><li>BillLastName</li><li>BillMiddleName</li><li>BillCompany</li><li>BillStreet</li><li>BillStreet2</li><li>BillCity</li><li>BillState</li><li>BillZip</li><li>BillCountry</li><li>BillPhoneNumber</li><li>BillPhone</li><li>BillMobile</li><li>BillFax</li></ul></td><td></td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"NextToken" : "",
	"PageSize" : 500,
	"Filters" : {
		"BillFirstName" : "John",
		"BillState" : "NY"
	}
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="154">Parameter</th><th width="150">Type</th><th width="230.5">Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>Customers</td><td>object[]</td><td><p>An array of customer objects.</p><p>Refer to the <a href="#getcustomer">/GetCustomer</a> endpoint for the values that are returned for each customer.</p></td><td></td></tr><tr><td>NextToken</td><td>string</td><td>A token to include in the next request to get the next set of results.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
	"Customers" : [
        {
            "CustomerId" : "c123456",
            "Revision" : 1,
            "BillFirstName" : "John",
            "BillLastName" : "Doe",
            "BillState" : "NY"
        },
        {
            "CustomerId" : "c123457",
            "Revision" : 1,
            "BillFirstName" : "Johnathan",
            "BillLastName" : "Doe",
            "BillState" : "NY"
        }
    ]
}
```

## Payment Method Endpoints

### /CreatePaymentMethod

Adds a new payment method to a customer’s account profile.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="204.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>CustomerId</td><td>Yes</td><td>string</td><td>The ID of the customer to update with the new payment method.</td></tr><tr><td>Token</td><td>Yes</td><td>string</td><td><p>Sola token that represents a payment method.</p><p>*Raw card information cannot be passed in the request.</p></td></tr><tr><td>TokenType</td><td>Yes</td><td>string</td><td>The <code>Token</code> payment type.</td></tr><tr><td>TokenAlias</td><td>No</td><td>string</td><td>Custom name for the <code>Token</code>.</td></tr><tr><td>Exp</td><td>Yes*</td><td>string</td><td><p>Credit card expiration date.</p><p>*Required if <code>Token</code> is an iFields token and <code>TokenType</code> is <strong>cc</strong>.</p></td></tr><tr><td>Routing</td><td>Yes*</td><td>string</td><td><p>ACH payment routing number.</p><p>*Required if <code>Token</code> is an iFields token and <code>TokenType</code> is <strong>ach</strong>.</p></td></tr><tr><td>AccountType</td><td>No</td><td>string</td><td><p>The account type - checking / savings.</p><p>*Allowed if the <code>TokenType</code> is <strong>check</strong>.</p></td></tr><tr><td>Name</td><td>No</td><td>string</td><td><p>Name on the customer's account.</p><p>*Required for ACH (check) transactions.</p></td></tr><tr><td>Street</td><td>No</td><td>string</td><td>Customer's street address for their billing profile.</td></tr><tr><td>Zip</td><td>No</td><td>string</td><td>Customer's ZIP code or postal code for their billing profile.</td></tr><tr><td>SetAsDefault</td><td>No</td><td>boolean</td><td><p>Sets this payment method as the default payment method.</p><p><strong>Note</strong>: If there are no other payment methods, this method is automatically set as the default.</p></td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerId" : "c123456",
	"Token" : "pm4408q3327hq551h5h51058qh6n87mn",
	"TokenType" : "cc",
	"TokenAlias" : "",
	"Exp" : "1220",
	"Routing" : "",
	"AccountType" : "",
	"Name" : "",
	"Street" : "",
	"Zip" : "",
	"SetAsDefault" : false
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="161">Parameter</th><th width="150">Type</th><th width="237.40787623066106">Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>PaymentMethodId</td><td>string</td><td>The ID of the created payment method.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "PaymentMethodId": "c123456_pm123456
}
```

### /UpdatePaymentMethod

Updates an existing payment method.

**Note:** All fields with values must be passed in (even fields that are not being updated). Any fields not passed in are treated as being set to blank.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>Revision</td><td>Yes</td><td>integer</td><td>The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.</td></tr><tr><td>PaymentMethodId</td><td>Yes</td><td>string</td><td>The ID of the payment method to update.</td></tr><tr><td>TokenAlias</td><td>No</td><td>string</td><td>Custom name for the <code>Token</code>.</td></tr><tr><td>Exp</td><td>No</td><td>string</td><td>Credit card expiration date.</td></tr><tr><td>AccountType</td><td>No</td><td>string</td><td><p>The account type - checking / savings</p><p>*Allowed if <code>TokenType</code> is <strong>check</strong>.</p></td></tr><tr><td>Routing</td><td>Yes*</td><td>string</td><td><p>ACH payment routing number.</p><p>*Required if <code>Token</code> is an iFields token and <code>TokenType</code> is <strong>ach</strong>.</p></td></tr><tr><td>Name</td><td>No*</td><td>string</td><td><p>Name on the customer's account.</p><p>*Required for ACH (check) transactions.</p></td></tr><tr><td>Street</td><td>No</td><td>string</td><td>Customer's street address for their billing profile.</td></tr><tr><td>Zip</td><td>No</td><td>string</td><td>Customer's ZIP code or postal code for their billing profile.</td></tr><tr><td>SetAsDefault</td><td>No</td><td>boolean</td><td><p>Sets this payment method as the default payment method.</p><p><strong>Note</strong>: If there are no other payment methods, this method is automatically set as the default.</p></td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "Revision" : 1,
    "PaymentMethodId" : "c123456",
    "TokenAlias" : "",
    "Exp" : "1220",
    "AccountType": "",
    "Routing" : "",
    "Name" : "",
    "Street" : "",
    "Zip" : "",
    "SetAsDefault" : false
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="164">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents an error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /GetPaymentMethod

Retrieves an existing payment method.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="200.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>PaymentMethodId</td><td>Yes</td><td>string</td><td>The ID of the payment method to retrieve.</td></tr><tr><td>ShowDeleted</td><td>No</td><td>boolean</td><td>A flag that can be set to retrieve deleted items. If set to <strong>true</strong>, only deleted items can be retrieved (i.e., payment methods that are not deleted will not be returned).</td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "PaymentMethodId" : "c123456_pm123456",
	"ShowDeleted" : false
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>PaymentMethodId</td><td>string</td><td>The ID of the payment method.</td><td></td></tr><tr><td>Revision</td><td>number</td><td>The revision number of the record to update. If this does not match the current revision number of the record the update will fail.</td><td></td></tr><tr><td>Token</td><td>string</td><td>Sola token that references a previously used payment method to use for the charge.</td><td></td></tr><tr><td>TokenType</td><td>string</td><td>The <code>Token</code> payment type.</td><td>CC, Check</td></tr><tr><td>TokenAlias</td><td>string</td><td>Custom name for the <code>Token</code>.</td><td></td></tr><tr><td>Exp</td><td>string</td><td>Credit card expiration date (in <code>MMYY</code> format).</td><td></td></tr><tr><td>AccountType</td><td>string</td><td><p>The account type - checking / savings</p><p><strong>Note:</strong> This field is only populated when <code>TokenType</code> is <strong>Check</strong>.</p></td><td></td></tr><tr><td>Issuer</td><td>string</td><td><p>The credit card issuer.</p><p><strong>Note:</strong> This field is only populated when <code>TokenType</code> is <strong>CC</strong>.</p></td><td></td></tr><tr><td>MaskedCardNumber</td><td>string</td><td><p>The masked credit card number.</p><p><strong>Note:</strong> This field is only populated when <code>TokenType</code> is <strong>CC</strong>.</p></td><td></td></tr><tr><td>Name</td><td>string</td><td><p>The name on the check.</p><p><strong>Note:</strong> This field is only populated when <code>TokenType</code> is <strong>Check</strong>.</p></td><td></td></tr><tr><td>Street</td><td>string</td><td>The building number and street name of the customer being billed.</td><td></td></tr><tr><td>Zip</td><td>string</td><td>The zip code of the customer being billed.</td><td></td></tr><tr><td>CreatedDate</td><td>string</td><td>The date and time the payment method was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "PaymentMethodId": "c12345678_pm12345678",
    "Revision": 1,
    "Token": "qfjjf12m4iimkldfvoijv9012frljl0a",
    "TokenType": "cc",
    "TokenAlias": "",
    "Exp": "1220",
    "AccountType": "checking",
    "Issuer": "Visa",
    "MaskedCardNumber": "4xxxxxxxxxxx1111",
    "Name": "",
    "Street": "",
    "Zip": "",
    "CreatedDate": "2019-01-01 00:00:00.000"
}
```

### /DeletePaymentMethod

Removes a payment method from the customer’s record. This will fail if the payment method is the customer's only payment method and there are active schedules.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>PaymentMethodId</td><td>Yes</td><td>string</td><td>The ID of the payment method to retrieve.</td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "PaymentMethodId" : "c123456_pm123456"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="157">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /ListPaymentMethods

Return payment methods based on specific search parameters.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="188">Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td><td>Valid Values</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td><td></td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td><td></td></tr><tr><td>PageSize</td><td>No</td><td>integer</td><td>100</td><td>The maximum number of items to retrieve for this request.</td><td></td></tr><tr><td>NextToken</td><td>No</td><td>string</td><td></td><td>A token that can be sent in to the following request to get the next set of payment methods.</td><td></td></tr><tr><td>SortOrder</td><td>No</td><td>string</td><td>Ascending</td><td>The list order. Order is determined by payment method creation date.</td><td>Ascending, Descending</td></tr><tr><td>Filters</td><td>No</td><td>object</td><td><p>{</p><p>    "IsDeleted" : false</p><p>}</p></td><td><p>Filters that can be applied to limit the result set.</p><p>Filters will remove any items that do not contain the string for that filter value. If there are multiple filters applied, the item must match all of them.</p><p>Available filters:</p><ul><li>IsDeleted</li><li>CustomerId</li><li>PaymentMethodId</li><li>Token</li><li>TokenType</li><li>TokenAlias</li></ul></td><td></td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"NextToken" : "",
	"PageSize" : 500,
	"Filters" : {
		"IsDeleted" : false
	}
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="172">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>PaymentMethods</td><td>object[]</td><td><p>An array of payment method objects.</p><p>Refer to the <a href="#getpaymentmethod">/GetPaymentMethod</a><a href="https://docs.cardknox.com/api/recurring#getpaymentmethod"> </a>endpoint for the values that are returned for each payment method.</p></td><td></td></tr><tr><td>NextToken</td><td>string</td><td>A token to include in the next request to get the next set of results.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
  	"PaymentMethods": [
    	{
      		"PaymentMethodId": "c123456_pm123456",
      		"Token": "ervb24g45fcr2gsdbsgbwxbtrgxt314",
 		    "TokenType": "check",
		    "Street": "123",
		    "Zip": "08701",
		    "CreatedDate": "0001-01-01 12:00:AM",
		    "Revision": 1
	    },
    	{
    		"PaymentMethodId": "c123456_pm123457",
		    "Token": "mpq93n8519hq6pm29312m1n7mm3n7204",
		    "TokenType": "cc",
		    "CreatedDate": "0001-01-01 12:00:AM",
		    "Revision": 1
    	}
    ]
}
```

## Schedule Endpoints

### /CreateSchedule

Create a recurring payment schedule. Schedules have two main parameters: `IntervalType` and `IntervalCount`. You can set `IntervalType` to day, week, month, or year. The `IntervalCount` parameter determines the number of times the `IntervalType` should pass before the next payment schedule is triggered.

*Example 1:* To process a charge every two weeks, set `IntervalType` to week and set `IntervalCount` to 2. This specifies that two weeks should pass before initiating a new charge.

*Example 2:* To process a charge every 10 days, set `IntervalType` to day and set `IntervalCount` to 10. This specifies that 10 days should pass before initiating a new charge.

**Unsuccessful Payments:** If an attempted payment is unsuccessful (e.g., the card is declined), the system reschedules the charge for the following day. This can be done up to five times, provided that the rescheduled payment doesn’t overlap into the next payment cycle. After five unsuccessful attempts, or if rescheduling the payment as above will overlap into the next payment cycle, this individual payment will be canceled. The entire schedule remains in effect.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="190">Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td><td>Valid Values</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td><td></td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td><td></td></tr><tr><td>CustomerId</td><td>Yes*</td><td>string</td><td></td><td><p>Customer's unique ID number.</p><p>*Required if linking the schedule to an existing customer.</p></td><td></td></tr><tr><td>PaymentMethodId</td><td>No</td><td>string</td><td></td><td><p>The unique ID number of the payment method the schedule should use to process the transactions. If none is set, the default payment method on the customer will be used. </p><p>*Allowed if linking the schedule to an existing customer</p></td><td></td></tr><tr><td>NewCustomer</td><td>Yes*</td><td>object</td><td></td><td><p>The customer details. Refer to the <a href="#createcustomer">/CreateCustomer</a> endpoint for fields that can be set for this object.</p><p>*Required if <strong>not</strong> linking the schedule to an existing customer. This cannot be set if linking to an existing customer.<br></p></td><td></td></tr><tr><td>NewPaymentMethod</td><td>Yes*</td><td>object</td><td></td><td><p>The payment method details. Refer to the <a href="#createpaymentmethod">/CreatePaymentMethod</a> endpoint for fields that can be set for this object.</p><p>*Required if <strong>not</strong> linking the schedule to an existing customer. This cannot be set if linking to an existing customer.</p></td><td></td></tr><tr><td>IntervalType</td><td>Yes</td><td>string</td><td></td><td>Type of time interval.</td><td>day, week, month, year</td></tr><tr><td>Amount</td><td>Yes</td><td>decimal</td><td></td><td>Total amount of each transaction.</td><td>Must be a number with up to 2 decimal places</td></tr><tr><td>Currency</td><td>No</td><td>string</td><td></td><td><p>Currency code to be used when processing transactions</p><p><strong>Note:</strong> If the currency code used is not supported for the merchant and it does not run a transaction on schedule creation, the schedule will not error until the first transaction is processed.</p></td><td></td></tr><tr><td>TotalPayments</td><td>No</td><td>integer</td><td>infinite</td><td><p>Total count of scheduled payment occurrences, including the initial payment.</p><p><strong>Note:</strong> If left blank, the count is indefinite. This field cannot be set together with <code>EndDate</code>.</p></td><td></td></tr><tr><td>Cvv</td><td>No</td><td>string</td><td></td><td>The CVV value for the first transaction that is run if a transaction is run immediately. This value will not be applied to a future transaction run by the created schedule.</td><td></td></tr><tr><td>Description</td><td>No</td><td>string</td><td></td><td>Additional data sent with the transaction.</td><td></td></tr><tr><td>Invoice</td><td>No</td><td>string</td><td></td><td><p>Customer's invoice number for the transaction. </p><p>Use <code>Invoice</code> when available for improved duplicate handling (recommended).</p></td><td></td></tr><tr><td>PONumber</td><td>No</td><td>string</td><td></td><td>Customer's purchase order number for the transaction.</td><td></td></tr><tr><td>ScheduleName</td><td>No</td><td>string</td><td></td><td>Merchant's internal schedule identifier.</td><td></td></tr><tr><td>IntervalCount</td><td>No</td><td>integer</td><td>1</td><td><p>Number of time periods to elapse before the payment schedule is re-triggered. </p><p><em>Examples:</em></p><p>For every 28 days, set <code>IntervalType</code> to day and set <code>IntervalCount</code> to 28.</p><p>For every other month, set <code>IntervalType</code> to month and set <code>IntervalCount</code> to 2.</p></td><td></td></tr><tr><td>FailedTransactionRetryTimes</td><td>No</td><td>integer</td><td>5</td><td>Maximum number of times to retry before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day. If it’s set to 0, it will try one time total.</td><td></td></tr><tr><td>DaysBetweenRetriesnew</td><td>No</td><td>integer</td><td>1</td><td>Number of days between retries after a declined transaction.</td><td>Any natural number greater than 0.</td></tr><tr><td>SkipSaturdayAndHolidays</td><td>No</td><td>boolean</td><td>false</td><td>Indicates whether to process payments on the Sabbath and Jewish holidays.</td><td></td></tr><tr><td>CustReceipt</td><td>No</td><td>boolean</td><td>false</td><td>A flag that can be set to send the receipts to the email set in <code>Email</code> for the customer.</td><td></td></tr><tr><td>CalendarCulture</td><td>No</td><td>string</td><td>Gregorian</td><td>Type of calendar to use when executing month and year interval types.</td><td>Gregorian, Hebrew</td></tr><tr><td>UseDefaultPaymentMethodOnly</td><td>No</td><td>boolean</td><td>false</td><td>Indicates that the system should not try another card if the default card fails.</td><td></td></tr><tr><td>ScheduleRule</td><td>No</td><td>object</td><td></td><td><p>The schedule rule used to determine the next run time after each processed payment.</p><p>See <a href="https://docs.cardknox.com/api/recurring#appendix-a-schedule-rules">Appendix A</a> for more information on the <code>ScheduleRule</code> object.</p></td><td></td></tr><tr><td>StartDate</td><td>No</td><td>string</td><td>current date</td><td><p>Schedule start date in YYYY-MM-DD format. The start date must be within one year.</p><p>Unless the <code>StartDate</code> parameter is included to specify a future start date for the schedule, the first charge takes place immediately by default.</p></td><td></td></tr><tr><td>EndDate</td><td>No</td><td>string</td><td></td><td><p>Schedule expiration date in YYYY-MM-DD format.</p><p><strong>Note:</strong> This field cannot be set together with <code>TotalPayments</code>.</p></td><td></td></tr><tr><td>AfterMaxRetriesAction</td><td>No</td><td>string</td><td>ContinueNextInterval</td><td><p>The action to perform after a schedule hits the maximum number of failed attempts in a single interval.</p><ul><li><strong>Disable:</strong> Disables the schedule.</li><li><strong>ContinueNextInterval:</strong> Skips the current interval and continues at the next interval.</li></ul></td><td>Disable, ContinueNextInterval</td></tr><tr><td>AllowInitialTransactionToDecline</td><td>No</td><td>Boolean</td><td>False</td><td><p>Create the schedule even if the initial payment fails.</p><p><strong>Note:</strong> Can be used only if the <code>StartDate</code> is set to today's date (or left empty).</p></td><td></td></tr><tr><td>SplitInstruction</td><td>No</td><td>Object</td><td>False</td><td>On Instructional Funding accounts, add split instructions for each scheduled transaction. Format is an array of json objects, each having a mid and the amount for that mid.</td><td></td></tr><tr><td>CustomXX</td><td>No</td><td>String</td><td></td><td><p>Custom fields (19 available) used for custom data, such as customer comments and so forth.</p><p><code>Custom01</code> is reserved. Use <code>Custom02</code> - <code>Custom20</code>.</p></td><td></td></tr><tr><td>InitialAmount</td><td>No</td><td>String or Integer</td><td></td><td>Overrides Amount on initial transaction</td><td>5.99</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"CustomerId" : "c123456",
	"PaymentMethodId" : "c123456_pm654321",
	"Amount" : "1.23",
	"IntervalType" : "month",
	"IntervalCount" : 1,
	"ScheduleName" : "Sample Schedule",
	"TotalPayments" : 5,
	"SkipSaturdayAndHolidays" : false,
	"AllowInitialTransactionToDecline" : false,
	"CustReceipt" : false,
	"Custom01" : "customValue1",
	"Custom02" : "customValue2",
	"Custom03" : "customValue3"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="168">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>ScheduleId</td><td>string</td><td>The ID of the schedule that was created.</td><td></td></tr><tr><td>CustomerId</td><td>string</td><td>The ID of the customer that was created if the schedule was not linked to an existing customer.</td><td></td></tr><tr><td>PaymentMethodId</td><td>string</td><td>The ID of the payment method that was created if the schedule was not linked to an existing customer.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "ScheduleId" : "c123456_s123456"
}
```

### /UpdateSchedule

This command allows you to update some details of a schedule. You can only update information that does not change the actual schedule. For example, the `CustomerId` field cannot be updated (and it is not listed in the parameter table below). Also, you cannot update inactive schedules.

The following fields can be updated at any point:

* AfterMaxRetriesAction
* Amount
* CustomXX
* CustReceipt
* DaysBetweenRetries
* Description
* Invoice
* PaymentMethodId
* PONumber
* RetryAmount
* ScheduleName
* SkipSaturdayAndHolidays
* UseDefaultPaymentMethodOnly
* SplitInstruction

Any fields that are not set will use the default values (or if no default is indicated, they will be removed).

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="183">Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td><td>Valid Values</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td><td></td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td><td></td></tr><tr><td>Revision</td><td>Yes</td><td>integer</td><td></td><td>The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.</td><td></td></tr><tr><td>ScheduleId</td><td>Yes</td><td>string</td><td></td><td>The ID of the schedule to update.</td><td></td></tr><tr><td>Amount</td><td>No</td><td>decimal</td><td></td><td>Transaction amount</td><td></td></tr><tr><td>Currency</td><td>No</td><td>string</td><td></td><td><p>Currency code to be used when processing transactions.</p><p><strong>Note:</strong> If the currency code used is not supported for the merchant and it does not run a transaction on schedule creation, the schedule will not error until the first transaction is processed.</p></td><td></td></tr><tr><td>TotalPayments</td><td>No</td><td>integer</td><td>infinite</td><td><p>Total count of scheduled payment occurrences, including the initial payment.</p><p>You can only change this field before a schedule has been completed. Additionally, you cannot set the value to be lower than the number of payments already processed.</p><p><strong>Note:</strong> This can be updated to at least the number of payments processed or higher.</p></td><td></td></tr><tr><td>Description</td><td>No</td><td>string</td><td></td><td>Additional data sent with the transaction.</td><td></td></tr><tr><td>Invoice</td><td>No</td><td>string</td><td></td><td><p>Customer's invoice number for the transaction </p><p>Use <code>Invoice</code> when available for improved duplicate handling (recommended).</p></td><td></td></tr><tr><td>PONumber</td><td>No</td><td>string</td><td></td><td>Customer's purchase order number for the transaction.</td><td></td></tr><tr><td>ScheduleName</td><td>No</td><td>string</td><td></td><td>Merchant's internal schedule identifier.</td><td></td></tr><tr><td>FailedTransactionRetryTimes</td><td>No</td><td>integer</td><td>5</td><td><p>Maximum number of times to retry before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day. If it’s set to 0, it will try one time.</p><p>You can only change this field before a schedule has been completed.</p></td><td></td></tr><tr><td>DaysBetweenRetries</td><td>No</td><td>integer</td><td></td><td>Number of days between retries after a declined transaction.</td><td>Any natural number greater than 0</td></tr><tr><td>SkipSaturdayAndHolidays</td><td>No</td><td>boolean</td><td>false</td><td>Indicates whether to process payments on the Sabbath and Jewish holidays.</td><td></td></tr><tr><td>CustReceipt</td><td>No</td><td>boolean</td><td>false</td><td>A flag that can be set to send the receipts to the email set in <code>Email</code> for the customer.</td><td></td></tr><tr><td>CalendarCulture</td><td>Yes</td><td>string</td><td>Gregorian</td><td><p>Type of calendar to use when executing month and year interval types.</p><p><strong>Note:</strong> You cannot change this once the schedule has begun.</p></td><td>Gregorian, Hebrew</td></tr><tr><td>UseDefaultPaymentMethodOnly</td><td>No</td><td>boolean</td><td>false</td><td>Indicates that the system should not try another card if the default card fails.</td><td></td></tr><tr><td>PaymentMethodId</td><td>No</td><td>string</td><td></td><td>The unique ID of the payment method the schedule should use to process the transactions</td><td></td></tr><tr><td>ScheduleRule</td><td>No</td><td>object</td><td></td><td><p>The schedule rule used to determine the next run time after each processed payment.</p><p>See <a href="#appendix-a-schedule-rules">Appendix A</a> for more information on the <code>ScheduleRule</code> object.</p></td><td></td></tr><tr><td>StartDate</td><td>Yes</td><td>string</td><td></td><td><p>Schedule start date in YYYY-MM-DD format. The start date must be within one year.</p><p><strong>Note:</strong> This cannot be changed once the schedule has begun.</p></td><td></td></tr><tr><td>EndDate</td><td>No</td><td>string</td><td></td><td><p>Schedule expiration date in YYYY-MM-DD format.</p><p><strong>Note:</strong> This field cannot be set together with <code>TotalPayments</code>. This cannot be changed once the schedule has completed.</p></td><td></td></tr><tr><td>AfterMaxRetriesAction</td><td>No</td><td>String</td><td>ContinueNextInterval</td><td><p>The action to perform after a schedule hits the maximum number of failed attempts in a single interval.</p><ul><li><strong>Disable:</strong> Disables the schedule.</li><li><strong>ContinueNextInterval:</strong> Skips the current interval and continues at the next interval.</li></ul></td><td>Disable, ContinueNextInterval</td></tr><tr><td>SplitInstruction</td><td>No</td><td>Object</td><td></td><td>On Instructional Funding accounts, update the split instructions for each scheduled transaction. Format is an array of json objects, each having a mid and the amount for that mid.</td><td></td></tr><tr><td>CustomXX</td><td>No</td><td>String</td><td></td><td><p>Custom fields (19 available) used for custom data, such as customer comments and so forth.</p><p><code>Custom01</code> is reserved. Use <code>Custom02</code> - <code>Custom20</code>.</p></td><td></td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"ScheduleId" : "c123456_s123456",
	"Amount" : "1.23",
	"ScheduleName" : "Sample Schedule",
	"PaymentMethodId" : "c123456_pm654321",
	"TotalPayments" : 5,
	"SkipSaturdayAndHolidays" : false,
	"CustReceipts" : false,
	"Custom01" : "customValue1",
	"Custom02" : "customValue2",
	"Custom03" : "customValue3"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="162">Parameter</th><th>Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /EnableSchedule

Restart a schedule that was previously disabled.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="186.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>ScheduleId</td><td>Yes</td><td>string</td><td>The ID of the schedule to enable.</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"ScheduleId" : "c123456_s123456"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="168">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>,this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /DisableSchedule

Stop, pause, cancel, or inactivate an active schedule.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="191.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>ScheduleId</td><td>Yes</td><td>string</td><td>The ID of the schedule to disable.</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"ScheduleId" : "c123456_s123456"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="171">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /DeleteSchedule

Removes a schedule. You can only delete a schedule that is not active.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="194.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>ScheduleId</td><td>Yes</td><td>string</td><td>The ID of the schedule to delete.</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"ScheduleId" : "c123456_s123456"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="154">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
```

### /GetSchedule

Retrieves the details for a schedule.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="189.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>ScheduleId</td><td>Yes</td><td>string</td><td>The ID of the schedule to retrieve.</td></tr><tr><td>ShowDeleted</td><td>No</td><td>boolean</td><td>A flag that can be set to retrieve deleted items. If set to <strong>true</strong>, only deleted items can be retrieved (i.e., schedules that are not deleted will not be returned).</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"ScheduleId" : "c123456_s123456",
    "ShowDeleted" : false
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="168">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>Revision</td><td>integer</td><td>The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.</td><td></td></tr><tr><td>ScheduleId</td><td>string</td><td>Schedule reference number.</td><td></td></tr><tr><td>ScheduleName</td><td>string</td><td>Schedule name.</td><td></td></tr><tr><td>CustomerId</td><td>string</td><td>Customer's unique ID number.</td><td></td></tr><tr><td>PaymentMethodId</td><td>string</td><td><p>The unique ID number of the payment method the schedule uses to process the transactions</p><p><strong>Note:</strong> Only populated when a specific PaymentMethodId was sent in on creating/updating schedule</p></td><td></td></tr><tr><td>IsDeleted</td><td>boolean</td><td>A  flag indicating whether the record is deleted.</td><td></td></tr><tr><td>UseDefaultCardOnly</td><td>boolean</td><td>Indicates that the system should not try another card if the default card fails.</td><td></td></tr><tr><td>FailedTransactionRetryTimes</td><td>integer</td><td>Maximum number of times to retry before rescheduling to the next run time if the transaction fails. The tries are spaced apart into 1-day intervals.</td><td></td></tr><tr><td>FailedAttemptsInCurrentInterval</td><td>integer</td><td>The number of unsuccessful transactions that were processed for the current interval. This value will reset to 0 at the start of the next interval.</td><td></td></tr><tr><td>DaysBetweenRetries</td><td>integer</td><td>Number of days between retries after a declined transaction.</td><td></td></tr><tr><td>ScheduleRule</td><td>object</td><td><p>The schedule rule used to determine the next run time after each processed payment.</p><p>See <a href="#appendix-a-schedule-rules">Appendix A</a> for more information on the <code>ScheduleRule</code> object.</p></td><td></td></tr><tr><td>StartDate</td><td>string</td><td>Schedule start date in YYYY-MM-DD format.</td><td></td></tr><tr><td>EndDate</td><td>string</td><td>Schedule end date in YYYY-MM-DD format.</td><td></td></tr><tr><td>AllowInitialTransactionToDecline</td><td>boolean</td><td>Indicates whether the schedule was set up to allow the first transaction to be declined.</td><td></td></tr><tr><td>Description</td><td>string</td><td>Additional data sent with the transaction (optional).</td><td></td></tr><tr><td>Amount</td><td>decimal</td><td>Transaction amount.</td><td></td></tr><tr><td>Currency</td><td>string</td><td>Currency code to be used when processing transactions.</td><td></td></tr><tr><td>TotalPayments</td><td>integer</td><td>Total count of scheduled payment occurrences, including the initial payment.</td><td></td></tr><tr><td>PaymentsProcessed</td><td>integer</td><td>The number of payments processed by the schedule.</td><td></td></tr><tr><td>SkipSaturdayAndHolidays</td><td>boolean</td><td>Indicates whether to process payments on the Sabbath and Jewish holidays.</td><td></td></tr><tr><td>IntervalType</td><td>string</td><td>Type of time interval.</td><td></td></tr><tr><td>IntervalCount</td><td>integer</td><td><p>Number of time periods to elapse before the payment schedule is re-triggered. </p><p><strong>Note:</strong> Refer to the <a href="#createschedule">/CreateSchedule</a> endpoint for more details.</p></td><td></td></tr><tr><td>LastTransactionStatus</td><td>string</td><td>The status of the last transaction run by the schedule.</td><td></td></tr><tr><td>LastTransactionError</td><td>string</td><td>The error message of the last transaction if the status was <strong>Error</strong>.</td><td></td></tr><tr><td>LastProjectedPaymentDate</td><td>string</td><td><p>The projected payment date of the last transaction that the schedule will run.</p><p><strong>Note:</strong> This may not be 100% accurate if that last date falls on a Saturday or Holiday and <code>SkipSaturdayAndHolidays</code> is set.</p></td><td></td></tr><tr><td>Invoice</td><td>string</td><td>Customer's invoice number for the transaction.</td><td></td></tr><tr><td>PONumber</td><td>string</td><td>Customer's purchase order number for the transaction.</td><td></td></tr><tr><td>CustReceipt</td><td>boolean</td><td>A flag indicating whether receipts will be sent to the email set in <code>Email</code> for the customer.</td><td></td></tr><tr><td>NextScheduledRunTime</td><td>string</td><td>The date and time that the schedule will next run.</td><td></td></tr><tr><td>InitialRunTime</td><td>string</td><td>The date and time of the first transaction run by the schedule.</td><td></td></tr><tr><td>LastRunTime</td><td>string</td><td>The date and time of the last transaction run by the schedule.</td><td></td></tr><tr><td>IsActive</td><td>boolean</td><td>A flag indicating whether the schedule is currently enabled/active.</td><td></td></tr><tr><td>CalendarCulture</td><td>string</td><td>Type of calendar to use when executing month and year interval types.</td><td></td></tr><tr><td>CreatedDate</td><td>string</td><td>Date that the schedule was created.</td><td></td></tr><tr><td>CustomerNumber</td><td>string</td><td>Merchant's internal customer identifier.</td><td></td></tr><tr><td>Email</td><td>string</td><td>Customer's email address.</td><td></td></tr><tr><td>BillFirstName</td><td>string</td><td>Customer's first name for their billing profile.</td><td></td></tr><tr><td>BillMiddleName</td><td>string</td><td>Customer's middle name or initial for their billing profile.</td><td></td></tr><tr><td>BillLastName</td><td>string</td><td>Customer's last/family name for their billing profile.</td><td></td></tr><tr><td>BillCompany</td><td>string</td><td>Customer's company for their billing profile.</td><td></td></tr><tr><td>AfterMaxRetriesAction</td><td>string</td><td><p>The action to perform after a schedule hits the maximum number of failed attempts in a single interval.</p><ul><li><strong>Disable:</strong> Disables the schedule.</li><li><strong>ContinueNextInterval:</strong> Skips the current interval and continues at the next interval.</li></ul></td><td>Disable, ContinueNextInterval</td></tr><tr><td>SplitInstruction</td><td>Object</td><td>On Instructional Funding accounts, the split instructions used for each scheduled transaction.</td><td></td></tr><tr><td>CustomXX</td><td>string</td><td><p>Custom fields (19 available) used for custom data, such as customer comments and so forth.</p><p><code>Custom01</code> is reserved.</p></td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum" : "r1234567890",
    "Result" : "S",
    "Error" : "",
    "Revision" : 1,
    "ScheduleId" : "c123456_s123456",
    "ScheduleName" : "Sample Schedule",
    "CustomerId" : "c123456",
    "PaymentMethodId": "c123456_p987654",
    "IsDeleted" : false,
    "UseDefaultCardOnly" : false,
    "FailedTransactionRetryTimes": 5,
    "DaysBetweenRetries" : 2,
    "IntervalType" : "month",
    "IntervalCount" : 12
    "ScheduleRule" : {
      "RuleType" : "Nth",
      "N" : 1,
      "NthOfType" : "Weekday"
     }
    "StartDate" : "2020-04-27",
    "EndDate" :  "2021-04-27",
    "AllowInitialTransactionToDecline" : false,
    "Description" : "Sample Schedule",
    "Amount" : 1.23,
    "TotalPayments" : 12,
    "PaymentsProcessed" : 2,
    "SkipSaturdayAndHolidays" : false,
    "LastTransactionStatus" : "Approved",
    "LastTransactionError" : ""
    "LastProjectedPaymentDate" : "2021-04-27",
    "Invoice" : "1234567",
    "PONumber" : "1234567",
    "CustReceipts" : false,
    "NextScheduledRunTime" : "2020-06-27",
    "InitialRunTime" : "2020-04-27 01:03:50",
    "LastRunTime" : "2020-05-27 012:15:34",
    "IsActive" : true,
    "CalendarCulture" : "Gregorian",
    "CreatedDate" : "2020-03-21 10:15:40",
    "CustomerNumber" :  "123456",
    "Email" : "sample@example.com",
    "BillFirstName" : "John",
    "BillMiddleName" : "G",
    "BillLastName" : "Doe",
    "BillCompany" : "ACME Inc.",
    "AfterMaxRetriesAction" : "Disable",
    "SplitInstruction": [
		{
			"xMid": "1234",
			"xAmount": "1.10"
		},
		{
			"xMid": "5678",
			"xAmount": "0.13"
		}
	],
    "Custom01" : "customValue1",
    "Custom02" : "customValue2",
    "Custom03" : "customValue3"
}
```

### /GetUpcomingPaymentDates

Returns a list of upcoming payment dates (up to 100) for a specific schedule.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td><td>Valid Values</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td><td></td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td><td></td></tr><tr><td>ScheduleId</td><td>Yes</td><td>string</td><td></td><td>The ID of the schedule to retrieve.</td><td></td></tr><tr><td>NumberOfPayments</td><td>Yes</td><td>integer</td><td></td><td>The number of payment dates to retrieve.</td><td>An integer between 1 and 100 (inclusive)</td></tr><tr><td>CalendarCulture</td><td>No</td><td>string</td><td>Gregorian</td><td>The culture the dates should be returned in.</td><td>Gregorian, Hebrew</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"ScheduleId" : "c123456_s123456",
    "NumberOfPayments" : 12,
    "CalendarCulture" : "Gregorian",
    "ShowDeleted" : false
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="184">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents an error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>UpcomingPaymentDates</td><td>string[]</td><td>The upcoming payment dates for the specified schedule in the format yyyy-mm-dd.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "UpcomingPaymentDates" : [
        "2020-01-01",
		"2020-02-01",
		"2020-03-01"
    ]
}
```

### /ListSchedules

Returns a list of schedules that are sorted by creation date (ascending or descending order). You can use search filters to narrow the search results that are returned.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td><td>Valid Values</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td><td></td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td><td></td></tr><tr><td>PageSize</td><td>No</td><td>integer</td><td>100</td><td>The maximum number of items to retrieve for this request.</td><td></td></tr><tr><td>NextToken</td><td>No</td><td>string</td><td></td><td>A token that can be sent in to the following request to get the next set of schedules.</td><td></td></tr><tr><td>SortOrder</td><td>No</td><td>string</td><td>Ascending</td><td>The list order. Order is determined by schedule creation date.</td><td>Ascending, Descending</td></tr><tr><td>Filters</td><td>No</td><td>object</td><td><p>{</p><p>    "IsDeleted" : false</p><p>}</p></td><td><p>Filters that can be applied to limit the result set.</p><p>Filters will remove any items that don't contain the string for that filter value. If there are multiple filters applied the item must match all of them.</p><p>Available filters:</p><ul><li>IsDeleted</li><li>Active</li><li>Amount</li><li>IntervalCount</li><li>CustomerId</li><li>ScheduleId</li><li>BillFirstName</li><li>BillMiddleName</li><li>BillLastName</li><li>BillName</li><li>Email</li><li>BillCompany</li><li>CustomerNumber</li><li>ScheduleName</li><li>Description</li><li>IntervalType</li><li>StartDate</li><li>PaymentsRemaining</li></ul></td><td></td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"NextToken" : "",
	"PageSize" : 500,
	"Filters" : {
		"IsDeleted" : false
	}
}

```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="150">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents an error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>Schedules</td><td>object[]</td><td><p>An array of schedule objects. Refer to the <a href="https://cardknox.atlassian.net/wiki/spaces/REC/pages/92045335/Recurring+v2+Api#/GetSchedule">/GetSchedule</a> endpoint for the values that are returned for each schedule.</p><p><strong>Note:</strong> The <code>ScheduleRule</code> field is not returned by this endpoint for each schedule.</p></td><td></td></tr><tr><td>NextToken</td><td>string</td><td>A token to include in the next request to get the next set of results.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
	"Schedules" : [
		{
       	 	"ScheduleId": "c123456_s123456",
      		"Revision": 5,
      		"CustomerId": "c123456",
	    	"FailedTransactionRetryTimes": 5,
		    "StartDate": "2018-04-27",
		    "Amount": 0.03,
		    "TotalPayments": 3,
		    "PaymentsProcessed": 2,
		    "IntervalType": "Day",
		    "IntervalCount": 1,
		    "LastTransactionStatus": "Approved",
		    "LastProjectedPaymentDate": "2019-05-16",
		    "InitialRunTime": "2019-05-16 01:03:50",
		    "LastRunTime": "2019-06-19 01:03:48",
		    "CalendarCulture": "Gregorian",
		    "CreatedDate": "2018-04-26 16:33:27.571",
		    "CustomerNumber": "1",
		    "BillFirstName": "John",
		    "BillLastName": "Smith",
	     	"BillCompany": "ACME Inc.",
			"SplitInstruction": [
				{
					"xMid": "1234",
					"xAmount": "1.10"
				},
				{
					"xMid": "5678",
					"xAmount": "0.13"
				}
			]
    	}
    ]
}
```

## Transaction Endpoints

### /ProcessTransaction

Processes a single payment transaction for a customer. You can specify a backup payment method to use should the initial payment fail. If desired, you can have the system send an email receipt of the transaction to the customer.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td></tr><tr><td>CustomerId</td><td>Yes</td><td>string</td><td></td><td><p>Customer's unique ID number.</p><p><br>*This field is required if PaymentMethodID is not passed in. Valid combinations are below:</p><ul><li>PM ID only</li><li>Customer ID Only (will use default PM on file)</li><li>Customer ID &#x26; new PM info</li></ul></td></tr><tr><td>PaymentMethodId</td><td>Yes*</td><td>string</td><td></td><td><p>The ID of the payment method to use for the transaction.</p><p>*Required if using an existing non-default payment method.<br></p></td></tr><tr><td>Amount</td><td>Yes</td><td>decimal</td><td></td><td>The amount of the transaction.</td></tr><tr><td>Tax<br></td><td>No</td><td>decimal</td><td></td><td>The tax portion that is included in the total transaction amount.</td></tr><tr><td>PaymentDetails</td><td>No*</td><td>object</td><td></td><td><p>The details for a new method of payment.</p><p>*Required if <strong>not</strong> using an existing payment method.</p><p><strong>Note:</strong> Refer to the <a href="#createpaymentmethod">/CreatePaymentMethod</a> endpoint for available and required fields.</p></td></tr><tr><td>UseBackupPaymentMethods</td><td>No</td><td>boolean</td><td>false</td><td>Indicates that the system should try another card if the default card fails.</td></tr><tr><td>Invoice</td><td>No</td><td>string</td><td></td><td><p>Customer's invoice number for the transaction. </p><p>Use <code>Invoice</code> when available for improved duplicate handling (recommended).</p></td></tr><tr><td>PONumber</td><td>No</td><td>string</td><td></td><td>Customer's purchase order number for the transaction.</td></tr><tr><td>Description</td><td>No</td><td>string</td><td></td><td>Additional data sent with the transaction.</td></tr><tr><td>AllowDuplicates</td><td>No</td><td>boolean</td><td>false</td><td>A flag indicating whether to disable duplicate detection. Useful for testing, but it is not suggested that this be set to <strong>true</strong> in production.</td></tr><tr><td>CustReceipt</td><td>No</td><td>boolean</td><td></td><td>A flag that can be set to send the receipts to the email address set in <code>Email</code> for the customer.</td></tr><tr><td>Cvv</td><td>No</td><td>string</td><td></td><td>The CVV value for the transaction.</td></tr><tr><td>Email</td><td>No</td><td>string</td><td></td><td>Customer's email address.</td></tr><tr><td>Fax</td><td>No</td><td>string</td><td></td><td>Customer's fax number.</td></tr><tr><td>BillFirstName</td><td>Yes*</td><td>string</td><td></td><td><p>Customer's first name for their billing profile.</p><p>*This field is required if <code>BillLastName</code> and <code>BillCompany</code> are not passed in.</p></td></tr><tr><td>BillMiddleName</td><td>No</td><td>string</td><td></td><td>Customer's middle name or initial for their billing profile.</td></tr><tr><td>BillLastName</td><td>Yes*</td><td>string</td><td></td><td><p>Customer's last/family name for their billing profile.</p><p>*This field is required if <code>BillFirstName</code> and <code>BillCompany</code> are not passed in.</p></td></tr><tr><td>BillCompany</td><td>Yes*</td><td>string</td><td></td><td><p>Customer's company for their billing profile.</p><p>*This field is required if <code>BillFirstName</code> and <code>BillLastName</code> are not passed in.</p></td></tr><tr><td>BillStreet</td><td>No</td><td>string</td><td></td><td>Customer's street address for their billing profile.</td></tr><tr><td>BillStreet2</td><td>No</td><td>string</td><td></td><td>Customer's street address second line for their billing profile.</td></tr><tr><td>BillCity</td><td>No</td><td>string</td><td></td><td>Customer's city for their billing profile.</td></tr><tr><td>BillState</td><td>No</td><td>string</td><td></td><td>Customer's state for their billing profile.</td></tr><tr><td>BillZip</td><td>No</td><td>string</td><td></td><td>Customer's ZIP code or postal code for their billing profile.</td></tr><tr><td>BillCountry</td><td>No</td><td>string</td><td></td><td>Customer's country for their billing profile.</td></tr><tr><td>BillPhone</td><td>No</td><td>string</td><td></td><td>Customer's phone number for their billing profile.</td></tr><tr><td>BillMobile</td><td>No</td><td>string</td><td></td><td>Customer's mobile number for their billing profile.</td></tr><tr><td>ShipFirstName</td><td>No</td><td>string</td><td></td><td>Customer’s first name for their shipping profile.</td></tr><tr><td>ShipMiddleName</td><td>No</td><td>string</td><td></td><td>Customer’s middle name or initial for their shipping profile.</td></tr><tr><td>ShipLastName</td><td>No</td><td>string</td><td></td><td>Customer’s last/family name for their shipping profile.</td></tr><tr><td>ShipCompany</td><td>No</td><td>string</td><td></td><td>Customer’s company name for their shipping profile.</td></tr><tr><td>ShipStreet</td><td>No</td><td>string</td><td></td><td>Customer’s street address for their shipping profile.</td></tr><tr><td>ShipStreet2</td><td>No</td><td>string</td><td></td><td>Customer’s street address second line for their shipping profile.</td></tr><tr><td>ShipCity</td><td>No</td><td>string</td><td></td><td>Customer’s city for their shipping profile.</td></tr><tr><td>ShipState</td><td>No</td><td>string</td><td></td><td>Customer’s state for their shipping profile.</td></tr><tr><td>ShipZip</td><td>No</td><td>string</td><td></td><td>Customer’s ZIP or postal code for their shipping profile.</td></tr><tr><td>ShipCountry</td><td>No</td><td>string</td><td></td><td>Customer’s country for their shipping profile.</td></tr><tr><td>ShipPhone</td><td>No</td><td>string</td><td></td><td>Customer’s phone number for their shipping profile.</td></tr><tr><td>ShipMobile</td><td>No</td><td>string</td><td></td><td>Customer’s mobile number for their shipping profile.</td></tr><tr><td>ShipEmail</td><td>No</td><td>string</td><td></td><td>Customer’s shipping email address for their shipping profile.</td></tr><tr><td>CustomXX</td><td>No</td><td>string</td><td></td><td><p>Custom fields (19 available) used for custom data, such as customer comments and so forth.</p><p><code>Custom01</code> is reserved. Use <code>Custom02</code> - <code>Custom20</code>.</p></td></tr><tr><td>Currency</td><td>No</td><td>string</td><td></td><td>Currency code for the transaction.</td></tr><tr><td>SplitInstruction</td><td>No</td><td>object</td><td>sale</td><td>On Instructional Funding accounts, add split instructions for the transaction. Format is an array of json objects, each having a mid and the amount for that mid.</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"PaymentMethodId" : "c123456_pm123456",
	"Amount" : 1.23,
	"PaymentDetails" : null,
	"UseBackupPaymentMethods" : false,
	"Invoice" : "1234567",
	"PONumber" : "1234567",
	"Description" : "Sample One Time Transaction",
	"AllowDuplicates" : false,
	"Cvv" : "123",
	"BillStreet" : "123 Main St.",
	"splitinstruction":[
		{
			"xmid":53141,
			"xamount":1.01
		},
		{
			"xmid":53138,
		 	"xamount":0.01
		}
	]
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>GatewayRefnum</td><td>string</td><td>The gateway reference number for the transaction.</td><td></td></tr><tr><td>GatewayStatus</td><td>string</td><td>The status of the transaction passed back by the gateway.</td><td>Approved, Declined, Error</td></tr><tr><td>GatewayErrorMessage</td><td>string</td><td>The error message for the transaction passed back by the gateway if the status indicates an error.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "GatewayRefnum" : "1234567890"
    "GatewayStatus" : "Approved",
    "GatewayErrorMessage" : ""
}
```

### /GetTransaction

Returns the details of an existing transaction, such as transaction date and customer ID. Also returned are the transaction's processing status and any error messages from the gateway.

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>RefNum</td><td>Yes</td><td>string</td><td>The ID of the transaction to retrieve.</td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"RefNum" : "c123456_s123456_t123456"
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>TransactionId</td><td>string</td><td>The ID of the retrieved transaction.</td><td></td></tr><tr><td>ScheduleId</td><td>string</td><td>The ID of the schedule that the transaction was run for.</td><td></td></tr><tr><td>CustomerId</td><td>string</td><td>The ID of the customer that the transaction was run for.</td><td></td></tr><tr><td>PaymentMethodId</td><td>string</td><td>The ID of the payment method used in the transaction.</td><td></td></tr><tr><td>TransactionDate</td><td>string</td><td>The date the transaction was run.</td><td></td></tr><tr><td>GatewayRefNum</td><td>string</td><td>The reference number generated by the gateway for the transaction.</td><td></td></tr><tr><td>GatewayStatus</td><td>string</td><td>The transaction processing status returned by the gateway.</td><td>Approved, Declined, Error</td></tr><tr><td>GatewayError</td><td>string</td><td>The error message returned by the gateway if <code>GatewayStatus</code> indicates an error.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
  "RefNum": "r1234567890",
  "Result": "S",
  "Error": "",
  "TransactionId": "c123456_s123456_t123456",
  "ScheduleId": "c123456_s123456",
  "CustomerId": "c123456",
  "PaymentMethodId": "c123456_pm123456",
  "TransactionDate": "2019-08-02 15:06:57",
  "GatewayRefNum": "1234567890",
  "GatewayStatus": "Approved",
  "GatewayError": ""
}
```

### /ListTransactions

Returns a list of transactions, that are sorted by transaction date (in ascending or descending order). You can use specific search criteria to define which transactions to return.

{% hint style="info" %}
`/ListTransactions` will only return transactions initiated from a schedule. Single transactions won't be returned, even if linked to a customer.
{% endhint %}

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Required</th><th width="150">Type</th><th width="150">Default Value</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Default Value</td><td>Description</td><td>Valid Values</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td></td><td>The name of the software making the request.</td><td></td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td></td><td>The version of the software making the request.</td><td></td></tr><tr><td>PageSize</td><td>No</td><td>integer</td><td>100</td><td>The maximum number of items to retrieve for this request.</td><td></td></tr><tr><td>NextToken</td><td>No</td><td>string</td><td></td><td>A token that can be sent in to the following request to get the next set of transactions.</td><td></td></tr><tr><td>SortOrder</td><td>No</td><td>string</td><td>Ascending</td><td>The list order. Order is determined by the date the transaction ran.</td><td>Ascending, Descending</td></tr><tr><td>Filters</td><td>No</td><td>object</td><td></td><td><p>Filters that can be applied to limit the result set.</p><p>Filters will remove any items that do not contain the string for that filter value. If there are multiple filters applied, the item must match all of them.</p><p>Available filters:</p><ul><li>IsApproved</li><li>FromDate</li><li>ToDate</li><li>CustomerId</li><li>ScheduleId</li><li>PaymentMethodId</li><li>TransactionId</li></ul></td><td></td></tr></tbody></table>

**Sample Request**

```javascript
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"NextToken" : "",
	"PageSize" : 500,
	"Filters" : {
		"IsApproved" : true
	}
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th>Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents  error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>Transactions</td><td>object[]</td><td><p>An array of transaction objects.</p><p>Refer to the <a href="#gettransaction">/GetTransaction</a> endpoint for the values that are returned for each transaction.</p></td><td></td></tr><tr><td>NextToken</td><td>string</td><td>A token to include in the next request to get the next set of results.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
	"Transactions" : [
		{
        	"TransactionId": "c123456_s123456_t123456",
        	"ScheduleId": "c123456_s123456",
        	"CustomerId": "c123456",
      		"PaymentMethodId": "c123456_pm123456",
      		"TransactionDate": "2019-08-02 15:06:57",
      		"GatewayRefNum": "1234567890",
      		"GatewayStatus": "Approved"
    	},
    	{
     		"TransactionId": "c123456_s123456_t123456",
		    "ScheduleId": "c123456_s123456",
		    "CustomerId": "c123456",
      		"PaymentMethodId": "c123456_pm123456",
   		    "TransactionDate": "2019-08-07 16:34:16",
    		"GatewayRefNum": "1234567891",
    	    "GatewayStatus": "Approved"
    	},
    ]
}
```

## Merchant Endpoints

### /UpdateMerchant

Changes the recurring report settings for the merchant, which includes:

* Email address&#x20;
* Enabled status
* Show Details setting&#x20;

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="193.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr><tr><td>Revision</td><td>Yes</td><td>integer</td><td>The current revision number of the record. If his value is incorrect the update will fail.</td></tr><tr><td>ScheduleReportSettings</td><td>Yes</td><td>object</td><td><p>The schedule report settings for the merchant:</p><ul><li><strong>Enabled</strong> (boolean): A flag indicating if the system should send the report.</li><li><strong>EmailAddresses</strong> (array of string): One or more email addresses that will be sent the report.</li><li><strong>ShowDetails</strong> (boolean): A flag indicating if the system should send the detailed version of the report with transaction details. The system can send the detailed version sent only if there are 500 transactions or less.</li></ul></td></tr><tr><td>MaxRetriesReachedNotification</td><td>No</td><td>object</td><td><p>Settings for an email notification when a schedule reaches the maximum number of retries in an interval.</p><ul><li><strong>Enabled</strong> (boolean): A flag indicating if the system should send the email notification.</li><li><strong>EmailAddresses</strong> (array of string): One or more email addresses that will be sent the notification.</li></ul><p>Note: Values are only updated if they are not set to null. To clear the EmailAddresses, an empty array must be passed in.</p></td></tr></tbody></table>

**Sample Request**

```javascript
{
    "SoftwareName" : "ACME Inc.", 
    "SoftwareVersion" : "1.0",
    "Revision" : 1,
    "ScheduleReportSettings" : {
      "Enabled" : true,
      "EmailAddresses" : [
        "sample@example.com",
        "sample2@example.com"
      ],
      "ShowDetails" : true
    },
    "MaxRetriesReachedNotification" : {
      "Enabled" : true,
      "EmailAddresses" : [
        "sample@example.com",
        "sample2@example.com"
      ]
    }
}
```

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="154">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
  "RefNum": "r1234567890",
  "Result": "S",
  "Error": ""
}
```

### /DescribeMerchant

Returns the merchant's current configuration for recurring report settings (see [/UpdateMerchant](#updatemerchant)).

#### Request Body (JSON)

<table data-header-hidden><thead><tr><th width="187.7142857142857">Parameter</th><th width="150">Required</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>SoftwareName</td><td>Yes</td><td>string</td><td>The name of the software making the request.</td></tr><tr><td>SoftwareVersion</td><td>Yes</td><td>string</td><td>The version of the software making the request.</td></tr></tbody></table>

**Sample Request**

{ "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0" }

#### Response Body (JSON)

<table data-header-hidden><thead><tr><th width="165">Parameter</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>Result</td><td>char</td><td>The result of the API call. <strong>S</strong> represents success, <strong>E</strong> represents error.</td><td>S, E</td></tr><tr><td>RefNum</td><td>string</td><td>A unique request ID.</td><td></td></tr><tr><td>Error</td><td>string</td><td>If the <code>Result</code> parameter contains a value of <strong>E</strong>, this parameter will contain any relevant error messages.</td><td></td></tr><tr><td>Revision</td><td>integer</td><td>The current revision number of the record.</td><td></td></tr><tr><td>ScheduleReportSettings</td><td>object</td><td><p>The schedule report settings for the merchant:</p><ul><li><strong>Enabled</strong> (boolean): A flag indicating if the system should send the report.</li><li><strong>EmailAddresses</strong> (array of string): One or more email addresses that will be sent the report.</li><li><strong>ShowDetails</strong> (boolean): A flag indicating if the system should send the detailed version of the report with transaction details. The system can send the detailed version sent only if there are 500 transactions or less.</li></ul></td><td></td></tr><tr><td>MaxRetriesReachedNotification</td><td>object</td><td><p>The max retry reached notification settings for the merchant:</p><ul><li><strong>Enabled</strong> (boolean): A flag indicating if the system should send the email notification.</li><li><strong>EmailAddresses</strong> (array of string): One or more email addresses that will be sent the notification.</li></ul></td><td></td></tr></tbody></table>

**Sample Response**

```javascript
{
  "RefNum": "r1234567890",
  "Result": "S",
  "Error": "",
  "ScheduleReportSettings" : {
    "Enabled" : true,
    "EmailAddresses" : [
      "sample@example.com",
      "sample2@example.com"
    ],
    "ShowDetails" : true
  },
  "MaxRetriesReachedNotification" : {
    "Enabled" : true,
    "EmailAddresses" : [
      "sample@example.com",
      "sample2@example.com"
    ]
  }
}
```

## **Appendix A - Schedule Rules**

### Fields

<table data-header-hidden><thead><tr><th width="157">Name</th><th width="150">Type</th><th>Description</th><th>Valid Values</th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Description</td><td>Valid Values</td></tr><tr><td>RuleType</td><td>string</td><td>The type of rule to create.</td><td>On, Nth</td></tr><tr><td>DayOfWeek</td><td>integer</td><td>The day of the week to run the schedule on.</td><td>1 - 7</td></tr><tr><td>DayOfMonth</td><td>integer</td><td>The day of the month to run the schedule on.</td><td><p>1 - 31 for gregorian schedules</p><p>1 - 30 for hebrew schedules</p></td></tr><tr><td>MonthOfYear</td><td>integer</td><td>The month of the year to run the schedule on.</td><td><p>1 - 12 for gregorian schedules</p><p>1 - 13 for hebrew schedules</p></td></tr><tr><td>N</td><td>integer</td><td>The nth value to run the schedule on.</td><td>Any positive or negative integer other than zero</td></tr><tr><td>NthOfType</td><td>string</td><td>The type that the nth value should be applied to.</td><td>Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Day, Weekday, WeekendDay</td></tr></tbody></table>

### RuleType

There are two types of rules: `On` and `Nth`.

`On` rules run on a specified day within the specified interval (*Examples:* every Sunday, the 3rd of each month, or February 17th each year).

`Nth` rules run on nth (or nth from last) of the specified interval (*Examples:* the first weekday of each month, or the second to last Sunday of each month).

### Restrictions

* `DayOfWeek`, `DayOfMonth`, and `MonthOfYear` can only be used when `RuleType` is `On`.
* `DayOfWeek` can only be used for weekly schedules.
* `DayOfMonth` can only be used for monthly and yearly schedules.
* `MonthOfYear` can only be used for yearly schedules.
* `N` and `NthOfType` can only be used when `RuleType` is `Nth`.
* Weekly schedules can only have a `RuleType` of `On`.
* Daily schedules cannot use rule types.

### Additional Notes

* Weekdays begin with Monday and continue through Friday.
* Weekends are Saturday and Sunday.
* The following are the values for the days of the week:
  * Sunday = 1
  * Monday = 2
  * Tuesday = 3
  * Wednesday = 4
  * Thursday = 5
  * Friday = 6
  * Saturday = 7
* The following are the values for `MonthOfYear` for the **Hebrew** calendar:
  * Tishrei = 1
  * Cheshvan = 2
  * Kislev = 3
  * Teves = 4
  * Shevat = 5
  * Adar = 6
  * (Adar Beis = 7 in a leap year)
  * Nisan = 7 (8 in a leap year)
  * Iyar = 8 (9 in a leap year)
  * Sivan = 9 (10 in a leap year)
  * Tamuz = 10 (11 in a leap year)
  * Av = 11 (12 in a leap year)
  * Elul = 12 (13 in a leap year)
* Use a negative number as the value of `N` to run as the nth from last.
  * An `N` value of `1` indicates the first
  * An `N` value of -1 indicates the last
* A schedule with an `IntervalCount` greater than 1 will first run on the next matching date and will skip intervals from now on.
  * *Example:* The current date is January 1st, 2023 (a Wednesday), and the schedule rule says it should run on the first Thursday of the month with an `IntervalCount` of 2. The first run time will be on January 2nd, 2023, and the second run time will be on March 5th, 2023.
* Schedules will begin running on the first matching date on or after the scheduled start date. If the start date is past the first matching date in the current period, it will begin the next interval period.
  * *Example:* A yearly schedule that runs on January 1st with a start date of January 2nd, 2023, will first run on January 1st, 2024.
* If no schedule rule is passed in when creating a schedule, a default rule will be created based on the interval type. The default `RuleType` is `On` with the `DayOfWeek`, `DayOfMonth`, and `MonthOfYear` values set based on the start date.

#### Example 1

A monthly schedule that runs every 3 months on the first weekday of the month:

```javascript
{
  "IntervalType" : "Month",
  "IntervalCount" : 3,
  "ScheduleRule" : { 
    "RuleType" : "Nth",
    "N" : 1,
    "NthOfType" : "Weekday"
  }
}
```

#### Example 2

A yearly schedule that runs every year on January 1st:

```javascript
{
  "IntervalType" : "Year",
  "IntervalCount" : 1,
  "ScheduleRule" : { 
    "RuleType" : "On",
	"DayOfMonth" : 1,
    "MonthOfYear" : 1
  }
}
```

#### Example 3

A weekly schedule that runs every other Monday:

```javascript
{
  "IntervalType" : "Week",
  "IntervalCount" : 2,
  "ScheduleRule" : { 
    "RuleType" : "On",
	"DayOfWeek" : 2
  }
}
```

### Appendix B - Timeouts

Timeouts

Transactions that take longer than 45 seconds to process will now be automatically voided by the gateway and marked as declined on recurring.