The second method of interaction is using Chargify Direct. Chargify Direct has two methods of connectivity:
- via the submitted form values
- via a regular REST call
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&two=dos" /> <input type="hidden" name="secure[signature]" value="412951d095ebbb3800dfb2126fe5073d2ab6c260" /> </form>
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
data parameters. Any optional parameter that is not given is converted to an empty string.
For additional information, please see Chargify Direct.
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
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:
- API Key/ID
- API password
- 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.
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.