Spreedly API

These are the API reference documents for version 1 of the Spreedly API (prev. Spreedly Core).

API v1 is a standard REST-style API that accepts/returns XML or JSON requests and is located at:

https://core.spreedly.com/v1/

Using the API

API authentication

To authenticate to Spreedly's API, you will need an environment key and an access secret. These credentials can be created in the merchant portal. Please review our application overview for instructions, noting Spreedly's best-practices for account setup and API credential management for further details.

Unless otherwise noted, all calls to the Spreedly API use HTTP basic authentication over HTTPS. Spreedly requires TLS 1.2.

Use the environment key of the Spreedly environment you wish to execute against as the HTTP basic user, and one of your organization’s access secrets as the HTTP basic password.

HTTP basic authentication can be set when using curl in the -u option as environment-key:access-secret.

$ curl https://core.spreedly.com/v1/gateways.json -u 'env_key:secret'

Credential management

Once you've obtained an environment key of your choosing, you will need to generate an access secret in that environment to complete authentication. Be sure to use unique naming conventions and copy down the access secret, as it will not be accessible following the initial creation window.

JSON endpoints

To make a request for the JSON version of an endpoint, send the Content-Type: application/json header to the endpoint with the .json URL suffix.

JSON endpoint examples are contained within the json tab of the code column here in docs. If a particular snippet is ambiguous to format, it will be displayed in all code tabs without label.

XML endpoints

To make a request for the XML version of an endpoint, send the Content-Type: application/xml header to the endpoint with the .xml URL suffix.

XML endpoint examples are contained within the xml tab of the code column here in docs. If a particular snippet is ambiguous to format, it will be displayed in all code tabs without label.

Variables

Request variables are displayed as <var_name> in docs. Anytime a variable exists in an example API request, it will be defined in the associated request/response areas. Required fields will be marked as such in the request body area of the reference documentation.

POST /v1/gateways/<gateway_token>/verify.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>

{
  "transaction": {
    "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
    "retain_on_success": true
  }
}

Parameter	Required/Optional	Description
`gateway_token`	required	The token of the gateway to execute against
`format`	required	One of `json` or `xml`

API examples

These reference docs are meant to clearly define URLs, parameters, request bodies, responses and error states of the Spreedly API. Most sections will be accompanied by the HTTP representation of the API call in the right-most column and should be easily translated to the equivalent curl (or other library) command.

For instance, the following HTTP request:

Is equivalent to the following curl command:

The response section immediately follows the request and outputs the following HTTP response code:

along with the response body: