# 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

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

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

                                                                    # Delete Plan

                                                                    Delete the specified plan.

                                                                    Request Method: DELETE

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

                                                                      # Create Subscription

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

                                                                      Request Method: POST

                                                                      URL Endpoint: /api/recurring/subscription

                                                                        # Get Subscription By ID

                                                                        Retrieve details for the specified subscription.

                                                                        Request Method: GET

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

                                                                          # Update Subscription

                                                                          Edit details for the specified subscription.

                                                                          Request Method: POST

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

                                                                            # Pause Subscription

                                                                            Pause the specified subscription.

                                                                            Request Method: GET

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

                                                                              # Mark Subscription Past Due

                                                                              Mark the specified subscription as past due.

                                                                              Request Method: GET

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

                                                                                # Cancel Subscription

                                                                                Cancel the specified subscription.

                                                                                Request Method: GET

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

                                                                                  # 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

                                                                                    # Complete Subscription

                                                                                    Complete the specified subscription.

                                                                                    Request Method: GET

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

                                                                                      # Delete Subscription

                                                                                      Delete the specified subscription.

                                                                                      Request Method: DELETE

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

                                                                                        # 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

                                                                                          # Invoices

                                                                                          # Create Invoice

                                                                                          Create a new invoice.

                                                                                          Request Method: POST

                                                                                          URL Endpoint: /api/invoice

                                                                                            # Get Invoice By ID

                                                                                            Retrieve details for the specified invoice.

                                                                                            Request Method: GET

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

                                                                                              # Search Invoices

                                                                                              Retrieve details for all invoices that match provided search criteria.

                                                                                              Request Method: POST

                                                                                              URL Endpoint: /api/invoices/search

                                                                                                # Update Invoice

                                                                                                Update an existing invoice.

                                                                                                Request Method: POST

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

                                                                                                  # Delete Invoice

                                                                                                  Delete the specified invoice.

                                                                                                  Request Method: DELETE

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

                                                                                                    # 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

                                                                                                      # Get Customer Record By ID

                                                                                                      Retrieve details for the specified customer.

                                                                                                      Request Method: GET

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

                                                                                                        # Search Customer Records

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

                                                                                                        Request Method: POST

                                                                                                        URL Endpoint: /api/vault/customer/search

                                                                                                          # Update Customer Record

                                                                                                          Update an existing customer record.

                                                                                                          Request Method: POST

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

                                                                                                            # Delete Customer Record

                                                                                                            Delete the specified customer record.

                                                                                                            Request Method: DELETE

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

                                                                                                              # 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

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

                                                                                                                  # Delete Address Record

                                                                                                                  Delete the specified address within a customer record.

                                                                                                                  Request Method: DELETE

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

                                                                                                                    # 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 Payment Method Record Code Samples

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

                                                                                                                          # Update Payment Method Record Code Samples

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

                                                                                                                              # Customers (Deprecated)

                                                                                                                              WARNING

                                                                                                                              This section has been deprecated and is no longer under active development. Please see the Customer Vault section for the most up to date methods for managing customers.

                                                                                                                              # Create Customer (Deprecated)

                                                                                                                              Create a new customer.

                                                                                                                              Request Method: POST

                                                                                                                              URL Endpoint: /api/customer

                                                                                                                              Query Params

                                                                                                                              Name Default Description
                                                                                                                              validate "false" passing "true" will cause credit cards to have a $0 verification processed

                                                                                                                                # Get Customer By ID (Deprecated)

                                                                                                                                Retrieve details for the specified customer.

                                                                                                                                Request Method: GET

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

                                                                                                                                  # Search Customers (Deprecated)

                                                                                                                                  Retrieve details for all customers that match provided search criteria.

                                                                                                                                  Request Method: POST

                                                                                                                                  URL Endpoint: /api/customer/search

                                                                                                                                    # Update Customer (Deprecated)

                                                                                                                                    Edit details for the specified customer. If you have used the Create Customer Payment Method Token (Deprecated) endpoint to create a payment method token, or the Create Customer Address Token (Deprecated) endpoint to create an address token, the id's of those stored items can be supplied here to be set as the default payment method and billing/shipping addresses when a transaction is processed against the customer.

                                                                                                                                    Request Method: POST

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

                                                                                                                                      # Delete Customer (Deprecated)

                                                                                                                                      Delete the specified customer.

                                                                                                                                      Request Method: DELETE

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

                                                                                                                                        # Create Address Token (Deprecated)

                                                                                                                                        Create a new stored address token.

                                                                                                                                        Request Method: POST

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

                                                                                                                                          # Get Address Token By ID (Deprecated)

                                                                                                                                          Retrieve details for the specified address token.

                                                                                                                                          Request Method: GET

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

                                                                                                                                            # Get All Address Tokens (Deprecated)

                                                                                                                                            Retrieve details for all address tokens stored on the customer record.

                                                                                                                                            Request Method: GET

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

                                                                                                                                              # Update Address Token (Deprecated)

                                                                                                                                              Edit details for the specified address token.

                                                                                                                                              Request Method: POST

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

                                                                                                                                                # Delete Address Token (Deprecated)

                                                                                                                                                Delete the specified address token.

                                                                                                                                                Request Method: DELETE

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

                                                                                                                                                  # Create Payment Method Token (Deprecated)

                                                                                                                                                  Create a new stored payment method token on the specified customer. The url endpoint and request body properties vary depending on the type of payment method being created. When creating a new payment method using a token generated by the Tokenizer form, the resulting payment method will be stored as card or ach.

                                                                                                                                                  Request Method: POST

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

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

                                                                                                                                                  Create with Token - URL Endpoint: /api/customer/{ customer id }/paymentmethod/token

                                                                                                                                                  Query Params

                                                                                                                                                  Name Default Description
                                                                                                                                                  validate "false" passing "true" will cause credit cards to have a $0 verification processed

                                                                                                                                                    # Create Payment Method Token - Code Samples

                                                                                                                                                      # Get Payment Method Token By ID (Deprecated)

                                                                                                                                                      Retrieve details for the specified payment method token.

                                                                                                                                                      Request Method: GET

                                                                                                                                                      Get Card Token - URL Endpoint: /api/customer/{ customer id }/paymentmethod/card/{ card id }

                                                                                                                                                      Get ACH Token - URL Endpoint: /api/customer/{ customer id }/paymentmethod/ach/{ ach id }

                                                                                                                                                        # Get All Payment Method Tokens (Deprecated)

                                                                                                                                                        Retrieve details for all card or ach payment method tokens stored on the customer.

                                                                                                                                                        Request Method: GET

                                                                                                                                                        Get Card Tokens - URL Endpoint: /api/customer/{ customer id }/paymentmethod/card

                                                                                                                                                        Get ACH Tokens - URL Endpoint: /api/customer/{ customer id }/paymentmethod/ach

                                                                                                                                                          # Update Payment Method Token (Deprecated)

                                                                                                                                                          Edit details for the specified payment method token.

                                                                                                                                                          Request Method: POST

                                                                                                                                                          Update Card - URL Endpoint: /api/customer/{ customer id }/paymentmethod/card/{ card id }

                                                                                                                                                          Update ACH - URL Endpoint: /api/customer/{ customer id }/paymentmethod/ach/{ ach id }

                                                                                                                                                          Update with Token - URL Endpoint: /api/customer/{ customer id }/paymentmethod/{ card or ach }/{ payment method id }

                                                                                                                                                            # Update Payment Method Token - Code Samples

                                                                                                                                                              # Delete Payment Method Token (Deprecated)

                                                                                                                                                              Edit details for the specified add-on.

                                                                                                                                                              Request Method: DELETE

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

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