Skip to content
stripe-cfml is a CFML (Lucee and ColdFusion) library for interacting with the Stripe API.
ColdFusion
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib currency is optional here Sep 26, 2019
metadata Update to latest Stripe API endpoints Aug 1, 2019
tests Ignore empty structs when serializing Sep 13, 2019
.cfformat.json Update to latest Stripe API endpoints Aug 1, 2019
.gitattributes Update to latest Stripe API endpoints Aug 1, 2019
.gitignore merge branch stripe-cfml Apr 14, 2018
LICENSE merge branch stripe-cfml Apr 14, 2018
ModuleConfig.cfc Update module config and readme Jun 1, 2018
README.md
box.json v2.0.2 Sep 26, 2019
reference.md Add subscriptionItems method Aug 22, 2019
server.json merge branch stripe-cfml Apr 14, 2018
stripe.cfc Update to latest Stripe API endpoints Aug 1, 2019
task.cfc Update to latest Stripe API endpoints Aug 1, 2019

README.md

stripe-cfml

stripe-cfml is a CFML (Lucee and ColdFusion) library for interacting with the Stripe API.

Installation

This wrapper can be installed as standalone library or as a ColdBox Module. Either approach requires a simple CommandBox command:

$ box install stripecfml

Alternatively the git repository can be cloned into the desired directory.

Standalone Usage

Once the library has been installed, the core stripe component can be instantiated directly:

stripe = new path.to.stripecfml.stripe(
    apiKey = '',
    config = {}
);

ColdBox Module

To use the library as a ColdBox Module, add the init arguments to the moduleSettings struct in config/Coldbox.cfc:

moduleSettings = {
    stripecfml: {
        apiKey: '',
        config: {}
    }
}

You can then leverage the library via the injection DSL: stripe@stripecfml:

property name="stripe" inject="stripe@stripecfml";

Note: You can bypass the init arguments altogether and use Java system properties or environment variables to configure stripe-cfml. See Configuration via environment variables and system properties below.

Getting Started

// To charge $20 to a card for which a card token has been created
charge = stripe.charges.create({amount: 2000, currency: 'usd', source: cardToken});
// OR
charge = stripe.charges.create(amount = 2000, currency = 'usd', source = cardToken);

// charge is a struct which can be inspected for the result of the create charge api call
writeDump(charge);

stripe-cfml is modeled after the official Stripe SDKs. In particular it copies the class and method names used in the Node SDK. The Node examples given in the official Stripe documentation are simply able to be copied and used (with the notable difference that this library does not make use of callbacks - everything is done synchronously). However, since CFML supports named arguments, you can also use named arguments instead of passing the arguments in a single struct. The following examples are all valid ways of using this library:

stripe.customers.updateSource('customer_id', 'source_id', {metadata = {'a': 1}});
stripe.customers.updateSource(customer_id = 'customer_id', source_id = 'source_id', params = {metadata: {'a': 1}});
stripe.customers.updateSource(customer_id = 'customer_id', source_id = 'source_id', metadata = {'a': 1});

Note that the customers component and the method name, updateSource, do not change, only the how the arguments are passed to the method. See the reference for more information on the method signatures.

Headers

There are a several arguments you can pass to any method that are passed to the Stripe API as headers: apiKey, stripeVersion (or apiVersion), idempotencyKey, and stripeAccount.

When copying the Node SDK method signatures, headers are passed in a single struct:

charge = stripe.charges.create(
    {amount: 2000, currency: 'usd', source: cardToken},
    {stripeAccount: 'abc', idempotencyKey: 'def'}
);

They can also be passed as named arguments:

charge = stripe.charges.create(
    amount = 2000,
    currency = 'usd',
    source = cardToken,
    stripeAccount = 'abc',
    idempotencyKey = 'def'
);
// OR
charge = stripe.charges.create(
    params = {amount: 2000, currency: 'usd', source: cardToken},
    headers = {stripeAccount: 'abc', idempotencyKey: 'def'}
);

Configuration

You can pass some configuration parameters in a struct to the constructor of stripe.cfc:

config = {
    apiVersion: '',
    defaultCurrency: '',
    convertTimestamps: true,
    convertToCents: false
}
stripe = new stripe('stripe_api_key', config);
  • apiVersion specifies the version of the Stripe API to use - see versioning in the documentation.
  • defaultCurrency specifies the currency to use when making requests (e.g. usd) - when it is specified in the config you do not need to specify it when making requests.
  • convertTimestamps (default: true) - The Stripe API expects all datetimes to be given as Unix timestamps; when this setting is true, stripe-cfml converts all CFML date objects passed into methods to UNIX timestamps and converts timestamps in the API responses back to CFML date objects.
  • convertToCents (default: false) - when this is set to true all currency amounts passed in are multiplied by 100 and all amounts in the responses are divided by 100. (This enables one to work in dollar amounts instead of cents, if so desired.)

Configuration via environment variables and system properties

All of these configuration keys, including the Stripe secret key, can be specified in environment variables or Java system properties instead of being passed in at initialization. When using environment variables your config keys should be prefixed with STRIPE_ and underscores are used to separate words: STRIPE_API_KEY, STRIPE_API_VERSION, STRIPE_DEFAULT_CURRENCY, STRIPE_CONVERT_TIMESTAMPS, and STRIPE_CONVERT_TO_CENTS. When using system properties your config keys should be prefixed with stripe. and all lowercase: stripe.apikey, stripe.apiversion, stripe.defaultcurrency, stripe.converttimestamps, and stripe.converttocents.

Responses

The Stripe API returns a JSON object in response to all HTTP requests (see https://stripe.com/docs/api). stripe-cfml deserializes this object into a CFML struct and makes it available in a response struct under the content key.

Responses to API calls are all returned as structs in the following format:

{
    requestId: ''  // request identifier - see https://stripe.com/docs/api#request_ids
    content: {}    // struct containing the body of the response
    duration: 300  // time the HTTP request took in milliseconds
    headers: {}    // struct containing headers returned by the Stripe API
    status: 200    // status code returned by the Stripe API
}

Webhooks

stripe-cfml can verify signed webhooks received by your server in a similar fashion to the official Stripe SDKs:

try {
    event = stripe.webhooks.constructEvent(webhookJSONPayload, stripeSignatureHeader, endpointSecret);
} catch (any e) {
    // the webhook was not signed properly
}
// otherwise do something with the event

See https://stripe.com/docs/webhooks and https://stripe.com/docs/webhooks/signatures for more information on setting up signed webhooks.

You can’t perform that action at this time.