Skip to content

Instantly share code, notes, and snippets.

@beneggett

beneggett/savvi-user-payment-integration-api.md

Created October 10, 2013 15:29
Show Gist options
  • Save beneggett/6920321 to your computer and use it in GitHub Desktop.
Save beneggett/6920321 to your computer and use it in GitHub Desktop.
Download ZIP
Savvi User & Payment Integration API for Call Centers
Raw
savvi-user-payment-integration-api.md

Savvi User & Payment Integration API for Call Centers

This guide covers the inner working of Braintree's Payment API & Savvi's RESTful API. It assumes a basic understanding of the principles of REST.

There are two steps that need to happen in order to successfully enroll a Savvi member:

1.) Create an customer with a credit card & billing address with Braintree

2.) Post the user's information to Savvi including the newly created Braintree token via the "Creating Call Center Members via API" method.

Upon receipt of the user's information, Savvi will automatically set up a user account, handle the users monthly recurring subscription, notify the user via email that their account has been created and send them login credentials, track the account under the call center's account in Savvi to manage payouts, etc. The call center will be able to access reports for all of the users they have enrolled.

Two optional methods "Updating Call Center Members via API", and "Finding Members via API" exist and can be used as needed.

Prior to integration, you will need to receive the following from Savvi:

1.) Braintree API Keys

2.) Savvi Authentication Token/credentials

Savvi will issue credentials for both the Sandbox & Production environments.

1.) Integrating with Braintree

Braintree provides both a staging (sandbox) environment for testing, and production for live transactions. The sandbox behaves identical to the production environment, so there isn't much of a need for live testing, other than to confirm the access credentials.

Braintree provides development libraries and documentation for most languages including: Ruby, PHP, Python, Java, Perl, .NET, Node.js. Braintree also provides Client side encryption mechanisms to make PCI compliance very simple, for Web via Javascript, and Mobile for iOS, Android, and Windows Phone.

Call centers do not need to do a full integration with Braintree, they only need to Create a Customer with a credit card & billing address in Braintree, and retrieve the Braintree Customer id token

The following information should be submitted to Braintree:

User Information:

:email                 | Required | String
:first_name            | Required | String
:last_name             | Required | String
:phone                 | Required | String

Credit Card block:

:number                | Required | String
:expiration_month      | Required | String 
:expiration_year       | Required | String
:cvv                   | Required | String

Address block:

:address1              | Required | String
:address2              | Optional | String 
:locality              | Required | String (City)
:region                | Required | String (State)
:postal_code           | Required | String (Zip Code)
:country               | Required | String

2.) Integrating with Savvi

Once you have created a user with credit card & billing information in Braintree and received your braintree_customer_id token, a call must be made to Savvi to establish the user's account using the "Creating Call Center Members via API" method as described in Savvi's Rest API below.

Savvi's REST API

The Savvi REST API is designed to give developers a convenient way to access data contained within Savvi. As Savvi continues to grow, the API will continue to be developed.

Making an API Call

Savvi provides a staging and production URL for creating users.

Staging URL: http://www.savvi-staging.com/api/v1/

Production URL: https://www.savvi.com/api/v1/

You will need an authentication token to access the API. If you have not received one, please contact Savvi and we will provide one for you.

Savvi API Methods defined in this guide

  • Creating Call Center Members via API

  • Updating Call Center Members via API

  • Finding Members via API

Rules

The following are some simple rules that all Savvi API endpoints comply with.

  1. All successful requests for the API will return a status of 200.
  2. Both create and update requests will return Savvi's representation of the data upon success.
  3. If a create or update request fails, a status code of 422 will be returned, with a hash containing an "error" key, and an "errors" key. The errors value will contain all ActiveRecord validation errors encountered when saving this record.
  4. Delete requests will return status of 200, and no content.
  5. If a resource can not be found, the API will return a status of 404.
  6. If no authentication token is provided, or your authentication token is invalid, a status code of 401 will be returned with an error message indicating the authentication token is invalid.

API Communication Methods

Savvi API supports three common communication methods:

  • HTTP
  • JSON
  • XML

HTTP Data

Developers communicate with the Savvi API using the HTTP Requests. Requests for data are communicated in the standard manner using the HTTP protocol.

JSON Data

Developers communicate with the Savvi API using the JSON data format. Requests for data are communicated in the standard manner using the HTTP protocol.

XML Data

Developers communicate with the Savvi API using the XML data format. Requests for data are communicated in the standard manner using the HTTP protocol.

Creating Call Center Members via API

URL Path: /api/v1/create_call_center_member

A call center member can be created by posting the the URL path shown above. A standard post includes your Authentication token, and a users block with nested address block and associated parameters:

Fields Needed for Savvi Users:

Authentication Token:

:authentication_token | Required | String (provided by Savvi)

User block:

:email                 | Required | String
:first_name            | Required | String
:last_name             | Required | String
:braintree_customer_id | Required | String (Received from Braintree)
:username              | Optional | String
:date_of_birth         | Optional | Date "YYYY-MM-DD" format
:gender                | Optional | String ("Male", "Female", "Prefer not to say")

Address block:

:address1            | Required | String
:address2            | Optional | String 
:city                | Required | String
:state               | Required | String (Two Digit State Code)
:zipcode             | Required | String
:country             | Optional | String (Will default to "United States of America", as Savvi is currently only available in the US)
:phone               | Required | String

(Address values will need to be passed in an :address_attributes block, see examples below)

Responses

Savvi will respond to your post in one of three ways:

  • 200 Ok: Success. User < Email Address > created by < Your Account Name >"
  • 422: Unprocessable Entity. Appropriate Errors will be returned.
  • 401: Unauthorized

Upon successful creation, an account will be setup within Savvi under your account. You can view your enrollees through your profile at www.savvi.com/profile

Create User via HTTP method & Sample

May be accessed via the browser or command line.

http://www.savvi-staging.com/api/v1/create_call_center_member?authentication_token=AzXimVQyVqgDtRiGd3EH&user[email][email protected]&user[first_name]=testFirst&user[last_name]=TestLast&user[braintree_customer_id]=btid123&user[address_attributes][address1]=123 fk st&user[address_attributes][city]=Salt Lake City&user[address_attributes][state]=UT&user[address_attributes][zipcode]=84101&user[address_attributes][phone]=8015555555
curl --data "authentication_token=AzXimVQyVqgDtRiGd3EH&user[email][email protected]&user[first_name]=testFirst&user[last_name]=TestLast&user[braintree_customer_id]=btid123&user[username]=Testusername&user[date_of_birth]=1970-07-25&user[gender]=Female&user[address_attributes][address1]=123 fk st&user[address_attributes][city]=Salt Lake City&user[address_attributes][state]=UT&user[address_attributes][zipcode]=84101&user[address_attributes][phone]=8015555555" http://www.savvi-staging.com/api/v1/create_call_center_member

Expanded for readability:

http://www.savvi-staging.com/api/v1/create_call_center_member?
authentication_token=AzXimVQyVqgDtRiGd3EH
&user[email][email protected]
&user[first_name]=Testfirst
&user[last_name]=Testlast
&user[braintree_customer_id]=btid123
&user[username]=Testusername
&user[date_of_birth]=1970-07-25
&user[gender]=Female
&user[address_attributes][address1]=123 fk st
&user[address_attributes][city]=Salt Lake City
&user[address_attributes][state]=UT
&user[address_attributes][zipcode]=84101
&user[address_attributes][phone]=8015555555

Create User via JSON & Sample

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"authentication_token":"AzXimVQyVqgDtRiGd3EH", "user":{"email":"[email protected]", "first_name":"Testfirst", "last_name":"Testlast", "status":"active", "braintree_customer_id":"btid123", "username":"Testusername", "date_of_birth":"1970-07-25", "gender":"Female", "address_attributes":{"address1":"123 e Main Street", "address2":"", "address_type":"billing", "city":"Salt Lake City", "country":"United States", "county":"", "phone":"8015554312", "state":"UT", "zipcode":"84101"} } }' http://www.savvi-staging.com/api/v1/create_call_center_member

Expanded for readability:

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{ 
  "authentication_token":"AzXimVQyVqgDtRiGd3EH", 
  "user":{ 
    "email":"[email protected]", 
    "first_name":"Testfirst", 
    "last_name":"Testlast", 
    "status":"active", 
    "braintree_customer_id":"btid123", 
    "username":"Testusername",
    "date_of_birth":"1970-07-25",
    "gender":"Female",
    "address_attributes":{ 
      "address1":"123 e Main Street", 
      "address2":"", 
      "address_type":"billing", 
      "city":"Salt Lake City", 
      "country":"United States", 
      "county":"", 
      "phone":"8015554312", 
      "state":"UT", 
      "zipcode":"84101"
    }
  }
}' http://www.savvi-staging.com/api/v1/create_call_center_member

Create User via XML & Sample

curl -v  -H "Content-Type: application/xml" -X POST  -d   "<?xml version="1.0" encoding="UTF-8" ?> <user> <email>[email protected]</email> <first_name>Testfirst</first_name> <last_name>Testlast</last_name> <username>apitester</username> <status>active</status> <braintree_customer_id>btid123</braintree_customer_id> <username>Testusername</username> <date_of_birth>1970-07-25</date_of_birth> <gender>Female</gender> <address_attributes> <address1>123 e Main Street</address1> <address2></address2> <address_type>billing</address_type> <city>Salt Lake City</city> <country>United States</country> <county></county> <phone>8015554312</phone> <state>UT</state> <zipcode>84101</zipcode> </address_attributes> </user> " http://www.savvi-staging.com/api/v1/create_call_center_member?authentication_token=AzXimVQyVqgDtRiGd3EH

Expanded for readability:

curl -v  -H "Content-Type: application/xml" -X POST  -d   "
  <?xml version="1.0" encoding="UTF-8" ?>
    <user>
      <email>[email protected]</email>
      <first_name>Testfirst</first_name>
      <last_name>Testlast</last_name>
      <username>apitester</username>
      <status>active</status>
      <braintree_customer_id>btid123</braintree_customer_id>
      <username>Testusername</username>
      <date_of_birth>1970-07-25</date_of_birth>
      <gender>Female</gender>
      <address_attributes>
        <address1>123 e Main Street</address1>
        <address2></address2>
        <address_type>billing</address_type>
        <city>Salt Lake City</city>
        <country>United States</country>
        <county></county>
        <phone>8015554312</phone>
        <state>UT</state>
        <zipcode>84101</zipcode>
      </address_attributes>
    </user>
" http://www.savvi-staging.com/api/v1/create_call_center_member?authentication_token=AzXimVQyVqgDtRiGd3EH

Updating Call Center Members via API

URL Path: /api/v1/update_call_center_member

A call center member can be updated by posting the the URL path shown above. Please note, wholesale partners may only update wholesale members for whom they are the direct sponsor. A standard post includes your Authentication token, the users email you want to update, and a users block with nested address block and associated parameters:

Fields Needed for Savvi Users:

Authentication Token:

:authentication_token | Required | String (Provided by Savvi.)

Email Address of User to update:

:email | Required | String

User block:

Any/All fields are optional.

:email                 | Optional | String
:first_name            | Optional | String
:last_name             | Optional | String
:braintree_customer_id | Optional | String (Received from Braintree)
:username              | Optional | String
:date_of_birth         | Optional | Date "YYYY-MM-DD" format
:gender                | Optional | String ("Male", "Female", "Prefer not to say")
:status                | Optional | String ("active", "inactive", "banned")

Address block:

:address_1           | Optional | String
:address_2           | Optional | String 
:address_3           | Optional | String 
:city                | Optional | String
:state               | Optional | String (Two Digit State Code)
:zipcode             | Optional | String
:country             | Optional | String (Will default to "United States of America", as Savvi is currently only available in the US)
:phone               | Optional | String

(Address values will need to be passed in an :address_attributes block, see examples below)

Responses

Savvi will respond to your post in one of three ways:

  • 200 Ok: Success. User < Email Address > created by < Your Account Name >"
  • 422: Unprocessable Entity. Appropriate Errors will be returned.
  • 401: Unauthorized

Upon successful creation, an account will be setup within Savvi under your account. You can view your enrollees through your profile at www.savvi.com/profile

Update User via HTTP method & Sample

May be accessed via the browser or command line.

http://www.savvi-staging.com/api/v1/update_call_center_member?authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]&user[status]=inactive&user[address_attributes][phone]=8015555555
curl --data "authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]&user[status]=inactive&user[address_attributes][phone]=8015555555" http://www.savvi-staging.com/api/v1/update_call_center_member

Expanded for readability:

http://www.savvi-staging.com/api/v1/update_call_center_member?
authentication_token=AzXimVQyVqgDtRiGd3EH
&[email protected]
&user[status]=inactive
&user[address_attributes][phone]=8015555555

Update User via JSON & Sample

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"authentication_token":"AzXimVQyVqgDtRiGd3EH", "email":"[email protected]", "user":{"status":"inactive", "address_attributes":{"phone":"8015555555"} } }' http://www.savvi-staging.com/api/v1/update_call_center_member

Expanded for readability:

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{
  "authentication_token":"AzXimVQyVqgDtRiGd3EH",
  "email":"[email protected]", 
  "user":{
    "status":"inactive", 
    "address_attributes":{
      "phone":"8015555555"
    } 
  } 
}' http://www.savvi-staging.com/api/v1/create_call_center_member

Update User via XML & Sample

curl -v  -H "Content-Type: application/xml" -X POST  -d   "<?xml version="1.0" encoding="UTF-8" ?> <user> <status>inactive</status> <address_attributes> <phone>8015555555</phone> </address_attributes> </user> " http://www.savvi-staging.com/api/v1/update_call_center_member?authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]

Expanded for readability:

curl -v  -H "Content-Type: application/xml" -X POST  -d   "
  <?xml version="1.0" encoding="UTF-8" ?>
    <user>
      <status>inactive</status>
      <address_attributes>
        <phone>801555555</phone>
      </address_attributes>
    </user>
" http://www.savvi-staging.com/api/v1/update_call_center_member?authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]

Finding Members via API

URL Path: /api/v1/find_member

A member can be looked up by posting to the URL path shown above. A standard post includes your Authentication token and an email address

Fields Needed for Savvi Users:

Authentication Token:

:authentication_token | Required | String (provided by Savvi)

User block:

:email                 | Required | String

Responses

Savvi will respond to your post in one of three ways:

  • 200 Ok: Success.
  • 422: Unprocessable Entity. Appropriate Errors will be returned.
  • 401: Unauthorized

Upon successful lookup, a 200 status and the users block will be returned.

Find Member via HTTP method & Sample

May be accessed via the browser or command line.

http://www.savvi-staging.com/api/v1/find_member?authentication_token=AzXimVQyVqgDtRiGd3EH&user[email][email protected]
curl --data "authentication_token=AzXimVQyVqgDtRiGd3EH&user[email][email protected]" http://www.savvi-staging.com/api/v1/find_member

Expanded for readability:

http://www.savvi-staging.com/api/v1/find_member?
authentication_token=AzXimVQyVqgDtRiGd3EH
&user[email][email protected]

Find Member via JSON & Sample

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"authentication_token":"AzXimVQyVqgDtRiGd3EH", "user":{"email":"[email protected]"} }' http://www.savvi-staging.com/api/v1/find_member

Expanded for readability:

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{ 
  "authentication_token":"AzXimVQyVqgDtRiGd3EH", 
  "user":{ 
    "email":"[email protected]"
  }
}' http://www.savvi-staging.com/api/v1/find_member

Find Member via XML & Sample

curl -v  -H "Content-Type: application/xml" -X POST  -d   "<?xml version="1.0" encoding="UTF-8" ?> <user> <email>[email protected]</email> </user> " http://www.savvi-staging.com/api/v1/find_member?authentication_token=AzXimVQyVqgDtRiGd3EH

Expanded for readability:

curl -v  -H "Content-Type: application/xml" -X POST  -d   "
  <?xml version="1.0" encoding="UTF-8" ?>
    <user>
      <email>[email protected]</email>
    </user>
" http://www.savvi-staging.com/api/v1/find_member?authentication_token=AzXimVQyVqgDtRiGd3EH
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment