Sample Integration Roadmap

  1. Know the Docs
  2. Decide on a Wrapper
  3. Wireframe the Workflows
  4. The Code, of Course
    1. Fire Up the Client
    2. Create a Customer on a Free Plan
    3. Create a Customer on a Paid Plan
    4. Change an Existing Customer's Plan
    5. Change an Existing Customer's Payment Information
    6. Mix In Some Error Handling
    7. Using the Custom Code Values
  5. Using Fake Credit Card Numbers for Development

1. Know the Docs

Be sure to familiarize yourself with the API reference documentation. You'll probably be primarily interested in the Request Dictionary section for periodic reference.

2. Decide on a Wrapper

There are many open-source wrappers available for several different languages. Those known to us are listed on the Developer's Page. If a wrapper is not listed there, please let us know and we'll add it and/or blog about it. The more the merrier! Of course, you can always write your own! There isn't much to it. If you do, please let us know and will add it to the developer page and blog about it.

3. Wireframe the Workflows

  1. Signup and Initial Subscription
    • Collect minimum information
      1. Name
      2. Email
      3. Pricing Plan
      4. Payment information (optional)
        • Credit Card or PayPal
        • Billing Address (if desired)
  2. Current Account Status and History (authorization)
    • Current pricing plan
    • Current tracked item usage (if applicable)
    • Pending invoice and bill date
    • Previously billed invoices
  3. Change Pricing Plan or Payment Information
    • Upgrade or downgrade the subscription
      • Use existing payment information
      • Change payment information
    • Update Payment information only

4. The Code, of Course

The following examples use the PHP wrapper to illustrate the API interaction.

4.1 Fire Up the Client

require('CheddarGetter/Client.php');
require('CheddarGetter/Client/Exception.php');
require('CheddarGetter/Response.php');
require('CheddarGetter/Response/Exception.php');

$client = new CheddarGetter_Client(
    'https://cheddargetter.com',
    'your.username@example.com',
    'your.password',
    'YOUR_PRODUCT_CODE'
);

4.2 Create a Customer on a Free Plan

$data = array(
    'code'          => 'MILTON_WADDAMS',
    'firstName'     => 'Milton',
    'lastName'      => 'Waddams',
    'email'         => 'milt@initech.com',
    'subscription'  => array(
        'planCode'      => 'FREE_TRIAL'
    )
);

$response = $client->newCustomer($data);

4.3 Create a Customer on a Paid Plan

$data = array(
    'code'          => 'BILL_LUMBERG',
    'firstName'     => 'Bill',
    'lastName'      => 'Lumberg',
    'email'         => 'bill@initech.com',
    'subscription'  => array(
        'planCode'      => 'PREMIUM',
        'ccNumber'      => '4111111111111111',
        'ccExpiration'  => '10/2014',
        'ccCardCode'    => '123',
        'ccFirstName'   => 'Bill',
        'ccLastName'    => 'Lumberg'
    )
);

$response = $client->newCustomer($data);

4.4 Change an Existing Customer's Plan

    $data = array('planCode'=>'ADVANCED');
    $response = $client->editSubscription('BILL_LUMBERG', null, $data);

4.5 Change an Existing Customer's Payment Information

    $data = array(
               'ccNumber'=>'4111111111111111',
               'ccExpiration'=>'2014/02'
     );

    $response = $client->editSubscription('BILL_LUMBERG', null, $data);

4.6 Mix In Some Error Handling

If you so desire, you can simply pass any error returned from the API back to the end user. Some of the errors may not entirely be meaningful to them so we recommend a more comprehensive approach. Below is an example of the granularity of error control you can employ:

$data = array(
    'code'          => 'BILL_LUMBERG',
    'firstName'     => 'Bill',
    'lastName'      => 'Lumberg',
    'email'         => 'bill@initech.com',
    'subscription'  => array(
        'planCode'      => 'PREMIUM',
        'ccNumber'      => '4111111111111111',
        'ccExpiration'  => '10/2014',
        'ccCardCode'    => '123',
        'ccFirstName'   => 'Bill',
        'ccLastName'    => 'Lumberg',
        'ccZip'         => '05003'  // simulates an error of 
                                    // "Credit card type is not accepted"
    )
);
try {
    $response = $client->newCustomer($data); 
} catch (CheddarGetter_Response_Exception $re) {
    if ($re->getCode() == 412) { // missing fields or field format errors
        echo "\n\tERROR - MISSING OR INVALID FIELDS:\n";
        echo "\n\t(" . $re->getCode() . ':' . $re->getAuxCode() . ') ';
        echo $re->getMessage()."\n";
    } else if ($re->getCode() == 422) { // payment processing errors
        echo "\n\tAN ERROR OCCURED DURING PAYMENT PROCESSING:\n";
        echo "\n\t(" . $re->getCode() . ':' . $re->getAuxCode() . ') ';
        echo $re->getMessage()."\n";
    } else {
        echo "\n\t".'ERROR: (" . $re->getCode() . ':' . $re->getAuxCode() . ') ';
        echo $re->getMessage()."\n";
    }
} catch (Exception $e) {
    echo "\n\t" . 'ERROR: (' . $e->getCode() . ') ' . $e->getMessage() . "\n"; 
}

You may simulate any type of error that CG can throw at you with the error simulator. We recommend you do this in order to test and fine-tune your error handling. For more information on error handling and error simulation, see the KB Article.

4.7 Using the Custom Code Values

All CG data has unique identifiers (they're UUID's actually) but when you're integrating your application or an accounting package or whatever with CG, it can be very convenient to use the existing unique identifiers from that system. CG stores an external or auxiliary field with each data item which we call the "code". So, every customer has a code. Every charge has a code. Every pricing plan has a code. Pretty much everything has a code. Really, you can utilize this code field for whatever you want but we decided to include it in the design of CG in an effort to make integrating with CG's API as easy as possible. When integrating another system with CG you don't have to store the CG unique identifiers in your database. Just use your own, they're already there. Just make sure you give CG the correct "code" when creating a customer or charge or whatever. You can, of course, do it the old fashioned way and use the CG UUID's and store them in your DB but that's crazy.

One caveat, though: if you would ever want to change the value of the "code" for a record, you'd of course need to use the CG UUID to uniquely identify that record. I'm not quite sure why you'd ever need to do this though. There's always the web interface where you can manually change any piece of data, including the "code".

5. Using Fake Credit Card Numbers for Development

You may use any credit card number for development purposes in CheddarGetter. Really, you can use any number as long as it starts with a few numbers that fit the scheme for the different card types and it passes the Luhn Algorithm format test. Below is a list of some examples that we like to use:

  • 370000000000002 American Express
  • 6011000000000012 Discover
  • 5424000000000015 MasterCard
  • 4111111111111111 Visa <===== Our favorite! It's so easy to remember.

You could also get a large set of numbers from here if that's something you're into.

When passing a CVV number you may pass any number you choose. There's no such thing as a test CVV number as they are not evaluated (other than format and requirement) in development.

View Plans and Pricing   or   Get Started with CheddarGetter now →