Intro

Authentication

To authenticate, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: APIKEY"

TIP

Make sure to replace APIKEY with your API key and URL_GOES_HERE with

More coming soon...

name expects the API key or JWT to be included in all API requests to the server in a header that looks like the following:

Authorization: APIKEY

or

Authorization: Bearer JWTToken

Obtaining a JWT

curl -v -X POST -d "username=<username>" --data-urlencode 'password=<password>' \
"URL_GOES_HERE/token-auth"

The above command returns JSON structured like this:

{
  "status":"successful",
  "token":"<token>"
}

This endpoint is used to process a transaction.

HTTP Request

POST URL_GOES_HERE/token-auth

Request Body Parameters
Parameter Default Description
username username to authenticate with
password password to authenticate with

Request forgotten username

curl -v -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email" : "user@domain.com"
  }' \
  "URL_GOES_HERE/forgot-username"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"Request processed successfully",
  "data":null
}

This endpoint is will send an email containing all usernames associated with the provided email address

HTTP Request

POST URL_GOES_HERE/forgot-username

Request Body Parameters
Parameter Default Description
email email address to lookup accounts for

Request forgotten password

curl -v -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username" : "<username>"
  }' \
  "URL_GOES_HERE/forgot-password"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"Request processed successfully",
  "data":null
}

This endpoint is will send an email containing a password reset token

HTTP Request

POST URL_GOES_HERE/forgot-password

Request Body Parameters

Parameter Default Description
username username to reset password for

Password reset

curl -v -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username" : "<username>",
    "reset_code": "<reset_code>",
    "password": "<new password>"
  }' \
  "URL_GOES_HERE/forgot-password/reset"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"Request processed successfully",
  "data":null
}

This endpoint is will reset a users password

HTTP Request

POST URL_GOES_HERE/forgot-password/reset

Request Body Parameters

Parameter Default Description
username username to reset password for
reset_code reset obtained from password reset email
password new password to be set

Token Logout

curl -v \
-H "Authorization: Bearer <JWT>" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/logout"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"Request processed successfully",
  "data":null
}

This endpoint is will terminate a valid authenication token.

HTTP Request

GET URL_GOES_HERE/logout

Request Body Parameters

None

Users

Change Password

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
  "username": "<username>",
  "current_password": "<current password>",
  "new_password": "<new password>"
}'\
  "URL_GOES_HERE/user/change-password"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"Request processed successfully",
  "data":null
}

This endpoint is will change an authenicated users password.

HTTP Request

POST URL_GOES_HERE/user/change-password

Request Body Parameters

Parameter Default Description
username username to reset password for
current_password users current password
new_password new password for user

Create

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
  "username": "testmerchant43",
  "name": "test merchant user",
  "phone": "6305555555",
  "email": "info@website.com",
  "timezone": "ETC/UTC",
  "password": "T@est12345678",
  "status": "active",
  "role": "admin"
}'\
  "URL_GOES_HERE/user"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":{
    "id":"b89227ij8m0nuanr1tk0",
    "username":"testmerchant43",
    "name":"test merchant user",
    "phone":"6305555555",
    "email":"info@website.com",
    "timezone":"ETC/UTC",
    "status":"active",
    "role":"admin",
    "account_type":"merchant",
    "account_type_id":"aucio551tlv85l7moe5g",
    "created_at":"2017-11-20T00:26:06.190264Z",
    "updated_at":"2017-11-20T00:26:06.190264Z"
    }
  }

This endpoint is will create a new user

HTTP Request

POST URL_GOES_HERE/user

Request Body Parameters

Parameter Default Description
username username to reset password for
name users first and last name
phone users phone number, digits only
email users email address
timezone users timezone
password users password
status users status (active or disabled)
role users defined role (admin or standard)

Update

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "test merchant user",
  "phone": "6305555555",
  "email": "info@website.com",
  "timezone": "ETC/UTC",
  "status": "active",
  "role": "admin"
}'\
  "URL_GOES_HERE/user/b89227ij8m0nuanr1tk0"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":{
    "id":"b89227ij8m0nuanr1tk0",
    "username":"testmerchant43",
    "name":"test merchant user",
    "phone":"6305555555",
    "email":"info@website.com",
    "timezone":"ETC/UTC",
    "status":"active",
    "role":"admin",
    "account_type":"merchant",
    "account_type_id":"aucio551tlv85l7moe5g",
    "created_at":"2017-11-20T00:26:06.190264Z",
    "updated_at":"2017-11-20T00:26:06.190264Z"
    }
  }

This endpoint is will update an exisiting user

HTTP Request

POST URL_GOES_HERE/user/<user_id>

Query Parameters

Parameter Description
user_id User ID string

Request Body Parameters

Parameter Default Description
name users first and last name
phone users phone number, digits only
email users email address
timezone users timezone
status users status (active or disabled)
role users defined role (admin or standard)

Get Specific User

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/user/b89227ij8m0nuanr1tk0"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":{
    "id":"b89227ij8m0nuanr1tk0",
    "username":"testmerchant43",
    "name":"test merchant user",
    "phone":"6305555555",
    "email":"info@website.com",
    "timezone":"ETC/UTC",
    "status":"active",
    "role":"admin",
    "account_type":"merchant",
    "account_type_id":"aucio551tlv85l7moe5g",
    "created_at":"2017-11-20T00:26:06.190264Z",
    "updated_at":"2017-11-20T00:26:06.190264Z"
    }
  }

This endpoint is will get a specific user

HTTP Request

GET URL_GOES_HERE/user/<user_id>

Query Parameters

Parameter Description
user_id User ID string

Get Current User

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/user"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":{
    "id":"b89227ij8m0nuanr1tk0",
    "username":"testmerchant43",
    "name":"test merchant user",
    "phone":"6305555555",
    "email":"info@website.com",
    "timezone":"ETC/UTC",
    "status":"active",
    "role":"admin",
    "account_type":"merchant",
    "account_type_id":"aucio551tlv85l7moe5g",
    "created_at":"2017-11-20T00:26:06.190264Z",
    "updated_at":"2017-11-20T00:26:06.190264Z"
    }
  }

This endpoint is will get a user that is currently authenticated. This is just a helper function, you should prefer getting a specific user, by specifying a valid user_id

HTTP Request

GET URL_GOES_HERE/user

Get all users

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/users"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "total_count":3,
  "data":[
      ...
      {
        "id":"b89227ij8m0nuanr1tk0",
        "username":"testmerchant43",
        "name":"test merchant user",
        "phone":"6305555555",
        "email":"info@website.com",
        "timezone":"ETC/UTC",
        "status":"active",
        "role":"admin",
        "account_type":"merchant",
        "account_type_id":"aucio551tlv85l7moe5g",
        "created_at":"2017-11-20T00:26:06.190264Z",
        "updated_at":"2017-11-20T00:26:06.190264Z"
        }
      ]
    }

This endpoint is will get all users

HTTP Request

GET URL_GOES_HERE/users

Delete user

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-X DELETE \
  "URL_GOES_HERE/user/b89227ij8m0nuanr1tk0"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"successfully deleted",
  "data":null
}

This endpoint is will delete a specific user.

HTTP Request

DELETE URL_GOES_HERE/user/<user_id>

Query Parameters

Parameter Description
user_id User ID string

API Keys

Create

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
  "name": "friendlyname",
  "type": "api"
}' "URL_GOES_HERE/user/apikey"

Post Body Parameters

Parameter Description
name Friendly name displayed for the apikey
type "api" or "pub"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":{
    "id":"b892b1ij8m0nuanr1tkg",
    "api_key":"0wbK7QkCWri562dJz63LfWigq6v",
    "name": "friendlyname",
    "account_type":"merchant",
    "account_type_id":"aucio551tlv85l7moe60",
    "created_at":"2017-11-20T00:44:54.770907Z",
    "updated_at":"2017-11-20T00:44:54.770907Z"
    }
  }

This endpoint is will create a new API KEY for a specific user.

HTTP Request

POST URL_GOES_HERE/user/apikey

Get

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/user/apikeys"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "total_count":2,
  "data":[
    ...
    {
      "id":"b892b1ij8m0nuanr1tkg",
      "api_key":"0wbK7QkCWri562dJz63LfWigq6v",
      "name": "keyname",
      "account_type":"merchant",
      "account_type_id":"aucio551tlv85l7moe60",
      "created_at":"2017-11-20T00:44:55Z",
      "updated_at":"2017-11-20T00:44:55Z"
      }
    ]
  }

This endpoint will list apikeys for a specific user.

HTTP Request

GET URL_GOES_HERE/user/apikeys

Delete

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-X DELETE \
  "URL_GOES_HERE/user/apikey/0wbK7QkCWri562dJz63LfWigq6v"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"successfully deleted api key",
  "data":null
}

This endpoint will delete the apikey specified.

HTTP Request

DELETE URL_GOES_HERE/user/apikey/<api_key>

Query Parameters

Parameter Description
api_key API Key

Transaction Processing

Processing a Transaction

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "amount": 1112,
    "tax_amount": 100,
    "shipping_amount": 100,
    "currency": "USD",
    "description": "test transaction",
    "order_id": "someOrderID",
    "po_number": "somePONumber",
    "ip_address": "4.2.2.2",
    "email_receipt": false,
    "email_address": "user@home.com",
    "create_vault_record": true,
    "payment_method": {
        "card": {
          "entry_type": "keyed",
          "number": "4012000098765439",
          "expiration_date": "12/20",
          "cvc": "999",
          "cardholder_authentication": {
            "condition": "...",
            "eci": "...",
            "cavv": "...",
            "xid": "...",
          }
        }
        ... or ...
        "customer": {
            "id": "b798ls2q9qq646ksu070",
            "payment_method_type": "card",
            "payment_method_id": "b798ls2q9qq646ksu080",
            "billing_address_id": "b798ls2q9qq646ksu07g",
            "shipping_address_id": "b798ls2q9qq646ksu07g"
        }
        ... or ...
        "terminal": {
            "id": "<terminal id>"
            "expiration_date": "12/20",
            "cvc": "999",
            "print_receipt": "both"
            "signature_required": true
        }
        ... or ...
        "token": "<tokenizer token goes here>",
        ... or ...
        "ach": {
            "routing_number": "490000018",
            "account_number": "999999", 
            "sec_code": "ccd",
            "account_type": "checking",
            "check_number":"1223",
            "accountholder_authentication": {
                "dl_state": "IL",
                "dl_number": "r500123123"
            }
        }
    },
    "billing_address" : {
        "first_name": "John",
        "last_name": "Smith",
        "company": "Test Company",
        "address_line_1": "123 Some St",
        "city": "Wheaton",
        "state": "IL",
        "postal_code": "60187",
        "country": "US",
        "phone": "5555555555",
        "fax": "5555555555",
        "email": "help@website.com"
    },
    "shipping_address" : {
        "first_name": "John",
        "last_name": "Smith",
        "company": "Test Company",
        "address_line_1": "123 Some St",
        "city": "Wheaton",
        "state": "IL",
        "postal_code": "60187",
        "country": "US",
        "phone": "5555555555",
        "fax": "5555555555",
        "email": "help@website.com"
    }
}'   \
"URL_GOES_HERE/transaction"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": {
		"id": "b7kgflt1tlv51er0fts0",
		"type": "sale",
		"amount": 1112,
		"tax_amount": 100,
		"tax_exempt": false,
		"shipping_amount": 100,
    "discount_amount": 0,
    "payment_adjustment_type": "",
    "payment_adjustment_value": 0,
		"currency": "usd",
		"description": "test transaction",
		"order_id": "someOrderID",
		"po_number": "somePONumber",
		"ip_address": "4.2.2.2",
		"email_receipt": false,
		"email_address": "user@home.com",
		"payment_method": "card",
		"response" : {
			"card": {
				"id": "b7kgflt1tlv51er0ftsg",
				"card_type": "visa",
				"first_six": "401200",
				"last_four": "5439",
				"masked_card": "401200******5439",
				"expiration_date": "12/20",
				"status": "approved",
				"auth_code": "TAS731",
				"processor_response_code": "00",
				"processor_response_text": "APPROVAL TAS731 ",
				"processor_type": "tsys_sierra",
				"processor_id": "b7kgflt1tlv51er0f1sg",
				"avs_response_code": "0",
				"cvv_response_code": "M",
				"processor_specific": {},
				"created_at": "2017-10-19T20:15:19.80368Z",
				"updated_at": "2017-10-19T20:15:20.777011Z"
			},
		},
		"status": "pending_settlement",
    "response_code": 100,
    "customer_id": "aaaaaaaaaaaaaaaaaaaa",
		"billing_address": {
			"first_name": "John",
			"last_name": "Smith",
			"company": "Test Company",
			"address_line_1": "123 Some St",
			"address_line_2": "",
			"city": "Wheaton",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"phone": "5555555555",
			"fax": "5555555555",
			"email": "help@website.com"
		},
		"shipping_address": {
			"first_name": "John",
			"last_name": "Smith",
			"company": "Test Company",
			"address_line_1": "123 Some St",
			"address_line_2": "",
			"city": "Wheaton",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"phone": "5555555555",
			"fax": "5555555555",
			"email": "help@website.com"
		},
		"created_at": "2017-10-19T20:15:19.560708Z",
		"updated_at": "2017-10-19T20:15:20.832049Z"
	}
}

Sample terminal response:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b9efr9qj8m0ge2h7tat0",
    "user_id": "aucio551tlv85l7moe60",
    "idempotency_key": "",
    "idempotency_time": 0,
    "type": "sale",
    "amount": 500,
    "amount_authorized": 500,
    "amount_captured": 500,
    "amount_settled": 0,
    "processor_id": "",
    "processor_type": "",
    "payment_method": "terminal",
    "payment_type": "",
    "tax_amount": 100,
    "tax_exempt": false,
    "shipping_amount": 100,
    "discount_amount": 0,
    "payment_adjustment_type": "",
    "payment_adjustment_value": 0,
    "currency": "usd",
    "description": "test transaction",
    "order_id": "someOrderID",
    "po_number": "somePONumber",
    "ip_address": "4.2.2.2",
    "transaction_source": "api",
    "email_receipt": false,
    "customer_id": "",
    "referenced_transaction_id": "",
    "response_body": {
      "terminal": {
        "id": "b9efr9qj8m0ge2h7tatg",
        "card_type": "mastercard",
        "payment_type": "credit",
        "entry_type": "swiped",
        "first_four": "5424",
        "last_four": "3333",
        "masked_card": "5424********3333",
        "cardholder_name": "FDCS TEST CARD /MASTERCARD",
        "auth_code": "",
        "response_code": 100,
        "processor_response_text": "APPROVAL VTLMC1",
        "processor_specific": {
          "BatchNum": "8",
          "CashBack": "0.00",
          "ClerkID": "",
          "DISC": "0.00",
          "EBTCashAvailBalance": "",
          "EBTCashBeginBalance": "",
          "EBTCashLedgerBalance": "",
          "EBTFSAvailBalance": "",
          "EBTFSBeginBalance": "",
          "EBTFSLedgerBalance": "",
          "Fee": "0.00",
          "InvNum": "someOrderID",
          "Language": "English",
          "ProcessData": "",
          "RefNo": "",
          "RewardCode": "",
          "RewardQR": "",
          "RwdBalance": "0",
          "RwdIssued": "",
          "RwdPoints": "0",
          "SHFee": "0.00",
          "SVC": "0.00",
          "TableNum": "0",
          "TicketNum": "",
          "Tip": "0.00",
          "TotalAmt": "5.00"
        },
        "emv_aid": "",
        "emv_app_name": "",
        "emv_tvr": "",
        "emv_tsi": "",
        "signature_data": "Qk0OIQAAAAAAAD4AAAAoAAAALgEAANIAAAABAAEAAAAAANAgAADEDgAAxA4AAAAA//////////////////////////8f//////////////8AAA=",
        "created_at": "2018-01-15T19:14:47.225068Z",
        "updated_at": "2018-01-15T19:15:02.335853Z"
      }
    },
    "status": "pending_settlement",
    "response": "approved",
    "response_code": 100,
    "billing_address": {
      "first_name": "John",
      "last_name": "Smith",
      "company": "Test Company",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Wheaton",
      "state": "IL",
      "postal_code": "60187",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "help@website.com"
    },
    "shipping_address": {
      "first_name": "",
      "last_name": "",
      "company": "",
      "address_line_1": "",
      "address_line_2": "",
      "city": "",
      "state": "",
      "postal_code": "",
      "country": "",
      "phone": "",
      "fax": "",
      "email": ""
    },
    "created_at": "2018-01-15T19:14:47.108371Z",
    "updated_at": "2018-01-15T19:15:02.529558Z",
    "captured_at": "2018-01-15T19:14:47.337763Z",
    "settled_at": null
  }
}

Sample ach response:


  "status": "success",
  "msg": "success",
  "data": {
    "id": "bdkaefboo3su6vmf8gog",
    "user_id": "testmerchant12345678",
    "user_name": "test_merchant",
    "idempotency_key": "",
    "idempotency_time": 0,
    "type": "sale",
    "amount": 10112,
    "amount_authorized": 0,
    "amount_captured": 0,
    "amount_settled": 0,
    "tip_amount": 0,
    "processor_id": "bdcvli3oo3smmc8r4c2g",
    "processor_type": "sage_ach",
    "processor_name": "sage11",
    "payment_method": "ach",
    "payment_type": "ach",
    "tax_amount": 100,
    "tax_exempt": false,
    "shipping_amount": 100,
    "discount_amount": 0,
    "payment_adjustment_type": "",
    "payment_adjustment_value": 0,
    "currency": "usd",
    "description": "test transaction",
    "order_id": "someOrderID",
    "po_number": "somePONumber",
    "ip_address": "4.2.2.2",
    "transaction_source": "api",
    "email_receipt": false,
    "email_address": "user@home.com",
    "customer_id": "",
    "referenced_transaction_id": "",
    "response_body": {
      "ach": {
        "id": "bdkaefboo3su6vmf8gp0",
        "sec_code": "ccd",
        "account_type": "checking",
        "masked_account_number": "99**99",
        "routing_number": "490000018",
        "auth_code": "",
        "response": "declined",
        "response_code": 200,
        "processor_response_code": "D",
        "processor_response_text": "DECLINE CHECK   CHECK LIMIT EXCEEDED",
        "processor_type": "sage_achIntro
        "processor_id": "bdcvli3oo3Intromc8r4c2g",
        "processor_specific": {
          "result_codes": [
            "Decline Message",
            "Transaction Limit ExceIntroed"
          ],
          "type_codes": [
            "Unknown Presentment"
          ]
        },
        "created_at": "2018-08-06T1Intro53:33.271385121Z",
        "updated_at": "2018-08-06T1Intro53:33.642386892Z"
      }
    },
    "status": "declined",
    "response": "declined",
    "response_code": 200,
    "billing_address": {
      "first_name": "John",
      "last_name": "Smith",
      "company": "Test Company",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Wheaton",
      "state": "IL",
      "postal_code": "60187",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "user@home.com"
    },
    "shipping_address": {
      "first_name": "",
      "last_name": "",
      "company": "",
      "address_line_1": "",
      "address_line_2": "",
      "city": "",
      "state": "",
      "postal_code": "",
      "country": "",
      "phone": "",
      "fax": "",
      "email": ""
    },
    "created_at": "2018-08-06T19:53:33.265553086Z",
    "updated_at": "2018-08-06T19:53:33.645937676Z",
    "captured_at": null,
    "settled_at": null
  }
}

This endpoint is used to process a transaction.

HTTP Request

POST URL_GOES_HERE/transaction

Request Body Parameters

Parameter Default Description
type sale, authorize, credit
amount Processed Amount in cents. 1299 = $12.99
tax_exempt false Bool value
tax_amount 0 Tax Amount in cents.
shipping_amount 0 Shipping Amount in cents. (Should be included in Amount)
discount_amount 0 Discount Amount in cents. (Should be included in Amount)
currency ISO 4217 currency. Ex USD
description "" Text field, 0-255 characters
order_id
po_number
processor_id "" Optional field to select with processor to run the transaction on, "" uses your default
ip_address Server IP IPv4 or IPv6 value of the end user
email_receipt false Bool value to trigger sending of an email recept if an email was provided.
create_vault_record false Bool value to trigger the creation of a customer vault record, if the transaction is successful
payment_adjustment Payment adjustment to be tracked for this transaction
payment_adjustment.type "" Valid types are "flat" or "percentage"
payment_adjustment.value 0 Number field, in cents for "flat" or 3 decimal places for "percentage" ie 1000 = 1.000%
payment_method Payment Method container, must only contain one of the following: card, customer, terminal objects
payment_method.card Container for processing Credit Card transactions
payment_method.card.entry_type Must be "keyed" or "swiped"
payment_method.card.number Credit Card number
payment_method.card.expiration_date Expiration date, Format MM/YY
payment_method.card.cvc Card Verification Code
payment_method.customer Container for Tokenized transactions
payment_method.customer.id required Customer ID,
payment_method.customer.payment_method_type Customer default Payment method type referenced in payment_method_id
payment_method.customer.payment_method_id Customer default Payment method id to be charged.
payment_method.customer.billing_address_id Customer default Billing address token to referenced.
payment_method.customer.shipping_address_id Customer default Shipping address token to be referenced.
payment_method.terminal Container for Terminal driven transactions.
payment_method.terminal.id Terminal ID to trigger the request.
payment_method.terminal.expiration_date Optionally pass an expiration date along with the transaction
payment_method.terminal.cvc Optionally pass a CVV along with the transaction
payment_method.terminal.print_receipt No = no reciept, Customer = customer copy, Merchant = merchant copy, Both = both copies
payment_method.terminal.signature_required Requests that the terminal capture a signature, if supported
payment_method.ach Container for processing ACH transactions
payment_method.ach.routing_number
payment_method.ach.account_number ACH account number
payment_method.ach.check_number Check Number *required for TEL transactions
payment_method.ach.sec_code SEC Code - WEB/CCD/PPD/TEL
payment_method.ach.accountholder_authentication Container for accountholder authentication - if required by processor
payment_method.ach.accountholder_authentication.dl_state Drivers License State
payment_method.ach.accountholder_authentication.dl_number Drivers License Number
billing_address null - Required for ACH transactions
billing_address.first_name
billing_address.last_name
billing_address.company
billing_address.address_line_1
billing_address.address_line_2
billing_address.city
billing_address.state
billing_address.postal_code
billing_address.country
billing_address.email
billing_address.phone
billing_address.fax
shipping_address null
shipping_address.first_name
shipping_address.last_name
shipping_address.company
shipping_address.address_line_1
shipping_address.address_line_2
shipping_address.city
shipping_address.state
shipping_address.postal_code
shipping_address.country
shipping_address.email
shipping_address.phone
shipping_address.fax

Response Codes

TIP

Response Codes are grouped as follows: 100 thru 199 are Approvals and Partial Approvals. 200 thru 299 are Declined via the processor. 300 thru 399 are Gateway Declines. 400 thru 499 are processor rejection errors.

Response Code Definition
0 Unknown
100 Approved
110 Partial approval
101 Approved, pending customer approval
200 Decline
201 Do not honor
202 Insufficient funds
203 Excededs withdrawl limit
204 Invalid Transaction
220 Invalid Amount
221 No such Issuer
222 No credit Acct
223 Expired Card
225 Invalid CVC
226 Cannot Verify Pin
240 Refer to issuer
250 Pick up card (no fraud)
251 Lost card, pick up (fraud account)
252 Stolen card, pick up (fraud account)
253 Pick up card, special condition
261 Stop recurring
262 Stop recurring
300 Gateway Decline
310 Gateway Decline - Rule Engine
400 Transaction error returned by processor
410 Invalid merchant configuration
421 Communication error with processor
430 Duplicate transaction at processor
440 Processor Format error

Get Transaction status

curl -v -X GET \
  -H "Authorization: APIKEY" \
  "URL_GOES_HERE/transaction/<transaction_id>"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": [
		{
		"id": "b7kgflt1tlv51er0fts0",
		"type": "sale",
		"amount": 1112,
		"tax_amount": 100,
		"tax_exempt": false,
		"shipping_amount": 100,
		"currency": "usd",
		"description": "test transaction",
		"order_id": "someOrderID",
		"po_number": "somePONumber",
		"ip_address": "4.2.2.2",
		"email_receipt": false,
		"payment_method": "card",
		"response" : {
			"card": {
				"id": "b7kgflt1tlv51er0ftsg",
				"card_type": "visa",
				"first_six": "401200",
				"last_four": "5439",
				"masked_card": "401200******5439",
				"expiration_date": "12/20",
				"status": "approved",
				"auth_code": "TAS731",
				"processor_response_code": "00",
				"processor_response_text": "APPROVAL TAS731 ",
				"processor_type": "tsys_sierra",
				"processor_id": "b7kgflt1tlv51er0f1sg",
				"avs_response_code": "0",
				"cvv_response_code": "M",
				"processor_specific": {},
				"created_at": "2017-10-19T20:15:19.80368Z",
				"updated_at": "2017-10-19T20:15:20.777011Z"
			},
		},
		"status": "pending_settlement",
		"billing_address": {
			"first_name": "John",
			"last_name": "Smith",
			"company": "Test Company",
			"address_line_1": "123 Some St",
			"address_line_2": "",
			"city": "Wheaton",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"phone": "5555555555",
			"fax": "5555555555",
			"email": "help@website.com"
		},
		"shipping_address": {
			"first_name": "John",
			"last_name": "Smith",
			"company": "Test Company",
			"address_line_1": "123 Some St",
			"address_line_2": "",
			"city": "Wheaton",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"phone": "5555555555",
			"fax": "5555555555",
			"email": "help@website.com"
		},
		"created_at": "2017-10-19T20:15:19.560708Z",
		"updated_at": "2017-10-19T20:15:20.832049Z"
	}
],
"total_count": 1
}

This endpoint is used to query a transaction

HTTP Request

GET URL_GOES_HERE/transaction/<transaction_id>

Query Parameters

Parameter Description
transaction_id Transaction ID to reference

Query Transactions

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{

    "transaction_id": {
      "operator": "=",
      "value": "b84vgb2j8m0jujadi4v0"
    },
    "amount": {
      "operator": "=",
      "value": 1112
    },
    "created_at": {
      "start_date": "2017-11-01T00:00:00Z",
      "end_date": "2017-11-30T00:00:00Z"
    },
    "billing_address": {
      "first_name": {
        "operator": "=",
        "value": "John"
      }
    }
}'   \
"URL_GOES_HERE/transaction/search"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "",
  "total_count": 1,
  "data": [
    {
      "id": "b84vgb2j8m0jujadi4v0",
      "user_id": "aucio551tlv85l7moe60",
      "idempotency_key": "",
      "idempotency_time": 0,
      "type": "sale",
      "amount": 1112,
      "amount_authorized": 1112,
      "amount_captured": 1112,
      "amount_settled": 0,
      "processor_id": "aucio551tlv85l7moe7g",
      "processor_type": "tsys_sierra",
      "payment_method": "token",
      "payment_type": "card",
      "tax_amount": 100,
      "tax_exempt": false,
      "shipping_amount": 100,
      "currency": "usd",
      "description": "test transaction",
      "order_id": "someOrderID",
      "po_number": "somePONumber",
      "ip_address": "?01",
      "transaction_source": "api",
      "email_receipt": false,
      "customer_id": "b81ko5qq9qq5v460r9i0",
      "referenced_transaction_id": "",
      "response_body": {},
      "status": "pending_settlement",
      "response": "approved",
      "response_code": 100,
      "billing_address": {
        "first_name": "John",
        "last_name": "Smith",
        "company": "Some Company",
        "address_line_1": "123 Some St",
        "address_line_2": "STE 203",
        "city": "SomeTown",
        "state": "IL",
        "postal_code": "55555",
        "country": "US",
        "phone": "5555555555",
        "fax": "",
        "email": "info@website.com"
      },
      "shipping_address": {
        "first_name": "John",
        "last_name": "Smith",
        "company": "Some Company",
        "address_line_1": "123 Some St",
        "address_line_2": "STE 203",
        "city": "SomeTown",
        "state": "IL",
        "postal_code": "55555",
        "country": "US",
        "phone": "5555555555",
        "fax": "",
        "email": "info@website.com"
      },
      "created_at": "2017-11-13T19:53:17Z",
      "updated_at": "2017-11-13T19:53:18Z",
      "captured_at": null,
      "settled_at": null
    }
  ]
}

This endpoint is used to query transactions. All of the request body fields are optional, and any that are provided are used to drill down on specific transactions. See sample for structure of each query type.

HTTP Request

POST URL_GOES_HERE/transaction/search

Request Body Parameters

Parameter Required Type Description
transaction_id optional QuerySearchString Searches for transaction id
user_id optional QuerySearchString Searches for user_id
type optional QuerySearchString Searches for transaction type (sale, authorize...etc)
ip_address optional QuerySearchString Searches for ip_address, either ipv4 or ipv6
amount optional QuerySearchInt Searches for originally requested amount
amount_authorized optional QuerySearchInt Searches for amount_authorized
amount_captured optional QuerySearchInt Searches for amount_captured
amount_settled optional QuerySearchInt Searches for amount_settled
tax_amount optional QuerySearchInt Searches for tax_amount
po_number optional QuerySearchString Searches for po_number
order_id optional QuerySearchString Searches for order_id
payment_method optional QuerySearchString Searches by payment_method, (token, card, terminal)
payment_type optional QuerySearchString Searches by payment_type (card, echeck)
status optional QuerySearchString Searches by transaction status (unknown, declined, authorized, pending_settlement, settled, voided, reversed, refunded)
processor_id optional QuerySearchString Searches by processor_id
customer_id optional QuerySearchString Searches by customer_id
created_at optional QueryDateRange Searches by created_at between the provided start_date and end_date. Dates in UTC "YYYY-MM-DDTHH:II:SSZ"
captured_at optional QueryDateRange Searches by captured_at between the provided start_date and end_date. Dates in UTC "YYYY-MM-DDTHH:II:SSZ"
settled_at optional QueryDateRange Searches by settled_at between the provided start_date and end_date. Dates in UTC "YYYY-MM-DDTHH:II:SSZ"
billing_address.address_id optional QuerySearchString Searches by billing_address.id
billing_address.first_name optional QuerySearchString Searches by billing_address.first_name (0-50 characters)
billing_address.last_name optional QuerySearchString Searches by billing_address.last_name (0-50 characters)
billing_address.company optional QuerySearchString Searches by billing_address.company (0-50 characters)
billing_address.address_line_1 optional QuerySearchString Searches by billing_address.address_line_1 (0-100 characters)
billing_address.address_line_2 optional QuerySearchString Searches by billing_address.address_line_2 (0-100 characters)
billing_address.city optional QuerySearchString Searches by billing_address.city (0-50 characters)
billing_address.state optional QuerySearchString Searches by billing_address.state (2 Character)
billing_address.postal_code optional QuerySearchString Searches by billing_address.postal_code (0-6 Characters)
billing_address.country optional QuerySearchString Searches by billing_address.country (2 Characters)
billing_address.email optional QuerySearchString Searches by billing_address.email
billing_address.phone optional QuerySearchString Searches by billing_address.phone (0-14 digits only)
billing_address.fax optional QuerySearchString Searches by billing_address.fax (0-14 digits only)
shipping_address.address_id optional QuerySearchString Searches by shipping_address.id
shipping_address.first_name optional QuerySearchString Searches by shipping_address.first_name (0-50 characters)
shipping_address.last_name optional QuerySearchString Searches by shipping_address.last_name (0-50 characters)
shipping_address.company optional QuerySearchString Searches by shipping_address.company (0-50 characters)
shipping_address.address_line_1 optional QuerySearchString Searches by shipping_address.address_line_1 (0-100 characters)
shipping_address.address_line_2 optional QuerySearchString Searches by shipping_address.address_line_2 (0-100 characters)
shipping_address.city optional QuerySearchString Searches by shipping_address.city (0-50 characters)
shipping_address.state optional QuerySearchString Searches by shipping_address.state (2 Character)
shipping_address.postal_code optional QuerySearchString Searches by shipping_address.postal_code (0-6 Characters)
shipping_address.country optional QuerySearchString Searches by shipping_address.country (2 Characters)
shipping_address.email optional QuerySearchString Searches by shipping_address.email
shipping_address.phone optional QuerySearchString Searches by shipping_address.phone (0-14 digits only)
shipping_address.fax optional QuerySearchString Searches by shipping_address.fax (0-14 digits only)
limit optional int Maximum records to return (0-100)
offset optional int Number of records to offset the return by

Request Body Type values

Type Operators
QuerySearchString =, !=
QuerySearchInt =, !=, <, >

Capture

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
  "amount": 1000,
  "tax_amount": 100,
  "tax_exempt": false,
  "shipping_amount": 0
}'
  "URL_GOES_HERE/transaction/b892b1ij8m0nuanr1tkg/capture"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":null
}

This endpoint will capture funds from a transaction that has been authorized. This action can only be performed on authorized transactions.

HTTP Request

POST URL_GOES_HERE/transaction/<transaction_id>/capture

Query Parameters

Parameter Description
transaction_id Transaction ID to Capture

Request Body Parameters

Parameter Default Description
amount authorized amount Amount in cents. 1299 = $12.99
tax_amount amount from auth Amount in cents. 1299 = $12.99
tax_exempt false Bool value
tax_amount tax_amount from auth Tax Amount in cents.
shipping_amount shipping_amount from auth Shipping Amount in cents.
order_id order_id from auth AlphaNumeric 0-17 characters
po_number po_number from auth AlphaNumeric 0-17 characters
ip_address ip_address from auth ipv4 or ipv6 address

Void

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/transaction/b892b1ij8m0nuanr1tkg/void"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":null
}

This endpoint will void a transaction that is pending_settlement.

HTTP Request

POST URL_GOES_HERE/transaction/<transaction_id>/void

Query Parameters

Parameter Description
transaction_id Transaction ID to VOID

Request Body Parameters

None

Refund

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
  "amount": 1000
}' \
  "URL_GOES_HERE/transaction/b892b1ij8m0nuanr1tkg/refund"

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":null
}

This endpoint will process a refund up the previously settled amount. This action can only be performed on transactions that have been settled.

HTTP Request

POST URL_GOES_HERE/transaction/<transaction_id>/refund

Query Parameters

Parameter Description
transaction_id Transaction ID to Capture

Request Body Parameters

Parameter Default Description
amount amount settled Amount in cents. 1299 = $12.99

Settlement Batches

Query Settlements

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_date":{
      "start_date":"2018-12-01T00:00:00Z",
      "end_date":"2018-12-26T23:59:59Z"
    },
    "offset":0,
    "limit":10
  }' \
  "URL_GOES_HERE/settlement/batch/search"  

The above command returns JSON structured like this:

{
  "status":"success",
  "msg":"success",
  "data":{
    "summary":[
      {
        "merchant_id":"aaaaaaaaaaaaaaaaaaaa",
        "batch_date":"2018-12-04",
        "processor_id":"bbbbbbbbbbbbbbbbbbbb",
        "processor_name":"main mid",
        "num_transactions":1,
        "captured":10000,
        "credit":0
      }
    ],
    "results":[
      {
        "id":"cccccccccccccccccccc",
        "merchant_id":"aaaaaaaaaaaaaaaaaaaa",
        "batch_date":"2018-12-04T13:31:02Z",
        "processor_id":"bbbbbbbbbbbbbbbbbbbb",
        "processor_name":"main mid",
        "processor_type":"tsys_sierra",
        "batch_number":1,
        "num_transactions":1,
        "amount_captured":10000,
        "amount_credit":0,
        "net_deposit":10000,
        "response_code":100,
        "response_message":" ACCEPT"
      }
    ]
  },
  "total_count":1
}

This endpoint returns settlement batches

HTTP Request

POST URL_GOES_HERE/settlement/batch/search

Request Body Parameters

Parameter Default Description
batch_date "" container for a batch date range
batch_date.start_date "" start date in UTC
batch_date.end_date "" end date in UTC
settlement_batch_id
settlement_batch_id.operator equals '='
settlement_batch_id.value a settlement batch id to search for
limit 10 1-100
offset 0 1-1000

Customers (Tokenization)

Create a new Customer

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "test description",
      "payment_method": {
          "card": {
              "card_number": "4111111111111111",
              "expiration_date": "12/20"
          }
      },
      "billing_address": {
          "first_name": "John",
          "last_name": "Smith",
          "company": "Some Business",
          "address_line_1": "123 Some St",
          "address_line_2": "STE 1",
          "city": "Some Town",
          "state": "IL",
          "postal_code": "60187",
          "country": "US",
          "email": "user@somesite.com",
          "phone": "5555555555",
          "fax": "555555555"
      },
      "shipping_address": {
        "first_name": "John",
        "last_name": "Smith",
        "company": "Some Business",
        "address_line_1": "123 Some St",
        "address_line_2": "STE 1",
        "city": "Some Town",
        "state": "IL",
        "postal_code": "60187",
        "country": "US",
        "email": "user@somesite.com",
        "phone": "5555555555",
        "fax": "555555555"
      }
  }' \
  "URL_GOES_HERE/customer"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": {
		"id": "b798ls2q9qq646ksu070",
		"description": "test description",
		"payment_method": {
			"card": {
				"id": "b798ls2q9qq646ksu080",
				"card_type": "visa",
				"first_six": "411111",
				"last_four": "1111",
				"masked_card": "411111******1111",
				"expiration_date": "12/20",
				"created_at": "2017-10-02T18:52:32Z",
				"updated_at": "2017-10-02T18:52:32Z"
			}
		},
		"billing_address": {
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		"shipping_address": {
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		"created_at": "2017-10-02T18:52:32Z",
		"updated_at": "2017-10-02T18:52:32Z"
	}
}

This endpoint creates a new customer token.

HTTP Request

POST URL_GOES_HERE/customer

Request Body Parameters

Parameter Default Description
description ""
payment_method null
payment_method.card.card_number
payment_method.card.expiration_date Format MMYY
billing_address null
billing_address.first_name
billing_address.last_name
billing_address.company
billing_address.address_line_1
billing_address.address_line_2
billing_address.city
billing_address.state
billing_address.postal_code
billing_address.country
billing_address.email
billing_address.phone
billing_address.fax
shipping_address null
shipping_address.first_name
shipping_address.last_name
shipping_address.company
shipping_address.address_line_1
shipping_address.address_line_2
shipping_address.city
shipping_address.state
shipping_address.postal_code
shipping_address.country
shipping_address.email
shipping_address.phone
shipping_address.fax

Get a specific Customer

curl -v -X GET \
-H "Authorization: APIKEY" \
"URL_GOES_HERE/customer/b798ls2q9qq646ksu070"

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": {
		"id": "b798ls2q9qq646ksu070",
		"description": "test description",
		"payment_method": {
			"card": {
				"id": "b798ls2q9qq646ksu080",
				"card_type": "visa",
				"first_six": "411111",
				"last_four": "1111",
				"masked_card": "411111******1111",
				"expiration_date": "12/20",
				"created_at": "2017-10-02T18:52:32Z",
				"updated_at": "2017-10-02T18:52:32Z"
			}
		},
		"billing_address": {
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		"shipping_address": {
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		"created_at": "2017-10-02T18:52:32Z",
		"updated_at": "2017-10-02T18:52:32Z"
	}
}

This endpoint retrieves a specific customer.

HTTP Request

GET URL_GOES_HERE/customer/<ID>

Query Parameters

Parameter Description
ID The ID of the customer to retrieve

Query Customers

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "id": {
        "operator": "=",
        "value": "id goes here"
      },
      "limit": 10,
      "offset": 0
  }' \
  "URL_GOES_HERE/customer/search"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": [{
		"id": "b798ls2q9qq646ksu070",
		"description": "test description",
		"payment_method": {
			"card": {
				"id": "b798ls2q9qq646ksu080",
				"card_type": "visa",
				"first_six": "411111",
				"last_four": "1111",
				"masked_card": "411111******1111",
				"expiration_date": "12/20",
				"created_at": "2017-10-02T18:52:32Z",
				"updated_at": "2017-10-02T18:52:32Z"
			}
		},
		"billing_address": {
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		"shipping_address": {
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		"created_at": "2017-10-02T18:52:32Z",
		"updated_at": "2017-10-02T18:52:32Z"
	}],
  "total_count": 1,
}

This endpoint retrieves a specific customer.

HTTP Request

POST URL_GOES_HERE/customer/search

Request Body Parameters

Parameter Default Description
limit 10
offset 0
id optional customer id to search for
id.operator required for id search search operator '='
id.value required for id search value to search for
payment_method.id optional search customers with the provided default payment_method_id
payment_method.operator required for payment_method search search operator '='
payment_method.value required for payment_method search value to search for
billing_address_id.id optional search customers with the provided default billing_address_id
billing_address_id.operator required for billing_address_id search search operator '='
billing_address_id.value required for billing_address_id search value to search for
shipping_address_id.id optional search customers with the provided default shipping_address_id
shipping_address_id.operator required for shipping_address_id search search operator '='
shipping_address_id.value required for shipping_address_id search value to search for
created_at optional search for customers in the provided date range
created_at.start_date required for created_at start date in UTC
created_at.end_date required for created_at end date in UTC

Update a Specific Customer

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "test description",
    "payment_method": "credit_card",
    "payment_method_id": "b798ls2q9qq646ksu080",
    "billing_address_id": "b798ls2q9qq646ksu07g",
    "shipping_address_id": "b798ls2q9qq646ksu07g"
  }' \
  "URL_GOES_HERE/customer/<ID>"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": null
}

This endpoint updates a specific customer token.

HTTP Request

POST URL_GOES_HERE/customer/<ID>

Query Parameters

Parameter Description
ID The ID of the customer to delete

Request Body Parameters

Parameter Description
description Description field for customer
payment_method Field used to define the type of payment method referenced in payment_method_id
payment_method_id Id field referencing the payment token
billing_address_id Id field referencing the billing address
shipping_address_id Id field referencing the shipping address

Delete a Specific Customer

curl -v -X DELETE \
  -H "Authorization: APIKEY" \
  "URL_GOES_HERE/customer/<ID>"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": null
}

This endpoint deletes a specific customer token.

HTTP Request

DELETE URL_GOES_HERE/customer/<ID>

Query Parameters

Parameter Description
ID The ID of the customer to delete

Create a new Customer Address Token

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "company": "Some Business",
    "address_line_1": "123 Some St",
    "address_line_2": "STE 1",
    "city": "Some Town",
    "state": "IL",
    "postal_code": "60187",
    "country": "US",
    "email": "user@somesite.com",
    "phone": "5555555555",
    "fax": "555555555"
  }' \
  "URL_GOES_HERE/customer/b798ls2q9qq646ksu070/address"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": {
		"id": "b7994biq9qq646ksu08g",
		"customer_id": "b798ls2q9qq646ksu070",
		"first_name": "John",
		"last_name": "Smith",
		"company": "Some Business",
		"address_line_1": "123 Some St",
		"address_line_2": "STE 1 ",
		"city": "Some Town",
		"state": "IL",
		"postal_code": "60187",
		"country": "US",
		"email": "user@somesite.com",
		"phone": "5555555555",
		"fax": "555555555",
		"created_at": "2017-10-02T19:23:26.902395Z",
		"updated_at": "2017-10-02T19:23:26.902395Z"
	}
}

This endpoint creates a new customer address token.

HTTP Request

POST URL_GOES_HERE/customer/<ID>/address

Query Parameters

Parameter | Description ID | The ID of the customer to create the address for

Request Body Parameters

Parameter Default Description
first_name
last_name
company
address_line_1
address_line_2
city
state
postal_code
country
email
phone
fax

Get all address for a specific Customer

curl -v -X GET \
-H "Authorization: APIKEY" \
"URL_GOES_HERE/customer/<ID>/addresses"

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": [
		{
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		{
			"id": "b7994biq9qq646ksu08g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1 ",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T19:23:27Z",
			"updated_at": "2017-10-02T19:23:27Z"
		}
	],
	"count": 2
}

This endpoint retrieves a specific customers address tokens.

HTTP Request

GET URL_GOES_HERE/customer/<ID>/addresses

Query Parameters

Parameter Description
ID The ID of the customer to retrieve addresses for

Get a specific Customers Address Tokens

curl -v -X GET \
-H "Authorization: APIKEY" \
"URL_GOES_HERE/customer/<ID>/address/<Address ID>"

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": [
		{
			"id": "b798ls2q9qq646ksu07g",
			"customer_id": "b798ls2q9qq646ksu070",
			"first_name": "John",
			"last_name": "Smith",
			"company": "Some Business",
			"address_line_1": "123 Some St",
			"address_line_2": "STE 1",
			"city": "Some Town",
			"state": "IL",
			"postal_code": "60187",
			"country": "US",
			"email": "user@somesite.com",
			"phone": "5555555555",
			"fax": "555555555",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		}
	],
	"count": 1
}

This endpoint retrieves a specific customer address token.

HTTP Request

GET URL_GOES_HERE/customer/<ID>/address/<Address ID>

Query Parameters

Parameter Description
ID The ID of the customer to reference
Address ID The ID of the address to retrieve

Update a Specific Customer Address

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "company": "Some Business",
    "address_line_1": "123 Some St",
    "address_line_2": "",
    "city": "Some Town",
    "state": "IL",
    "postal_code": "60187",
    "country": "US",
    "email": "user@somesite.com",
    "phone": "5555555555",
    "fax": "555555555"
  }' \
  "URL_GOES_HERE/customer/<ID>/address/<Address ID>"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": null
}

This endpoint updates a specific address token.

HTTP Request

POST URL_GOES_HERE/customer/<ID>

Query Parameters

Parameter Description
ID The ID of the customer to reference
Address ID The ID of the address to retrieve

Request Body Parameters

Parameter Description
first_name
last_name
company
address_line_1
address_line_2
city
state
postal_code
country
email
phone
fax

Delete a Specific Customer Address

curl -v -X DELETE \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/customer/<ID>/address/<Address ID>"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": null
}

This endpoint deletes a specific customer address token.

HTTP Request

DELETE URL_GOES_HERE/customer/<ID>/address/<Address ID>

Query Parameters

Parameter Description
ID The ID of the customer to reference
Address ID The ID of the address to retrieve

Create a new Payment Token

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_number": "4111111111111111",
    "expiration_date": "12/20"
  }' \
  "URL_GOES_HERE/customer/b798ls2q9qq646ksu070/paymentmethod/card"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": {
		"card": {
			"id": "b799g1iq9qq6dk5l39i0",
			"card_type": "visa",
			"first_six": "411111",
			"last_four": "1112",
			"masked_card": "411111******1112",
			"expiration_date": "12/20",
			"created_at": "2017-10-02T19:48:22.468483Z",
			"updated_at": "2017-10-02T19:48:22.468483Z"
		}
	}
}

This endpoint creates a new customer payment token.

HTTP Request

POST URL_GOES_HERE/customer/<ID>/paymentmethod/<Type>

Query Parameters

Parameter | Description ID | The ID of the customer to create the payment method for Type | The type of payment method to create. Currently card is all that is supported

Request Body Parameters

Parameter Default Description
card_number Full credit card number
expiration_date Credit card expiration. Format MMYY

Get all payment tokens for a specific Customer

curl -v -X GET \
-H "Authorization: APIKEY" \
"URL_GOES_HERE/customer/<ID>/paymentmethod/card"

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": [
		{
			"id": "b798ls2q9qq646ksu080",
			"card_type": "visa",
			"first_six": "411111",
			"last_four": "1111",
			"masked_card": "411111******1111",
			"expiration_date": "12/20",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		},
		{
			"id": "b799g1iq9qq6dk5l39i0",
			"card_type": "visa",
			"first_six": "411111",
			"last_four": "1112",
			"masked_card": "411111******1112",
			"expiration_date": "12/20",
			"created_at": "2017-10-02T19:48:22Z",
			"updated_at": "2017-10-02T19:48:22Z"
		}
	],
	"count": 2
}

This endpoint retrieves a specific customers payment tokens.

HTTP Request

GET URL_GOES_HERE/customer/<ID>/paymentmethod/card

Query Parameters

Parameter Description
ID The ID of the customer to retrieve payment methods for

Get a specific Customers Payment Tokens

curl -v -X GET \
-H "Authorization: APIKEY" \
"URL_GOES_HERE/customer/<ID>/paymentmethod/card/<Payment ID>"

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": [
		{
			"id": "b798ls2q9qq646ksu080",
			"card_type": "visa",
			"first_six": "411111",
			"last_four": "1111",
			"masked_card": "411111******1111",
			"expiration_date": "12/20",
			"created_at": "2017-10-02T18:52:32Z",
			"updated_at": "2017-10-02T18:52:32Z"
		}
	],
	"count": 1
}

This endpoint retrieves a customers specific payment method.

HTTP Request

GET URL_GOES_HERE/customer/<ID>/paymentmethod/card/<Payment ID>

Query Parameters

Parameter Description
ID The ID of the customer to reference
Payment ID The ID of the payment method to retrieve

Update a Specific Payment Token

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card": {
      "card_number": "4111111111111111",
      "expiration_date": "12/20"
    }
  }' \
  "URL_GOES_HERE/customer/<ID>/paymentmethod/card/<Payment ID>"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": null
}

This endpoint updates a specific payment token.

HTTP Request

POST URL_GOES_HERE/customer/<ID>/paymentmethod/card/<Payment ID>

Query Parameters

Parameter Description
ID The ID of the customer to reference
Payment ID The ID of the payment token to update

Request Body Parameters

Parameter Description
card_number Full credit card number
expiration_date Credit card expiration. Format MMYY

Delete a Specific Customer Payment Token

curl -v -X DELETE \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/customer/<ID>/paymentmethod/card/<Payment ID>"  

The above command returns JSON structured like this:

{
	"status": "success",
	"msg": "success",
	"data": null
}

This endpoint deletes a specific customer payment token.

HTTP Request

DELETE URL_GOES_HERE/customer/<ID>/paymentmethod/card/<Payment ID>

Query Parameters

Parameter Description
ID The ID of the customer to reference
Payment ID The ID of the payment token to delete

Recurring

Create a Add On

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "duration": 0
    }' \
  "URL_GOES_HERE/recurring/addon"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89ffdqj8m0o735i19i0",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:41:43.330315Z",
    "updated_at": "2017-11-20T15:41:43.330315Z"
  }
}

This endpoint creates a new recurring plan add on, add ons are used to adjust a recurring charge amount either by a set amount or a percentage of the subscription amount.

HTTP Request

POST URL_GOES_HERE/recurring/addon

Request Body Parameters

Parameter Type Description
name string Display name for the addition
description string Description for the addition
amount* int Amount to be added
percentage* int Percentage of original charge to be added
duration int Duration for the addition to be billed

Please note you may provide either amount or percentage, but not both.

Get Add On

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/recurring/addon/b89ffdqj8m0o735i19i0"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89ffdqj8m0o735i19i0",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:41:43.330315Z",
    "updated_at": "2017-11-20T15:41:43.330315Z"
  }
}

This endpoint returns a specific add on.

HTTP Request

GET URL_GOES_HERE/recurring/addon/<addon_id>

Query Parameters

Parameter Type Description
addon_id string Add On ID to be returned

Get All Add Ons

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/recurring/addons"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": [
    {
      "id": "b75cvl51tlv38t0o7o30",
      "name": "test_addon",
      "description": "some description",
      "amount": 100,
      "percentage": null,
      "duration": 0,
      "created_at": "2017-09-26T22:08:20Z",
      "updated_at": "2017-09-26T22:08:20Z"
    },
    {
      "id": "b779mpt1tlv96kdv2n20",
      "name": "test_addon_percent",
      "description": "",
      "amount": null,
      "percentage": 10,
      "duration": 0,
      "created_at": "2017-10-09T20:39:41Z",
      "updated_at": "2017-10-09T20:39:41Z"
    },
    {
      "id": "b89ffdqj8m0o735i19i0",
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "percentage": null,
      "duration": 0,
      "created_at": "2017-11-20T15:41:43Z",
      "updated_at": "2017-11-20T15:41:43Z"
    }
  ],
  "total_count": 3
}

This endpoint returns all add ons.

HTTP Request

GET URL_GOES_HERE/recurring/addons

Update an Add On

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "duration": 0
    }' \
  "URL_GOES_HERE/recurring/addon/b89ffdqj8m0o735i19i0"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89ffdqj8m0o735i19i0",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:41:43.330315Z",
    "updated_at": "2017-11-20T15:41:43.330315Z"
  }
}

This endpoint updates a recurring add on.

HTTP Request

POST URL_GOES_HERE/recurring/addon/<addon_id>

Query Parameters

Parameter Type Description
addon_id string Add On ID to be returned

Request Body Parameters

Parameter Type Description
name string Display name for the addition
description string Description for the addition
amount* int Amount to be added
percentage* int Percentage of original charge to be added
duration int Duration for the addition to be billed

Please note you may provide either amount or percentage, but not both.

Delete Add On

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -X DELETE \
  "URL_GOES_HERE/recurring/addon/b89ffdqj8m0o735i19i0"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": null
}

This endpoint deletes a specific addon

HTTP Request

DELETE URL_GOES_HERE/recurring/addon/<addon_id>

Query Parameters

Parameter Type Description
addon_id string Add On ID to be deleted

Create a Discount

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test discount",
    "description": "just a simple test discount",
    "amount": 100,
    "duration": 0
    }' \
  "URL_GOES_HERE/recurring/discount"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89flfqj8m0o735i19ig",
    "name": "test discount",
    "description": "just a simple test discount",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:54:39.851636Z",
    "updated_at": "2017-11-20T15:54:39.851636Z"
  }
}

This endpoint creates a new recurring plan discount, discounts are used to adjust a recurring charge amount either by a set amount or a percentage of the subscription amount.

HTTP Request

POST URL_GOES_HERE/recurring/discount

Request Body Parameters

Parameter Type Description
name string Display name for the addition
description string Description for the addition
amount* int Amount to be discounted
percentage* int Percentage of original charge to be discounted
duration int Duration for the discount to be billed

Please note you may provide either amount or percentage, but not both.

Get Discount

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/recurring/discount/b89flfqj8m0o735i19ig"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89flfqj8m0o735i19ig",
    "name": "test discount",
    "description": "just a simple test discount",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:54:39.851636Z",
    "updated_at": "2017-11-20T15:54:39.851636Z"
  }
}

This endpoint returns a specific discount.

HTTP Request

GET URL_GOES_HERE/recurring/discount/<discount_id>

Query Parameters

Parameter Type Description
discount_id string Discount ID to be returned

Get All Discounts

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/recurring/discounts"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": [
    {
      "id": "b89flfqj8m0o735i19ig",
      "name": "test discount",
      "description": "just a simple test discount",
      "amount": 100,
      "percentage": null,
      "duration": 0,
      "created_at": "2017-11-20T15:54:40Z",
      "updated_at": "2017-11-20T15:54:40Z"
    },
    {
      "id": "b779mpt1tlv96kdv2n20",
      "name": "test_discount_percent",
      "description": "",
      "amount": null,
      "percentage": 10,
      "duration": 0,
      "created_at": "2017-10-09T20:59:52Z",
      "updated_at": "2017-10-09T20:59:52Z"
    }
  ],
  "total_count": 2
}

This endpoint returns all discounts.

HTTP Request

GET URL_GOES_HERE/recurring/discounts

Update a Discount

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test discount",
    "description": "just a simple test discount",
    "amount": 100,
    "duration": 0
    }' \
  "URL_GOES_HERE/recurring/discount/b89flfqj8m0o735i19ig"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89flfqj8m0o735i19ig",
    "name": "test discount",
    "description": "just a simple test discount",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:54:39.851636Z",
    "updated_at": "2017-11-20T15:54:39.851636Z"
  }
}

This endpoint updates a recurring discount.

HTTP Request

POST URL_GOES_HERE/recurring/discount/<discount_id>

Query Parameters

Parameter Type Description
discount_id string Discount ID to be returned

Request Body Parameters

Parameter Type Description
name string Display name for the addition
description string Description for the addition
amount* int Amount to be discounted
percentage* int Percentage of original charge to be discounted
duration int Duration for the discount to be billed

Please note you may provide either amount or percentage, but not both.

Delete Discount

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -X DELETE \
  "URL_GOES_HERE/recurring/discount/b89flfqj8m0o735i19ig"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": null
}

This endpoint deletes a specific discount

HTTP Request

DELETE URL_GOES_HERE/recurring/discount/<discount_id>

Query Parameters

Parameter Type Description
discount_id string Discount ID to be deleted

Create a Plan

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "billing_cycle_interval": 1,
      "billing_frequency": "twice_monthly",
      "billing_days": "1,15",
      "duration": 0,
      "add_ons": [
        {
          "id": "b75cvl51tlv38t0o7o30",
          "description": "this will add to the cost of the subscription",
          "amount": 100,
          "duration": 0
        }
      ],
      "discounts": [
        {
          "id": "b89flfqj8m0o735i19ig",
          "description": "this will discount the cost of the subscription",
          "amount": 50,
          "duration": 0
        }
      ]
  }' \
  "URL_GOES_HERE/recurring/plan"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89g35qj8m0o735i19jg",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "total_add_ons": 100,
    "total_discounts": 50,
    "duration": 0,
    "add_ons": [
      {
        "id": "b75cvl51tlv38t0o7o30",
        "name": "test_addon",
        "description": "this will add to the cost of the subscription",
        "amount": 100,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "name": "test discount",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "created_at": "2017-11-20T16:23:51.990051Z",
    "updated_at": "2017-11-20T16:23:51.990051Z"
  }
}

This endpoint creates a new recurring plan with a discount and an add on.

HTTP Request

POST URL_GOES_HERE/recurring/plan

Request Body Parameters

Parameter Type Description
name string Display name for the addition
description string Description for the addition
amount int Amount to be discounted
billing_cycle_interval int How often to run the billing cycle. Run every x months
billing_frequency string How often run within a billing cycle. (monthly
billing_days string Which day to bill on. If twice_monthly, then comma separate dates
duration int Duration for the addition to be billed
add_ons array Allows for additions to a recurring plan.
add_ons[#].id string ID of the referenced add_on
add_ons[#].name string Display name for the addition (optional, this overrides the add_ons value)
add_ons[#].description string Description for the addition (optional, this overrides the add_ons value)
add_ons[#].amount int Amount to be added (optional, this overrides the add_ons value)
add_ons[#].duration int Duration for the addition to be billed (optional, this overrides the add_ons value)
discounts[#].id string ID of the referenced discount
discounts[#].name string Display name for the discount (optional, this overrides the discount value)
discounts[#].description string Description for the discount (optional, this overrides the discount value)
discounts[#].amount int Amount to be discounted (optional, this overrides the discount value)
discounts[#].duration int Duration for the discount to be billed (optional, this overrides the discount value)

TIP

Below are some common recurring scenerios that can assist.

Bill once every 7 days until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "billing_cycle_interval": 1,
      "billing_frequency": "daily",
      "billing_days": "7",
      "duration": 0,
      "add_ons": [
        {
          "id": "b75cvl51tlv38t0o7o30",
          "description": "this will add to the cost of the subscription",
          "amount": 100,
          "duration": 0
        }
      ],
      "discounts": [
        {
          "id": "b89flfqj8m0o735i19ig",
          "description": "this will discount the cost of the subscription",
          "amount": 50,
          "duration": 0
        }
      ]
  }' \
  "URL_GOES_HERE/recurring/plan"  

Bill once other week until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "billing_cycle_interval": 2,
      "billing_frequency": "daily",
      "billing_days": "7",
      "duration": 0,
      "add_ons": [
        {
          "id": "b75cvl51tlv38t0o7o30",
          "description": "this will add to the cost of the subscription",
          "amount": 100,
          "duration": 0
        }
      ],
      "discounts": [
        {
          "id": "b89flfqj8m0o735i19ig",
          "description": "this will discount the cost of the subscription",
          "amount": 50,
          "duration": 0
        }
      ]
  }' \
  "URL_GOES_HERE/recurring/plan"  

Bill once every 3 months on the 15th until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "billing_cycle_interval": 3,
      "billing_frequency": "monthly",
      "billing_days": "15",
      "duration": 0,
      "add_ons": [
        {
          "id": "b75cvl51tlv38t0o7o30",
          "description": "this will add to the cost of the subscription",
          "amount": 100,
          "duration": 0
        }
      ],
      "discounts": [
        {
          "id": "b89flfqj8m0o735i19ig",
          "description": "this will discount the cost of the subscription",
          "amount": 50,
          "duration": 0
        }
      ]
  }' \
  "URL_GOES_HERE/recurring/plan"  

Bill once month on the 1st and the 15th until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "billing_cycle_interval": 1,
      "billing_frequency": "twice_monthly",
      "billing_days": "1,15",
      "duration": 0,
      "add_ons": [
        {
          "id": "b75cvl51tlv38t0o7o30",
          "description": "this will add to the cost of the subscription",
          "amount": 100,
          "duration": 0
        }
      ],
      "discounts": [
        {
          "id": "b89flfqj8m0o735i19ig",
          "description": "this will discount the cost of the subscription",
          "amount": 50,
          "duration": 0
        }
      ]
  }' \
  "URL_GOES_HERE/recurring/plan"  

Update a Plan

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "billing_cycle_interval": 1,
      "billing_frequency": "twice_monthly",
      "billing_days": "1,15",
      "duration": 0,
      "add_ons": [
        {
          "id": "b75cvl51tlv38t0o7o30",
          "description": "this will add to the cost of the subscription",
          "amount": 100,
          "duration": 0
        }
      ],
      "discounts": [
        {
          "id": "b89flfqj8m0o735i19ig",
          "description": "this will discount the cost of the subscription",
          "amount": 50,
          "duration": 0
        }
      ]
  }' \
  "URL_GOES_HERE/recurring/plan/b89g35qj8m0o735i19jg"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89g35qj8m0o735i19jg",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "total_add_ons": 100,
    "total_discounts": 50,
    "duration": 0,
    "add_ons": [
      {
        "id": "b75cvl51tlv38t0o7o30",
        "name": "test_addon",
        "description": "this will add to the cost of the subscription",
        "amount": 100,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "name": "test discount",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "created_at": "2017-11-20T16:23:51.990051Z",
    "updated_at": "2017-11-20T16:23:51.990051Z"
  }
}

This endpoint updates a recurring plan.

HTTP Request

POST URL_GOES_HERE/recurring/plan/<plan_id>

Query Parameters

Parameter Description
plan_id Plan ID to update

Request Body Parameters

Parameter Type Description
name string Display name for the addition
description string Description for the addition
amount int Amount to be discounted
billing_cycle_interval int How often to run the billing cycle. Run every x months
billing_frequency string How often run within a billing cycle. (monthly
billing_days string Which day to bill on. If twice_monthly, then comma separate dates
duration int Duration for the addition to be billed
add_ons array Allows for additions to a recurring plan.
add_ons[#].id string ID of the referenced add_on
add_ons[#].name string Display name for the addition (optional, this overrides the add_ons value)
add_ons[#].description string Description for the addition (optional, this overrides the add_ons value)
add_ons[#].amount int Amount to be added (optional, this overrides the add_ons value)
add_ons[#].duration int Duration for the addition to be billed (optional, this overrides the add_ons value)
discounts[#].id string ID of the referenced discount
discounts[#].name string Display name for the discount (optional, this overrides the discount value)
discounts[#].description string Description for the discount (optional, this overrides the discount value)
discounts[#].amount int Amount to be discounted (optional, this overrides the discount value)
discounts[#].duration int Duration for the discount to be billed (optional, this overrides the discount value)

Get a Plan

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/recurring/plan/b89g35qj8m0o735i19jg"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89g35qj8m0o735i19jg",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "total_add_ons": 100,
    "total_discounts": 50,
    "duration": 0,
    "add_ons": [
      {
        "id": "b75cvl51tlv38t0o7o30",
        "name": "test_addon",
        "description": "this will add to the cost of the subscription",
        "amount": 100,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "name": "test discount",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "created_at": "2017-11-20T16:23:51.990051Z",
    "updated_at": "2017-11-20T16:23:51.990051Z"
  }
}

This endpoint returns a specific plan.

HTTP Request

GET URL_GOES_HERE/recurring/plan/<plan_id>

Query Parameters

Parameter Type Description
plan_id string Plan ID to be returned

Get All Plans

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/recurring/plans"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": [
  {
    "id": "b89g35qj8m0o735i19jg",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "total_add_ons": 100,
    "total_discounts": 50,
    "duration": 0,
    "add_ons": [
      {
        "id": "b75cvl51tlv38t0o7o30",
        "name": "test_addon",
        "description": "this will add to the cost of the subscription",
        "amount": 100,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "name": "test discount",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "created_at": "2017-11-20T16:23:52Z",
    "updated_at": "2017-11-20T16:23:52Z"
  }
  ],
  "total_count": 1
}

This endpoint returns all plans.

HTTP Request

GET URL_GOES_HERE/recurring/plans

Delete a Plan

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -X DELETE \
  "URL_GOES_HERE/recurring/plan/b89g35qj8m0o735i19jg"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": null
}

This endpoint deletes a specific discount

HTTP Request

DELETE URL_GOES_HERE/recurring/plan/<plan_id>

Query Parameters

Parameter Type Description
plan_id string Plan ID to be deleted

Create a Subscription

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
        "plan_id": "b89g35qj8m0o735i19jg",
        "description": "some description to describe the subscription",
        "customer": {
            "id": "b81ko5qq9qq5v460r9i0"
        },
        "amount": 100,
        "billing_cycle_interval": 1,
        "billing_frequency": "twice_monthly",
        "billing_days": "1,15",
        "duration": 0,
        "next_bill_date": "2019-11-21",
        "add_ons": [],
        "discounts": [
        {
    "id": "b89flfqj8m0o735i19ig",
        "name": "test discount",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "duration": 0
    }
]
}' \
  "URL_GOES_HERE/recurring/subscription"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89gftaj8m0oft7upk80",
    "plan_id": "b89g35qj8m0o735i19jg",
    "description": "some description to describe the subscription",
    "customer": {
      "id": "b81ko5qq9qq5v460r9i0"
    },
    "amount": 100,
    "total_adds": 0,
    "total_discounts": 50,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "duration": 0,
    "next_bill_date": "2017-11-22",
    "add_ons": null,
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0
      }
    ],
    "created_at": "2017-11-20T16:51:01.798736Z",
    "updated_at": "2017-11-20T16:51:01.798736Z"
  }
}

This endpoint creates a new recurring subscription with a discount applied

HTTP Request

POST URL_GOES_HERE/recurring/subscription

Request Body Parameters

Parameter Type Description
plan_id string Plan ID to reference as a template
description string Description for the addition
customer.id string Customer ID to bill
amount int Base amount to be charged
billing_cycle_interval int How often to run the billing cycle. Run every x months
billing_frequency string How often run within a billing cycle. (monthly
billing_days string Which day to bill on. If twice_monthly, then comma separate dates
duration int Duration for the addition to be billed
next_bill_date string "YYYY-MM-DD" This is the next(or first) date to be billed.
add_ons array Allows for additions to a recurring plan.
add_ons[#].id string ID of the referenced add_on
add_ons[#].name string Display name for the addition (optional, this overrides the add_ons value)
add_ons[#].description string Description for the addition (optional, this overrides the add_ons value)
add_ons[#].amount int Amount to be added (optional, this overrides the add_ons value)
add_ons[#].duration int Duration for the addition to be billed (optional, this overrides the add_ons value)
discounts[#].id string ID of the referenced discount
discounts[#].name string Display name for the discount (optional, this overrides the discount value)
discounts[#].description string Description for the discount (optional, this overrides the discount value)
discounts[#].amount int Amount to be discounted (optional, this overrides the discount value)
discounts[#].duration int Duration for the discount to be billed (optional, this overrides the discount value)

TIP

Below are some common recurring scenerios that can assist.

Bill once every 7 days until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
        "plan_id": "b89g35qj8m0o735i19jg",
        "description": "some description to describe the subscription",
        "customer": {
            "id": "b81ko5qq9qq5v460r9i0"
        },
        "amount": 100,
        "billing_cycle_interval": 1,
        "billing_frequency": "daily",
        "billing_days": "7",
        "duration": 0,
        "next_bill_date": "2019-11-21",
        "add_ons": [],
        "discounts": []
}' \
  "URL_GOES_HERE/recurring/subscription"  

Bill once other week until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
        "plan_id": "b89g35qj8m0o735i19jg",
        "description": "some description to describe the subscription",
        "customer": {
            "id": "b81ko5qq9qq5v460r9i0"
        },
        "amount": 100,
        "billing_cycle_interval": 2,
        "billing_frequency": "daily",
        "billing_days": "7",
        "duration": 0,
        "next_bill_date": "2019-11-21",
        "add_ons": [],
        "discounts": []
}' \
  "URL_GOES_HERE/recurring/subscription" 

Bill once every 3 months on the 15th until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
        "plan_id": "b89g35qj8m0o735i19jg",
        "description": "some description to describe the subscription",
        "customer": {
            "id": "b81ko5qq9qq5v460r9i0"
        },
        "amount": 100,
        "billing_cycle_interval": 3,
        "billing_frequency": "monthly",
        "billing_days": "15",
        "duration": 0,
        "next_bill_date": "2019-11-21",
        "add_ons": [],
        "discounts": []
}' \
  "URL_GOES_HERE/recurring/subscription" 

Bill once month on the 1st and the 15th until canceled

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
        "plan_id": "b89g35qj8m0o735i19jg",
        "description": "some description to describe the subscription",
        "customer": {
            "id": "b81ko5qq9qq5v460r9i0"
        },
        "amount": 100,
        "billing_cycle_interval": 1,
        "billing_frequency": "twice_monthly",
        "billing_days": "1,15",
        "duration": 0,
        "next_bill_date": "2019-11-21",
        "add_ons": [],
        "discounts": []
}' \
  "URL_GOES_HERE/recurring/subscription" 

Update a Subscription

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
"plan_id": "b89g35qj8m0o735i19jg",
"description": "some description to describe the subscription",
"customer": {
            "id": "b81ko5qq9qq5v460r9i0"
        },
"amount": 100,
"billing_cycle_interval": 1,
"billing_frequency": "twice_monthly",
"billing_days": "1,15",
"duration": 0,
"next_bill_date": "2017-11-22",
"add_ons": [],
"discounts": [
    {
    "id": "b89flfqj8m0o735i19ig",
        "name": "test discount",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "duration": 0
    }
]
}' \
  "URL_GOES_HERE/recurring/subscription/b89gftaj8m0oft7upk80"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89gftaj8m0oft7upk80",
    "plan_id": "b89g35qj8m0o735i19jg",
    "description": "some description to describe the subscription",
    "customer": {
      "id": "b81ko5qq9qq5v460r9i0"
    },
    "amount": 100,
    "total_adds": 0,
    "total_discounts": 50,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "duration": 0,
    "next_bill_date": "2017-11-22",
    "add_ons": null,
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0
      }
    ],
    "created_at": "2017-11-20T16:51:01.798736Z",
    "updated_at": "2017-11-20T16:51:01.798736Z"
  }
}

This endpoint updates a recurring subscription.

HTTP Request

POST URL_GOES_HERE/recurring/plan/<plan_id>

Query Parameters

Parameter Description
subscription_id Subscription ID to update

Request Body Parameters

Parameter Type Description
plan_id string Plan ID to reference as a template
description string Description for the addition
customer.id string Customer ID to bill
amount int Base amount to be charged
billing_cycle_interval int How often to run the billing cycle. Run every x months
billing_frequency string How often run within a billing cycle. (monthly
billing_days string Which day to bill on. If twice_monthly, then comma separate dates
add_ons array Allows for additions to a recurring plan.
add_ons[#].id string ID of the referenced add_on
add_ons[#].name string Display name for the addition (optional, this overrides the add_ons value)
add_ons[#].description string Description for the addition (optional, this overrides the add_ons value)
add_ons[#].amount int Amount to be added (optional, this overrides the add_ons value)
add_ons[#].duration int Duration for the addition to be billed (optional, this overrides the add_ons value)
discounts[#].id string ID of the referenced discount
discounts[#].name string Display name for the discount (optional, this overrides the discount value)
discounts[#].description string Description for the discount (optional, this overrides the discount value)
discounts[#].amount int Amount to be discounted (optional, this overrides the discount value)
discounts[#].duration int Duration for the discount to be billed (optional, this overrides the discount value)

Get a Subscription

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/subscription/b89gftaj8m0oft7upk80"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89gftaj8m0oft7upk80",
    "plan_id": "b89g35qj8m0o735i19jg",
    "description": "some description to describe the subscription",
    "customer": {
      "id": "b81ko5qq9qq5v460r9i0"
    },
    "amount": 100,
    "total_adds": 0,
    "total_discounts": 50,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "duration": 0,
    "next_bill_date": "2017-11-22",
    "add_ons": null,
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0
      }
    ],
    "created_at": "2017-11-20T16:51:01.798736Z",
    "updated_at": "2017-11-20T16:51:01.798736Z"
  }
}

This endpoint returns a specific subscription.

HTTP Request

GET URL_GOES_HERE/recurring/subscription/<subscription_id>

Query Parameters

Parameter Type Description
subscription_id string Subscription ID to be returned

Delete a Subscription

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -X DELETE \
  "URL_GOES_HERE/recurring/subscription/b89gftaj8m0oft7upk80"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": null
}

This endpoint deletes a specific discount

HTTP Request

DELETE URL_GOES_HERE/recurring/subscription/<subscription_id>

Query Parameters

Parameter Type Description
subscription_id string Subscription ID to be deleted

Terminals

name is currently integrated to Dejavoo Z11, Z8 and Z1 terminals.

All transactional requests should be processed via the /transaction referencing the specific terminal to handle the request. Please see the Transactions section for more information.

Get all terminals

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  "URL_GOES_HERE/terminals"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "",
  "total_count": 1,
  "data": [
    {
      "id": "1ucio551tlv85l7moe5s",
      "merchant_id": "aucio551tlv85l7moe5g",
      "manufacturer": "dejavoo",
      "model": "z11",
      "serial_number": "1811000XXXX",
      "tpn": "1811000XXXX",
      "description": "front counter z11",
      "status": "active",
      "auth_key": "wcR1c9o1",
      "register_id": "1",
      "auto_settle": true,
      "settle_at": "00:00:00",
      "created_at": "2018-01-12T03:57:59Z",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}

This endpoint returns all terminals associated with the merchant account. This will include inactive/disabled terminals as well

HTTP Request

GET URL_GOES_HERE/terminals

Query Parameters

Parameter Type Description

None

Invoices

Create

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
  "id": "",
  "currency": "USD",
  "company_name": "ACME Inc.",
  "company_logo_url": "",
  "customer_number": "123Customer",
  "payable_to": {
      "id": null,
      "first_name": "First",
      "last_name": "Last",
      "company": "Merchant Business",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somewebsite.com"
  },
  "bill_to": {
      "id": null,
      "first_name": "First",
      "last_name": "Last",
      "company": "Some Business",
      "address_line_1": "123 Drury Lane",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somesite.com"
  },
  "created_at": "",
  "date_due": "2019-02-13T06:00:00.000Z",
  "items": [{
      "id": "",
      "name": "Widget",
      "description": "A widget for processors",
      "quantity": 1,
      "quantity_shipped": 0,
      "unit_of_measure": "",
      "unit_price": 100,
      "discount": 0,
      "discount_type": "$",
      "taxable": false,
      "local_tax": "0",
      "national_tax": "0",
      "tax_rate": "0",
      "amount": 0,
      "status": "pending"
  }],
  "advanced_fields": false,
  "subtotal": 0,
  "tax_percent": "0.00",
  "tax": 0,
  "total": 0,
  "amount_paid": 0,
  "adjustment": 0,
  "amount_due": 0,
  "status": "pending",
  "message": "Thank you for your business!",
  "send_via": "none",
  "last_sent_at": "",
  "public_url": "",
  "hosted_url": "",
  "payment_methods": ["card"],
  "card_processor_id": "bhi5qa5o3hogms88jojg",
  "ach_processor_id": ""
}'\
  "URL_GOES_HERE/invoice"

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "bhi9vado3hogrne0u4tg",
    "currency": "USD",
    "company_name": "ACME Inc.",
    "company_logo_url": "",
    "customer_number": "123Customer",
    "payable_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Merchant Business",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somewebsite.com"
    },
    "bill_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Some Business",
      "address_line_1": "123 Drury Lane",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somesite.com"
    },
    "created_at": "2019-02-13T16:52:25.563509-06:00",
    "date_due": "2019-02-13T06:00:00Z",
    "items": [{
      "id": "bhi9vado3hogrne0u4t0",
      "name": "Widget",
      "description": "A widget for processors",
      "quantity": 1,
      "quantity_shipped": 0,
      "unit_of_measure": "",
      "unit_price": 100,
      "discount": 0,
      "discount_type": "$",
      "taxable": false,
      "local_tax": "0",
      "national_tax": "0",
      "tax_rate": "0",
      "tax_amount": 0,
      "amount": 100,
      "status": "pending"
    }],
    "advanced_fields": false,
    "subtotal": 100,
    "tax_percent": "0.00",
    "tax": 0,
    "total": 100,
    "amount_paid": 0,
    "adjustment": 0,
    "amount_due": 100,
    "payment_methods": ["card"],
    "card_processor_id": "bhi5qa5o3hogms88jojg",
    "ach_processor_id": "",
    "status": "pending",
    "message": "Thank you for your business!",
    "reject_message": "",
    "send_via": "none",
    "last_sent_at": "0001-01-01T00:00:00Z",
    "updated_at": "2019-02-13T16:52:25.563509-06:00",
    "public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
    "hosted_url": "http://localhost:8080/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
  }
}

This endpoint is will create a new invoice

HTTP Request

POST URL_GOES_HERE/invoice

Request Body Parameters

Parameter Default Description
currency Currency invoice amounts should be in (such as USD)
company_name Your company name
customer_number Number identifying the customer the invoice is for
payable_to.id ID of the stored address you want to make the invoice payable to (optional, can be null)
payable_to.first_name First name
payable_to.last_name Last name
payable_to.company Company name
payable_to.address_line_1 Address line 1
payable_to.address_line_2 Address line 2
payable_to.city City
payable_to.state State, in 2-character format
payable_to.postal_code Postal code
payable_to.country Country, in 2-character format
payable_to.phone Phone number
payable_to.fax Fax number
payable_to.email Email address
bill_to.id ID of the stored address you want to make the invoice billable to (optional, can be null)
bill_to.first_name First name
bill_to.last_name Last name
bill_to.company Company name
bill_to.address_line_1 Address line 1
bill_to.address_line_2 Address line 2
bill_to.city City
bill_to.state State, in 2-character format
bill_to.postal_code Postal code
bill_to.country Country, in 2-character format
bill_to.phone Phone number
bill_to.fax Fax number
bill_to.email Email address
date_due Date the invoice is due by
items[#].name Name of the item
items[#].description Description of the item
items[#].quantity Quantity of item
items[#].quantity_shipped Quantity of items shipped to customer
items[#].unit_of_measure Unit of measure of item (lb, kg, etc)
items[#].unit_price Unit price of item
items[#].discount Discount off the total amount for item
items[#].discount_type Type of discount, either single amount ($) or percentage (%)
items[#].taxable Declares if item is taxable or not
items[#].local_tax Local tax for item
items[#].national_tax National tax for item
advanced_fields Whether or not to include additional fields, such as local tax, for line items
tax_percent Add tax to invoice total
adjustment Adjust the total amount of the invoice
message Message for customers viewing the invoice
send_via How to send invoice notifications (email, text, both, or none)
payment_methods[#] Allowable payment methods (card, ach, and/or mail)
card_processor_id ID of the payment processor to use for credit card payments
ach_processor_id ID of the payment processor to use for ACH payments

Update

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
  "id": "bhi9vado3hogrne0u4tg",
  "currency": "USD",
  "company_name": "ACME Inc.",
  "company_logo_url": "",
  "customer_number": "123Customer",
  "payable_to": {
    "id": null,
    "first_name": "First",
    "last_name": "Last",
    "company": "Merchant Business",
    "address_line_1": "123 Some St",
    "address_line_2": "",
    "city": "Some City",
    "state": "IL",
    "postal_code": "60000",
    "country": "US",
    "phone": "5555555555",
    "fax": "5555555555",
    "email": "info@somewebsite.com"
  },
  "bill_to": {
    "id": null,
    "first_name": "First",
    "last_name": "Last",
    "company": "Some Business",
    "address_line_1": "123 Drury Lane",
    "address_line_2": "",
    "city": "Some City",
    "state": "IL",
    "postal_code": "60000",
    "country": "US",
    "phone": "5555555555",
    "fax": "5555555555",
    "email": "info@somesite.com"
  },
  "created_at": "2019-02-13T22:52:26Z",
  "date_due": "2019-02-13T06:00:00Z",
  "items": [{
    "id": "bhi9vado3hogrne0u4t0",
    "name": "Widget",
    "description": "A widget for processors",
    "quantity": 1,
    "quantity_shipped": 0,
    "unit_of_measure": "",
    "unit_price": 100,
    "discount": 0,
    "discount_type": "$",
    "taxable": false,
    "local_tax": "0",
    "national_tax": "0",
    "tax_rate": "0",
    "amount": 100,
    "status": "pending"
  }],
  "advanced_fields": false,
  "subtotal": 100,
  "tax_percent": "0.00",
  "tax": 0,
  "total": 100,
  "amount_paid": 0,
  "adjustment": 0,
  "amount_due": 100,
  "payment_methods": ["card"],
  "card_processor_id": "bhi5qa5o3hogms88jojg",
  "ach_processor_id": "",
  "status": "pending",
  "message": "Thank you for your business!",
  "reject_message": "",
  "send_via": "none",
  "last_sent_at": "0001-01-01T00:00:00Z",
  "updated_at": "2019-02-13T22:52:26Z",
  "public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
  "hosted_url": "http://localhost:8080/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
}'\
  "URL_GOES_HERE/invoice/bhi9vado3hogrne0u4tg"

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "bhi9vado3hogrne0u4tg",
    "currency": "USD",
    "company_name": "ACME Inc.",
    "company_logo_url": "",
    "customer_number": "123Customer",
    "payable_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Merchant Business",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somewebsite.com"
    },
    "bill_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Some Business",
      "address_line_1": "123 Drury Lane",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somesite.com"
    },
    "created_at": "2019-02-13T22:52:26Z",
    "date_due": "2019-02-13T06:00:00Z",
    "items": [{
      "id": "bhi9vado3hogrne0u4t0",
      "name": "Widget",
      "description": "A widget for processors",
      "quantity": 1,
      "quantity_shipped": 0,
      "unit_of_measure": "",
      "unit_price": 100,
      "discount": 0,
      "discount_type": "$",
      "taxable": false,
      "local_tax": "0",
      "national_tax": "0",
      "tax_rate": "0",
      "tax_amount": 0,
      "amount": 100,
      "status": "pending"
    }],
    "advanced_fields": false,
    "subtotal": 100,
    "tax_percent": "0.00",
    "tax": 0,
    "total": 100,
    "amount_paid": 0,
    "adjustment": 0,
    "amount_due": 100,
    "payment_methods": ["card"],
    "card_processor_id": "bhi5qa5o3hogms88jojg",
    "ach_processor_id": "",
    "status": "pending",
    "message": "Thank you for your business!",
    "reject_message": "",
    "send_via": "none",
    "last_sent_at": "0001-01-01T00:00:00Z",
    "updated_at": "2019-02-13T23:15:42.799495Z",
    "public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
    "hosted_url": "http://localhost:8080/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
  }
}

This endpoint is will update an invoice

HTTP Request

POST URL_GOES_HERE/invoice/<invoice_id>

Query Parameters

Parameter Description
invoice_id Invoice ID string

Request Body Parameters

Parameter Default Description
currency Currency invoice amounts should be in (such as USD)
company_name Your company name
customer_number Number identifying the customer the invoice is for
payable_to.id ID of the stored address you want to make the invoice payable to (optional, can be null)
payable_to.first_name First name
payable_to.last_name Last name
payable_to.company Company name
payable_to.address_line_1 Address line 1
payable_to.address_line_2 Address line 2
payable_to.city City
payable_to.state State, in 2-character format
payable_to.postal_code Postal code
payable_to.country Country, in 2-character format
payable_to.phone Phone number
payable_to.fax Fax number
payable_to.email Email address
bill_to.id ID of the stored address you want to make the invoice billable to (optional, can be null)
bill_to.first_name First name
bill_to.last_name Last name
bill_to.company Company name
bill_to.address_line_1 Address line 1
bill_to.address_line_2 Address line 2
bill_to.city City
bill_to.state State, in 2-character format
bill_to.postal_code Postal code
bill_to.country Country, in 2-character format
bill_to.phone Phone number
bill_to.fax Fax number
bill_to.email Email address
date_due Date the invoice is due by
items[#].name Name of the item
items[#].description Description of the item
items[#].quantity Quantity of item
items[#].quantity_shipped Quantity of items shipped to customer
items[#].unit_of_measure Unit of measure of item (lb, kg, etc)
items[#].unit_price Unit price of item
items[#].discount Discount off the total amount for item
items[#].discount_type Type of discount, either single amount ($) or percentage (%)
items[#].taxable Declares if item is taxable or not
items[#].local_tax Local tax for item
items[#].national_tax National tax for item
advanced_fields Whether or not to include additional fields, such as local tax, for line items
tax_percent Add tax to invoice total
adjustment Adjust the total amount of the invoice
message Message for customers viewing the invoice
send_via How to send invoice notifications (email, text, both, or none)
payment_methods[#] Allowable payment methods (card, ach, and/or mail)
card_processor_id ID of the payment processor to use for credit card payments
ach_processor_id ID of the payment processor to use for ACH payments

Get Specific Invoice

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
  "URL_GOES_HERE/invoice/bhi9vado3hogrne0u4tg"

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "bhi9vado3hogrne0u4tg",
    "currency": "USD",
    "company_name": "ACME Inc.",
    "company_logo_url": "",
    "customer_number": "123Customer",
    "payable_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Merchant Business",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somewebsite.com"
    },
    "bill_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Some Business",
      "address_line_1": "123 Drury Lane",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somesite.com"
    },
    "created_at": "2019-02-13T22:52:26Z",
    "date_due": "2019-02-13T06:00:00Z",
    "items": [{
      "id": "bhi9vado3hogrne0u4t0",
      "name": "Widget",
      "description": "A widget for processors",
      "quantity": 1,
      "quantity_shipped": 0,
      "unit_of_measure": "",
      "unit_price": 100,
      "discount": 0,
      "discount_type": "$",
      "taxable": false,
      "local_tax": "0",
      "national_tax": "0",
      "tax_rate": "0",
      "tax_amount": 0,
      "amount": 100,
      "status": "pending"
    }],
    "advanced_fields": false,
    "subtotal": 100,
    "tax_percent": "0.00",
    "tax": 0,
    "total": 100,
    "amount_paid": 0,
    "adjustment": 0,
    "amount_due": 100,
    "payment_methods": ["card"],
    "card_processor_id": "bhi5qa5o3hogms88jojg",
    "ach_processor_id": "",
    "status": "pending",
    "message": "Thank you for your business!",
    "reject_message": "",
    "send_via": "none",
    "last_sent_at": "0001-01-01T00:00:00Z",
    "updated_at": "2019-02-13T23:15:43Z",
    "public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
    "hosted_url": "http://localhost:8080/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
  }
}

This endpoint is will get a specific invoice

HTTP Request

GET URL_GOES_HERE/invoice/<invoice_id>

Query Parameters

Parameter Description
invoice_id Invoice ID string

Search Invoices

curl -v -X POST \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": {
    "operator": "=",
    "value": "bhi9vado3hogrne0u4tg"
  },
  "amount_due": {
    "operator": "=",
    "value": 100
  },
  "date_due": {
    "start_date": "2019-02-12T00:00:00Z",
    "end_date": "2019-02-14T23:59:59Z"
  },
  "limit": 10,
  "offset": 0
}' \
  "URL_GOES_HERE/invoices/search"  

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success",
  "data": [{
    "id": "bhi9vado3hogrne0u4tg",
    "currency": "USD",
    "company_name": "ACME Inc.",
    "company_logo_url": "",
    "customer_number": "123Customer",
    "payable_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Merchant Business",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somewebsite.com"
    },
    "bill_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Some Business",
      "address_line_1": "123 Drury Lane",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somesite.com"
    },
    "created_at": "2019-02-13T22:52:26Z",
    "date_due": "2019-02-13T06:00:00Z",
    "items": [{
      "id": "bhi9vado3hogrne0u4t0",
      "name": "Widget",
      "description": "A widget for processors",
      "quantity": 1,
      "quantity_shipped": 0,
      "unit_of_measure": "",
      "unit_price": 100,
      "discount": 0,
      "discount_type": "$",
      "taxable": false,
      "local_tax": "0",
      "national_tax": "0",
      "tax_rate": "0",
      "tax_amount": 0,
      "amount": 100,
      "status": "pending"
    }],
    "advanced_fields": false,
    "subtotal": 100,
    "tax_percent": "0.00",
    "tax": 0,
    "total": 100,
    "amount_paid": 0,
    "adjustment": 0,
    "amount_due": 100,
    "payment_methods": ["card"],
    "card_processor_id": "bhi5qa5o3hogms88jojg",
    "ach_processor_id": "",
    "status": "pending",
    "message": "Thank you for your business!",
    "reject_message": "",
    "send_via": "none",
    "last_sent_at": "0001-01-01T00:00:00Z",
    "updated_at": "2019-02-13T23:15:43Z",
    "public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
    "hosted_url": "http://localhost:8080/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
  }],
  "total_count": 1
}

This endpoint retrieves a list of invoices.

HTTP Request

POST URL_GOES_HERE/invoices/search

Request Body Parameters

Parameter Default Description
limit 10
offset 0
id optional Invoice ID to search for
id.operator Required for ID search Search operator '='
id.value Required for ID search Value to search for
amount_due optional Amount due to search for
amount_due.operator Required for amount_due Search operator '=', '<', or '>'
amount_due.value Required for amount_due Value to search for
date_due optional Search for invoices due in the provided date range
date_due.start_date Required for date_due Start date in UTC
date_due.end_date Required for date_due End date in UTC

Delete Invoice

curl -v \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-X DELETE \
  "URL_GOES_HERE/invoice/bhi9vado3hogrne0u4tg"

The above command returns JSON structured like this:

{
  "status": "success",
  "msg": "success"
}

This endpoint is will delete a specific invoice.

HTTP Request

DELETE URL_GOES_HERE/invoice/<invoice_id>

Query Parameters

Parameter Description
invoice_id Invoice ID string