# Composing Requests

# Base Urls

TIP

Whenever you see the placeholder { url goes here } within this documentation, you will need to replace it with one of the following urls based on which API environment you are processing against.

When accessing endpoints, the request url should always obey the following format:

https://{ base url }{ url endpoint }

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 }

See Request JWT and API Keys > Create for guidance on generating these assets.

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

# Authentication

To authenticate with a username and password:

  1. Collect login credentials from the user.

  2. Pass the credentials to the /api/token-auth endpoint to obtain a token.

  3. Use the token to authenticate subsequent calls by using it as the value of your Authorization header.

TIP

An active JWT will expire if 20 minutes have elapsed since it has been used in a request.

# Request JWT

Supply the user's login credentials and receive a token that can be used to authenticate subsequent API requests.

Request Method: POST

URL Endpoint: /api/token-auth

    # Forgot Username

    Supply the email address associated with a user's account to send an email containing the usernames listed for that account.

    Request Method: POST

    Request Endpoint: /api/user/forgot-username

      # Forgot Password

      Supply the username associated with a user account and an email will be sent to the address on file with a password reset token. This token is used to make a Password Reset request.

      Request Method: POST

      Request Endpoint: /api/user/forgot-password

        # Password Reset

        Supply a username, a valid password reset token, and a new password to be set for the account in order to update the user's saved password.

        Request Method: POST

        URL Endpoint: /api/user/forgot-password/reset

          # Logout

          Logout will terminate the JWT used to authorize the request.

          Request Method: GET

          URL Endpoint: /api/logout

            # 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

                          # API Keys

                          API keys give a user access to manage data within a gateway account without needing to generate and persist a JWT token.

                          TIP

                          There are two key types: API and Public. The "API" type is a secret key for use on the back-end of your application. "Public" keys are safe to use in front-end code (for example, initializing the tokenizer) and do not have full access to all endpoints.

                          # Create API Key

                          Generate a new API key for the user account associated with the API key or JWT token provided in the Authorization header of this request.

                          Request Method: POST

                          URL Endpoint: /api/user/apikey

                            # Get API Keys

                            Get a list of API keys attached to the user account associated with the API key or JWT token provided in the Authorization header of this request.

                            Request Method: GET

                            URL Endpoint: /api/user/apikeys

                              # Delete API Key

                              Delete the API Key specified in the request url. Public keys cannot be used in the Authorization header for this request.

                              Request Method: DELETE

                              URL Endpoint: /api/user/apikey/{ API Key }

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

                                Request Method: POST

                                URL Endpoint: /api/transaction

                                  # Process a Transaction - Code Samples

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


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