Requests

Base Urls

Sandbox

The Sandbox environment is provided for testing. Transaction responses are simulated and do not leave the platform for processing. No billing related items occur within this environment.

Sandbox url:

Production

The Production environment should be used for all LIVE transactional processing.

Production url:

Versioning

The platform's semi-RESTful API is fully backwards compatible and versioning is not necessary. Changes and feature updates are sent out via the platform prior to release.

Current version: 1.5.1

Headers

The following headers should be included with your requests:

Authorization

Calls to the API must include an Authorization header with the request. Either a JWT (JSON Web Token) or an API Key can be used as the value of this header, like so:

Authorization: Bearer { JWTToken }

Authorization: { API Key }

API Keys

API keys are used to authenticate your requests to the API. You can create and manage your API keys in the control panel. API keys are tied to a user account.

Their are two types of API keys:

• Public API keys (ex: pub_***) - used for making requests to the API from the client side (ex. Tokenizer and Cart Sessions)
• Private API keys (ex: api_***) - used for making requests to the API from the server side (ex. Transaction Processing)

DANGER

Private API keys should never be exposed to the public. Please do not include them in client side code, emails or support ticket request.

DANGER

Use of Public API keys to make requests to the API from the server side will result in an unauthorzed response.

Content-Type

Content-Type should typically be set to application/json, unless you need to send your request body in a different format. All API responses will be in JSON format.

Errors

The API uses standard HTTP status codes to indicate the success or failure of a request. In the event of an error, the response will include a JSON object with the following properties:

Example:

{
  "status": "failed",
  "msg": "bad request error: invalid Postal Code"
}

Unauthorized

If you receive an unauthorized response, there are a few things you can check:

• Missing Authorization header see Authorization
• API key does not exist or has been deleted
• Correct API key (public "pub_" vs private "api_")
• Correct account Parnter vs Merchant
• Correct environment (sandbox vs production)

Corelation ID

Every header response will include a correlation-id (x-correlation-id) which can be used to help identify and troubleshoot issues with the API. If you are experiencing issues, please include this ID in any support requests.

Users

Create User

Create a new user account.

Request Method: POST

URL Endpoint: /api/user

Name	Type	Default	Description	Required
username	string		unique username (must contain alpha and numeric characters)
name	string		first and last name
phone	string		phone number, digits only
email	string		email address (must be valid email format)
timezone	string		timezone (ex. ETC/UTC)
password	string		password
status	string		status (active or disabled)
role	string		defined role (admin or standard)

Get User by ID

Retrieve the properties of a specific user.

Request Method: GET

URL Endpoint: /api/user/{ user id }

{
  "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"
  }
}

Get Current User

Retrieve the properties of the currently authenticated user. This is intended as a helper function, it is recommended to get a specific user by providing the ID if possible.

Request Method: GET

URL Endpoint: /api/user

{
  "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"
  }
}

Get All Users

Retrieve the properties of all users for the gateway or partner account associated with the API Key or JWT token provided in the Authorization header.

Request Method: GET

URL Endpoint: /api/users

{
  "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"
    }
  ]
}

Update User

Edit the properties of an existing user account.

Request Method: POST

URL Endpoint: /api/user/{ user id }

Name	Type	Default	Description	Required
name	string		first and last name
phone	string		phone number, digits only
email	string		email address (must be valid email format)
timezone	string		timezone (ex. ETC/UTC)
status	string		status (active or disabled)
role	string		defined role (admin or standard)
permissions	object	(account defaults)	users permissions
permissions.manage_users	boolean	false
permissions.manage_api_keys	boolean	false
permissions.manage_terminals	boolean	false
permissions.manage_rule_engine	boolean	false
permissions.view_settlement_batches	boolean	false
permissions.view_billing_reports	boolean	false
permissions.process_authorization	boolean	false
permissions.process_capture	boolean	false
permissions.process_sale	boolean	false
permissions.process_void	boolean	false
permissions.process_credit	boolean	false
permissions.process_refund	boolean	false
permissions.process_verification	boolean	false
permissions.allow_dashboard_stats	boolean	false
permissions.vault_create	boolean	false
permissions.vault_update	boolean	false
permissions.vault_delete	boolean	false
permissions.access_file_batch	boolean	false
permissions.view_others_transactions	boolean	false
permissions.manage_card_bans	boolean	false
permissions.restrict_viewing_others_invoices	boolean	false
permissions.recurring_status_change	boolean	false
notifications.merchant	object	(account defaults)	notification values
notifications.merchant.transaction_receipts	boolean	false
notifications.merchant.settlement_reports	boolean	false
notifications.merchant.triggered_rules	boolean	false
notifications.merchant.security_alerts	boolean	false
notifications.merchant.invoice_create	boolean	false
notifications.merchant.transaction_void	boolean	false
defaults	object		default settings
defaults.processor_id	string		default processor
defaults.terminal_id	string		default terminal_id
defaults.transaction_csv_format_id	string		default transaction csv export format
defaults.transaction_report_format_id	string		default transaction report format
defaults.vault_table_format_id	string		default vault report format
defaults.show_transaction_totals	boolean		reports should show transaction totals

Delete User

Delete a specific user.

Request Method: DELETE

URL Endpoint: /api/user/{ user id }

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

Change Password

Change a user's password. Must provide an API Key or JWT token associated with the user as the Authorization header value.

Request Method: POST

URL Endpoint: /api/user/change-password

Name	Type	Default	Description	Required
username	string		User's username
current_password	string		User's current password
new_password	string		The new password to be set on the user's account. Must be 8-64 characters and contain an uppercase character, a number, and a special character.

Api Keys

Create API Key

Create an API key for a user.

Request Method: POST URL Endpoint: /api/user/apikey

Name	Type	Default	Description	Required
type	string		api(private) or public key	*
name	string		A name for the API key	*

Get All API Keys

Retrieve all API keys for the gateway or partner account associated with the API Key or JWT token provided in the Authorization header.

Request Method: GET URL Endpoint: /api/user/apikeys

{
  "status": "success",
  "msg": "success",
  "total_count": 1,
  "data": [
    {
      "id": "cpfkb7rug2jghjrp79rg",
      "user_id": "testmerchant43",
      "type": "api",
      "name": "Private Key",
      "api_key": "api_2hQIG638fYIq0KiP96k3XDZXrLJ",
      "created_at": "2024-06-04T16:49:36Z",
      "updated_at": "2024-06-04T16:49:36Z"
    }
  ]
}

Delete API Key

Delete a specific API key.

Request Method: DELETE URL Endpoint: /api/user/apikey/{ api key }

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

Transactions

Process

Process a transaction through the gateway.

TIP

If you do not have a default processor set, you must include the processor_id property in the request body or the transaction will fail.

TIP

Base Amount - If you are using base_amount it will be the base amount of the transaction. The surcharge and other related fees(if applicable) will be calculated and added unless those values are specifically passed in.

Amount - This will be the final amount you want charged and will include all surcharges and related fees(if applicable).

Request Method: POST

URL Endpoint: /api/transaction

Name	Type	Default	Description	Required
idempotency_key	uint(uuid format)		used to identify duplicate transactions. Default time is 5 minutes
type	string		"sale", "authorize", "verification" or "credit"
amount	integer		Amount to process in cents (should contain all applicable fees and taxes) (1299 = $12.99)
base_amount	integer		Amount to process in cents (surcharge and related fees will be added to this amount during processing) (1299 = $12.99)
tax_exempt	boolean	false	Is the transaction tax exempt	Required for L3
tax_amount	integer	0	Tax Amount in cents	Required for L3
shipping_amount	integer	0	Shipping Amount in cents (should be included in Amount)
discount_amount	integer	0	Discount Amount in cents (should be included in Amount)
tip_amount	integer	0	Tip Amount in cents (should be included in Amount)
currency	string	"USD"	ISO 4217 currency (ex "USD")
description	string	""	Text field for miscellaneous notes (max 255 characters)
order_id	string		Supports up to 15 alphanumeric characters	Required for L3
po_number	string		Supports up to 15 alphanumeric characters
processor_id	string	""	Designates a specific processor for the transaction. If no value is provided, the transaction will run against the default processor set on your gateway. If no value is provided and there is no default set, the transaction will fail.	see description
ip_address	string	Server IP	IPv4 or IPv6 value of the end user
allow_partial_payment	bool	false	Allow partial transactions to be approved (only if supported by processor)
email_receipt	boolean	false	If true, sends an email receipt (email_address must be provided)
email_address	string		Email address (must be valid email format, "example@mail.com")	required if email_receipt is true
create_vault_record	boolean	false	If true, triggers the creation of a customer vault record after a successful transaction. Multiple transactions with the same details will create duplicative customer records.
vendor_id	string	""	Vendor ID passed along to certain processors if supported (Special Field, only use if instructed by support)
billing_method	string	"straight"	"straight", "initial_recurring", or "recurring"
summary_commodity_code	string		Summary Commodity Code 4 AlphaNumeric characters	Required for L3
ship_from_postal_code	string		Ship From Postal Code	Required for L3
payment_adjustment	object		Object containing payment adjustment details. (ex. convenience fees, service fees, and surcharges)
payment_adjustment     .type	string	""	"flat" or "percentage"
payment_adjustment     .value	integer	0	Amount of adjustment in cents for "flat" (ex. 199 = $1.99) or 3 decimal places for "percentage" (ex. 1000 = 1.000%)
payment_method	object		Object containing payment method details, must contain only one of the following: card, ach, customer, terminal, token, apm	must include one payment method
payment_method     .card	object		Object containing details for processing a transaction against a debit or credit card
payment_method     .card     .entry_type	string		Must be "keyed" or "swiped"
payment_method     .card     .number	string		Card number (digits only)	required if payment_method.card is present
payment_method     .card     .expiration_date	string		Expiration date (format MM/YY)	required if payment_method.card is present
payment_method     .card     .cvc	string		Card Verification Code	required if the applicable rule is set on the gateway
payment_method     .card     .track_1	string		Decrypted track_1
payment_method     .card     .track_2	string		Decrypted track_2
payment_method     .card     .encrypted_track_1	string		Encrypted Track 1
payment_method     .card     .encrypted_track_2	string		Encrypted Track 2
payment_method     .card     .ksn	string		KSN used to encrypt the supplied encrypted tracks
payment_method     .card     .cardholder_authentication	object		Optionally pass 3DS collected data	if passed, it must contain valid values
payment_method     .card     .cardholder_authentication     .eci	string		ECI indicator, ie 01,02,05,07..etc
payment_method     .card     .cardholder_authentication     .cavv	string		CAVV
payment_method     .card     .cardholder_authentication     .xid	string		XID
payment_method     .card     .cardholder_authentication     .cryptogram	string		Cryptogram
payment_method     .card     .cardholder_authentication     .version	string		Version, 1 or 2
payment_method     .card     .cardholder_authentication     .ds_transaction_id	string		DS Transaction ID
payment_method     .card     .cardholder_authentication     .acs_transaction_id	string		ACS Transaction ID
payment_method     .ach	object		Object containing details for processing a transaction via ACH
payment_method     .ach     .routing_number	string		Routing number for account to be charged	required if payment_method.ach is present
payment_method     .ach     .account_number	string		Account number for account to be charged	required if payment_method.ach is present
payment_method     .ach     .sec_code	string		SEC code for ACH transaction type: "web", "ccd", "ppd", or "tel"	required if payment_method.ach is present
payment_method     .ach     .account_type	string		ACH account type: "checking" or "savings"	required if payment_method.ach is present
payment_method     .ach     .check_number	string		Check number	required if payment_method.ach.sec_code = "tel"
payment_method     .ach     .accountholder_authentication	string		Object containing details for accountholder authentication	if required by processor
payment_method     .ach     .accountholder_authentication     .dl_state	string		Driver's License state	required if payment_method.ach.accountholder_authentication is present
payment_method     .ach     .accountholder_authentication     .dl_number	string		Driver's License number	required if payment_method.ach.accountholder_authentication is present
payment_method     .customer	object		Object containing details for processing a transaction against a vaulted customer record
payment_method     .customer     .id	string		Customer ID	required if payment_method.customer is present
payment_method     .customer     .payment_method_id	string	Customer default	ID of customer's saved payment method to be charged
payment_method     .customer     .payment_method_type	string	Customer default	The type of the payment method referenced in payment_method_id
payment_method     .customer     .billing_address_id	string	Customer default	ID of customer's saved billing address to be used
payment_method     .customer     .shipping_address_id	string	Customer default	ID of customer's saved shipping address to be used
payment_method     .terminal	object		Object containing details for processing a transaction against a Terminal
payment_method     .terminal     .id	string		ID of the terminal to be used for the transaction	required if payment_method.terminal is present
payment_method     .terminal     .expiration_date	string		Optionally pass an expiration date along with the transaction
payment_method     .terminal     .cvc	string		Optionally pass a CVV along with the transaction
payment_method     .terminal     .print_receipt	string		"no" (no receipt), "customer" (customer copy only), "merchant" (merchant copy only), or "both" (both copies)	required if payment_method.terminal is present
payment_method     .terminal     .signature_required	string		If true, requests that the terminal capture a signature (if supported)	required if payment_method.terminal is present
payment_method     .apm	object		Object containing details for processing APM transactions
payment_method     .apm     .type	string		APM type (see chart below)	required if payment_method.apm is present
payment_method     .apm     .merchant_redirect_url	string		This is the redirect url you wish to send the customer to after processing the payment	required if payment_method.apm is present
payment_method     .apm     .locale	string		Locale to be used for the payment page, if supported by the APM (ex. "en-US")	required if payment_method.apm is present
payment_method     .apm     .mobile_view	boolean		If true, tells the APM to render a mobile version of the landing page (if supported by the APM)	required if payment_method.apm is present
payment_method     .apm     .national_id	string		Consumer's National ID (max 30 characters)
payment_method     .apm     .consumer_ref	string		Unique reference identifiying the customer. May contain [a-z0-9-], max 20 characters
billing_address	object	null	Object containing billing address details
billing_address     .first_name	string		Up to 50 characters
billing_address     .last_name	string		Up to 50 characters
billing_address     .company	string		Up to 100 characters
billing_address     .address_line_1	string		Up to 100 characters
billing_address     .address_line_2	string		Up to 100 characters
billing_address     .city	string		Up to 50 characters
billing_address     .state	string		State abbrevation
billing_address     .postal_code	string		If payment_method.card is present, defaults to Postal Code associated with card	Required for L3
billing_address     .country	string		"US"
billing_address     .email	string		Email address (must be valid email format, "example@mail.com")
billing_address     .phone	string		Digits only
billing_address     .fax	string		Digits only
shipping_address	object	null	Object containing billing address details
shipping_address     .first_name	string		Up to 50 characters
shipping_address     .last_name	string		Up to 50 characters
shipping_address     .company	string		Up to 100 characters
shipping_address     .address_line_1	string		Up to 100 characters
shipping_address     .address_line_2	string		Up to 100 characters
shipping_address     .city	string		Up to 50 characters
shipping_address     .state	string		State abbreviation
shipping_address     .postal_code	string			Required for L3
shipping_address     .country	string
shipping_address     .email	string		Email address (must be valid email format, "example@mail.com")
shipping_address     .phone	string		Digits only
shipping_address     .fax	string		Digits only
group_name	string	"default"	custom fields group name
custom_fields	object		Object based where the key is the id of the custom field and the value is an array of strings(even is single value)	Only required if fields are set to required
iias_status	string	""	Required for HSA/FSA Valid values are: "verified" or "exempt"
additional_amounts	object
additional_amounts     .hsa     .total	int	0	Required for HSA/FSA Total amount for HSA/FSA, passed as an unsigned integer
additional_amounts     .hsa     .rx_amount	int	0	RX AMount for HSA/FSA, passed as an unsigned integer
additional_amounts     .hsa     .vision_amount	int	0	Vision Mount for HSA/FSA, passed as an unsigned integer
additional_amounts     .hsa     .clinic_amount	int	0	Clinic Mount for HSA/FSA, passed as an unsigned integer
additional_amounts     .hsa     .dental_amount	int	0	Dental Mount for HSA/FSA, passed as an unsigned integer
line_items	array		Array of line items	Required for L3
line_items[]     name	string		Friendly name up to 50 alpha characters
line_items[]     description	string		Product Description up to 50 alpha characters
line_items[]     product_code	string		Product Code/SKU up to 50 alpha characters
line_items[]     commodity_code	string		Commodity Code up to 12 alpha characters
line_items[]     quantity	float64		Quantity ##.##
line_items[]     discount_amount	int		in cents
line_items[]     freight_amount	int		in cents
line_items[]     unit_price	int		in cents
line_items[]     tax_amount	int		in cents
line_items[]     national_tax_amount	int		in cents
line_items[]     amount	int		in cents
line_items[]     national_tax_rate	string		3 decimal rate. 10% = 10.000
line_items[]     tax_rate	string		3 decimal rate. 10% = 10.000
line_items[]     unit_of_measure	string
processor_specific	object			Optional: this only applys to specific processor types
processor_specific     .paysafe_direct     .subscription_trial_solution	bool
processor_specific     .paysafe_direct     .subscription_start_date	string		YYYY-MM-DD
processor_specific     .paysafe_direct     .subscription_trial_start_date	string		YYYY-MM-DD
processor_specific     .paysafe_direct     .subscription_trial_end_date	string		YYYY-MM-DD
processor_specific     .paysafe_direct     .subscription_secondary_billing_date	string		YYYY-MM-DD
processor_specific     .paysafe_direct     .subscription_cancel_url	string		weburl
processor_specific     .paysafe_direct     .subscription_amount	uint		in cents
processor_specific     .paysafe_direct     .subscription_unit_cost	uint		in cents
processor_specific     .paysafe_direct     .subscription_item_quantity	uint
processor_specific     .paysafe_direct     .subscription_product_desc	string
descriptor	object			Optional: this only applys to specific processor types
descriptor     .name	string (38 Char)
descriptor     .address	string (38 Char)
descriptor     .city	string (21 Char)
descriptor     .state	string (2 Char)
descriptor     .postal_code	string (5 Char)
subscriptions	array		Array of subscriptions
card_on_file_indicator	string		[CR]	Optional value, C = General purpose storage, R = recurring payment
initiated_by	string	"customer" or "merchant"	Who is inititating the transaction, "customer" or "merchant"
initial_transaction_id	string		Optional if using our tokenization, otherwise this is transaction id used when storing the payment
stored_credential_indicator	string		Optional if using our tokenization, otherwise "used" or "stored"

Code Samples

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"
        }
        ... 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"
          }
          ... or ...
        "apm": {
          "type": "alipay",
          "merchant_redirect_url": "http://merchantwebsite.com/",
          "locale": "en-US",
          "mobile_view": false
        }
      }
    },
    "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"
    }
}'   \
"https://sandbox.gosparrowone.com/api/transaction"

CIT - MIT

TIP

When processing transactions the following variables are available for including CIT/MIT variables to the processors.

Name	Required	Description
card_on_file_indicator	Optional
initiated_by	Required	Indicates who initiated the transaction.
initial_transaction_id	Optional	Optional if using our tokenization
stored_credential_indicator	Optional	Indicates if a stored payment was used or not
billing_method	Optional	Defaults to "straight", but if this is a recurring transaction, passing "recurring" will set recurring indicators on the transaction

Fee Calculation

TIP

Using this endpoint will calculate any applicable fees that should be applied to the transaction. This includes Surcharge, Cash Discount Fees and Payment Adjustment, if applicable.

Request Method: POST

URL Endpoint: /api/lookup/fees

Name	Type	Required	Description
type	string	yes	Type of request, "integrations"
state	string	no	Billing address state
bin	string	no	6 - 19 digits of a card
customer_id	string	no	Customer ID
payment_id	string	no	Payment method ID for a customer
payment_method	string	yes	The method of payment, i.e 'card' or 'ach'
base_amount	uint	yes	Amount in lowest form of currency. $1.00 = 100

➜  ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
        "type": "integrations",
        "type_id":"",
        "state": "IL",
        "bin": "517246700",
        "payment_method": "card",
        "base_amount": 1000
}' { url goes here }/api/api/lookup/fees

{
  "status": "success",
  "msg": "success",
  "data": {
    "service_fee": 0,
    "payment_adjustment": {
      "value": 0,
      "type": ""
    },
    "requested_amount": 1350,
    "discount_amount": null,
    "surcharge": 350
  }
}

Amount calculation

Request Method: POST

URL Endpoint: /api/calculate/amounts

Name	Type	Required	Default	Description
processor_id	string	true
subtotal	uint	true	null
amount	uint	if line_items or products not present	null
currency	string	true
payment_method	string	true		Can be 'card' or 'ach'
transaction_type	string	true		Can be 'verification', 'auth', 'sale', 'void', 'refund', 'credit'
products	array	if amount or line_items not present	null
products[].id	string	true
products[].name	string	true
products[].description	string	false
products[].price	string	true
products[].local_tax	string	false
products[].national_tax	string	false
products[].fixed_amount	bool	false	false
products[].fixed_qty	bool	false	false
products[].unit_of_measure	string	false	null
line_items	array	if amount or products not present	null
line_items[].id	string	true
line_items[].status	string	true		Can be 'paid', 'pending', 'rejected'
line_items[].type	string	true		Can be 'flat' or 'percentage'
line_items[].name	string	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
line_items[].description	string	false	false	If true, the calculated amount will be added to the total amount
line_items[].unit_price	int	true
line_items[].quantity	float64	true
line_items[].quantity_shipped	float64	false
line_items[].product_code	string	false
line_items[].commodity_code	string	false
line_items[].unit_of_measure	string	false
line_items[].alternate_tax_identifier	string	false
line_items[].taxable	bool	false	false
line_items[].local_tax_rate	string	false		Format is 10.25
line_items[].national_tax_rate	string	false		Format is 10.25
line_items[].tax_rate	string	false		Format is 10.25
line_items[].discount_amount	uint	false
line_items[].freight_amount	uint	false
line_items[].discount_rate	string	false
processor_payment_adjustment	object	false	null
processor_payment_adjustment.type	string	true		Can be 'flat' or 'percentage'
processor_payment_adjustment.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
processor_payment_adjustment.include	bool	false	false	If true, the calculated amount will be added to the total amount
shipping_amount	object	false	null
shipping_amount.type	string	true		Can be 'flat' or 'percentage'
shipping_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
shipping_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
addon_amount	array	false	null
addon_amount[].type	string	true		Can be 'flat' or 'percentage'
addon_amount[].value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
addon_amount[].include	bool	false	false	If true, the calculated amount will be added to the total amount
discount_amount	array	false	null
discount_amount[].type	string	true		Can be 'flat' or 'percentage'
discount_amount[].value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
discount_amount[].include	bool	false	false	If true, the calculated amount will be added to the total amount
duty_amount	object	false	null
duty_amount.type	string	true		Can be 'flat' or 'percentage'
duty_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
duty_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
tip_amount	object	false	null
tip_amount.type	string	true		Can be 'flat' or 'percentage'
tip_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
tip_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
additional_amounts	array	false	null
additional_amounts[].type	string	true		Can be 'flat' or 'percentage'
additional_amounts[].value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
additional_amounts[].include	bool	false	false	If true, the calculated amount will be added to the total amount
tax_amount	object	false	null
tax_amount.type	string	true		Can be 'flat' or 'percentage'
tax_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
tax_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
national_tax_amount	object	false	null
national_tax_amount.type	string	true		Can be 'flat' or 'percentage'
national_tax_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
national_tax_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
local_tax_amount	object	false	null
local_tax_amount.type	string	true		Can be 'flat' or 'percentage'
local_tax_amount.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
local_tax_amount.include	bool	false	false	If true, the calculated amount will be added to the total amount
service_fee	object	false	null
service_fee.type	string	true		Can be 'flat' or 'percentage'
service_fee.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
service_fee.include	bool	false	false	If true, the calculated amount will be added to the total amount
surcharge	object	false	null
surcharge.type	string	true		Can be 'flat' or 'percentage'
surcharge.value	uint	true		If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
surcharge.include	bool	false	false	If true, the calculated amount will be added to the total amount
cc_bin	string	if surcharge allowed	null
country	string	if surcharge allowed	null
state	string	if surcharge allowed	null
flags	object	false
flags.skip_cash_discount	bool	false	false	If true, skips the cash discount calculation
flags.skip_surcharge	bool	false	false	If true, skips the cash surcharge calculation
flags.skip_service_fee	bool	false	false	If true, skips the cash service fee calculation
flags.skip_consumer_choice	bool	false	false	If true, skips the cash consumer choice calculation
flags.include_default_tax_to_total	bool	false	null	If true, and tax has not been overridden, the merchant's default tax amount will be added to the total amount
flags.tax_exempt	bool	false	null	If true, sets the national, local and tax amount fields to 0
flags.processor_surcharge_fallback	bool	false	false	If true, processor's surcharge fallback will be available
flags.add_tax_to_total	bool	false	null	If true, the tax will be added to the total amount
source	string	false

Workflow:

1. Call the Amount calculation endpoint with the properly filled request
2. Take the response of the Amount calculation and place it into the Transaction Request into the amounts field and fill the other fields of the request
3. Submit the transaction with the pre-calculated amounts

➜  ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
    "processor_id": "<processor id>",
    "amount" : 1000,
    "subtotal" : 1000,
    "currency": "USD",
    "payment_method": "card",
    "transaction_type": "sale"
}' { url goes here }/api/calculate/amounts

{
  "status": "success",
  "msg": "success",
  "data": {
    "line_items": null,
    "shipping_amount": null,
    "discount_amount": null,
    "freight_amount": null,
    "addon_amount": null,
    "duty_amount": null,
    "tip_amount": null,
    "additional_amounts": null,
    "tax_amount": 180,
    "national_tax_amount": null,
    "local_tax_amount": null,
    "service_fee": 350,
    "surcharge": null,
    "processor_id": "<processor id>",
    "payment_method": "card",
    "included_amounts": {
      "shipping_amount": null,
      "discount_amount": null,
      "duty_amount": null,
      "tip_amount": null,
      "tax_amount": 180,
      "national_tax_amount": null,
      "local_tax_amount": null,
      "service_fee": 350,
      "surcharge": null
    },
    "subtotal": 1000,
    "amount": 1000,
    "additional_total": 0,
    "total": 1530,
    "features": {
      "surcharge": false,
      "cash_discount": false,
      "dual_pricing": false,
      "dual_pricing_v2": false
    },
    "display": {
      "subtotal": {
        "value": 1000,
        "display": true
      },
      "amount": {
        "value": 1000,
        "display": true
      },
      "shipping": {
        "value": 0,
        "display": false
      },
      "freight": {
        "value": 0,
        "display": false
      },
      "duty": {
        "value": 0,
        "display": false
      },
      "discount": {
        "value": 0,
        "display": false
      },
      "service_fee": {
        "value": 350,
        "display": true
      },
      "surcharge": {
        "value": 0,
        "display": false
      },
      "tax": {
        "value": 180,
        "display": true
      },
      "national_tax": {
        "value": 0,
        "display": false
      },
      "local_tax": {
        "value": 0,
        "display": false
      },
      "tip": {
        "value": 0,
        "display": false
      },
      "total": {
        "value": 1530,
        "display": true
      },
      "consumer_choice": {
        "card": 0,
        "ach": 0,
        "display": false
      }
    },
    "disclaimer": {
      "text": "",
      "html": "",
      "display": false
    }
  }
}

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	Processor Definition	Description
0	Unknown	Unknown, please contact support for more information
99	Pending payment	Used in redirect processors prior to payment being received
100	Approved	Transaction was successfully approved
110	Partial approval	Transaction was successfully approved, but for a lesser amount
200 - 299	Decline	Transaction has been declined by the issuer for various reasons
300 - 399	Gateway Decline	Platform decline for configuration or fraud reasons
400 - 499	Transaction error returned by processor	Errors returned from the processor

AVS Response Codes

Address verification response codes (AVS)

AVS Response Code	Definition	Code Applies to	Card Brands
0	AVS Not Available	Domestic + International	V, MC, AX, D, PP, JCB
A	Address match only	Domestic + International	V, AX, D,PP, JCB
B	Address matches, ZIP not verified	Domestic + International	V
C	Incompatible format	Domestic + International	V
D	Exact match	International	V
F	Exact match, UK-issued cards	Domestic + International	V
G	Non-U.S. Issuer does not participate	International	V
I	Not verified	International	V, D, PP, JCB
M	Exact match	International	V
N	No address or ZIP match	Domestic + International	V, MC, AX, D, PP, JCB
P	Postal Code match	Domestic + International	V
R	Issuer system unavailable	Domestic	V, MC, AX, D, PP, JCB
S	Service not supported	Domestic	MC, AX, D, PP, JCB
U	Address unavailable	Domestic	V, MC, AX, D, PP, JCB
W	9-character numeric ZIP match only	Domestic + International (MC)	MC, D, PP, JCB
X	Exact match, 9-character numeric ZIP	Domestic + International (MC)	MC, D, PP, JCB
Y	Exact match, 5-character numeric ZIP	Domestic	V, MC, AX, D, PP, JCB
Z	5-character ZIP match only	Domestic + International (V)	V, MC, AX, D, PP, JCB
L	Partial match, Name and billing postal code match	For AMEX cards only	AX
1	Cardholder name and ZIP match	Domestic	AX
2	Cardholder name, address and ZIP match	Domestic	AX
3	Cardholder name and address match	Domestic	AX
4	Cardholder name matches	Domestic	AX
5	Cardholder name incorrect, ZIP matches	Domestic	AX
6	Cardholder name incorrect, address and zip match	Domestic	AX
7	Cardholder name incorrect, address matches	Domestic	AX
8	Cardholder name, address, and ZIP do not match	Domestic	AX

Get Transaction By ID

Retrieve details for a specific transaction.

Request Method: GET

URL Endpoint: /api/transaction/{ transaction ID }

{
  "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
}

Search Transactions

Retrieve details for all transactions that match provided search criteria.

Request Method: POST

URL Endpoint: /api/transaction/search

QuerySearchString: Operator can be =, !=

QuerySearchInt: Operator can be =, !=, <, >

Example Body
{
  "{name}": {
    "operator": "=", // =, !=, <, >
    "value": "{value}"
  }
}

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

Capture

Capture funds for a specified transaction that has already been authorized.

Request Method: POST

URL Endpoint: /api/transaction/{ transaction ID }/capture

Name	Type	Default	Description	Required
amount	integer	amount from auth	Total amount to capture, in cents. (1299 = $12.99)
tax_amount	integer	tax_amount from auth	Tax amount to capture, in cents. (199 = $1.99)
shipping_amount	integer	shipping_amount from auth	Shipping amount to capture, in cents. (299 = $2.99)
tax_exempt	boolean	false	Is the transaction tax exempt
order_id	string	order_id from auth	Alphanumeric (max 17 characters)
po_number	string	po_number from auth	Alphanumeric (max 17 characters)
ip_address	string	ip_address from auth	IPV4 or IPV6 address

Void / Auth Reversal

Void a transaction that is pending settlement. Where applicable, a void will be processed as an auth reversal.

Request Method: POST

URL Endpoint: /api/transaction/{ transaction ID }/void

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

Refund

Process a refund for a transaction that has already been settled. Multiple partial refunds can be processed, but the total amount of all refunds cannot exceed the previously settled amount.

Request Method: POST

URL Endpoint: /api/transaction/{ transaction ID }/refund

Name	Type	Default	Description	Required
amount	integer	amount from auth	Total amount to capture, in cents. (1299 = $12.99)
surcharge	integer	null	Surcharge amount, in cents. (1299 = $12.99)

Settlement Batches

Batch Terminal

You can settle individual terminals by sending a POST request to the following endpoint: /api/terminal/{terminalID}/settle

TIP

You can use batch_number to identify the batch number for a specific transaction.

For a terminal transaction you will get a BatchNum in the response in data->response_body->terminal->processor_specific->BatchNum

You can see an example in the terminal tab response Transaction

Search

Retrieve details for all settlement batches that match provided search criteria.

Request Method: POST

URL Endpoint: /api/settlement/batch/search

Name	Type	Default	Description	Required
batch_date	object		Object containing details defining a batch date range
batch_date     .start_date	string	""	Searches by batch_date between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ")
batch_date     .end_date	string	""	Searches by batch_date between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ")
settlement_batch_id	object		Object containing details defining a range of id's
settlement_batch_id     .operator	string literal		"=" or "!="
settlement_batch_id     .value	string		The settlement batch id to match or exclude
limit	integer	10	The number of results to return (1-100)
offset	integer	0	The number of results to skip (1-1000)

File Batch

Upload File

Upload a CSV file for batch processing.

TIP

CSV File Format

The input file for the upload endpoint should contain records to process in the following format (example below):

• First row should be a header using the fields below, fields can be in any order and not all fields are required.
• Each field should be wrapped in quotes and should not contain any quotes
• Each field should be seperated with a comma
• Each row should be terminated with a newline \n character.

Request Method: POST

URL Endpoint: /api/filebatch

Name	Type	Default	Description	Required
transaction_type	string		"verification", "authorize", "capture", "sale", "credit" or "refund"	*
cc_number	string		CC Number	if credit card
cc_expiration	string		CC Expiration Date	if credit card
cc_cvc	string		Optional unless your account requires CVC for processing
ach_account_number	string		ACH account number	if ACH
ach_routing_number	string		ACH routing number	if ACH
ach_account_type	string		"checking" or "savings"	if ACH
ach_sec_code	string		SEC code: "WEB", "CCD", or "PPD"	if ACH
customer_id	string		customer vault id to charge	if using customer vault
amount	integer		Total amount to process in cents (100 = $1.00)	*
shipping_amount	integer		Shipping amount to process in cents (100 = $1.00)
tax_amount	integer		Tax amount to process in cents (100 = $1.00)
discount_amount	integer		Discount amount to process in cents (100 = $1.00)
order_id	string		Alphanumeric string for reference (max 17 characters)
description	string		Alphanumeric string for notes (max 100 characters)
po_number	string		Alphanumeric string for reference (max 17 characters)
tax_exempt	boolean	false	is the transaction tax exempt
email_address	string		Email address to tag to the transaction, emails are not sent.
processor_id	string		Processor ID to process the transaction, otherwise the default is used.
billing_first_name	string
billing_last_name	string
billing_company	string
billing_address_line_1	string
billing_address_line_2	string
billing_city	string
billing_state	string
billing_postal_code	string
billing_country	string
billing_phone	string
billing_fax	string
billing_email	string
shipping_first_name	string
shipping_last_name	string
shipping_company	string
shipping_address_line_1	string
shipping_address_line_2	string
shipping_city	string
shipping_state	string
shipping_postal_code	string
shipping_country	string
shipping_phone	string
shipping_fax	string
shipping_email	string

Get Status

Get the current status of a specified settlement batch.

Request Method: GET

URL Endpoint: /api/filebatch/{ batch id }

function getBatchStatus(batchId) {
  var myHeaders = new Headers();

  myHeaders.append("Authorization", apiKey);

  myHeaders.append("Content-Type", "application/json");

  var requestOptions = {
    method: "GET",

    headers: myHeaders,
  };

  fetch("https://sandbox.gosparrowone.com/api/filebatch/" + batchId, requestOptions)
    .then((response) => response.text())

    .then((result) => {
      if (result.status === "success") {
        // handle success

        var message = result.msg;
      } else {
        // handle non success
      }
    })

    .catch((error) => console.log("error", error));
}

Download File

Returns a CSV text response for the specified batch.

Request Method: GET

URL Endpoint: /api/filebatch/{ batch id }/download

function downloadBatchFile(batchId) {
  var myHeaders = new Headers();

  myHeaders.append("Authorization", apiKey);

  myHeaders.append("Content-Type", "application/json");

  var requestOptions = {
    method: "GET",

    headers: myHeaders,
  };

  fetch(
    "https://sandbox.gosparrowone.com/api/filebatch/" + batchId + "/download",
    requestOptions
  )
    .then((response) => {
      if (response.ok) {
        return response.text().then((csvData) => {
          // return csv file.. csvData
        });
      } else {
        return response.text().then((result) => {
          var msg = result.msg;
        });
      }
    })

    .catch((error) => console.log("error", error));
}

Recurring

Add-Ons

Add-ons are used to adjust a recurring charge amount, either by a set amount or a percentage of the subscription amount.

Create Add-On

Create a new recurring plan add-on.

Request Method: POST

URL Endpoint: /api/recurring/addon

Name	Type	Default	Description	Required
name	string	""	Display name for the add-on
description	string	""	Description for the add-on
amount	integer	null	Amount to be added in cents (100 = $1.00)	* (see note below)
percentage	integer	null	Percentage of original charge to be added (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)	* (see note below)
duration	integer	0	Number of times for the add-on to be billed (use 0 if you want the add-on to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Get Add-On By ID

Retrieve details for the specified add-on.

Request Method: GET

URL Endpoint: /api/recurring/addon/{ add-on id }

{
  "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"
  }
}

Get All Add-Ons

Retrieve details for all add-ons accosciated with the gateway account.

Request Method: GET

URL Endpoint: /api/recurring/addons

{
  "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
}

Update Add-On

Edit details for the specified add-on.

Request Method: POST

URL Endpoint: /api/recurring/addon/{ add-on id }

Name	Type	Default	Description	Required
name	string	""	Display name for the add-on
description	string	""	Description for the add-on
amount	integer	null	Amount to be added in cents (100 = $1.00)	* (see note below)
percentage	integer	null	Percentage of original charge to be added (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)	* (see note below)
duration	integer	0	Number of times for the add-on to be billed (use 0 if you want the subscription to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Delete Add-On

Delete the specified add-on.

Request Method: DELETE

URL Endpoint: /api/recurring/addon/{ add-on id }

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

Discounts

Create Discount

Create 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.

Request Method: POST

URL Endpoint: /api/recurring/discount

Name	Type	Default	Description	Required
name	string	""	Display name for the discount
description	string	""	Description for the discount
amount	integer	null	Amount to be discounted in cents (100 = $1.00)	* (see note below)
percentage	integer	null	Percentage of original charge to be discounted (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)	* (see note below)
duration	integer	0	Number of times for the discount to be billed (use 0 if you want the discount to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Get Discount By ID

Retrieve details for the specified discount.

Request Method: GET

URL Endpoint: /api/recurring/discount/{ discount id }

{
  "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"
  }
}

Get All Discounts

Retrieve the properties of all discounts for the gateway account associated with the API Key or JWT token provided in the Authorization header.

Request Method: GET

URL Endpoint: /api/recurring/discounts

{
  "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
}

Update Discount

Edit details for the specified discount.

Request Method: POST

URL Endpoint: /api/recurring/discount/{ discount id }

Name	Type	Default	Description	Required
name	string	""	Display name for the discount
description	string	""	Description for the discount
amount	integer	null	Amount to be discounted in cents (100 = $1.00)	* (see note below)
percentage	integer	null	Percentage of original charge to be discounted (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)	* (see note below)
duration	integer	0	Number of times for the discount to be billed (use 0 if you want the discount to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Delete Discount

Delete the specified discount.

Request Method: DELETE

URL Endpoint: /api/recurring/discount/{ discount id }

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

Plans

Create Plan

Creates a new recurring plan with discounts and/or add-ons.

Request Method: POST

URL Endpoint: /api/recurring/plan

Name	Type	Default	Description	Required
name	string	""	Display name for the plan	*
description	string	""	Description for the plan
amount	integer	null	Amount to be billed in cents (100 = $1.00)	*
billing_cycle_interval	integer	null	How often to run the billing cycle (run every X months)	*
billing_frequency	string literal	"monthly"	How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily")	*
billing_days	string	null	Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".	*
charge_on_day	boolean	false	If true, this will set the billing day to the current day
duration	integer	0	Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled)
add_ons	array of objects		Enumerates add-ons for a recurring plan
add_ons[#]     .id	string		ID of the referenced add_on
add_ons[#]     .name	string		Display name for the add_on (optional, this overrides the add_ons value)
add_ons[#]     .description	string		Description for the add_on (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 add_on to be billed (optional, this overrides the add_ons value)
discounts	array of objects		Enumerates discounts for a recurring plan
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 Plan By ID

Retrieve details for the specified plan.

Request Method: GET

URL Endpoint: /api/recurring/plan/{ plan id }

{
  "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"
  }
}

Get All Plans

Retrieve the properties of all plans for the gateway account associated with the API Key or JWT token provided in the Authorization header.

Request Method: GET

URL Endpoint: /api/recurring/plans

{
  "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
}

Update Plan

Edit details for the specified plan.

Request Method: POST

URL Endpoint: /api/recurring/plan/{ plan id }

Name	Type	Default	Description	Required
name	string	""	Display name for the plan	*
description	string	""	Description for the plan
amount	integer	null	Amount to be billed in cents (100 = $1.00)	*
billing_cycle_interval	integer	null	How often to run the billing cycle (run every X months)	*
billing_frequency	string literal	"monthly"	How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily")	*
billing_days	string	null	Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".	*
charge_on_day	boolean	false	If true, this will set the billing day to the current day
duration	integer	0	Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled)
add_ons	array of objects		Enumerates add-ons for a recurring plan
add_ons[#]     .id	string		ID of the referenced add_on
add_ons[#]     .name	string		Display name for the add_on (optional, this overrides the add_ons value)
add_ons[#]     .description	string		Description for the add_on (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 add_on to be billed (optional, this overrides the add_ons value)
discounts	array of objects		Enumerates discounts for a recurring plan
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)
update_subscriptions	boolean	false	If true, this will update the amount for all subscriptions that have this plan ID

Delete Plan

Delete the specified plan.

Request Method: DELETE

URL Endpoint: /api/recurring/plan/{ plan id }

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

Subscriptions

Create Subscription

Creates a new subscription which applies a recurring billing plan to a customer.

Request Method: POST

URL Endpoint: /api/recurring/subscription

Name	Type	Default	Description	Required
plan_id	string	""	ID of the plan being subscribed to
description	string	""	Description for the subscription
customer	object		Object containing details for the customer being subscribed to the plan
customer     .id	string		ID for the customer being subscribed to the billing plan	*
customer     .payment_method_type	string	default payment method type	"card" or "ach"
customer     .payment_method_id	string	default payment method id	ID of the customer's saved payment method to use for the billing plan	required if payment_method_type is present
customer     .billing_address_id	string	default billing address	ID of the customer's saved billing address to use for the billing plan
customer     .shipping_address_id	string	default shipping address	ID of the customer's saved shipping address to use for the billing plan
amount	integer	null	Amount to be billed in cents (100 = $1.00)	*
billing_cycle_interval	integer	null	How often to run the billing cycle (run every X months)	*
billing_frequency	string literal	"monthly"	How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily")	*
billing_days	string	null	Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".	*
charge_on_day	boolean	false	If true, this will set the billing day to the current day
duration	integer	0	Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled)
next_bill_date	string "YYYY-MM-DD"		The date of the next time the billing plan will be processed
add_ons	array of objects		Enumerates add-ons for a recurring subscription
add_ons[#]     .id	string		ID of the referenced add_on
add_ons[#]     .name	string		Display name for the add_on (optional, this overrides the add_ons value)
add_ons[#]     .description	string		Description for the add_on (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 add_on to be billed (optional, this overrides the add_ons value)
discounts	array of objects		Enumerates discounts for a recurring subscription
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 Subscription By ID

Retrieve details for the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89gftaj8m0oft7upk80",
    "plan_id": "b89g35qj8m0o735i19jg",
    "description": "some description to describe the subscription",
    "customer": {
      "id": "b81ko5qq9qq5v460r9i0",
      "payment_method_type": "card",
      "payment_method_id": "b81ko5qq9qq5v460r9i0",
      "billing_address_id": "b81ko5qq9qq5v460r9i0",
      "shipping_address_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"
  }
}

Update Subscription

Edit details for the specified subscription.

Request Method: POST

URL Endpoint: /api/recurring/subscription/{ subscription id }

Name	Type	Default	Description	Required
plan_id	string	""	ID of the plan being subscribed to
description	string	""	Description for the subscription
customer	object		Object containing details for the customer being subscribed to the plan
customer     .id	string		ID for the customer being subscribed to the billing plan	*
customer     .payment_method_type	string	default payment method type	"card" or "ach"
customer     .payment_method_id	string	default payment method id	ID of the customer's saved payment method to use for the billing plan	required if payment_method_type is present
customer     .billing_address_id	string	default billing address	ID of the customer's saved billing address to use for the billing plan
customer     .shipping_address_id	string	default shipping address	ID of the customer's saved shipping address to use for the billing plan
amount	integer	null	Amount to be billed in cents (100 = $1.00)	*
billing_cycle_interval	integer	null	How often to run the billing cycle (run every X months)	*
billing_frequency	string literal	"monthly"	How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily")	*
billing_days	string	null	Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".	*
charge_on_day	boolean	false	If true, this will set the billing day to the current day
duration	integer	0	Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled)
next_bill_date	string "YYYY-MM-DD"		The date of the next time the billing plan will be processed
add_ons	array of objects		Enumerates add-ons for a recurring subscription
add_ons[#]     .id	string		ID of the referenced add_on
add_ons[#]     .name	string		Display name for the add_on (optional, this overrides the add_ons value)
add_ons[#]     .description	string		Description for the add_on (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 add_on to be billed (optional, this overrides the add_ons value)
discounts	array of objects		Enumerates discounts for a recurring subscription
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)

Pause Subscription

Pause the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/paused

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "paused",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T20:45:50.953717Z",
    "charge_on_day": false
  }
}

Mark Subscription Past Due

Mark the specified subscription as past due.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/past_due

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cnb14e3ug2jpf9mtp6k0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "past_due",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-21",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-21T15:09:45Z",
    "updated_at": "2024-02-21T15:13:03.001456Z",
    "charge_on_day": false
  }
}

Cancel Subscription

Cancel the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/cancelled

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "cancelled",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T21:05:39.561726Z",
    "charge_on_day": false
  }
}

Activate Subscription

Activate the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/active

Query Params

Name	Default	Description
next_bill_date		Date in 'YYYY-MM-DD' format

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "active",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T21:10:36.976006Z",
    "charge_on_day": false
  }
}

Complete Subscription

Complete the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/completed

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "completed",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T21:25:01.161503Z",
    "charge_on_day": false
  }
}

Delete Subscription

Delete the specified subscription.

Request Method: DELETE

URL Endpoint: /api/recurring/subscription/{ subscription id }

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

Terminals

All transaction requests should be processed via the /transaction endpoint referencing the specific terminal to handle the request. Please see the Processing a Transaction section for more information.

Get All Terminals

Retrieve all terminals associated with the gateway account. This will include inactive/disabled terminals as well.

Request Method: GET

URL Endpoint: /api/terminals

{
  "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"
    }
  ]
}

Invoices

TIP

The invoice ID will be set to the following fields on a transaction when paid:

• Order ID
• PO number

This will allow you to look up a transaction by an invoice ID and vice versa. If you set the invoice number field on an invoice, then the transaction order ID field will be this invoice number in place of the invoice ID.

Create Invoice

Create a new invoice.

Request Method: POST

URL Endpoint: /api/invoice

Name	Type	Default	Description	Required
currency	string literal		Currency that invoice amounts should be in ("USD", etc.)	*
company_name	string		Name of company issuing the invoice
company_logo_url	string		Hosted location of logo image to include on invoice
customer_number	string		Optional identifier for the invoiced customer to match merchant records
customer_id	string		ID of the saved customer being invoiced (must be a valid customer id if included)
invoice_number	string		Optional identifier for the invoice to match merchant records
payable_to	object		object containing details for the person the invoice is being paid to	*
payable_to     .id	string		ID of the stored address you want to make the invoice payable to
payable_to     .first_name	string		First name
payable_to     .last_name	string		Last name
payable_to     .company	string		Company name
payable_to     .address_line_1	string		Address line 1	*
payable_to     .address_line_2	string		Address line 2
payable_to     .city	string		City	*
payable_to     .state	string literal		State, in 2-character format ("KS", "QC", etc.))	*
payable_to     .postal_code	string		Postal code (must be a valid postal code for the country provided)	*
payable_to     .country	string literal		Country, in 2-character format ("US", "CA", "MX", etc.)	*
payable_to     .phone	string		Phone number
payable_to     .fax	string		Fax number
payable_to     .email	string		Email address (must be valid email format, "example@mail.com")
bill_to	object		object containing details for the person the invoice is being billed to	*
bill_to     .id	string		ID of the stored address you want to make the invoice billable to
bill_to     .first_name	string		First name
bill_to     .last_name	string		Last name
bill_to     .company	string		Company name
bill_to     .address_line_1	string		Address line 1	*
bill_to     .address_line_2	string		Address line 2
bill_to     .city	string		City	*
bill_to     .state	string literal		State, in 2-character ("KS", "QC", etc.)format	*
bill_to     .postal_code	string		Postal (must be a valid postal code for the country provided) code	*
bill_to     .country	string literal		Country, in 2-character ("US", "CA", "MX", etc.) format	*
bill_to     .phone	string		Phone number
bill_to     .fax	string		Fax number
bill_to     .email	string		Email address (must be valid email format, "example@mail.com")
date_due	datetime string		Date the invoice is due ("2021-02-13T06:00:00.000Z")by	*
items[#]	object array		array containing line items included in the invoice	*
items[#]     .status	string literal		"pending" or "paid"	*
items[#]     .type	string	""	Type of item
items[#]     .name	string	""	Name of item
items[#]     .description	string	""	Description of item
items[#]     .unit_price	integer		Unit price of item	*
items[#]     .quantity	integer		Quantity of item	*
items[#]     .quantity_shipped	integer	0	Quantity of items shipped to customer
items[#]     .product_code	string	""	Product Code of item
items[#]     .commodity_code	string	""	Commodity Code of item
items[#]     .unit_of_measure	string	""	Unit of measure of item ("lb", "kg", etc.)
items[#]     .alternate_tax_identifier	string	""	Alternate tax ID for item
items[#]     .taxable	boolean	false	Whether local and national tax should be applied at the item level rather than the invoice level
items[#]     .local_tax_rate	string	""	Local tax rate for item ("1.000")
items[#]     .local_tax	integer	0	Local tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .national_tax_rate	string	""	National tax rate for item ("1.000")
items[#]     .national_tax	integer	0	National tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .tax_rate	string	""	Combined tax rate for item (local tax + national tax)
items[#]     .tax_amount	integer	0	Tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .discount_amount	integer	0	Discount to take off the item's total amount, expressed in cents (100 = $1.00))
items[#]     .freight_amount	integer	0	Freight amount to add to the item's total, expressed in cents (100 = $1.00)
advanced_fields	boolean	false	Whether or not to include additional fields for line items (advanced fields include quantity_shipped, freight_amount, unit_of_measure, taxable, local_tax_rate, local_tax, national_tax_rate, national_tax)
enable_tax	boolean	false	Whether or not to enable tax (if enabled, tax applied at the invoice level will override taxes applied at the item level)
enable_shipping	boolean	false	Whether or not to enable shipping
require_shipping_details	boolean	false	Whether or not to require shipping details
require_billing_details_on_payment_only	boolean	false	Whether or not to require billing details only at time of payment
tax_percent	string		Tax rate to apply to invoice total if enable_tax is true. A rate of "0.000" will cause tax to be read as a flat amount.	*
tax	integer	calculated amount	Total tax amount of the invoice, expressed in cents (100 = $1.00). If tax_percent is included and is not "0", this field will be overridden with the calculated amount.
shipping	integer	calculated amount	Shipping amount of the invoice, expressed in cents (100 = $1.00)
amount_paid	integer	calculated amount	Amount of the invoice that has already been paid, expressed in cents (100 = $1.00)
service_fees_paid	integer	calculated amount	Service fee amount that has already been paid, expressed in cents (100 = $1.00)
surcharge_paid	integer	calculated amount	Surcharge amount that has already been paid, expressed in cents (100 = $1.00)
discount_credited	integer	calculated amount	Discount amount that has already been credited, expressed in cents (100 = $1.00)
adjustment	integer	0	Apply a payment adjustment to the total amount of the invoice, expressed in cents (100 = $1.00)
allow_partial_payment	boolean	false	Whether or not to allow partial payment of the amount due
transaction_type	string literal	"sale"	"sale" or "authorize"
payment_methods[#]	string array		Allowable payment method types ("card", "ach", and/or "mail")	*
card_processor_id (can be "")	string		ID of the payment processor to use for credit card payments	*
ach_processor_id (can be "")	string		ID of the payment processor to use for ACH payments	*
message	string		Message for customers viewing the invoice
send_via	string literal		How to send invoice notifications ("email", "text", "both", or "none")	*
email_to	string		Email address (must be valid email format, "xxxxx@xxxxx.xxx")

Get Invoice By ID

Retrieve details for the specified invoice.

Request Method: GET

URL Endpoint: /api/invoice/{ invoice id }

{
  "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"
  }
}

Search Invoices

Retrieve details for all invoices that match provided search criteria.

Request Method: POST

URL Endpoint: /api/invoices/search

Name	Type	Description
id	object	Object containing details for searching by id
id     .operator	string literal	"=" or "!="
id     .value	string	invoice id to match or exclude
amount_due	object	Object containing details for searching by amount_due
amount_due     .operator	string literal	"=", "!=", "<", or ">"
amount_due     .value	integer	amount to match or exclude
date_due	object	Object containing details for searching by date_due
date_due     .start_date	date string	Searches by date_due between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ")
date_due     .end_date	date string	Searches by date_due between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ")
limit	integer	Maximum records to return (0-100)
offset	integer	Number of records to offset the return by

Update Invoice

Update an existing invoice.

Request Method: POST

URL Endpoint: /api/invoice/{ invoice id }

Name	Type	Default	Description	Required
currency	string literal		Currency that invoice amounts should be in ("USD", etc.)	*
company_name	string		Name of company issuing the invoice
company_logo_url	string		Hosted location of logo image to include on invoice
customer_number	string		Optional identifier for the invoiced customer to match merchant records
customer_id	string		ID of the saved customer being invoiced (must be a valid customer id if included)
invoice_number	string		Optional identifier for the invoice to match merchant records
payable_to	object		object containing details for the person the invoice is being paid to	*
payable_to     .id	string		ID of the stored address you want to make the invoice payable to
payable_to     .first_name	string		First name
payable_to     .last_name	string		Last name
payable_to     .company	string		Company name
payable_to     .address_line_1	string		Address line 1	*
payable_to     .address_line_2	string		Address line 2
payable_to     .city	string		City	*
payable_to     .state	string literal		State, in 2-character format ("KS", "QC", etc.))	*
payable_to     .postal_code	string		Postal code (must be a valid postal code for the country provided)	*
payable_to     .country	string literal		Country, in 2-character format ("US", "CA", "MX", etc.)	*
payable_to     .phone	string		Phone number
payable_to     .fax	string		Fax number
payable_to     .email	string		Email address (must be valid email format, "example@mail.com")
bill_to	object		object containing details for the person the invoice is being billed to	*
bill_to     .id	string		ID of the stored address you want to make the invoice billable to
bill_to     .first_name	string		First name
bill_to     .last_name	string		Last name
bill_to     .company	string		Company name
bill_to     .address_line_1	string		Address line 1	*
bill_to     .address_line_2	string		Address line 2
bill_to     .city	string		City	*
bill_to     .state	string literal		State, in 2-character ("KS", "QC", etc.)format	*
bill_to     .postal_code	string		Postal (must be a valid postal code for the country provided) code	*
bill_to     .country	string literal		Country, in 2-character ("US", "CA", "MX", etc.) format	*
bill_to     .phone	string		Phone number
bill_to     .fax	string		Fax number
bill_to     .email	string		Email address (must be valid email format, "example@mail.com")
date_due	datetime string		Date the invoice is due ("2021-02-13T06:00:00.000Z")by	*
items[#]	object array		array containing line items included in the invoice	*
items[#]     .status	string literal		"pending" or "paid"	*
items[#]     .type	string	""	Type of item
items[#]     .name	string	""	Name of item
items[#]     .description	string	""	Description of item
items[#]     .unit_price	integer		Unit price of item	*
items[#]     .quantity	integer		Quantity of item	*
items[#]     .quantity_shipped	integer	0	Quantity of items shipped to customer
items[#]     .product_code	string	""	Product Code of item
items[#]     .commodity_code	string	""	Commodity Code of item
items[#]     .unit_of_measure	string	""	Unit of measure of item ("lb", "kg", etc.)
items[#]     .alternate_tax_identifier	string	""	Alternate tax ID for item
items[#]     .taxable	boolean	false	Whether local and national tax should be applied at the item level rather than the invoice level
items[#]     .local_tax_rate	string	""	Local tax rate for item ("1.000")
items[#]     .local_tax	integer	0	Local tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .national_tax_rate	string	""	National tax rate for item ("1.000")
items[#]     .national_tax	integer	0	National tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .tax_rate	string	""	Combined tax rate for item (local tax + national tax)
items[#]     .tax_amount	integer	0	Tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .discount_amount	integer	0	Discount to take off the item's total amount, expressed in cents (100 = $1.00))
items[#]     .freight_amount	integer	0	Freight amount to add to the item's total, expressed in cents (100 = $1.00)
advanced_fields	boolean	false	Whether or not to include additional fields for line items (advanced fields include quantity_shipped, freight_amount, unit_of_measure, taxable, local_tax_rate, local_tax, national_tax_rate, national_tax)
enable_tax	boolean	false	Whether or not to enable tax (if enabled, tax applied at the invoice level will override taxes applied at the item level)
enable_shipping	boolean	false	Whether or not to enable shipping
require_shipping_details	boolean	false	Whether or not to require shipping details
require_billing_details_on_payment_only	boolean	false	Whether or not to require billing details only at time of payment
tax_percent	string		Tax rate to apply to invoice total if enable_tax is true. A rate of "0.000" will cause tax to be read as a flat amount.	*
tax	integer	calculated amount	Total tax amount of the invoice, expressed in cents (100 = $1.00). If tax_percent is included and is not "0", this field will be overridden with the calculated amount.
shipping	integer	calculated amount	Shipping amount of the invoice, expressed in cents (100 = $1.00)
amount_paid	integer	calculated amount	Amount of the invoice that has already been paid, expressed in cents (100 = $1.00)
service_fees_paid	integer	calculated amount	Service fee amount that has already been paid, expressed in cents (100 = $1.00)
surcharge_paid	integer	calculated amount	Surcharge amount that has already been paid, expressed in cents (100 = $1.00)
discount_credited	integer	calculated amount	Discount amount that has already been credited, expressed in cents (100 = $1.00)
adjustment	integer	0	Apply a payment adjustment to the total amount of the invoice, expressed in cents (100 = $1.00)
amount_due	integer	calculated amount	Amount of the invoice that remains due, expressed in cents (100 = $1.00)
allow_partial_payment	boolean	false	Whether or not to allow partial payment of the amount due
transaction_type	string literal	"sale"	"sale" or "authorize"
payment_methods[#]	string array		Allowable payment method types ("card", "ach", and/or "mail")	*
card_processor_id (can be "")	string		ID of the payment processor to use for credit card payments	*
ach_processor_id (can be "")	string		ID of the payment processor to use for ACH payments	*
message	string		Message for customers viewing the invoice
send_via	string literal		How to send invoice notifications ("email", "text", "both", or "none")	*
email_to	string		Email address (must be valid email format, "xxxxx@xxxxx.xxx")

Delete Invoice

Delete the specified invoice.

Request Method: DELETE

URL Endpoint: /api/invoice/{ invoice id }

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

Customer Vault

TIP

This section describes the canonical methods for creating and managing Customer records. The endpoints described in the Customers (Deprecated) section are still available for use, but be advised that using endpoints from both groups in your application simultaneously can result in unintended behaviors.

Create Customer Record

Creates a new Customer record that can contain stored preferences, payment methods, and addresses.

Request Method: POST

URL Endpoint: /api/vault/customer

Name	Type	Default	Description	Required
id	string	generated value	Optionally, you may provide a custom id for storing the vaulted customer. Max 40 characters (a-z, A-Z, 0-9)
id_format	string literal		Optionally defines a format for the gateway to use when auto-generating an id ("xid_type_last4"). Cannot be used if providing a custom id.
description	string	""	Text field, max 255 characters
flags	string array	[]	Array containing flags for customer settings ("surcharge_exempt")
default_payment	object	null	Object containing ach payment method details
default_payment     .card	object	null	Object containing card payment method details
default_payment     .card         .number	string	""	Card number
default_payment     .card         .expiration_date	string	""	Card expiration date ("MMYY" or "MM/YY")	required if default_payment.card is present
default_payment     .ach	object	null	Object containing ach payment method details
default_payment     .ach         .account_number	string	""	Account number
default_payment     .ach         .routing_number	string	""	Routing number
default_payment     .ach         .account_type	string literal		Ach account type ("checking" or "savings")	required if default_payment.ach is present
default_payment     .ach         .sec_code	string literal		Ach sec code ("web", "ccd", or "ppd")	required if default_payment.ach is present
default_payment     .token	string		Payment method token generated by Tokenizer form
default_payment     .apple_pay	object	null	Object containing Apple Pay payment method details
default_payment     .apple_pay         .key_id	string	""	Merchant Apple Pay ID	required if default_payment.apple_pay is present
default_payment     .apple_pay         .processor_id	string	""	Processor ID
default_payment     .apple_pay         .temporary_token	string	""	Token from WalletJS response	required if using WalletJS
default_payment     .apple_pay         .pkpaymenttoken	object	null	PKPaymentToken from Apple Pay JS response	required if using Apple Pay JS
default_payment     .google_pay_token	object or string	null	Object or string containing a Google Pay token
default_billing_address	object	null	Object containing billing address details
default_billing_address     .first_name	string	""	Addressee first name
default_billing_address     .last_name	string	""	Addressee last name
default_billing_address     .company	string	""	Company name
default_billing_address     .line_1	string	""	Street address
default_billing_address     .line_2	string	""	Additional delivery details
default_billing_address     .city	string	""	City name
default_billing_address     .state	string	""	State code ("CA")
default_billing_address     .postal_code	string	""	Postal code ("12345")
default_billing_address     .country	string	""	Country code ("US")
default_billing_address     .email	string	""	Email address (must be valid email format, "example@mail.com")
default_billing_address     .phone	string	""	Phone number ("3216540987")
default_billing_address     .fax	string	""	("3216540987")
default_shipping_address	object	null	Object containing shipping address details
default_shipping_address     .first_name	string	""	Addressee first name
default_shipping_address     .last_name	string	""	Addressee last name
default_shipping_address     .company	string	""	Company name
default_shipping_address     .line_1	string	""	Street address
default_shipping_address     .line_2	string	""	Additional delivery details
default_shipping_address     .city	string	""	City name
default_shipping_address     .state	string	""	State code ("CA")
default_shipping_address     .postal_code	string	""	Postal code ("12345")
default_shipping_address     .country	string	""	Country code ("US")
default_shipping_address     .email	string	""	Email address (must be valid email format, "example@mail.com")
default_shipping_address     .phone	string	""	Phone number ("3216540987")
default_shipping_address     .fax	string	""	("3216540987")

Get Customer Record By ID

Retrieve details for the specified customer.

Request Method: GET

URL Endpoint: /api/vault/{ customer id }

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "952f250d-fa85-40ac-a45e-3886f98032c6",
    "owner_id": "testmerchant12345678",
    "data": {
      "customer": {
        "addresses": [
          {
            "city": "Some Town",
            "company": "Some Business",
            "country": "US",
            "email": "user@somesite.com",
            "fax": "555555555",
            "first_name": "John",
            "hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
            "id": "bl6nqk69ku6897l45fp0",
            "last_name": "Smith",
            "line_1": "",
            "line_2": "",
            "phone": "5555555555",
            "postal_code": "60187",
            "state": "IL"
          }
        ],
        "defaults": {
          "billing_address_id": "bl6nqk69ku6897l45fp0",
          "payment_method_id": "bl6nqk69ku6897l45fq0",
          "payment_method_type": "card",
          "shipping_address_id": "bl6nqk69ku6897l45fp0"
        },
        "description": "test description",
        "payments": {
          "ach": [],
          "cards": [
            {
              "card_type": "visa",
              "expiration_date": "2020-12-31T00:00:00Z",
              "id": "bl6nqk69ku6897l45fq0",
              "masked_number": "411111******1111"
            }
          ]
        }
      }
    },
    "created_at": "2019-08-09T09:04:00.786094073-05:00",
    "updated_at": "2019-08-09T09:04:00.786094116-05:00"
  }
}

Search Customer Records

Retrieve details for all customer records that match provided search criteria.

Request Method: POST

URL Endpoint: /api/vault/customer/search

Name	Type	Default	Description	Required
id	object		Object containing details defining a customer id to match or exclude
id     .value	string	""	Customer record ID to match or exclude
id     .operator	string	""	"=" or "!="
address_id	object		Object containing details defining an address id to match or exclude
address_id     .value	string	""	Address ID to match or exclude
address_id     .operator	string	""	"=" or "!="
first_name	object		Object containing details defining a customer first name to match or exclude
first_name     .value	string	""	Customer first name to match or exclude
first_name     .operator	string	""	"=" or "!="
last_name	object		Object containing details defining a customer last name to match or exclude
last_name     .value	string	""	Customer last name to match or exclude
last_name     .operator	string	""	"=" or "!="
company	object		Object containing details defining a company name to match or exclude
company     .value	string	""	Customer company to match or exclude
company     .operator	string	""	"=" or "!="
address_line_1	object		Object containing details defining a street address to match or exclude
address_line_1     .value	string	""	Customer street address to match or exclude
address_line_1     .operator	string	""	"=" or "!="
address_line_2	object		Object containing details defining additional address details to match or exclude
address_line_2     .value	string	""	Customer address details to match or exclude
address_line_2     .operator	string	""	"=" or "!="
city	object		Object containing details defining a city to match or exclude
city     .value	string	""	Customer city to match or exclude
city     .operator	string	""	"=" or "!="
state	object		Object containing details defining a state to match or exclude
state     .value	string	""	Customer state to match or exclude
state     .operator	string	""	"=" or "!="
postal_code	object		Object containing details defining a postal code to match or exclude
postal_code     .value	string	""	Customer postal code to match or exclude
postal_code     .operator	string	""	"=" or "!="
country	object		Object containing details defining a country to match or exclude
country     .value	string	""	Customer country to match or exclude
country     .operator	string	""	"=" or "!="
email	object		Object containing details defining a customer email to match or exclude
email     .value	string	""	Customer email to match or exclude
email     .operator	string	""	"=" or "!="
phone	object		Object containing details defining a phone number to match or exclude
phone     .value	string	""	Customer phone to match or exclude
phone     .operator	string	""	"=" or "!="
fax	object		Object containing details defining a fax number to match or exclude
fax     .value	string	""	Customer fax to match or exclude
fax     .operator	string	""	"=" or "!="
payment_method_type	object		Object containing details defining a payment method type to match or exclude
payment_method_type     .value	string	""	Customer payment method type to match or exclude
payment_method_type     .operator	string	""	"=" or "!="
billing_address_id	object		Object containing details defining a billing address id to match or exclude
billing_address_id     .value	string	""	Customer billing address id to match or exclude
billing_address_id     .operator	string	""	"=" or "!="
shipping_address_id	object		Object containing details defining a shipping address id to match or exclude
shipping_address_id     .value	string	""	Customer shipping address id to match or exclude
shipping_address_id     .operator	string	""	"=" or "!="
created_at	object		Object containing details defining a date range to match
created_at     .start_date	string	""	Beginning of date range
created_at     .end_date	string	""	End of date range
updated_at	object		Object containing details defining a date range to match
updated_at     .start_date	string	""	Beginning of date range
updated_at     .end_date	string	""	End of date range
limit	integer	10	The number of results to return (1-100)
offset	integer	0	The number of results to skip (1-1000)

Update Customer Record

Update an existing customer record.

Request Method: POST

URL Endpoint: /api/vault/customer/{ customer id }

Name	Type	Default	Description	Required
description	string	""	Text field, max 255 characters
notes	string	""	Text field, max 255 characters
flags	string array	[]	Array containing flags for customer settings ("surcharge_exempt")
defaults	object	null	Object containing id's designating payment methods and addresses to be used as defaults for the customer's transactions
defaults     .billing_address_id	string	If only one stored address exists on the customer record, that will be used by default	Id of stored address to use as the default billing address for transactions
defaults     .shipping_address_id	string	If only one stored address exists on the customer record, that will be used by default	Id of stored address to use as the default shipping address for transactions
defaults     .payment_method_id	string		Id of stored payment method to use as the default payment method for transactions	required if defaults.payment_method_type is present
defaults     .payment_method_type	string literal	""	Type of the payment method id supplied ("card" or "ach")	required if defaults.payment_method_id is present

Delete Customer Record

Delete the specified customer record.

Request Method: DELETE

URL Endpoint: /api/vault/{ customer id }

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

Create Address Record

Create a new address record that will be stored within the customer record. A stored address can be used as the billing and/or shipping address on transactions processed for the customer.

Request Method: POST

URL Endpoint: /api/vault/customer/{ customer id }/address

Name	Type	Default	Description	Required
first_name	string	""	Addressee first name
last_name	string	""	Addressee last name
company	string	""	Company name
line_1	string	""	Street address
line_2	string	""	Additional delivery details
city	string	""	City name
state	string	""	State code ("CA")
postal_code	string	""	Postal code ("12345")
country	string	""	Country code ("US")
email	string	""	Email address (must be valid email format, "example@mail.com")
phone	string	""	Phone number ("3216540987")
fax	string	""	Fax number ("3216540987")

Get Address Record By ID

TIP

Address records cannot be fetched individually, please use the Get Customer Record By ID endpoint to retrieve the collection of address records for a specified customer.

Update Address Record

Update an existing address within a customer record.

Request Method: POST

URL Endpoint: /api/vault/customer/{ customer id }/address/{ address id }

Name	Type	Default	Description	Required
first_name	string	""	Addressee first name
last_name	string	""	Addressee last name
company	string	""	Company name
line_1	string	""	Street address
line_2	string	""	Additional delivery details
city	string	""	City name
state	string	""	State code ("CA")
postal_code	string	""	Postal code ("12345")
country	string	""	Country code ("US")
email	string	""	Email address (must be valid email format, "example@mail.com")
phone	string	""	Phone number ("3216540987")
fax	string	""	Fax number ("3216540987")

Delete Address Record

Delete the specified address within a customer record.

Request Method: DELETE

URL Endpoint: /api/vault/customer/{ customer id }/address/{ address id }

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

Create Payment Method Record

Create a new stored payment method on the specified customer record. The url endpoint and request body properties vary depending on the type of payment method being created.

Request Method: POST

Create Card - URL Endpoint: /api/vault/customer/{ customer id }/card

Create ACH - URL Endpoint: /api/vault/customer/{ customer id }/ach

Create Card or ACH with Token - URL Endpoint: /api/vault/customer/{ customer id }/token

Create Card with Apple Pay Token - URL Endpoint: /api/vault/customer/{ customer id }/applepay

Create Card with Google Pay Token - URL Endpoint: /api/vault/customer/{ customer id }/googlepay

Name	Type	Default	Description	Required
number	string	""	Card number
expiration_date	string	""	Card expiration date ("MMYY" or "MM/YY")	*

Create Payment Method Record Code Samples

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "952f250d-fa85-40ac-a45e-3886f98032c6",
    "owner_id": "testmerchant12345678",
    "data": {
      "customer": {
        "addresses": [
          {
            "city": "Some Town",
            "company": "Some Business",
            "country": "US",
            "email": "user@somesite.com",
            "fax": "555555555",
            "first_name": "John",
            "hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
            "id": "bl6nqk69ku6897l45fp0",
            "last_name": "Smith",
            "line_1": "",
            "line_2": "",
            "phone": "5555555555",
            "postal_code": "60187",
            "state": "IL"
          }
        ],
        "defaults": {
          "billing_address_id": "bl6nqk69ku6897l45fp0",
          "payment_method_id": "bl6nqk69ku6897l45fq0",
          "payment_method_type": "card",
          "shipping_address_id": "bl6nqk69ku6897l45fp0"
        },
        "description": "test description",
        "notes": "",
        "flags": ["surcharge_exempt"],
        "payments": {
          "ach": [],
          "cards": [
            {
              "card_type": "visa",
              "expiration_date": "2020-12-31T00:00:00Z",
              "id": "bl6nqk69ku6897l45fq0",
              "masked_number": "411111******1111"
            }
          ]
        }
      }
    },
    "created_at": "2019-08-09T09:04:00.786094073-05:00",
    "updated_at": "2019-08-09T09:04:00.786094116-05:00"
  }
}

Get Payment Method Record By ID

TIP

Payment method records cannot be fetched individually, please use the Get Customer Record By ID endpoint to retrieve the collection of payment method records for a specified customer.

Update Payment Method Record

Update an existing payment method within a customer record.

Request Method: POST

Update Card - URL Endpoint: /api/vault/customer/{ customer id }/card/{ payment method id }

Update ACH - URL Endpoint: /api/vault/customer/{ customer id }/ach/{ payment method id }

Update Token - URL Endpoint: /api/vault/customer/{ customer id }/token/{ payment method id }

Name	Type	Default	Description	Required
number	string	""	Card number
expiration_date	string	""	Card expiration date ("MMYY" or "MM/YY")	*
flags	array	[]	"surcharge_exempt", "applepay", "closed_contact", "contact", "locked_security", "locked_stop_recurring"

Update Payment Method Record Code Samples

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "952f250d-fa85-40ac-a45e-3886f98032c6",
    "owner_id": "testmerchant12345678",
    "data": {
      "customer": {
        "addresses": [
          {
            "city": "Some Town",
            "company": "Some Business",
            "country": "US",
            "email": "user@somesite.com",
            "fax": "555555555",
            "first_name": "John",
            "hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
            "id": "bl6nqk69ku6897l45fp0",
            "last_name": "Smith",
            "line_1": "",
            "line_2": "",
            "phone": "5555555555",
            "postal_code": "60187",
            "state": "IL"
          }
        ],
        "defaults": {
          "billing_address_id": "bl6nqk69ku6897l45fp0",
          "payment_method_id": "bl6nqk69ku6897l45fq0",
          "payment_method_type": "card",
          "shipping_address_id": "bl6nqk69ku6897l45fp0"
        },
        "description": "test description",
        "notes": "",
        "flags": ["surcharge_exempt"],
        "payments": {
          "ach": [],
          "cards": [
            {
              "card_type": "visa",
              "expiration_date": "2020-12-31T00:00:00Z",
              "id": "bl6nqk69ku6897l45fq0",
              "masked_number": "411111******1111"
            }
          ]
        }
      }
    },
    "created_at": "2019-08-09T09:04:00.786094073-05:00",
    "updated_at": "2019-08-09T09:04:00.786094116-05:00"
  }
}

Delete Payment Method Record

Delete the specified payment method within a customer record.

Request Method: DELETE

Delete Card - URL Endpoint: /api/vault/customer/{ customer id }/card/{ card id }

Delete ACH - URL Endpoint: /api/vault/customer/{ customer id }/ach/{ ach id }

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