# Composing 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.

# Users

# Create User

Create a new user account.

Request Method: POST

URL Endpoint: /api/user

    # Get User By ID

    Retrieve the properties of a specific user.

    Request Method: GET

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

      # Get Authenticated 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

        # 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

          # Update User

          Edit the properties of an existing user account.

          Request Method: POST

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

            # Delete User

            Delete a specific user.

            Request Method: DELETE

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

              # 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

                # Transactions

                # Process a Transaction

                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

                  # Process a Transaction - Code Samples

                    # 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 yes 6 - 19 digits of a card
                    payment_method string yes card
                    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.



                      # 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 }

                        # Search Transactions

                        Retrieve details for all transactions that match provided search criteria.

                        Request Method: POST

                        URL Endpoint: /api/transaction/search

                          # Capture

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

                          Request Method: POST

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

                            # 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

                              # 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

                                # Settlement Batches

                                # Search Settlement Batches

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

                                Request Method: POST

                                URL Endpoint: /api/settlement/batch/search

                                  # Upload Batch 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

                                    # Get Batch Status

                                    Get the current status of a specified settlement batch.

                                    Request Method: GET

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

                                      # Download Batch File

                                      Returns a CSV text response for the specified batch.

                                      Request Method: GET

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

                                        # Recurring

                                        # Create Add-On

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

                                        Request Method: POST

                                        URL Endpoint: /api/recurring/addon

                                          :::

                                          # Get Add-On By ID

                                          Retrieve details for the specified add-on.

                                          Request Method: GET

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

                                            # Get All Add-Ons

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

                                            Request Method: GET

                                            URL Endpoint: /api/recurring/addons

                                              # Update Add-On

                                              Edit details for the specified add-on.

                                              Request Method: POST

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

                                                :::

                                                # Delete Add-On

                                                Delete the specified add-on.

                                                Request Method: DELETE

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

                                                  # 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

                                                    :::

                                                    # Get Discount By ID

                                                    Retrieve details for the specified discount.

                                                    Request Method: GET

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

                                                      # 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

                                                        # Update Discount

                                                        Edit details for the specified discount.

                                                        Request Method: POST

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

                                                          :::

                                                          # Delete Discount

                                                          Delete the specified discount.

                                                          Request Method: DELETE

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

                                                            # Create Plan

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

                                                            Request Method: POST

                                                            URL Endpoint: /api/recurring/plan

                                                              # Get Plan By ID

                                                              Retrieve details for the specified plan.

                                                              Request Method: GET

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

                                                                # 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

                                                                  # Update Plan

                                                                  Edit details for the specified plan.

                                                                  Request Method: POST

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