Authentication

Introduction Authentication

Learn how to use API authentication to communicate directly with Chargify from any programming language that you wish.


There are two methods of authentication, depending on what you are accessing:

Both methods of authentication assume you have previously generated API keys have have securely stored them for later use. For more information, see “Obtaining Credentials”.

For most integrations, the API will be the easiest to implement. Chargify Direct is a method of very securely creating subscriptions where the information is posted directly to Chargify and none of the payment information is passed through your code. Your requirements will dictate the need to use one or the other (or both).

API

The first method of interaction is through the API. API Authentication is implemented as HTTP Basic Authentication over TLS (HTTPS).

Your API login credentials are not the same as the credentials you use to log in to the web interface. You must obtain your API credentials separately, and you must connect to the API via TLS 1.2 (or better) as of January 2016.

One of the most common calls you will make via the API is to retrieve a list of subscriptions to retrieve additional information, such as the status of a specific subscription. For the basic http authentication of this call, you would use the API Key as the username and “X” as the password, like the following:

curl -u {api_key}:X -H Accept:application/json -X GET https://{subdomain}.chargify.com/subscriptions.{format}

For more information about API authentication, please see our API Documentation/Example.

Chargify Direct

The second method of interaction is using Chargify Direct. Chargify Direct has two methods of connectivity:

  1. via the submitted form values
  2. via a regular REST call

Chargify Direct via Secure Parameters

Secure parameters are used when using the transparent redirect (posting values directly) to Chargify using a <form method='POST' \>. This is done when creating new subscriptions and updating payment profile information.

Every Chargify Direct post must contain a set of cryptographically signed secure parameters. The secure parameters are necessary in order to:

  • Authenticate the request so that Chargify can verify it comes from a trusted source (since anyone on the internet can post to Chargify Direct endpoints)
  • Allow you to send tamper-proof data along with the request
  • Specify a Redirection URI (or override your default)

The following are the list of secure parameters inputs necessary for authentication:

  • api_id (required) - Your API Key/ID, as assigned by Chargify (see “Obtaining Credentials”).
  • timestamp (optional) - The time of the request, given as an integer number of seconds elapsed since Jan 1, 1970 00:00:00 UTC (i.e. Unix time). If you provide a timestamp, it will be reflected back to you in the response parameters, and MAY be used to invalidate the request if it is older than a certain threshold (see Timestamping requests)
  • nonce (required) - A string (max 40 characters) used to uniquely identify the request. The nonce must be unique when scoped by the timestamp and your API ID. With nonce provided, it will be reflected back to you in the response parameters, and MAY be used to invalidate the request if it matches a previously used value for the same timestamp (see Nonce values)
  • data (optional) - A string in URL query-string format that may be used to transmit tamper-proof data to Chargify through the form (see Secure data). Note that you will want to escape any HTML characters in this string before embedding it in your form.
  • signature (required) - A verification signature based on the other 4 secure inputs and the shared api_secret for the API User (See Signature Calculation)

These secure inputs should be sent to Chargify through the Direct endpoint nested inside the secure parameter. For example, the following form demonstrates how to use hidden form inputs to submit all 5 secure inputs:

<form method="post" action="https://api.chargify.com/api/v2/signups">
  <input type="hidden" name="secure[api_id]"    value="1234" />
  <input type="hidden" name="secure[timestamp]" value="1301148971" />
  <input type="hidden" name="secure[nonce]"     value="5b2763d0-39e1-012e-858d-64b9e8d3946e" />
  <input type="hidden" name="secure[data]"      value="one=uno&amp;two=dos" />
  <input type="hidden" name="secure[signature]" value="412951d095ebbb3800dfb2126fe5073d2ab6c260" />
</form>

Signature Calculation

The authentication value in this method is the signature. The signature is the hexadecimal representation of a computed Hash-based Message Authentication Code, using SHA-1 as the cryptographic function (HMAC-SHA1). The secret for the function is the API shared secret (api_secret) issued to the API user by Chargify. The message for the function is the concatenation of the api_id, timestamp, nonce, and data parameters. Any optional parameter that is not given is converted to an empty string.

HMAC-SHA1(api_secret, api_id+timestamp+nonce+data)

For additional information, please see Chargify Direct.

Chargify Direct via REST

One of the most common calls you will need to make is to retrieve a previous Chargify Direct call to determine if it’s been successful. For the basic http authentication of this call, you would use the API Key/ID as the username and the API password as the password, like the following:

curl -u <API_ID>:<API_PASSWORD> -H Accept:application/json -X GET https://api.chargify.com/api/v2/calls/<CALL_ID>.json

Obtaining Credentials

For both API and Chargify Direct credentials, your API Key can be generated from the “Integrations” tab of your site dashboard.

For API, your basic http authentication username is your API Key while the password is always “X”.

For Chargify Direct credentials, you will be provided three values:

  1. API Key/ID
  2. API password
  3. API secret

For the transparent redirect (posting values directly to Chargify), you will be using the API Key/ID and the API secret. The API password is reserved for use in Chargify Direct calls (like to the “call” endpoint to verify the last submission was successful).

Note: The shared secret and password are only shared once via the admin interface, so it is important that you copy them down for all future use as you won’t be able to retrieve them after creating the credential.

Troubleshooting: Unable to Connect

If you are unable to connect, the problem is often that you are using an old/unsupported version of SSL or TLS. In this case, Chargify will simply drop the connection, and the error message you receive may be cryptic.

Here are some common error messages that have been reported:

  • The underlying connection was closed: An unexpected error occurred on a send.
  • Authentication failed because the remote party has closed the transport stream.

Please, review the information on the Upgrade Notice in order to correct the problem.


Next Steps

After you’ve mastered authentication, you should check out the following articles:

  • Managing sites
  • Creating products and how they control what you bill customers
  • Creating subscriptions, (ie. signing up customers)