This documentation provides the details necessary to easily integrate with the SwervePay system. This API is provided to give complete control of payment data collection and fulfillment within your application by leveraging any or all features of the SwervePay system in an automated fashion.

Please use the following links to quickly navigate this documentation.

The SwervePay REST API exists to provide a programmatic means of accessing and utilizing the SwervePay system. This API utilizes RESTful architectural principles to facilitate client access to the available services provided by the SwervePay system. For more information on Representational state transfer (REST), please visit the associated Wikipedia page.

Developers familiar with the SwervePay system or the methodology of similar RESTful API interfaces can feel free to proceed directly to the resource-specific documentation directly. First time developers for the SwervePay system and those unfamiliar with RESTful architectural principles may want to review the remaining information on this page before proceeding.

Return to the top

As noted, this API utilizes a RESTful architecture. SwervePay services are utilized through stateless client-server communication utilizing standard HTTP 1.1 requests and responses. Requests are made utilizing HTTP methods available to the given resource (e.g. GET, POST, PUT, DELETE). The utilization of these request methods will be defined in detail for every available resource in the associated documentation.

All HTTP client requests will be provided utilizing a application/x-www-form-urlencoded encoded Content-Type. Responses from the server will utilize either JSON (application/json) or XML (application/xml) encoding depending on the value specified in the Accept header (JSON will be provided by default or in the case of an unaccepted requested type).

To ensure data security, the SwervePay REST API is served exclusively over HTTPS; unencrypted HTTP is not supported.

Return to the top

All resource URLs provided by the SwervePay REST API utilize the following base URL:

The {accountSid} portion of the URL is specific to your account and will always be available from within the "My Account" page when you are logged into your SwervePay account. If you do not find an "API Information" section on the My Account page, please contact your SwervePay support representative to request API access for your account.

Return to the top

Security for the SwervePay REST API is achieved through HTTP basic access authentication. Basic access authentication is achieved by providing a base64 encoding of your username and secure API key in an "Authorization: Basic" header within your HTTP request. Most programming languages and software packages should provide built-in or easy plugin support for HTTP basic access authentication, but a raw example of this using an example username and API key can be seen below:

Assuming the following:

In order to generate the appropriate basic access authentication header you would need to base64 encode the following string:

Resulting in the following HTTP header being submitted with each request:

The values provided above are only an example, your actual authentication header will be derived from your own username and API key. Your API key can be generated from the "My Account" page when you are logged into your SwervePay account. This key can only be viewable at the time it is generated, so be sure to store it securely! There is no mechanism to retrieve this stored key once you have left the generation screen, however you can regenerate a new key if it becomes lost or compromised.

IMPORTANT NOTE: Regenerating your API key will instantly cause all existing automation using your prior key to fail authentication until such applications have been updated with the newly generated key.

Return to the top

These resources provide the available server functionality for your system to integrate into. Resources are divided into two classes: Base Resources (listed below) and Sub-resources. Base resources will provide the highest level endpoint for a specific type of resource (e.g. customers, transactions). The sub-resources provided beneath this high level resource endpoint will provide more specific functionality. Please review the individual resource-specific documentation for more information.

Available resources include:

• Customers Resource

• Transactions Resource

Return to the top

The SwervePay REST API accepts standard HTTP 1.1 requests to any of the documented resource endpoint URLs (See Resources). Where applicable, request data is provided with an application/x-www-form-urlencoded Content-Type. Each client request represents a stateless, standalone operation. The type of operation performed (and therefore any or all possible associated request data) is determined by the HTTP request method used to access a given resource. Not all resources provide functionality for all request methods, refer to the appropriate resource-specific documentation for these definitions.

Return to the top

The SwervePay REST API provides standard HTTP 1.1 responses to client requests. The success or failure of a particular client request can be determined by the HTTP status code provided in the response header. It is extremely important that client applications check the status code on all responses and act accordingly. Successful responses will be indicated by an HTTP 200 status code.

For any request resulting in a successful response, there will typically be three types of results: Status-only responses (e.g. DELETE record), single-record responses (e.g. detail record GET request), and list responses (e.g. query for records). The type of result to expect will be defined in the associated resource-specific documentation.

All unsuccessful (non-200) responses that occur in the processing of a client request will cause the server to return error data within the response metadata. It is important that applications examine the resulting error information for any client request that returns a non-200 status code to determine the cause. See the Response Metadata section of this document for more detail on how this error information will be provided.

The Content-Type header of the response will dictate the format of the response data provided. The default Content-Type utilized is application/json (JSON) unless a different format is provided in the Accept header of the client request. At this time, the only content types the server will accept are application/json (JSON) and application/xml (XML). The response data for each will be structured similarly, however specific nuances of each format may dictate some differences. See below for a high level overview of formatting concepts to note for each content type. For additional clarification, request/response examples in all formats are provided for every resource in the associated resource-specific documentation.

JSON

• The entire response payload will be encapsulated in a hash.
• The response hash will include a (possibly empty) child hash under a key named metadata (See Response Metadata).
• Single-record responses will be provided in a child hash of the main response hash. The key for this record's hash will be determined by the specific resource in question.
• List responses will be provided in a child array of hashes, with each hash in this array containing a single response record. The key for this array will be determined by the specific resource in question.

XML

• The entire response payload will be encapsulated within an outermost parent element named <responseRecord>.
• The response record will include a (possibly empty) element named <metadata> (See Response Metadata).
• Single-record responses will be provided in a child element of the main response element. The element name will be determined by the specific resource in question.
• List responses will be provided in an ordered list of child elements of the same name, with each element containing a single response record. The element name will be determined by the specific resource in question.

Return to the top

All server responses (except those resulting in an HTTP 500 error) will provide a metadata record in the form of a hash (JSON) or element (XML) containing various metadata parameters including, among other possible information, a count and list of any errors resulting from a client request that returns a non-successful (non-200) status code.

Return to the top

Many aspects of the SwervePay REST API have been designed specifically with future growth and extensibility in mind. Server-side updates resulting in a minor version number change should remain fully backwards compatible to support any prior integration. New features and functionality will be added through the provision of additional resources and through the addition or extension of response keys/elements and metadata.

Return to the top

Before you will be able to process a transaction for a customer you must first have a customer record and, most importantly, the associated customerId identifying that record. To do this, you must first create a new customer record using a POST request to the Customers resource. The successful response to this resource should return the record for the newly created customer, including the customerId field. Once you have acquired this information, simply provide a POST request to the Transactions resource including the customerId parameter to run a transaction for the newly created customer.

New tokenized payment options are created by running a new transaction for the customer in question. This is done with a POST request to the Transactions resource. Note that you must include the associated customerId parameter to tokenize this payment option for the customer. Note that you must also exclude the old tokenId.

If you would like to tokenize a new payment option without charging the customer you can simply opt to perform a validation-only by utilizing a transactionType of validate (NOTE: If validation is not a supported operation for your merchant account setup, you may use a low-dollar authorization instead).

To utilize a previously tokenized payment option to process a new payment for a customer, simply utilize a GET request to the Tokens resource to list the available active tokenized payment options stored for that customer (with the most recently used listed first). The tokenId provided for a given token record is all that is needed to recall this payment information for a new transaction. To use the token, simply employ a POST request to the Transactions resource including the customerId and tokenId parameters for the customer and token, respectively. The newly issued transaction will be tied to the customer and will automatically utilize the previously stored payment information.

Token data cannot be modified directly through the Tokens resource or any of the associated sub-resources. New token data can be generated anytime a new transaction is issued. In order to generate new token data, supply the customerId, exclude the old tokenId, and provide new account details on this transaction.

If you need to update this payment data without collecting a payment from the customer, this can be done by utilizing a transactionType of validate (NOTE: If validation is not a supported operation for your merchant account setup, you may use a low-dollar authorization instead).

Customer payment tokens that have been deactivated through a DELETE request to the Token Details resource cannot be reactivated. You must collect the customer's payment information and issue a new transaction to re-tokenize this payment method.

Return to the top