Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

All requests require passing in an Authorization header. The value of the Authorization header should be your gateway API key. Contact Cardknox at support@cardknox.com, and we will send you an API key via email.

...

The base URL for all requests is https://api.cardknox.com/v2

Base URL: Developers (Internal Documentation Only)

The base URL for each endpoint depends on the deployment environment being used.

...

Environment

...

AWS Account

...

Distributable URL

...

CloudFront URL

...

API Gateway URL

...

CORS Enabled

...

tst

...

devcard

...

https://tstapi.cardknox.com/{major_version}

...

https://0xer7mk1zd.execute-api.us-west-2.amazonaws.com/Prod/

...

Global

...

dev

...

cardknox

...

https://devapi.cardknox.com/{major_version}

...

Global

...

qa

...

N/A

...

N/A

...

stg

...

N/A

...

N/A

...

prd

...

cardknox

...

https://api.cardknox.com/{major_version}

...

Global

Environment is the name the environment is given when used to name resources.

Account is the name of the AWS account the environment lives on.

URL is the standard distributable URL (The CNAME for the CloudFront URL).

CloudFront URL is the direct URL generated by CloudFront. It can be used to bypass the distributable URL (if it hasn't been set up yet or is not working). This URL should not be distributed.

API Gateway URL is the direct URL generated by API Gateway. It can be used to bypass the CloudFront URL (if the CloudFront distribution has not been created or is not working). This URL should not be distributed.

CORS Enabled describes the status of CORS for the API.

     Valid values for CORS Enabled are:

  • No (CORS not enabled)

  • Static (A single URL is enabled for CORS)

  • Global (All URLs are enabled for CORS and can be access by an referrer)

  • Dynamic (All URLs are enabled for CORS, but only from the URL that made the original request).

Customer Endpoints

/CreateCustomer

...

Parameter

Required

Type

Default Value

Description

Valid Values

SoftwareName

Yes

string


The name of the software making the request.


SoftwareVersion

Yes

string


The version of the software making the request.


CustomerId

Yes*

string


Customer's unique ID number.

*Required if linking the schedule to an existing customer.


NewCustomer

Yes*

object


The customer details. Refer to the /CreateCustomer endpoint for fields that can be set for this object.

*Required if not linking the schedule to an existing customer. This cannot be set if linking to an existing customer.


NewPaymentMethod

Yes*

object


The payment method details. Refer to the /CreatePaymentMethod endpoint for fields that can be set for this object.

*Required if not linking the schedule to an existing customer. This cannot be set if linking to an existing customer.


IntervalType

Yes

string


Type of time interval.

day, week, month, year

Amount

Yes

decimal


Total amount of each transaction.

Must be a number with up to 2 decimal places

Currency

No

string

Currency code to be used when processing transactions

Note: 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.

TotalPayments

No

integer

infinite

Total count of scheduled payment occurrences, including the initial payment.

Note:If left blank, the count is indefinite. This field cannot be set together with EndDate.


Cvv

No

string


The CVV value for the first transaction that is run if a transaction is run immediately. This value will not be applied to future transaction run by the created schedule.


Description

No

string


Additional data sent with the transaction.


Invoice

No

string


Customer's invoice number for the transaction. 

Use Invoice when available for improved duplicate handling (recommended).


PONumber

No

string


Customer's purchase order number for the transaction.


ScheduleName

No

string


Merchant's internal schedule identifier.


IntervalCount

No

integer

1

Number of time periods to elapse before the payment schedule is re-triggered. 

Examples:

For every 28 days, set IntervalType to day and set IntervalCount to 28.

For every other month, set IntervalType to month and set IntervalCount to 2.


FailedTransactionRetryTimes

No

integer

5

Maximum number of times to try before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day.


DaysBetweenRetriesnew

No

integer

1

Number of days between retries after a declined transaction.

Any natural number greater than 0.

SkipSaturdayAndHolidays

No

boolean

false

Indicates whether to process payments on the Sabbath and Jewish holidays.


CustReceipt

No

boolean

false

A flag that can be set to send the receipts to the email set in Email for the customer.


CalendarCulture

No

string

Gregorian

Type of calendar to use when executing month and year interval types.

Gregorian, Hebrew

UseDefaultPaymentMethodOnly

No

boolean

false

Indicates that the system should not try another card if the default card fails.


ScheduleRule

No

object


The schedule rule used to determine the next run time after each processed payment.

See Appendix A for more information on the ScheduleRule object.


StartDate

No

string

current date

Schedule start date in YYYY-MM-DD format. The start date must be within one year.

Unless the StartDate parameter is included to specify a future start date for the schedule, the first charge takes place immediately by default.


EndDate

No

string


Schedule expiration date in YYYY-MM-DD format.

Note: This field cannot be set together with TotalPayments.


AfterMaxRetriesAction

No

string

ContinueNextInterval

What action to perform after a schedule hits the maximum number of failed attempts in a single interval.

  • Disable: Disables the schedule.

  • ContinueNextInterval: Skips the current interval and continues at the next interval.

Disable, ContinueNextInterval

AllowInitialTransactionToDecline

No

boolean

false

Create the schedule even if the initial payment fails.

Note: Can be used only if the StartDate is set to today's date (or left empty).


CustomXX

No

string


Custom fields (19 available) used for custom data, such as customer comments and so forth.

Custom01 is reserved. Use Custom02 - Custom20.


...

Parameter

Required

Type

Default Value

Description

Valid Values

SoftwareName

Yes

string


The name of the software making the request.


SoftwareVersion

Yes

string


The version of the software making the request.


Revision

Yes

integer


The revision number of the record to update. If this does not match the current revision number of the record the update will fail.


ScheduleId

Yes

string


The ID of the schedule to update.


Amount

No

decimal

Transaction amount

Currency

No

string

Currency code to be used when processing transactions

Note: 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.

TotalPayments

No

integer

infinite

Total count of scheduled payment occurrences, including the initial payment.

You can only change this field before a schedule has been completed. Additionally, you cannot set the value lower than the number of payments already processed.

Note: It can be updated to at least the number of payments processed or higher.


Description

No

string


Additional data sent with the transaction.


Invoice

No

string


Customer's invoice number for the transaction 

Use Invoice when available for improved duplicate handling (recommended).


PONumber

No

string


Customer's purchase order number for the transaction.


ScheduleName

No

string


Merchant's internal schedule identifier.


FailedTransactionRetryTimes

No

integer

5

Maximum number of times to try before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day.

You can only change this field before a schedule has been completed.


DaysBetweenRetries

No

integer


Number of days between retries after a declined transaction.

Any natural number greater than 0

SkipSaturdayAndHolidays

No

boolean

false

Indicates whether to process payments on the Sabbath and Jewish holidays.


CustReceipt

No

boolean

false

A flag that can be set to send the receipts to the email set in Email for the customer.


CalendarCulture

Yes

string

Gregorian

Type of calendar to use when executing month and year interval types.

Note: You cannot change this once the schedule has begun.

Gregorian, Hebrew

UseDefaultPaymentMethodOnly

No

boolean

false

Indicates that the system should not try another card if the default card fails.


ScheduleRule

No

object


The schedule rule used to determine the next run time after each processed payment.

See Appendix A for more information on the ScheduleRule object.


StartDate

Yes

string


Schedule start date in YYYY-MM-DD format. The start date must be within one year.

Note: This cannot be changed once the schedule has begun.


EndDate

No

string


Schedule expiration date in YYYY-MM-DD format.

Note: This field cannot be set together with TotalPayments. This cannot be changed once the schedule has completed.


AfterMaxRetriesAction

No

string

ContinueNextInterval

What action to perform after a schedule hits the maximum number of failed attempts in a single interval.

  • Disable: Disables the schedule.

  • ContinueNextInterval: Skips the current interval and continues at the next interval.

Disable, ContinueNextInterval

CustomXX

No

string


Custom fields (19 available) used for custom data, such as customer comments and so forth.

Custom01 is reserved. Use Custom02 - Custom20.


...

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

Status
subtletrue
colourGreen
titlePOST

...