Introduction

Welcome to the PayWhirl API Reference. Here you will find details about our API and the methods it supports. We are consistently trying to make our web services better, so if you run into any issues or need help getting set up, please reach out to our support team.

Here's a high-level overview of how the PayWhirl services work:

  1. Make a PayWhirl account
  2. Create some plans
  3. Add your customers
  4. Add the customer's payment cards
  5. Attach plans to customers using subscribe
  6. Sit back and let us handle the recurring payments as you focus on your core product

The details for the rest of the options you see to the left will be explained in their individual sections.

Next will be a slightly more technical explanation of the usage details. The target audience is assumed to have general knowledge of software development and that our RESTful API uses POST and GET methods to send and receive data behind the scenes, so an active internet connection is required.

The PayWhirl libraries follow a typical object-oriented or object-based software pattern, where you simply instantiate a PayWhirl object using your API credentials (which will be discussed in the Authentication section) and call a variety of methods to manipulate your account while the PayWhirl object abstracts away network authentication and requests.

The vast majority of methods recieve a JSON object from our servers that is translated by the library into that language's native dictionary-like data structure. The returned object is either something that you've directly requested, or is an object that can be seen as a sort of receipt, verifying that your changes have been acknowledged and stored. Anything that doesn't operate this way will explicitly say so in its section of this documentation.


                

Authentication

The standard way to use the API is to download the library for the language of your project as described below.

Place the library file in your project and import the class so that you can instantiate a PayWhirl object. When you create a new PayWhirl object you need to pass in your API key and secret, which can be found in the API key section of the main site.

You can also find this page in your dashboard in the following section:

Settings & Account > Developer > API Keys

If you're planning on writing your own version of the API or just want to use your own HTTP requests, you simply need to pass the api key and api secret in the headers of your requests. You can see examples of how to do this by downloading and inspecting any of the supplied libraries.


Endpoint

All calls made to the API will use the following endpoint:
https://api.paywhirl.com

PHP SDK

Drop the PHP SDK into your project and enter your API credentials to get started quickly. Examples of SDK usage are present on the right-hand column of the API documentation.

Download the PHP SDK
You can also visit the repository at this github link.

Python SDK

Drop the Python SDK into your project and enter your API credentials to get started quickly. Examples of SDK usage are present on the right-hand column of the API documentation.

Download the Python SDK
You can also visit the repository at this github link.

NodeJS SDK

Drop the NodeJS SDK into your project and enter your API credentials to get started quickly. Examples of SDK usage are present on the right-hand column of the API documentation.

Download the Node SDK
You can also visit the repository at this github link.

Ruby SDK

The preferred method for using the Ruby library is to gem install paywhirl from your terminal of choice, but if you are not using ruby gems you can still download the basic .rb file here.

Drop the Ruby SDK into your project and enter your API credentials to get started quickly. Examples of SDK usage are present on the right-hand column of the API documentation.

Download the Ruby SDK
You can also visit the repository at this github link.

// include PayWhirl PHP SDK
require_once("PayWhirl.php");

$api_key = "pwpk_xxxxxxxxxxxxxxx";
$api_secret = "pwpsk_xxxxxxxxxxx";

$payWhirl = new \PayWhirl\PayWhirl($api_key, $api_secret);
# include PayWhirl Python SDK
import paywhirl as pw

api_key = 'pwpk_xxxxxxxxxxxxxxx'
api_secret = 'pwpsk_xxxxxxxxxxx'

paywhirl = pw.PayWhirl(api_key, api_secret)
# The 'faraday' dependency is required
# If you used 'gem install paywhirl' it will be included automatically

# include PayWhirl Ruby SDK
require_relative "paywhirl"

api_key = "pwpk_xxxxxxxxxxxxxxx"
api_secret = "pwpsk_xxxxxxxxxxx"

paywhirl = PayWhirl.new(api_key, api_secret)

Customers

Customer objects are the primary abstraction mechanism for storing information about a specific real person. You can later attach customers to plans using a subscription, or you can charge them directly for single-instance payments.

The customer section of the API allows you to create, update, and retrieve information about your customers.

You might find it useful to keep track of your customer id numbers as you create them so that you have an easy way to select customers you want to find information about or to manipulate.

GET /customers

The primary purpose of this method is to retrieve a selection of your customers (that can be ordered via the parameters below). This is useful for keeping track of your customers in a local database for bookkeeping purposes and for having a local copy that you can edit before submitting changes via the update customer method.

An important distinction to keep in mind is that the customer's id is distinct from your (the PayWhirl account holder's) user_id.

This method returns an indexed array containing Customers of type object.

Parameters

For parameters, the method will accept one of the key-value pairs listed below.

limit
integer Number of entries to return. Limit 100.
order_key
string Field to sort by. Default `id`.
order_direction
string Direction to order. (asc/desc) Defaults to `desc`.
before_id
integer All customers returned will have an ID less than before_id.
after_id
integer All customers returned will have an ID greater than after_id
keyword
string (Optional) Filter by keyword

// pass in an array containing any of the available params to the left
$data = array( "limit" => 2 );
$myobj = $payWhirl->getCustomers($data);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [id] => 34
      [user_id] => 1
      [first_name] => Awesome
      [last_name] => Person
      [email] => awesome+person@paywhirl.com
      [phone] => 4564564566
      [address] => 123 Easy Street
      [city] => Los Angeles
      [state] => California
      [zip] => 93003
      [country] => US
      [created_at] => 2015-11-17 19:52:34
      [updated_at] => 2015-11-21 04:29:45
      [gateway_reference] => 783789y6r890
      [default_card] => 34
      [gateway_type] => PayPal
      [gateway_id] => 18
      [currency] => USD
      [deleted_at] =>
      [utm_source] =>
      [utm_medium] =>
      [utm_term] => online payments
      [utm_content] =>
      [utm_campaign] =>
      [utm_group] =>
      [metadata] =>
    )
  [1] => stdClass Object
    (
      [id] => 46
      [user_id] => 1
      [first_name] => Joe
      [last_name] => Cool
      [email] => joe@paywhirl.com
      [phone] => 8978768768
      [address] => 123 Easy Street
      [city] => Dallas
      [state] => Texas
      [zip] => 93003
      [country] => US
      [created_at] => 2015-11-24 17:04:01
      [updated_at] => 2015-11-25 16:48:19
      [gateway_reference] => cus_56549881e6e03
      [default_card] => 45
      [gateway_type] => Stripe
      [gateway_id] => 20
      [currency] => USD
      [deleted_at] =>
      [utm_source] =>
      [utm_medium] =>
      [utm_term] =>
      [utm_content] =>
      [utm_campaign] =>
      [utm_group] =>
      [metadata] =>
    )
)

GET /customer/{id}

The primary purpose of this method is to retrieve information about an individual customer from the PayWhirl database for your personal use. This will most likely be useful to you as a tool for displaying customer information in your app, or as a way to grab a current version of a specific customer's data in order to modify it before submitting an update customer request.

This method returns a Customer object of type object.

Parameters

For parameters, you can select the customer you desire by passing in the customer's database assigned (integer) ["id"] or the user-supplied (string) ["email"].


// pass in an integer or string to retrieve the desired customer data
$customerId = 34;
$myobj = $payWhirl->getCustomer($customerId);
print_r($myobj);


// example response
stdClass Object
(
  [id] => 34
  [user_id] => 1
  [first_name] => Awesome
  [last_name] => Person
  [email] => awesome+person@paywhirl.com
  [phone] => 4564564566
  [address] => 123 Easy Street
  [city] => Los Angeles
  [state] => California
  [zip] => 93003
  [country] => US
  [created_at] => 2015-11-17 19:52:34
  [updated_at] => 2015-11-21 04:29:45
  [gateway_reference] => 783789y6r890
  [default_card] => 34
  [gateway_type] => PayPal
  [gateway_id] => 18
  [currency] => USD
  [deleted_at] =>
  [utm_source] =>
  [utm_medium] =>
  [utm_term] => online payments
  [utm_content] =>
  [utm_campaign] =>
  [utm_group] =>
  [metadata] =>
)

POST /create/customer

Create a new Customer by passing in an array of key-value pairs. The parameters below tagged "(required)" can be used to create a minimal Customer. The ["email"] field in particular is used as one of two candidate keys for the database. The second candidate key is a database-supplied ["id"] field.

This method is the third step after setting up your account and creating some plans.

Later, when you're binding a customer and plan via a subscription, you will need to supply the customer's id.

Also of note is that the minimum viable password needs to be between 6 and 20 characters, and uses the following perl-compatible regex that might be useful to include in your own code:

/^[A-Za-z0-9~!@#$%^&*()_\-+=<>,.?\/;:{}\\\\[\]|]{6,}$/

Although the technical minimum password length is 6 characters, we do recommend that you stress the importance of a password that is around 14-ish characters long to harness the power of combinatoric explosions. It's also a good idea to remind people that they shouldn't use the same password for multiple websites or services.

It is also important to never locally store the password string, especially in plaintext. The plaintext password should be secured by the HTTPS request, and is hashed on our servers before it ever touches the database. The best practice is to immediately submit the request upon a customers' data entry and then store the returned object.

Email Settings: this method will trigger the Welcome Email event if you've elected to create and use a welcome template email.

Parameters

first_name
string First name (required)
last_name
string Last name (required)
email
string Email address (required)
password
string Password (required)
currency
string Currency code of this user"s currency (ex. USD, GBP, AUD, CAD, EUR, etc) (required)
phone
integer Phone number
address
string Street address
city
string City
state
string State / Region
zip
string Zip / Postal Code
country
string Country Code (ex. US, GB, CA, AU, etc)
gateway_id
string PayWhirl ID of payment gateway to attach to customer. If left blank, first loaded gateway will be used.
utm_source
string Acquisition source (ex. google, bing, email, fall_campaign, etc)
utm_medium
string Acquisition medium (ex. CPC, banner, text_ad, etc)
utm_term
string Acquisition keyword
utm_content
string Acquisition Ad Content
utm_campaign
string Acquisition Ad Campaign
utm_group
string Acquisition Ad Group

// pass in an array containing any of the available params to the left
$exampleCustomer = array(
    "first_name" => "Sleve",
    "last_name" => "McDichael",
    "email" => "slevem@dandleton.com",
    "password" => "mSyGR+Ai4zXRBo",
    "currency" => "USD"
);

// the created customer is returned as an array
$myobj = $payWhirl->createCustomer($exampleCustomer);
print_r($myobj);

// example response
stdClass Object
(
  [id] => 36
  [user_id] =>
  [first_name] => Sleve
  [last_name] => McDichael
  [email] => slevem@dandleton.com
  [phone] =>
  [address] =>
  [city] =>
  [state] =>
  [zip] =>
  [country] =>
  [created_at] => 2015-11-17 19:52:34
  [updated_at] => 2015-11-21 04:29:45
  [gateway_reference] => 783789y6r890
  [default_card] => 0
  [gateway_type] => PayPal
  [gateway_id] => 18
  [currency] => USD
  [deleted_at] =>
  [utm_source] =>
  [utm_medium] =>
  [utm_term] => online payments
  [utm_content] =>
  [utm_campaign] =>
  [utm_group] =>
  [metadata] =>
)

POST /update/customer

The update customer method requires that you return ALL of the customer information to be updated, so the standard workflow should be get customer, then change any data you want, then return all of the customer data. Any empty fields will be removed from the customer object.

The update method is mostly useful for things like changing the default card on file for a customer, or for fixing an error in a name. You cannot use this method unless you've already used the create customer method to register a customer object with our service.

The update method will read in an array of key-value pairs that you wish to alter, and will update the customer associated with the ["id"] contained in the collection passed in. If you don't know the ["id"] of the customer you wish to modify, you can utilize the /GET/customer/ method for your language and search by email address. If you don't know the email address, you can use the /GET/customers/ method to retrieve an array of all customers and their ids.

Parameters

id
string PayWhirl customer ID (required)
first_name
string First name
last_name
string Last name
email
string Email address
password
string Password
phone
integer Phone number
address
string Street address
city
string City
state
string State / Region
zip
string Zip / Postal Code
country
string Country Code (ex. US, GB, CA, AU, etc)
default_card
integer Default Payment Card ID
utm_source
string Acquisition source (ex. google, bing, email, fall_campaign, etc)
utm_medium
string Acquisition medium (ex. CPC, banner, text_ad, etc)
utm_term
string Acquisition keyword
utm_content
string Acquisition Ad Content
utm_campaign
string Acquisition Ad Campaign
utm_group
string Acquisition Ad Group

// pass in your desired customer data with ID included
$exampleCustomer = array(
    "id" => 36,
    "first_name" => "Stove",
    "last_name" => "Dandleton",
    "email" => "slevem@dandleton.com",
    "currency" => "USD"
);

$myobj = $payWhirl->updateCustomer($exampleCustomer);
print_r($myobj);

// example response
stdClass Object
(
  [id] => 36
  [user_id] =>
  [first_name] => Stove
  [last_name] => Dandleton
  [email] => slevem@dandleton.com
  [phone] =>
  [address] =>
  [city] =>
  [state] =>
  [zip] =>
  [country] =>
  [created_at] => 2015-11-17 19:52:34
  [updated_at] => 2015-11-21 04:29:45
  [gateway_reference] => 783789y6r890
  [default_card] => 0
  [gateway_type] => PayPal
  [gateway_id] => 18
  [currency] => USD
  [deleted_at] =>
  [utm_source] =>
  [utm_medium] =>
  [utm_term] => online payments
  [utm_content] =>
  [utm_campaign] =>
  [utm_group] =>
  [metadata] =>
)

GET /questions

This method returns a list of all questions associated with your account that can be displayed on your checkout or sign up forms. For more information about the data fields, there is a graphical implementation in the PayWhirl dashboard that clearly elucidates the options.

The general purpose of any form question is for you to gather information from your customers without needing to use a secondary polling service. By utilizing the checkout questions, you can get small snippets of information that might be useful for your company to analyze. This method will most likely be useful for finding values needed to store in your database for easier parsing later.

Note that this does not grab questions associated with individual subscribers, but retrieves all of the questions associated with your PayWhirl account.

Parameters

limit
integer Number of records to return

$limit = 1;

// if params are left empty, the default limit is 100
$myobj = $payWhirl->getQuestions($limit);
print_r($myobj);

// example output
Array
(
  [0] => stdClass Object
    (
      [type] => select
      [required] => 1
      [label] => Is the sky blue?
      [placeholder] =>
      [className] => form-control
      [name] => select-1498507402
      [values] => Array
        (
          [0] => stdClass Object
            (
                [label] => Yes
                [value] => Yes
                [selected] => 1
            )
          [1] => stdClass Object
            (
                [label] => No
                [value] => No
            )
        )
    )
)

POST /update/answer

This method allows you to create or modify an answer provided by a given user, selected by ["customer_id"], ["question_name"], and ["answer"].

The general idea is that any given customer will answer questions during checkout (or with this method, whenever you choose). This method provides a way for you to associate a given answer with a customer and a question name. Later, you can use the get answers method to retrieve and parse the data you've acquired from your customers.

Parameters

question_name
string Question Name (required)
customer_id
integer PayWhirl customer ID (required)
answer
string Value of answer (required)

$updatedAnswer = array(
    "customer_id" => 238370,
    "question_name" => "select-1498507402",
    "answer" => "hats?"
);

$myobj = $payWhirl->updateAnswer($updatedAnswer);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [name] => select-1498507402
      [label] => Is the sky blue?
      [answer] => hats?
    )
)

GET /answers

Get a complete lists of a customer's answers to profile questions by passing in an integer representing the customer ID.

The general idea of the get answers method is that it allows you to retrieve all of the answered questions associated with a given customer. The most common use-case for this is to download all of the information stored about your customers and store it in a local database, or convert it to a spreadsheet-readable format so that you can parse the feedback you've acquired.

Parameters

customer_id
integer Customer ID (required)

$customerID = array("customer_id" => 36);
$myobj = $payWhirl->getAnswers($customerID);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [name] => select-1498507402
      [label] => Is the sky blue?
      [answer] => hats?
    )
)

GET /addresses

Get a complete lists of a customer's addresses by passing in an integer representing the customer ID.

The general idea of the get addresses method is that it allows you to retrieve all of the additional addresses that a customer has added to their account. The most common use-case for this is if you want to allow your customers to ship to multiple locations, and want to keep a reference for additional shipping options.

Parameters

customer_id
integer Customer ID (required)

$customerID = array("customer_id" => 36);
$myobj = $payWhirl->getAddresses($customerID);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [id] => 21
      [user_id] => 1
      [customer_id] => 34
      [first_name] => Awesome
      [last_name] => Person
      [phone] => 4564564566
      [address] => 123 Easy Street
      [city] => Los Angeles
      [state] => California
      [zip] => 93003
      [country] => US
      [created_at] => 2015-11-17 19:52:34
      [updated_at] => 2015-11-21 04:29:45
      [deleted_at] =>
    )
  [1] => stdClass Object
    (
      [id] => 11
      [user_id] => 1
      [customer_id] => 46
      [first_name] => Joe
      [last_name] => Cool
      [phone] => 8978768768
      [address] => 123 Easy Street
      [city] => Dallas
      [state] => Texas
      [zip] => 93003
      [country] => US
      [created_at] => 2015-11-24 17:04:01
      [updated_at] => 2015-11-25 16:48:19
      [deleted_at] =>
    )
)

GET /address

Get a single address by passing in an integer representing the address ID.

The general idea of the get address method is that it allows you to get a specific extra address a customer has added to their account. The most common use-case for this is if you want to allow your customers to ship to multiple locations, and want to keep a reference for additional shipping options.

Parameters

address_id
integer Address ID (required)

$addressID = array("address_id" => 21);
$myobj = $payWhirl->getAddress($addressID);
print_r($myobj);

// example response
stdClass Object
  (
    [id] => 21
    [user_id] => 1
    [customer_id] => 34
    [first_name] => Awesome
    [last_name] => Person
    [phone] => 4564564566
    [address] => 123 Easy Street
    [city] => Los Angeles
    [state] => California
    [zip] => 93003
    [country] => US
    [created_at] => 2015-11-17 19:52:34
    [updated_at] => 2015-11-21 04:29:45
    [deleted_at] =>
  )

GET /profile

Get a complete customer profile (customer info, addresses, and profile answers) by using an integer representing the customer ID.

The general idea of the get profile method is that it allows you to retrieve all of the information associated with a given customer. The most common use-case for this is if you want to keep a copy of your customer's records, or if you want a more detailed overview of a customer than the get customers methods provides.

Parameters

customer_id
integer Customer ID (required)

$customerID = array("customer_id" => 36);
$myobj = $payWhirl->getProfile($customerID);
print_r($myobj);

// example response
Array
(
  [customer] => stdClass Object
    (
      [id] => 34
      [user_id] => 1
      [first_name] => Awesome
      [last_name] => Person
      [email] => awesome+person@paywhirl.com
      [phone] => 4564564566
      [address] => 123 Easy Street
      [city] => Los Angeles
      [state] => California
      [zip] => 93003
      [country] => US
      [created_at] => 2015-11-17 19:52:34
      [updated_at] => 2015-11-21 04:29:45
      [gateway_reference] => 783789y6r890
      [default_card] => 34
      [gateway_type] => PayPal
      [gateway_id] => 18
      [currency] => USD
      [deleted_at] =>
      [utm_source] =>
      [utm_medium] =>
      [utm_term] => online payments
      [utm_content] =>
      [utm_campaign] =>
      [utm_group] =>
      [metadata] =>
    )
  [addresses] => Array
    (
      [0] => stdClass Object
        (
          [id] => 11
          [user_id] => 1
          [customer_id] => 46
          [first_name] => Joe
          [last_name] => Cool
          [phone] => 8978768768
          [address] => 123 Easy Street
          [city] => Dallas
          [state] => Texas
          [zip] => 93003
          [country] => US
          [created_at] => 2015-11-24 17:04:01
          [updated_at] => 2015-11-25 16:48:19
          [deleted_at] =>
        )
      [1] => stdClass Object
        (
          [id] => 25
          [user_id] => 1
          [customer_id] => 46
          [first_name] => Joe
          [last_name] => Cool
          [phone] => 8978768768
          [address] => 126 Difficult Street
          [city] => Dallas
          [state] => Texas
          [zip] => 93003
          [country] => US
          [created_at] => 2015-11-25 17:04:01
          [updated_at] => 2015-11-26 16:48:19
          [deleted_at] =>
        )
    )
  [answers] => Array
    (
      [0] => stdClass Object
        (
          [name] => select-1498507402
          [label] => Is the sky blue?
          [answer] => hats?
        )
    )
)

Plans

Plans can be considered one of the core products that PayWhirl manages for you. The general idea of a plan is that it establishes the "how much" and "when" to bill for the system, while also containing the "what" for the customer.

The PayWhirl plan page is the usual method for generating plans outside of this API, and can be a good resource for understanding each aspect of the plan object.

GET /plans

Get a list of plans created by your account.

The get plans method will return a list of up to 100 plans associated with your account. You can choose which slice of plans you want returned by using the before_id and after_id parameters. Each plan has a set of questions associated with it so that you can gather information on a per-plan basis.

Parameters

limit
integer Number of entries to return. Limit 100.
order_key
string Field to sort by. Default `id`.
order_direction
string Direction to order. (asc/desc) Defaults to `desc`.
before_id
integer All plans returned will have an id less than before_id.
after_id
integer All plans returned will have an id greater than after_id

plan_params = {
      'limit': 1,
      'order_key': 'id',
      'order_direction': 'asc',
}

myobj = paywhirl.get_plans(plan_params)
print(myobj)

# example response
[{'active': 0,
  'autorenew_plan': 0,
  'autorenew_setup_fee': 0,
  'billing_amount': 2,
  'billing_cycle_anchor': 0,
  'billing_dates': '',
  'billing_frequency': 'day',
  'billing_interval': 1,
  'created_at': '2017-06-26 20:03:22',
  'currency': 'USD',
  'deleted_at': None,
  'description': '',
  'enabled': 0,
  'file': '',
  'id': 17693,
  'image': '',
  'installments': 0,
  'metadata': '',
  'name': 'Daily Demo Plan',
  'questions': '[{'name':'select-1498507402','repeated':0}]',
  'require_shipping': 1,
  'require_tax': 1,
  'setup_fee': 0,
  'sku': 'DEMO-SKU-1',
  'starting_day': 0,
  'tags': '',
  'trial_days': 0,
  'updated_at': '2017-08-30 17:50:48',
  'user_id': 1}]


$planParams = array(
    "limit" => 1,
    "order_key" => "id",
    "order_direction" => "asc"
    );
$myobj = $payWhirl->getPlans($planParams);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [active] => 0
      [autorenew_plan] => 0
      [autorenew_setup_fee] => 0
      [billing_amount] => 2
      [billing_cycle_anchor] => 0
      [billing_dates] =>
      [billing_frequency] => day
      [billing_interval] => 1
      [created_at] => 2017-06-26 20:03:22
      [currency] => USD
      [deleted_at] => None
      [description] =>
      [enabled] => 0
      [file] =>
      [id] => 17693
      [image] =>
      [installments] => 0
      [metadata] =>
      [name] => Daily Demo Plan
      [questions] => [{"name":"select-1498507402","repeated":0}]
      [require_shipping] => 1
      [require_tax] => 1
      [setup_fee] => 0
      [sku] => DEMO-SKU-1
      [starting_day] => 0
      [tags] =>
      [trial_days] => 0
      [updated_at] => 2017-08-30 17:50:48
      [user_id] => 1
    )
)

GET /plan/{id}

Get a single plan by plan ID.

As described above in the get plans section, plans are the core object that PayWhirl manages for you. This method is useful for inspecting the details of a specific plan so that you can either keep track of plans in your own local database, or so that you can have a base object to modify before updating the data in a plan.

If you need to find the plan id for retrieval of a specific plan, you can either check your plans page or use get plans to retrieve a larger list to select from.

Parameters

id
integer Plan ID

plan_id = 17693

myobj = paywhirl.get_plan(plan_id)
print(myobj)

# example response
[{'active': 0,
  'autorenew_plan': 0,
  'autorenew_setup_fee': 0,
  'billing_amount': 2,
  'billing_cycle_anchor': 0,
  'billing_dates': '',
  'billing_frequency': 'day',
  'billing_interval': 1,
  'created_at': '2017-06-26 20:03:22',
  'currency': 'USD',
  'deleted_at': None,
  'description': '',
  'enabled': 0,
  'file': '',
  'id': 17693,
  'image': '',
  'installments': 0,
  'metadata': '',
  'name': 'Daily Demo Plan',
  'questions': '[{'name':'select-1498507402','repeated':0}]',
  'require_shipping': 1,
  'require_tax': 1,
  'setup_fee': 0,
  'sku': 'DEMO-SKU-1',
  'starting_day': 0,
  'tags': '',
  'trial_days': 0,
  'updated_at': '2017-08-30 17:50:48',
  'user_id': 1}]

$planID = 17693;
$myobj = $payWhirl->getPlan($planID);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [active] => 0
      [autorenew_plan] => 0
      [autorenew_setup_fee] => 0
      [billing_amount] => 2
      [billing_cycle_anchor] => 0
      [billing_dates] =>
      [billing_frequency] => day
      [billing_interval] => 1
      [created_at] => 2017-06-26 20:03:22
      [currency] => USD
      [deleted_at] => None
      [description] =>
      [enabled] => 0
      [file] =>
      [id] => 17693
      [image] =>
      [installments] => 0
      [metadata] =>
      [name] => Daily Demo Plan
      [questions] => [{"name":"select-1498507402","repeated":0}]
      [require_shipping] => 1
      [require_tax] => 1
      [setup_fee] => 0
      [sku] => DEMO-SKU-1
      [starting_day] => 0
      [tags] =>
      [trial_days] => 0
      [updated_at] => 2017-08-30 17:50:48
      [user_id] => 1
    )
)

POST /create/plan

Create a plan that allows you to set rules for how your customers will be billed. Each time a customer subscribes to one of your plans, the rules of your plan will be attached to your subscription. If you change the rules for the plan, they will be applied to the customer's next invoice. Your plan will automatically be given an id with which you can then store and use later to update the plan if necessary.

This is generally the second step in setting up your PayWhirl account. The high level overview is that you create customers and plans, then they are linked together via a subscription.

The easiest way to get a feel for how to create a plan is to inspect the plan page

Parameters

name
string Plan name (required)
setup_fee
decimal Plan setup fee (default: 0.00)
installments
integer Number of times the customer should be billed. Use 0 for unlimited. (default: 0)
description
string Plan description (default: "")
installments
integer Number of times the customer should be billed. Use 0 for unlimited. (default: 0)
billing_amount
decimal Amount customer should be billed (required)
billing_interval
integer Interval in which billing should occur (default: 1)
billing_frequency
string day, week, month, year (default: month)
trial_days
integer Number of days for a free trial (default: 0)
sku
string Plan SKU (default: "")
currency
string Currency Code for Plan (default: USD)
require_tax
boolean Should the plan have tax rules applied? (default: 0)
require_shipping
boolean Should the plan have shipping rules applied? (default: 0)
billing_cycle_anchor
integer Day of the month billing should begin. Use 0 for date of signup. (default: 0)
enabled
boolean Enable to show plan in browse section of customer portal (default: 0)
tags
string Comma-separated list of tags to be added to the plan (default: empty)

plan_data = {
  'user_id': 1,
  'name': 'Super Order Plan',
  'setup_fee': 0,
  'installments': 3,
  'require_shipping': 1,
  'active': 0,
  'image': '',
  'starting_day': 0,
  'description': '',
  'created_at': '2015-11-19 17:20:42',
  'updated_at': '2016-03-10 00:14:37',
  'billing_amount': 10,
  'billing_interval': 1,
  'billing_frequency': 'day',
  'billing_dates': '',
  'trial_days': 0,
  'sku': 'e456456',
  'currency': 'USD',
  'require_tax': 0,
  'billing_cycle_anchor': 0,
  'deleted_at': None,
  'file': '',
  'autorenew_plan': 0,
  'autorenew_setup_fee': 0,
  'tags': '',
  'enabled': 0,
  'questions': ''
}

myobj = paywhirl.create_plan(plan_data)
print(myobj)

# example response
{
  'billing_amount': '10',
  'billing_cycle_anchor': 0,
  'billing_dates': '',
  'billing_frequency': 'day',
  'billing_interval': '1',
  'created_at': '2017-11-11 01:59:36',
  'currency': 'USD',
  'description': '',
  'enabled': '0',
  'id': 32300,
  'installments': '3',
  'name': 'Super Order Plan',
  'require_shipping': '1',
  'require_tax': '0',
  'setup_fee': '0',
  'sku': 'e456456',
  'trial_days': '0',
  'updated_at': '2017-11-11 01:59:36',
  'user_id': 1
}

$planData = Array(
  "user_id" => 1,
  "name" => "Super Order Plan",
  "setup_fee" => 0,
  "installments" => 3,
  "require_shipping" => 1,
  "active" => 0,
  "image" => "",
  "starting_day" => 0,
  "description" => "",
  "created_at" => "2015-11-19 17:20:42",
  "updated_at" => "2016-03-10 00:14:37",
  "billing_amount" => 10,
  "billing_interval" => 1,
  "billing_frequency" => "day",
  "billing_dates" => "",
  "trial_days" => 0,
  "sku" => "e456456",
  "currency" => "USD",
  "require_tax" => 0,
  "billing_cycle_anchor" => 0,
  "deleted_at" => "",
  "file" => "",
  "autorenew_plan" => 0,
  "autorenew_setup_fee" => 0,
  "tags" => "",
  "enabled" => 0,
  "questions" => ""
);

$myobj = $payWhirl->createPlan($planData);
print_r($myobj);

// example response
stdClass Object
(
  [billing_amount] => 10
  [billing_cycle_anchor] => 0
  [billing_dates] =>
  [billing_frequency] => day
  [billing_interval] => 1
  [created_at] => 2017-11-11 01:59:36
  [currency] => USD
  [description] =>
  [enabled] => 0
  [id] => 32300
  [installments] => 3
  [name] => Super Order Plan
  [require_shipping] => 1
  [require_tax] => 0
  [setup_fee] => 0
  [sku] => e456456
  [trial_days] => 0
  [updated_at] => 2017-11-11 01:59:36
  [user_id] => 1
)

POST /update/plan

To update a plan you simply pass in a plan object that has the values you wish to update, and ensure that the plan_id field matches the plan you wish to change.

The general use-case for updating a plan is that maybe the products you're offering now are higher quality, so the current customers' rates need to go up, or maybe you noticed an error in the original plan and need to modify it without creating a whole new plan and re-subscribing your customers. Any changes made to an existing plan will automatically be applied to any subscribed customers, so you don't need to worry about any additional modifications other than changing your plan.

The easiest way to update a plan is to use the get plan method if you know the plan_id, or the get plans method to retrieve a larger list to find your plan_id that needs changing. Once you have your plan object, simply modify the fields you wish to change and re-submit via update plan.

Parameters

id
integer Plan ID (required)
name
string Plan name
setup_fee
decimal Plan setup fee
installments
integer Number of times the customer should be billed. Use 0 for unlimited.
description
string Plan description
installments
integer Number of times the customer should be billed. Use 0 for unlimited.
billing_amount
decimal Amount customer should be billed
billing_interval
integer Interval in which billing should occur
billing_frequency
string day,week,month,year,dates
billing_dates
string When billing_frequency is dates, send a JSON-encoded array of specific dates of the year to be used instead of billing interval.
trial_days
integer Number of days for a free trial
sku
string Plan SKU
currency
string Currency Code for Plan
require_tax
boolean Should the plan have tax rules applied?
require_shipping
boolean Should the plan have shipping rules applied?
billing_cycle_anchor
integer Day of the month billing should begin. Use 0 for date of signup.
enabled
boolean Enable to show plan in browse section of customer portal
tags
string Comma-separated list of tags to be added to the plan

updated_plan_data = {
  'id': 32300,
  'user_id': 1,
  'name': 'Super Order Plan',
  'setup_fee': 0,
  'installments': 6,
  'require_shipping': 1,
  'active': 0,
  'image': '',
  'starting_day': 0,
  'description': '',
  'created_at': '2015-11-19 17:20:42',
  'updated_at': '2016-03-10 00:14:37',
  'billing_amount': 120,
  'billing_interval': 1,
  'billing_frequency': 'day',
  'billing_dates': '',
  'trial_days': 0,
  'sku': 'e456456',
  'currency': 'USD',
  'require_tax': 0,
  'billing_cycle_anchor': 0,
  'deleted_at': None,
  'file': '',
  'autorenew_plan': 1,
  'autorenew_setup_fee': 0,
  'tags': '',
  'enabled': 0,
  'questions': ''
}

myobj = paywhirl.update_plan(updated_plan_data)
print(myobj)

# example response
{
  'billing_amount': '10',
  'billing_cycle_anchor': 0,
  'billing_dates': '',
  'billing_frequency': 'day',
  'billing_interval': '1',
  'created_at': '2017-11-11 01:59:36',
  'currency': 'USD',
  'description': '',
  'enabled': '0',
  'id': 32300,
  'installments': '3',
  'name': 'Super Order Plan',
  'require_shipping': '1',
  'require_tax': '0',
  'setup_fee': '0',
  'sku': 'e456456',
  'trial_days': '0',
  'updated_at': '2017-11-11 01:59:36',
  'user_id': 1
}

$updatedPlanData = Array(
  "id" => 32000,
  "user_id" => 1,
  "name" => "Super Order Plan",
  "setup_fee" => 0,
  "installments" => 6,
  "require_shipping" => 1,
  "active" => 0,
  "image" => "",
  "starting_day" => 0,
  "description" => "",
  "created_at" => "2015-11-19 17:20:42",
  "updated_at" => "2016-03-10 00:14:37",
  "billing_amount" => 120,
  "billing_interval" => 1,
  "billing_frequency" => "day",
  "billing_dates" => "",
  "trial_days" => 0,
  "sku" => "e456456",
  "currency" => "USD",
  "require_tax" => 0,
  "billing_cycle_anchor" => 0,
  "deleted_at" => "",
  "file" => "",
  "autorenew_plan" => 0,
  "autorenew_setup_fee" => 0,
  "tags" => "",
  "enabled" => 0,
  "questions" => ""
);

$myobj = $payWhirl->updatePlan($planData);
print_r($myobj);

// example response
stdClass Object
(
  [billing_amount] => 120
  [billing_cycle_anchor] => 0
  [billing_dates] =>
  [billing_frequency] => day
  [billing_interval] => 1
  [created_at] => 2017-11-11 01:59:36
  [currency] => USD
  [description] =>
  [enabled] => 0
  [id] => 32300
  [installments] => 6
  [name] => Super Order Plan
  [require_shipping] => 1
  [require_tax] => 0
  [setup_fee] => 0
  [sku] => e456456
  [trial_days] => 0
  [updated_at] => 2017-11-11 01:59:36
  [user_id] => 1
)

Subscriptions

Subscriptions are the core objects that handle the billing process when you're not doing individual charges.

You create a subscription using the subscribe customer method, which requires that you have at least one customer with a payment method on file, as well as a plan you wish to subscribe the customer to. Once you've subscribed a customer, PayWhirl will generate invoices at regular intervals, which will then attempt to process payments at a time specified by your plans.

If you want up-to-date information about the status of your subscribers, see the webhooks section below to learn how to get feedback from our system.

GET /subscriptions/{id}

Get a list of subscriptions associated with a given customer.

This method is useful for determining which services a customer is or isn't currently expecting, which you can determine by checking value of current_period_end, which will be a Unix Timestamp (UTC time zone).

To find a customerID to look up, you'll want to check the get customers method for your language, which will return a list of all customers that you can inspect for the customer IDs. It may also be helpful to locally keep your customer IDs stored when you create them, as a large number of methods require a customer ID as input.

Parameters

id
integer Customer ID

$customerID = 36;
$myobj = $payWhirl->getSubscriptions($customerID);
print_r($myobj);

// example response
stdClass Object
(
  [cancel_at_period_end] => 0
  [created_at] => 2017-11-16 00:46:35
  [current_period_end] => 1515974400
  [current_period_start] => 1510793195
  [customer_id] => 36
  [deleted_at] =>
  [id] => 123123
  [installment_plan] => 1
  [installments_left] => 6
  [plan] => stdClass Object
    (
      [active] => 0
      [autorenew_plan] => 0
      [autorenew_setup_fee] => 0
      [billing_amount] => 11
      [billing_cycle_anchor] => 0
      [billing_dates] =>
      [billing_frequency] => day
      [billing_interval] => 1
      [created_at] => 2017-11-11 01:59:36
      [currency] => USD
      [deleted_at] =>
      [description] =>
      [enabled] => 0
      [file] =>
      [id] => 32300
      [image] =>
      [installments] => 6
      [metadata] =>
      [name] => Super Order Plan
      [questions] =>
      [require_shipping] => 1
      [require_tax] => 0
      [setup_fee] => 0
      [sku] => e456456
      [starting_day] => 0
      [tags] =>
      [trial_days] => 0
      [updated_at] => 2017-11-11 05:33:30
      [user_id] => 1
    )
  [plan_id] => 1
  [quantity] => 1
  [trial_end] => 1515974400
  [trial_start] => 1510793195
  [updated_at] => 2017-11-16 00:46:35
  [user_id] => 1
  [widget_id] => 0
)

GET /subscription/{id}

Get a single subscription based on the subscription's ID.

This method returns information about a specific subscription without displaying information about the customer or the plan. This can be useful if you're locally keeping track of subscription ids and want to find out which customers are associated with each plan, or if you need to know how long a subscription has left before you prompt for renewal.

The easiest way to keep track of the subscription IDs to pass in as a parameter is to record the id field whenever you subscribe a customer.

If you choose not to do this, you can find subscription IDs by using the get subscriptions method and passing in your customer IDs, or by using the get subscribers method.

Parameters
id
integer Subscription ID

$subscriptionID = 123;
$myobj = $payWhirl->getSubscription($subscriptionID);
print_r($myobj);

// example response
stdClass Object
(
  [cancel_at_period_end] => 0
  [created_at] => 2017-11-16 00:46:35
  [current_period_end] => 1515974400
  [current_period_start] => 1510793195
  [customer_id] => 36
  [deleted_at] =>
  [id] => 123
  [installment_plan] => 1
  [installments_left] => 6
  [plan_id] => 2
  [quantity] => 1
  [trial_end] => 1515974400
  [trial_start] => 1510793195
  [updated_at] => 2017-11-16 00:46:35
  [user_id] => 1
  [widget_id] => 0
)

POST /subscribe/customer

Enroll a customer in an existing plan. The customer must have a valid payment method on file in order to be enrolled in a plan. Use the GET methods for customers and plans to retrieve your customer and plan IDs.

This is the fifth step described in the introduction, and is the method you'll use to begin charging your customers. The only required fields are customer id and plan id to create a subscription, but free trials are common for subscription services, and the code examples include a method for generating those.

The trial end field uses a Unix Timestamp in the UTC timezone, so you can also generate them using whatever the preferred method is for your system.

Email Settings: this method will trigger the New Subscription Email event if you've elected to create and use a new subscription template email.

The Payment Reminder and Payment Receipt emails are also tied to this method, as those emails are automatically sent when a transaction is about to process, or when a transaction actually processes (if you've chosen to use a template or to create your own emails.)

Unsuccessful Payment emails will also be sent if a customer with an active subscription's charge fails.

Parameters

customer_id
integer Customer ID (required)
plan_id
integer Plan ID (required)
trial_end
integer UNIX timestamp in the future
promo_id
integer ID of promo code to apply
quantity
integer Quantity (Default: 1)

// easy method to generate a timestamp in the future
// if you're looking end a promo on a specific day
// the documentation can be found at the following link:
// http://php.net/manual/en/function.mktime.php
const SECONDS_PER_MINUTE = 60;
const MINUTES_PER_HOUR = 60;
const HOURS_PER_DAY = 24;
const SECONDS_PER_DAY = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY;

$durationOfPlanInDays = 90;
$secondsToAddToTimestamp = ($durationOfPlanInDays * SECONDS_PER_DAY);

// this is just getting a current unix timestamp and adding
// the number of days defined above.
$trialEnd = time() + $secondsToAddToTimestamp;


$customerID = 36;
$planID = 32300;

$myobj = $payWhirl->subscribeCustomer($customerID, $planID, $trialEnd);

print_r($myobj);

// example Response
stdClass Object
(
  [cancel_at_period_end] => 0
  [created_at] => 2017-11-16 00:46:35
  [current_period_end] => 1515974400
  [current_period_start] => 1510793195
  [customer_id] => 36
  [deleted_at] =>
  [id] => 1
  [installment_plan] => 1
  [installments_left] => 6
  [plan_id] => 32300
  [quantity] => 1
  [trial_end] => 1515974400
  [trial_start] => 1510793195
  [updated_at] => 2017-11-16 00:46:35
  [user_id] => 1
  [widget_id] => 0
)

POST /update/subscription

Change the plan or quantity associated with a given subscription. A customer's subscription will stay the same, but the payment plan referenced by that subscription will be modified.

This method is useful as an error-correction mechanism if your customer accidentally selected the wrong plan, or if you want to provide a method for changing customer plans without needing to destroy the whole transaction to create a new one. It can also be used to correct quantity charged of a given plan.

For clarity, the subscription id references the object that handles the timing and execution of the transactions, while the plan id references the object that determines the amount charged and the services provided.

Parameters

subscription_id
integer Subscription ID
plan_id
integer Plan ID
quantity
integer (Optional) Quantity

$subscriptionID = 1;
$planID = 32301;

$myobj = $payWhirl->updateSubscription($subscriptionID, $planID);
print_r($myobj);

// example response
stdClass Object
(
  [cancel_at_period_end] => 0
  [created_at] => 2017-11-16 00:46:35
  [current_period_end] => 1515974400
  [current_period_start] => 1510793195
  [customer_id] => 36
  [deleted_at] =>
  [id] => 1
  [installment_plan] => 1
  [installments_left] => 9
  [plan_id] => 32301
  [quantity] => 1
  [trial_end] => 1515974400
  [trial_start] => 1510793195
  [updated_at] => 2017-11-16 19:50:19
  [user_id] => 1
  [widget_id] => 0
)

POST /unsubscribe/customer

Cancel a customer's existing subscription.

This method will prevent the subscription from making any additional charges, and will unbind a customer from a plan.

It is important to note that this will cancel the subscription immediately, so if you plan to provide additional services during the time remaining on your customers' account, that will be the responsibility of your software. This method strictly prevents additional payments from being processed.

Email Settings: this method will trigger the Cancelled Subscription Email event if you've elected to create and use a cancelled subscription email.

Parameters

subscription_id
integer Subscription ID

$subscriptionID = 1;

$myobj = $payWhirl->unsubscribeCustomer($subscriptionID);
print_r($myobj);

// example response
stdClass Object
(
  [status] => success
)

GET /subscribers

Get a list of active subscribers.

This method simply returns a list of customers that currently have an active subscription. This can be useful for grabbing a list of all customers that you need to provide services for.

The returned list is limited to 100 customers at a time, so it is important to use the starting_after and starting_before parameters to choose the slice you wish to work with.

Parameters

limit
integer Number of results to return. Defaults to 20, Max: 100
order
string Order of results. Values: asc, desc, rand
starting_after
integer Show results with a subscription ID greater than starting_after
starting_before
integer Show results with a subscription ID less than starting_before
keyword
string (Optional) Filter by keyword

$subscriberParams = Array(
  "limit" => 1,
  "order_key" => "id",
  "order_direction" => "asc"
);

$myobj = $payWhirl->getSubscribers($subscriberParams);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
  (
    [created_at] => 2017-11-16 20:21:02
    [current_period_end] => 1518768000
    [current_period_start] => 1510863662
    [customer_id] => 36
    [email] => slevem@dandleton.com
    [first_name] => Stove
    [installment_plan] => 1
    [installments_left] => 9
    [last_name] => Dandleton
    [plan_id] => 32300
    [profile] => Array
          (
            [0] => stdClass Object
                (
                    [answer] => hats?
                    [label] => Is the sky blue?
                    [name] => select-1498507402
                )
          )
    [quantity] => 1
    [subscription_id] => 1
    [updated_at] => 2017-11-16 20:21:02
    [user_id] => 1
  )
)

Invoices

An invoice is an object that contains all the information needed to process a single transaction. You can think of a subscription as a sort of invoice factory, where each invoice produced will handle its own individual task.

While the subscription and charge methods handle the generation of invoices, the methods in this section allow you to view the contents of a single invoice, or to see all of the upcoming invoices for a single customer.

GET /invoice/{id}

Get a single invoice by passing in an invoice ID.

This method returns a single invoice indicating things like whether or not a customer has paid yet, their currency type, or how many attempts were made to collect the payment. These are useful to query for record keeping, or for keeping track of which customers still have outstanding fees.

The main ways to find your invoice IDs programmatically are to either use the get invoices method to get all invoices for a specific customer, or to record the data sent by the payment processing webhooks as described in the wehbooks section of this page. For one-off cases, you can also find your invoice ids in your invoices page.

Parameters

id
integer Invoice ID

invoice_id = 27
myobj = paywhirl.get_invoice(invoice_id)
print(myobj)

# example response
{
  'additional_charge_id': None,
  'address_id': 0,
  'amount_due': 11,
  'attempt_count': 0,
  'attempted': 0,
  'card_id': 154557,
  'carrier': '',
  'charge_id': 0,
  'created_at': '2017-11-16 20:21:02',
  'currency': 'USD',
  'customer_id': 36,
  'deleted_at': None,
  'discount': '0.00',
  'discount_id': 0,
  'due_date': 0,
  'id': 27,
  'integration_errors': '',
  'is_order': 1,
  'is_queued': 0,
  'items':  [
              {
                'amount': 11,
                'created_at': '2017-11-16 20:21:02',
                'currency': 'USD',
                'customer_id': 238370,
                'deleted_at': None,
                'description': 'Subscription to Super Order Plan',
                'id': 409318,
                'invoice_id': 361675,
                'quantity': 1,
                'sku': 'e456456',
                'type': 'plan',
                'updated_at': '2017-11-16 20:21:02',
                'user_id': 1
              }
            ],
  'next_payment_attempt': 1518768000,
  'paid': 0,
  'paid_on': 0,
  'period_end': 1518768000,
  'period_start': 1510863662,
  'profile':  [
                {
                  'answer': 'hats?',
                  'label': 'Is the sky blue?',
                  'name': 'select-1498507402'
                }
              ],
  'promo_code': '',
  'promo_id': 0,
  'promo_uses': 0,
  'service': '',
  'shipping': 1,
  'shipping_total': 0,
  'shopify_created_at': None,
  'status': 'Subscribed',
  'subscription_id': 2342343,
  'subtotal': 11,
  'tax': 0,
  'tax_total': 0,
  'tracking_number': '',
  'updated_at': '2017-11-16 20:21:02',
  'user_id': 1,
  'webhooks_delivered_at': 0
}


$invoiceID = 27;
$myobj = $payWhirl->getInvoice($invoiceID);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [additional_charge_id] =>
      [address_id] => 0
      [amount_due] => 11
      [attempt_count] => 0
      [attempted] => 0
      [card_id] => 154557
      [carrier] =>
      [charge_id] => 0
      [created_at] => 2017-11-16 20:21:02
      [currency] => USD
      [customer_id] => 36
      [deleted_at] =>
      [discount] => 0.00
      [discount_id] => 0
      [due_date] => 0
      [id] => 27
      [integration_errors] =>
      [is_order] => 1
      [is_queued] => 0
      [items] => Array
                (
                  [0] => stdClass Object
                    (
                      [amount] => 11
                      [created_at] => 2017-11-16 20:21:02
                      [currency] => USD
                      [customer_id] => 238370
                      [deleted_at] =>
                      [description] => Subscription to Super Order Plan
                      [id] => 409318
                      [invoice_id] => 361675
                      [quantity] => 1
                      [sku] => e456456
                      [type] => plan
                      [updated_at] => 2017-11-16 20:21:02
                      [user_id] => 1
                    )
                  )
    [next_payment_attempt] => 1518768000
    [paid] => 0
    [paid_on] => 0
    [period_end] => 1518768000
    [period_start] => 1510863662
    [profile] => Array
                (
                  [0] => stdClass Object
                    (
                    [answer] => hats?
                    [label] => Is the sky blue?
                    [name] => select-1498507402
                    )
                )
    [promo_code] =>
    [promo_id] => 0
    [promo_uses] => 0
    [service] =>
    [shipping] => 1
    [shipping_total] => 0
    [shopify_created_at] =>
    [status] => Subscribed
    [subscription_id] => 2342343
    [subtotal] => 11
    [tax] => 0
    [tax_total] => 0
    [tracking_number] =>
    [updated_at] => 2017-11-16 20:21:02
    [user_id] => 1
    [webhooks_delivered_at] => 0
    )
)

GET /invoices/{id}?all=1

Get a list of upcoming (or all) invoices for a specified customer.

This method can be useful for determining which invoices will be processed soon, and for determining what a given customer is expecting. This is also a good place to retrieve information from any survey questions that are asked in ongoing services. Adding the all parameter will return all customer's invoices, not only the upcoming ones.

Parameters

id
integer Customer ID
all
integer 1 returns all invoices, 0 (or not submitted) returns only upcoming ones

$customerID = 36;
$myobj = $payWhirl->getInvoices($customerID);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [additional_charge_id] =>
      [address_id] => 0
      [amount_due] => 11
      [attempt_count] => 0
      [attempted] => 0
      [card_id] => 154557
      [carrier] =>
      [charge_id] => 0
      [created_at] => 2017-11-16 20:21:02
      [currency] => USD
      [customer_id] => 36
      [deleted_at] =>
      [discount] => 0.00
      [discount_id] => 0
      [due_date] => 0
      [id] => 27
      [integration_errors] =>
      [is_order] => 1
      [is_queued] => 0
      [items] => Array
                (
                  [0] => stdClass Object
                    (
                      [amount] => 11
                      [created_at] => 2017-11-16 20:21:02
                      [currency] => USD
                      [customer_id] => 238370
                      [deleted_at] =>
                      [description] => Subscription to Super Order Plan
                      [id] => 409318
                      [invoice_id] => 361675
                      [quantity] => 1
                      [sku] => e456456
                      [type] => plan
                      [updated_at] => 2017-11-16 20:21:02
                      [user_id] => 1
                    )
                  )
    [next_payment_attempt] => 1518768000
    [paid] => 0
    [paid_on] => 0
    [period_end] => 1518768000
    [period_start] => 1510863662
    [profile] => Array
                (
                  [0] => stdClass Object
                    (
                    [answer] => hats?
                    [label] => Is the sky blue?
                    [name] => select-1498507402
                    )
                )
    [promo_code] =>
    [promo_id] => 0
    [promo_uses] => 0
    [service] =>
    [shipping] => 1
    [shipping_total] => 0
    [shopify_created_at] =>
    [status] => Subscribed
    [subscription_id] => 2342343
    [subtotal] => 11
    [tax] => 0
    [tax_total] => 0
    [tracking_number] =>
    [updated_at] => 2017-11-16 20:21:02
    [user_id] => 1
    [webhooks_delivered_at] => 0
    )
)

POST /invoice/{id}/process

Process a pending invoice by passing in an integer representing the invoice ID.

This method can be useful if you want to charge a customer before the automatic invoice processing time rolls around.

You can find invoice IDs with any of the methods illustrated in the get invoices section.

Parameters

id
integer the invoice_id you intend to process

$invoiceID = 22;
$myobj = $payWhirl->processInvoice($invoiceID);
print_r($myobj);

// example response
stdClass Object
(
  [status] => success
)

POST /invoice/{id}/card

Change invoice's payment method.

This method is useful for changing an upcoming invoice's payment method to another card that a customer has on file. The first parameter is an integer representing the ID of the invoice to modify, and the second parameter is the ID of the card you want to use for the invoice.

You can find invoice IDs with any of the methods illustrated in the get invoices section.

Parameters

id
integer the invoice_id you intend to modify
card_id
integer Payment method to change to.

$invoiceID = 22;
$cardID = 6;
$myobj = $payWhirl->updateInvoiceCard($invoiceID, $cardID);
print_r($myobj);

// example response
stdClass Object
(
  [status] => success
)

POST /invoice/{id}/items

Modifies the quantities of line items in a specific invoice.

This method is useful when you want to change the number of line items in an existing invoice. For example, invoice '22' might have items '1111' with a quantity of '2', and '1112' with a quantity of '3', but the customer wants '4' and '5' respectively. Instead of creating a brand new invoice, you can simply call this method and pass in (22, {'1111': 4, '1112': 5}), which will set the line item quantities to the updated values.

You can find invoice IDs with any of the methods illustrated in the get invoices section.

You can find the line item IDs by using the get invoices method above, and looking at the "items", where you will want the "id".

If you set any of the line_items to '0', the item will be deleted from the invoice.

Parameters

id
integer the invoice_id you intend to modify
line_items
object Dictionary or hash with { <line_item_id>: <quantity>, ... }

$invoiceID = 22;
$lineItems = Array("1111" => 4, "1112" => 5);
$myobj = $payWhirl->updateInvoiceItems($invoiceID, $lineItems);
print_r($myobj);

// example response
stdClass Object
(
  [status] => success
  [items_updated] => 2
)

POST /invoice/{id}/items

Modifies the quantities of line items in this invoice.

Parameters

id
integer Invoice ID
POST body
object Hash with keys equal to line item IDs and values to their respective quantities. Quanaity of zero deletes the line item. E.g. {"8675": 2, "8676": 1}

TODO

TODO

POST /invoices

Create an upcoming invoice for a customer.

Parameters

id
customer_id Customer ID
next_payment_attempt
integer UNIX timestamp of the scheduled date of processing.
shipping
integer Charge shipping for this invoice.
tax
integer Charge tax for this invoice.
currency
string Invoice currency.
items
array Array of line items with keys: 'type', 'sku', 'quantity', 'description', 'amount', 'plan_id'

$myobj = $payWhirl->createInvoice([
  'customer_id' => 36, // acquired from using the get_customers() method
  'next_payment_attempt' => date,
  'shipping' => 1,
  'tax' => 1,
  'items' => [{
    'type' => 'product',
    'description' => 'Sample item',
    'amount' => 22.34,
    'quantity' => 1
  }]
]);

print_r($myobj);

// example Response
stdClass Object
(
  [status] => success
  [invoice_id] => 122
)

Gateways

Payment gateways are where you'll set up your business and bank account information so that PayWhirl's automatic transactions can deposit funds into your bank account.

During the development and testing phase, the PayWhirl Test Gateway will allow you to use your plans and create charges without any actual transaction taking place, so you can verify the integrity of your system and experiment with the available methods.

The methods in this section allow you to view the status of all gateways associated with your account, or to check the information about a single gateway.

GET /gateways

Get a list of payment gateways associated with your account.

Parameters


$myobj = $payWhirl->getGateways();
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [id] => 11203
      [user_id] => 1
      [name] => PayWhirl Test Gateway
      [created_at] => 2017-06-26 20:03:21
      [updated_at] => 2017-06-26 20:03:21
      [type] => PaywhirlTest
      [error_message] =>
      [expires] => 0
      [metadata] =>
    )
  [1] => stdClass Object
    (
      [id] => 11208
      [user_id] => 1
      [name] => testGateway
      [created_at] => 2017-06-26 20:46:31
      [updated_at] => 2017-06-26 20:46:31
      [type] => PaywhirlTest
      [error_message] =>
      [expires] => 0
      [metadata] =>
    )
)

GET /gateway/{id}

Get a single payment gateway by ID.

Parameters

id
integer Gateway ID

$gatewayID = 11203;
$myobj = $payWhirl->getGateway($gatewayID);
print_r($myobj);

// example response
stdClass Object
(
  [id] => 11203
  [user_id] => 1
  [name] => PayWhirl Test Gateway
  [created_at] => 2017-06-26 20:03:21
  [updated_at] => 2017-06-26 20:03:21
  [type] => PaywhirlTest
  [error_message] =>
  [expires] => 0
  [metadata] =>
)

Charges

Sometimes it's useful to do a one-time charge, often as a signup fee, or so that you don't need to deal with multiple payment services for non-recurring transactions.

The charge methods offer a simple way to create an invoice with just a charge amount and a customer ID, and to review the contents of a single charge without looking at the entire invoice.

If you want to keep track of the individual charge id, it's returned after a create charge in items[index]->id.

POST /create/charge

Create an invoice with a single charge.

Parameters

customer_id
integer (required)
amount
decimal (required)
quantity
integer (default: 1)
description
string (default: Charge)
schedule
UNIX timestamp defaults to now
sku
string product sku (optional)

$chargeData = Array(
  "customer_id" => 36,
  "amount" => 23.45,
  "quantity" => 1
);

$myobj = $payWhirl->createCharge($chargeData);
print_r($myobj);

// example response
(
  [additional_charge_id] =>
  [address_id] => 0
  [amount_due] => 46.9
  [attempt_count] => 0
  [attempted] => 0
  [card_id] => 154557
  [carrier] =>
  [charge_id] => 0
  [created_at] => 2017-11-16 21:48:41
  [currency] => USD
  [customer_id] => 36
  [deleted_at] =>
  [discount] => 0.00
  [discount_id] => 0
  [due_date] => 0
  [id] => 17
  [integration_errors] =>
  [is_order] => 1
  [is_queued] => 0
  [items] =>  Array
          (
            [0] => stdClass Object
              (
                [amount] => 23.45
                [created_at] => 2017-11-16 21:48:41
                [currency] => USD
                [customer_id] => 238370
                [deleted_at] =>
                [description] => Charge
                [id] => 21
                [invoice_id] => 15
                [quantity] => 2
                [sku] =>
                [type] => fee
                [updated_at] => 2017-11-16 21:48:41
                [user_id] => 1
              )
            )
  [next_payment_attempt] => 1510868921
  [paid] => 0
  [paid_on] => 0
  [period_end] => 1510868921
  [period_start] => 0
  [promo_code] =>
  [promo_id] => 0
  [promo_uses] => 0
  [service] =>
  [shipping] => 0
  [shipping_total] => 0
  [shopify_created_at] =>
  [status] => Scheduled
  [subscription_id] => 0
  [subtotal] => 46.9
  [tax] => 0
  [tax_total] => 0
  [tracking_number] =>
  [updated_at] => 2017-11-16 21:48:41
  [user_id] => 1
  [webhooks_delivered_at] => 0
)

GET /charge/{id}

Get a single charge using the charge ID.

Parameters

id
integer Charge ID

$chargeID = 4;

$myobj = $payWhirl->getCharge($chargeID);
print_r($myobj);

// example response
stdClass Object
(
  [id] => 4
  [user_id] => 1
  [gateway_reference] => ch_171eGCKsdBiM5uJj5rY
  [amount] => 20.3
  [currency] => USD
  [customer_id] => 2
  [description] => Payment for Invoice #52
  [created_at] => 2015-10-30 14:54:02
  [updated_at] => 2015-10-30 14:54:02
  [gateway_id] => 1
  [refunded] => 0
  [refunded_amount] => 0
  [refund_reference] =>
  [fee] => 0
  [bill_fee] => 0
  [fee_item_id] => 0
  [fee_refund_item_id] => 0
  [deleted_at] =>
  [usd] => 19.99
)

Cards

The card object handles the storage and creation of credit card information, along with a reference to the payment gateway you want to use to process charges.

Because it's important never to store unencrypted card information, we only accept either Stripe or Braintree card tokens.

However, if you're using the PayWhirl Test Gateway when building a service, we do allow test cards to be entered manually.

GET /cards/{customer_id}

Get a list of cards associated with a given customer ID.

Parameters

customer_id
integer Customer ID

$customerID = 36;

$myobj = $payWhirl->getCards($customerID);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
  (
    [brand] => Credit
    [country] => Ecuador
    [created_at] => 2017-11-16 00:01:53
    [customer_id] => 36
    [funding] => Credit
    [gateway_id] => 1
    [gateway_reference] => 5a0cd571212ae
    [id] => 23
    [last4] => 4242
    [updated_at] => 2017-11-16 00:01:53
    [user_id] => 1
  )
)

GET /card/{id}

Get a single card by passing in the card's ID.

Parameters

id
integer Card ID

$cardID = 1;

$myobj = $payWhirl->getCard($cardID);
print_r($myobj);

// example response
stdClass Object
(
  [brand] => Credit
  [country] => Ecuador
  [created_at] => 2017-11-16 00:01:53
  [customer_id] => 36
  [funding] => Credit
  [gateway_id] => 1
  [gateway_reference] => 5a0cd571212ae
  [id] => 1
  [last4] => 4242
  [updated_at] => 2017-11-16 00:01:53
  [user_id] => 1
)

POST /create/card

Create card information to store with a customer. To create a card, you need to supply an object containing customer information along with a Stripe or Braintree token. If you are managing card information in your own software, you must ensure that you are adhering to the Payment Card Industry (PCI) security standards. Their documentation can be found here.

You will choose the token type based on the gateway being used. For a test gateway, you can supply test card information using the extra parameters below.

Stripe integrations, please check documentation on how to obtain a stripeToken and send that to the server.

Braintree integrations, please check documentation on how to obtain the payment method nonce and send that to the server.

Email Settings: this method will trigger the New Card Email event if you've elected to create and use a new card email.

Parameters

id
integer Customer ID (required)
stripeToken
string token if using Stripe
payment_method_nonce
string token if using Braintree
number
string Credit card number, for test gateways only
exp_month
string Expiration Month (mm format), for test gateways only
exp_year
string Expiration Year (yyyy format), for test gateways only
first_name
string First name on card, for test gateways only
last_name
string Last name on card, for test gateways only
address
string Billing street address, for test gateways only
city
string Billing city, for test gateways only
state
string Billing state / region, for test gateways only
zip
string Billing zip / postal code, for test gateways only
country
string Billing country, for test gateways only

// One option if using Stripe as your payment gateway
// Replace "stripeToken" with "payment_method_nonce" for Braintree
$cardData = Array(
  "customer_id" => 36,
  "stripeToken" => <your stripe token here>
);

$myobj = $payWhirl->createCard($cardData);
print_r($myobj);

// example response
stdClass Object
(
  [brand] => Credit
  [country] => Ecuador
  [created_at] => 2017-11-16 00:01:53
  [customer_id] => 36
  [funding] => Credit
  [gateway_id] => 1
  [gateway_reference] => 5a0cd571212ae
  [id] => 1
  [last4] => 4242
  [updated_at] => 2017-11-16 00:01:53
  [user_id] => 1
)

POST /delete/card

Delete a card based on the card's unique card ID.

Parameters

id
integer Card ID

$cardID = 1;

$myobj = $payWhirl->deleteCard($cardID);
print_r($myobj);

// example response
stdClass Object
(
  [status] => success
)

Promo Codes

Promo codes allow you to specify special prices for limited amounts of time or for a certain number of users, without the need to create multiple temporary plans.

The methods in this section allow you to view, create, and delete promo codes.

A promo code object itself stores a reference to the plans it affects, so you might do something like create a 20% off code for the first 100 customers that use any of your plans.

GET /promos

Get a list of all promo codes on file.


$myobj = $payWhirl->getPromos();
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [id] => 25
      [user_id] => 1
      [code] => 1STSUB20
      [amount_off] => 0.00
      [percent_off] => 20
      [duration] => once
      [duration_uses] => 0
      [redeem_by] => 1534402800
      [max_redemptions] => 300
      [times_redeemed] => 0
      [is_valid] => 1
      [created_at] => 2017-11-17 00:35:58
      [updated_at] => 2017-11-17 00:35:58
      [one_use] => 1
      [apply_to] => subtotal
      [plans] =>
      [deleted_at] =>
    )
)

GET /promo/{id}

Get a promo code.

Parameters

id
integer Promo Code ID

$promoID = 25;

$myobj = $payWhirl->getPromo($promoID);
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [id] => 25
      [user_id] => 1
      [code] => 1STSUB20
      [amount_off] => 0.00
      [percent_off] => 20
      [duration] => once
      [duration_uses] => 0
      [redeem_by] => 1534402800
      [max_redemptions] => 300
      [times_redeemed] => 0
      [is_valid] => 1
      [created_at] => 2017-11-17 00:35:58
      [updated_at] => 2017-11-17 00:35:58
      [one_use] => 1
      [apply_to] => subtotal
      [plans] =>
      [deleted_at] =>
    )
)

POST /create/promo

Create a promo code.

Parameters

code
string Promo code. Must use upper-case letter and numbers only.
duration
string How many times should this promo code be applied after a customer uses it? Must be one of: once, repeating, forever.
duration_uses
integer How many billing cycles should this be applied to?
amount_off
decimal A fixed amount to discount (Not needed if using percent off)
percent_off
decimal A percentage of the order total to discount (Not needed if using amount off)
max_redemptions
integer How many customers can redeem this promo code before it is expired? (optional)
redeem_by
integer Expiration date of this promo code (optional). Must be a Unix timestamp, if specified.
apply_to
string Choose when to apply the promo code when calculating invoice totals: subtotal or grandtotal.
one_use
boolean If enabled, a customer can only redeem this code once.

// easy method to generate a timestamp in the future
// if you're looking end a promo on a specific day
// the documentation can be found at the following link:
// http://php.net/manual/en/function.mktime.php
const SECONDS_PER_MINUTE = 60;
const MINUTES_PER_HOUR = 60;
const HOURS_PER_DAY = 24;
const SECONDS_PER_DAY = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY;

$durationOfPlanInDays = 90;
$secondsToAddToTimestamp = ($durationOfPlanInDays * SECONDS_PER_DAY);
$nearlyThreeMonthsFromNow = time() + $secondsToAddToTimestamp;

$promoData = Array(
  'code' => '1STSUB20',
  'duration' => 'once',
  'percent_off' => 20.0,
  'max_redemptions' => 300,
  'redeem_by' => $nearlyThreeMonthsFromNow,
  'apply_to' => 'subtotal',
  'one_use' => 1
);

$myobj = $payWhirl->createPromo($promoData);
print_r($myobj);

stdClass Object
(
  [user_id] => 1
  [code] => 1STSUB20
  [duration] => once
  [duration_uses] => 0
  [amount_off] => 0
  [percent_off] => 20
  [max_redemptions] => 300
  [redeem_by] => 1519779695
  [apply_to] => subtotal
  [one_use] => 1
  [is_valid] => 1
  [updated_at] => 2017-11-30 01:01:34
  [created_at] => 2017-11-30 01:01:34
  [id] => 25
)

POST /delete/promo

Delete a promo code by passing in the promo ID.

Parameters

id
integer Promo ID

$promoID = 25;

$myobj = $payWhirl->deletePromo($promoID);
print_r($myobj);

// example response
stdClass Object
(
    [status] => success
)

Gift Codes

Gift Codes allow you to create objects that store a limited amount of value, which allow your customers to use their gift code balance instead of your regular currency.

GET /gift-codes

Get a list of all gift codes on file.


myobj = paywhirl.get_gift_codes()
print(myobj)

# example response
[
  {
    'id': 12,
    'code': '222-WKO-731',
    'amount': 15,
    'remaining': 15,
    'currency': 'USD',
    'sender_id': 71756,
    'sender': 'Thomas Tester',
    'recipient_email': 'brandon@paywhirl',
    'redeemer_id': 'None',
    'redeemer': 'None',
    'created_at': '2017-10-25 09:49:55',
    'send_on': 'None',
    'sent_at': '2017-10-25 12:02:19'
    'redeemed_at': 'None',
    'gift_message': 'Hey, here is a present for you!',
  },
  {
    'id': 13,
    'code': '947-EFC-851',
    'amount': 20,
    'remaining': 0,
    'currency': 'USD',
    'sender_id': 71756,
    'sender': 'Thomas Tester',
    'recipient_email': 'brandon@paywhirl',
    'redeemer_id': '71797',
    'redeemer': 'Brandon Swift',
    'created_at': '2017-10-25 12:05:45',
    'send_on': '2017-10-25',
    'sent_at': '2017-10-25 12:10:10',
    'redeemed_at': '2017-10-25 14:37:10',
    'gift_message': 'A wonderful gift awaits!',
  }
]

myobj = paywhirl.get_gift_codes()
puts(myobj)

# example response
[
  {
    "id" => 12,
    "code" => "222-WKO-731",
    "amount" => 15,
    "remaining" => 15,
    "currency" => "USD",
    "sender_id" => 71756,
    "sender" => "Thomas Tester",
    "recipient_email" => "brandon@paywhirl",
    "redeemer_id" => "nil",
    "redeemer" => "nil",
    "created_at" => "2017-10-25 09:49:55",
    "send_on" => "nil",
    "sent_at" => "2017-10-25 12:02:19"
    "redeemed_at" => "nil",
    "gift_message" => "Hey, here is a present for you!",
  },
  {
    "id" => 13,
    "code" => "947-EFC-851",
    "amount" => 20,
    "remaining" => 0,
    "currency" => "USD",
    "sender_id" => 71756,
    "sender" => "Thomas Tester",
    "recipient_email" => "brandon@paywhirl",
    "redeemer_id" => "71797",
    "redeemer" => "Brandon Swift",
    "created_at" => "2017-10-25 12:05:45",
    "send_on" => "2017-10-25",
    "sent_at" => "2017-10-25 12:10:10",
    "redeemed_at" => "2017-10-25 14:37:10",
    "gift_message" => "A wonderful gift awaits!",
  }
]

$myobj = $payWhirl->getGiftCodes();
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
        [id] => 12
        [code] => 222-WKO-731
        [amount] => 15
        [remaining] => 15
        [currency] => USD
        [sender_id] => 71756
        [sender] => Thomas Tester
        [recipient_email] => brandon@paywhirl
        [redeemer_id] =>
        [redeemer] =>
        [created_at] => 2017-10-25 09:49:55
        [send_on] =>
        [sent_at] => 2017-10-25 12:02:19
        [redeemed_at] =>
        [gift_message] => Hey here is a present for you!
    )
  [1] => stdClass Object
    (
        [id] => 13
        [code] => 947-EFC-851
        [amount] => 20
        [remaining] => 0
        [currency] => USD
        [sender_id] => 71756
        [sender] => Thomas Tester
        [recipient_email] => brandon@paywhirl
        [redeemer_id] => 71797
        [redeemer] => Brandon Swift
        [created_at] => 2017-10-25 12:05:45
        [send_on] => 2017-10-25
        [sent_at] => 2017-10-25 12:10:10
        [redeemed_at] => 2017-10-25 14:37:10
        [gift_message] => A wonderful gift awaits!
    )
)

Emails

The email section of the API just returns any emails you've created via the email-template page.

This is mostly used for displaying a page in your app that is identical to those you send to customers automatically when they make purchases or initially register.

For information on when your emails will be automatically sent, check your email settings page on your dashboard.

GET /email/{id}

Get a single email template via email ID. You can find your email ids at the end of the URL in the paywhirl email-template page. This functionality is mostly used to acquire copies of emails that are automatically sent on a variety of triggers. The template builder on the main paywhirl site is currently the best way to create and edit your templates.

Parameters

id
integer Email Template ID

$templateID = 1;

$myobj = $payWhirl->getEmailTemplate($templateID);
print_r($myobj);

// example response
stdClass Object
(
  [id] => 1
  [user_id] => 36
  [type] =>
  [name] => Welcome Email
  [from_name] =>
  [subject] => Welcome Aboard!
  [template] => <entire_html_template_here>
  [error_message] =>
  [created_at] => 2015-11-01 01:56:25
  [updated_at] => 2015-11-01 02:02:28
)

POST /send-email

Send a system generated email.

Email Settings: this method will trigger the corresponding email event if you've enabled it.

The parameters you pass in will be different depending on the email you want to send. The following list contains the basic structures that go with each type, while the parameter section below will indicate where to find specific ids or tokens.

  • "Welcome", customer_id
  • "NewSubscription", customer_id, invoice_id
  • "CancelledSubscription", customer_id, invoice_id
  • "NewCard", customer_id, card_id
  • "PaymentReminder", customer_id, invoice_id
  • "PaymentReceipt", customer_id, invoice_id
  • "PaymentRequest", customer_id, invoice_id
  • "ChargeFailed", customer_id, invoice_id
  • "PasswordReminder", customer_id, token
  • "RefundPayment", customer_id, charge_id
  • "ProfileUpdate", customer_id, changes[]
  • "RedeemGiftCode", customer_id, gift_code_id

Parameters

type
string (required) one of the following: Welcome, NewSubscription, CancelledSubscription, NewCard, PaymentReminder, PaymentReceipt, PaymentRequest, ChargeFailed, PasswordReminder, RefundPayment, ProfileUpdate, RedeemGiftCode
customer_id
string You can find a customer_id using get customers
invoice_id
string You can find an invoice_id using get invoices
subscription_id
string A subscription_id can be used instead of invoice_id param for NewSubscription and CancelledSubscription emails
card_id
string You can find a card_id using get cards
token
integer You can get a multiauth token using get multiauth token
charge_id
string You can find a charge_id using get charge
changes
array Array of changes for ProfileUpdate email, should contain the list of changes done to the profile
gift_code_id
string You can find a gift_code_id using get gift codes

// pass in an array containing any of the available params to the left
$request = array(
    "type" => "PasswordReminder",
    "customer_id" => "12345",
    "token" => "6c7a4a38d0555aae1c05c384d141d5cbf8fc1737"
);

// the created customer is returned as an array
$myobj = $payWhirl->sendEmail($request);
print_r($myobj);

// example response
stdClass Object
(
  [status] => success
)

Accounts

The account object is our internal representation of you or your company.

The information contained here also has information related to your account settings, so you can use this to determine the state of each variable option in your dashboard without needing to log in to the app to check each submenu.

In other methods, you might also have noticed a user_id field, which refers to the id of the account holder (you or your business) rather than any of your users.

GET /account

Get information about the account of the user calling this method. (The account information returned is the account that matches the API credentials used to connect to the PayWhirl API.)


$myobj = $payWhirl->getAccount();
print_r($myobj);

// example response
stdClass Object
(
  [account_manager] =>
  [active] => 0
  [address] =>
  [api_access] => 1
  [application_fee_percent] => 3
  [auth_token] =>
  [auth_token_expires] =>
  [badge] => on
  [city] =>
  [company_name] => Selling Business Things Inc.
  [country] => US
  [created_at] => 2017-06-26 20:03:21
  [currency] => USD
  [deleted_at] =>
  [editor] => editor
  [email] => a.business.email@companyName.com
  [email_confirmation] =>
  [email_settings] => stdClass Object
                    (
                      [cancel_subscription] => default
                      [cancel_subscription_cc] =>
                      [email_via] => paywhirl
                      [from_address] =>
                      [from_name] =>
                      [host] =>
                      [new_card] => default
                      [new_card_cc] =>
                      [new_subscription] => default
                      [new_subscription_cc] =>
                      [password] =>
                      [password_reminder] => default
                      [payment_problem] => default
                      [payment_problem_cc] =>
                      [payment_receipt] => default
                      [payment_receipt_cc] =>
                      [payment_reminder] => default
                      [payment_reminder_cc] =>
                      [payment_request] => default
                      [payment_request_cc] =>
                      [port] =>
                      [profile_update] => off
                      [profile_update_cc] =>
                      [test_mode] => off
                      [username] =>
                      [welcome_email] => default
                      [welcome_email_cc] =>
                    )
  [first_name] => Business
  [gateway_id] => 1
  [id] => 1
  [last_login] => 2017-11-20 22:30:30
  [last_name] => Person
  [login_enabled] => 1
  [logo] =>
  [phone] =>
  [plan] => starter
  [promo_codes] => 1
  [pw_id] => 1
  [reg_enabled] => 1
  [retry_days] => 7
  [send_reminders] => 3
  [shopify_access_token] =>
  [shopify_domain] =>
  [shopify_error] =>
  [slug] => sell-business-things-inc
  [state] =>
  [stripe_client_id] =>
  [stripe_pk] =>
  [stripe_sk] =>
  [subscription_id] => 0
  [trial_end] => 1499717001
  [updated_at] => 2017-11-20 22:30:30
  [utm_source] => shopify
  [zip] =>
)

GET /stats

Get invoice and revenue statistics about the account of the user calling this method. (The account information returned is the account that matches the API credentials used to connect to the PayWhirl API.)


$myobj = $payWhirl->getStats();
print_r($myobj);

// example response
stdClass Object
(
  [active] => 1
  [company_name] => Selling Business Things Inc.
  [customers] => 607
  [invoices] => 14568
  [logo] =>
  [plan] => starter
  [revenue_month] => 21245.75
  [revenue_today] => 708.17
  [revenue_total] => 509895.50
  [trial_end] => 2017-07-10 20:03:21
)

Shipping Rules

Shipping rules allow you to create and review shipping prices for items based on things like customer location or item price.

These are often used to handle covering international shipping costs, or to allow for deals like "free shipping on orders over $50".

Shipping rules can be created in the "Settings & Account" section of the PayWhirl dashboard.

GET /shipping

Get all shipping rules.


$myobj = $payWhirl->getShippingRules();
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [id] => 13
      [name] => Local Shipping
      [type] => in_location
      [plan_id] => 0
      [min_price] => 0
      [max_price] => 0
      [country] => CA
      [state] =>
      [zip] =>
      [shipping_price] => 0
      [created_at] => 2017-11-21 00:36:30
      [updated_at] => 2017-11-21 00:36:30
      [user_id] => 1
    )
[1] => stdClass Object
    (
      [id] => 12
      [name] => International Shipping
      [type] => out_location
      [plan_id] => 0
      [min_price] => 0
      [max_price] => 0
      [country] => US
      [state] =>
      [zip] =>
      [shipping_price] => 0
      [created_at] => 2017-11-21 00:45:21
      [updated_at] => 2017-11-21 00:47:34
      [user_id] => 1
    )
)

GET /shipping/{id}

Get a single shipping rule. Shipping rules can be created in the "Settings & Account" section of the PayWhirl dashboard.

Parameters

id
integer Shipping Rule ID

$shippingRule = 12;

$myobj = $payWhirl->getShippingRule($shippingRule);
print_r($myobj);

// example response
stdClass Object
(
  [id] => 12
  [name] => International Shipping
  [type] => in_location
  [plan_id] => 0
  [min_price] => 0
  [max_price] => 0
  [country] => CA
  [state] =>
  [zip] =>
  [shipping_price] => 15
  [created_at] => 2017-11-21 00:45:21
  [updated_at] => 2017-11-21 00:47:34
  [user_id] => 1
)

Tax Rules

Tax rules allow you to set specific percentages to charge based on customer location.

In general, you create a tax rule by choosing a name, a percentage, and a region. After the rules are made, customers in the set regions will automatically have the tax rules applied.

Tax rules can be created in the "Settings & Account" section of the PayWhirl dashboard.

GET /tax

Get all tax rules.


$myobj = $payWhirl->getTaxRules();
print_r($myobj);

// example response
Array
(
  [0] => stdClass Object
    (
      [id] => 1
      [name] => International Tax
      [country] => AD
      [state] =>
      [zip] =>
      [tax_price] => 4
      [tax_shipping] => 0
      [created_at] => 2017-11-21 01:11:58
      [updated_at] => 2017-11-21 01:12:44
      [user_id] => 1
    )
  [1] => stdClass Object
    (
      [id] => 2
      [name] => UK Tax
      [country] => GB
      [state] => Aberdeenshire
      [zip] =>
      [tax_price] => 4
      [tax_shipping] => 0
      [created_at] => 2017-11-21 01:14:43
      [updated_at] => 2017-11-21 01:14:43
      [user_id] => 1
    )
)

GET /tax/{id}

Get a single tax rule. Tax rules can be created in the "Settings & Account" section of the PayWhirl dashboard.

Parameters

id
integer Tax Rule ID

$taxRuleID = 1;
$myobj = $payWhirl->getTaxRule($taxRuleID);
print_r($myobj);

// example response
stdClass Object
(
  [id] => 1
  [name] => International Tax A
  [country] => AD
  [state] =>
  [zip] =>
  [tax_price] => 7
  [tax_shipping] => 0
  [created_at] => 2017-11-21 01:11:58
  [updated_at] => 2017-11-21 01:12:44
  [user_id] => 1
)

MultiAuth Tokens

MultiAuth tokens are usually used as a method for allowing your customers to skip dealing with a PayWhirl login after they've decided to make a purchase. If you've chosen to embed PayWhirl widgets into your page or app, including a MultiAuth token in your widget script allows your customers to go straight from selecting an option directly to payment.

For other purposes, you can also use the MultiAuth tokens to redirect your customers directly to their carts, show them their payment schedules, and log them in via a PayWhirl button. Each of these options will be explained in slightly more detail below, after the rest make sense conceptually.

A MultiAuth token will expire at the end of the given duration, it will not be 'consumed' when used.

For the timestamp, you will want to use a UTC timestamp that is current_time + seconds_in_24_hours rather than seconds_in_24_hours.

POST /multiauth

Get a MultiAuth token to use to automatically login a customer to a widget.

The most common method for embedding a widget into an HTML page is to copy and paste your the script from the bottom of the page after selecting edit from this table. You can also find the table at by following this path from your dashboard.

Widgets & Forms > Manage Widgets > Edit

At the bottom of the edit page, there will be two embed codes that have the following form:

<script type="text/javascript"
        id='{your account id}'
        src="https://app.paywhirl.com/pw.js">
</script>

<script> paywhirl('widget',
                  {domain:'{your paywhirl domain}',
                   autoscroll: 1,
                   uuid:'{the uuid of your widget}'},
                  '{your account id}');
</script>

In general, copy-pasting the script from your widget page will work fine. But to add a login token that allows customers to skip that step because they're already logged in to your service, you need to use the get multiauth method to retrieve a token for whichever customer you want to log in, then you can use your favorite method to generate the following snippet:

<script type="text/javascript"
        id='{your account id}'
        src="https://app.paywhirl.com/pw.js">
</script>

<script> paywhirl('widget',
                  {domain:'{your paywhirl domain}',
                   multiauth: '{your multiauth_token}',
                   autoscroll: 1,
                   uuid:'{the uuid of your widget}'},
                  '{your account id}');
</script>

When you use the get multiauth method, a token is returned, along with the customer's ID and email address so you can verify the correct customer was selected before you generate a login code for them.

Another set of options is to replace the widget string in the examples with cart to skip directly to checkout; button to generate a small "Buy now with PayWhirl" button that will display your widgets in a new frame; or create to display the selected customer's payment calendar.

Parameters

id
integer ID of customer. Required if email not provided.
email
string Email of customer. Required if ID not provided.
expires
integer UNIX timestamp of when token should expire. Defaults to 60 seconds from now. Max token lifetime is 24 hours.

$customerID = Array("id" => 36);
$myobj = $payWhirl->getMultiAuthToken($customerID);
print_r($myobj);

// example response
stdClass Object
(
  [multiauth_token] => RDbGFzcyI6Mjp7czoyOiJpZCI7cmV4cGlyZXMiO3M6MTA6IjE0NTk3MTYxNTIiO30%3D
  [email] => slevem@dandleton.com
  [id] => 36
)

Webhooks

Webhooks will allow you to receive push notifications for your account. Certain third-party plugins will create them for you or ask your to register your webhooks URL. You can register a URL under the Developer tab on your PayWhirl account page. The object to the right shows the format the data will be sent in.

For any fields with variable output types, there is a small explanation beneath the example webhook object on the right.

Events

type:
customer.created
type:
customer.updated
type:
plan.created
type:
plan.updated
type:
card.created
type:
card.deleted
type:
subscription.created
type:
subscription.deleted
type:
invoice.created
type:
invoice.processed
type:
invoice.paid
type:
charge.succeeded
type:
charge.failed
type:
charge.refunded
type:
giftcode.sent

Customer Created
The JSON object will have the following form:
{ "type": String, "customer": Object, "answers": Array.of(Object) }


Example:
{
  "type": "customer.created",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "answers": [    
    {
      "label": "Is the sky blue?",
      "answer": "Yes"
    },
    {
      "label": "Are all skies on all planets blue?",
      "answer": "Maybe?"
    }
  ]
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}

Customer Updated
The JSON object will have the following form:
{ "type": String, "customer": Object, "answers": array.of(Object) }


Example:
{
  "type": "customer.updated",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "answers": [
    {
      "label": "Is the sky blue?",
      "answer": "Yes"
    },
    {
      "label": "Are all skies on all planets blue?",
      "answer": "Maybe?"
    }
  ]
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}

Plan Created
The JSON object will have the following form:
{ "type": String, "plan": Object }


Example:
{
  "type": "plan.created",
  "plan": {
    "questions": "[{\"name\":\"checkbox-1513638794611\",\"repeated\":1}]",
    "name": "webhook test plan",
    "billing_amount": "0.01",
    "billing_interval": "1",
    "billing_dates": "[]",
    "billing_frequency": "month",
    "require_shipping": "1",
    "require_tax": "1",
    "trial_days": "5",
    "sku": "455KHU67",
    "setup_fee": "5.05",
    "autorenew_setup_fee": "0",
    "billing_cycle_anchor": "0",
    "billing_cycle_anchor_time": "",
    "currency": "USD",
    "enabled": "1",
    "installments": "0",
    "autorenew_plan": "0",
    "tags": "testplan, masterplan, goodplan?",
    "user_id": 1,
    "file": "",
    "updated_at": "2018-02-07 00:15:13",
    "created_at": "2018-02-07 00:15:13",
    "id": 41052
  }
}

If the "billing_frequency" field is set to "dates" you will see the following
form: 
{
  "billing_frequency": "dates",
  "billing_dates": "[\"2018-03-21\",\"2018-03-31\",\"2018-03-07\"]",
}

Plan Updated
The JSON object will have the following form:
{ "type": String, "plan": Object }


Example:
{
  "type": "plan.updated",
  "plan": {
    "id": 23,
    "user_id": 1,
    "name": "webhook test plan",
    "setup_fee": "5.05",
    "installments": "0",
    "require_shipping": "1",
    "active": 0,
    "image": "",
    "starting_day": 0,
    "description": "A fantastic plan!",
    "metadata": "{\"4277\":{\"place_orders\":\"all\"},\"4280\":{\"place_orders\":\"all\",\"customer_group\":\"none\"}}",
    "created_at": "2018-02-07 00:15:13",
    "updated_at": "2018-02-07 00:20:42",
    "billing_amount": "0.11",
    "billing_interval": "1",
    "billing_frequency": "month",
    "billing_dates": "[]",
    "trial_days": "0",
    "sku": "455KHU67",
    "currency": "USD",
    "require_tax": "1",
    "billing_cycle_anchor": "0",
    "billing_cycle_anchor_time": "",
    "deleted_at": null,
    "file": "",
    "autorenew_plan": "0",
    "tags": "testplan, masterplan, good... plan?",
    "enabled": "1",
    "questions": "[{\"name\":\"checkbox-1513638794611\",\"repeated\":1}]",
    "autorenew_setup_fee": "0"
  }
}

If the "billing_frequency" field is set to "dates" you will see the following
form: 
{
  "billing_frequency": "dates",
  "billing_dates": "[\"2018-03-21\",\"2018-03-31\",\"2018-03-07\"]",
}

Card Created
The JSON object will have the following form:
{ "type": String, "customer": Object, "card": Object }


Example:
{
  "type": "card.created",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "card": {
    "gateway_reference": "5a7a47e944e3b",
    "brand": "Credit",
    "funding": "Credit",
    "country": "US",
    "customer_id": 29489320,
    "last4": "2222",
    "user_id": 1,
    "gateway_id": 18,
    "updated_at": "2018-02-07 00:27:21",
    "created_at": "2018-02-07 00:27:21",
    "id": 15
  }
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1
}

Card Deleted
The JSON object will have the following form:
{ "type": String, "customer": Object, "card": Object }


Example:
{
  "type": "card.deleted",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "2018-02-05 13:42:23",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "card": {
    "gateway_reference": "5a7a47e944e3b",
    "brand": "Credit",
    "funding": "Credit",
    "country": "US",
    "customer_id": 29489320,
    "last4": "2222",
    "user_id": 1,
    "gateway_id": 18,
    "updated_at": "2018-02-07 00:27:21",
    "created_at": "2018-02-07 00:27:21",
    "id": 15
  }
}


The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1
}

Subscription Created
The JSON object will have the following form:
{ "type": String, "customer": Object, "subscription": Object, "invoice": Object }

The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

Example:
{
  "type": "subscription.created",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "subscription": {
    "user_id": 1,
    "customer_id": 36,
    "plan_id": 1,
    "widget_id": 0,
    "quantity": "1",
    "cancel_at_period_end": 0,
    "current_period_start": 1517963629,
    "current_period_end": 1517963629,
    "updated_at": "2018-02-07 00:33:49",
    "created_at": "2018-02-07 00:33:49",
    "id": 1337
  },
  "invoice": {
    "id": 461175,
    "user_id": 1,
    "customer_id": 27,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": 0,
    "additional_charge_id": null,
    "card_id": 273194,
    "shipping": 1,
    "tax": 1,
    "attempted": 0,
    "attempt_count": 0,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 1517963629,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Subscribed",
    "paid": 0,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 600,
    "tax_total": 0,
    "amount_due": 600.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:49",
    "paid_on": 0,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "123PROMO",
    "promo_uses": 0,
    "integration_errors": "",
    "address_id": 0,
    "carrier": "UBS",
    "service": "SV",
    "tracking_number": "1Z 999 AA1 01 2345 6784",
    "is_order": 1,
    "shopify_created_at": null,
    "is_queued": 0
  }
}


The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1
} 

Subscription Deleted
The JSON object will have the following form:
{ "type": String, "customer": Object, "subscription": Object, "invoice": Object }


Example:
{
  "type": "subscription.deleted",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "subscription": {
    "id": 150700,
    "user_id": 1,
    "customer_id": 27,
    "plan_id": 41052,
    "widget_id": 0,
    "quantity": 1,
    "cancel_at_period_end": 0,
    "current_period_start": 1517963629,
    "current_period_end": 1520382829,
    "trial_start": 0,
    "trial_end": 0,
    "installment_plan": 0,
    "installments_left": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:49",
    "deleted_at": null
  },
  "invoice": {
    "id": 461175,
    "user_id": 1,
    "customer_id": 27,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": 361457,
    "additional_charge_id": null,
    "card_id": 273194,
    "shipping": 1,
    "tax": 1,
    "attempted": 1,
    "attempt_count": 1,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 0,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Paid",
    "paid": 1,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 600,
    "tax_total": 0,
    "amount_due": 600.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:53",
    "paid_on": 1517963629,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "",
    "promo_uses": 0,
    "integration_errors": "null",
    "address_id": 0,
    "carrier": "UBS",
    "service": "SV",
    "tracking_number": "1Z 999 AA1 01 2345 6784",
    "is_order": 1,
    "shopify_created_at": "2018-02-07 00:33:52",
    "is_queued": 0
  }
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1
}

Invoice Created
The JSON object will have the following form:
{ "type": String, "customer": Object, "invoice": Object, "items": Array.of(Object), "answers": Array.of(Object) }


Example:
{
  "type": "invoice.created",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "invoice": {
    "customer_id": 227913,
    "currency": "USD",
    "shipping": 1,
    "tax": 1,
    "status": "Subscribed",
    "period_start": 1517963629,
    "period_end": 1517963629,
    "next_payment_attempt": 1517963629,
    "card_id": 273194,
    "updated_at": "2018-02-07 00:33:49",
    "created_at": "2018-02-07 00:33:49",
    "id": 461175,
    "user_id": 6529,
    "subscription_id": 150700,
    "subtotal": 0.11,
    "discount": 0,
    "tax_total": 0,
    "shipping_total": 600,
    "amount_due": 600.11,
    "items": [
      {
        "id": 518501,
        "type": "plan",
        "user_id": 1,
        "customer_id": 27,
        "invoice_id": 461175,
        "quantity": 1,
        "description": "Subscription to webhook test plan",
        "amount": 0.11,
        "currency": "USD",
        "created_at": "2018-02-07 00:33:49",
        "updated_at": "2018-02-07 00:33:49",
        "deleted_at": null,
        "sku": "455KHU67"
      }
    ]
  },
  "answers": [
    {
      "label": "Is the sky blue?",
      "answer": "Yes"
    },
    {
      "label": "Are all skies on all planets blue?",
      "answer": "Maybe?"
    }
  ]
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1
}

Invoice Processed
The JSON object will have the following form:
{ "type": String, "customer": Object, "invoice": Object, "items": Array.of(Object) }


Example:
{
  "type": "invoice.processed",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "invoice": {
    "id": 461175,
    "user_id": 1,
    "customer_id": 27,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": 0,
    "additional_charge_id": null,
    "card_id": 273194,
    "shipping": 1,
    "tax": 1,
    "attempted": 1,
    "attempt_count": 1,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 1517963629,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Attempting Payment",
    "paid": 0,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 600,
    "tax_total": 0,
    "amount_due": 600.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:49",
    "paid_on": 1517963629,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "123PROMO",
    "promo_uses": 5,
    "integration_errors": "",
    "address_id": 0,
    "carrier": "UBS",
    "service": "SV",
    "tracking_number": "1Z 999 AA1 01 2345 6784",
    "is_order": 1,
    "shopify_created_at": null,
    "is_queued": 0,
    "items": [
      {
        "id": 518501,
        "type": "plan",
        "user_id": 6529,
        "customer_id": 227913,
        "invoice_id": 461175,
        "quantity": 1,
        "description": "Subscription to webhook test plan",
        "amount": 0.11,
        "currency": "USD",
        "created_at": "2018-02-07 00:33:49",
        "updated_at": "2018-02-07 00:33:49",
        "deleted_at": null,
        "sku": "455KHU67"
      }
    ]
  }
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}

Invoice Paid
The JSON object will have the following form:
{ "type": String, "customer": Object, "invoice": Object, "items": Array.of(Object) }


Example:
{
  "type": "invoice.paid",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "invoice": {
    "id": 461175,
    "user_id": 6529,
    "customer_id": 227913,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": 361457,
    "additional_charge_id": null,
    "card_id": 273194,
    "shipping": 1,
    "tax": 1,
    "attempted": 1,
    "attempt_count": 1,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 0,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Paid",
    "paid": 1,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 600,
    "tax_total": 0,
    "amount_due": 600.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:49",
    "paid_on": 1517963629,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "",
    "promo_uses": 0,
    "integration_errors": "",
    "address_id": 0,
    "carrier": "UBS",
    "service": "SV",
    "tracking_number": "1Z 999 AA1 01 2345 6784",
    "is_order": 1,
    "shopify_created_at": null,
    "is_queued": 0,
    "items": [
      {
        "id": 518501,
        "type": "plan",
        "user_id": 6529,
        "customer_id": 227913,
        "invoice_id": 461175,
        "quantity": 1,
        "description": "Subscription to webhook test plan",
        "amount": 0.11,
        "currency": "USD",
        "created_at": "2018-02-07 00:33:49",
        "updated_at": "2018-02-07 00:33:49",
        "deleted_at": null,
        "sku": "455KHU67"
      }
    ]
  }
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}

Charge Succeeded
The JSON object will have the following form:
{ "type": String, "customer": Object, "charge": Object, "invoice": Object }


Example:
{
  "type": "charge.succeeded",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "charge": {
    "gateway_reference": "5a7a496d74572",
    "amount": 600.11,
    "currency": "USD",
    "customer_id": 227913,
    "description": "Payment for Invoice #461175",
    "user_id": 6529,
    "gateway_id": 11203,
    "usd": 600.11,
    "fee": 0,
    "bill_fee": 0,
    "updated_at": "2018-02-07 00:33:49",
    "created_at": "2018-02-07 00:33:49",
    "id": 361457
  },
  "invoice": {
    "id": 461175,
    "user_id": 1,
    "customer_id": 34,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": null,
    "additional_charge_id": null,
    "card_id": 273194,
    "shipping": 1,
    "tax": 1,
    "attempted": 1,
    "attempt_count": 1,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 0,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Paid",
    "paid": 1,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 600,
    "tax_total": 0,
    "amount_due": 600.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:53",
    "paid_on": 1517963629,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "123PROMO",
    "promo_uses": 0,
    "integration_errors": "null",
    "address_id": 0,
    "carrier": "UBS",
    "service": "SV",
    "tracking_number": "1Z 999 AA1 01 2345 6784",
    "is_order": 1,
    "shopify_created_at": "2018-02-07 00:33:52",
    "is_queued": 0,
    "items": [
      {
        "id": 518501,
        "type": "plan",
        "user_id": 1,
        "customer_id": 34,
        "invoice_id": 461175,
        "quantity": 1,
        "description": "Subscription to webhook test plan",
        "amount": 0.11,
        "currency": "USD",
        "created_at": "2018-02-07 00:33:49",
        "updated_at": "2018-02-07 00:33:49",
        "deleted_at": null,
        "sku": "455KHU67"
      }
    ]
  }
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}

Charge Failed
The JSON object will have the following form:
{ "type": String, "customer": Object, "invoice": Object }


Example:
{
  "type": "charge.failed",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "invoice": {
    "id": 461175,
    "user_id": 1,
    "customer_id": 227913,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": 0,
    "additional_charge_id": null,
    "card_id": 0,
    "shipping": 0,
    "tax": 0,
    "attempted": 1,
    "attempt_count": 0,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 1517966629,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Cannot charge a customer that has no active card",
    "paid": 0,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 0,
    "tax_total": 0,
    "amount_due": 0.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:53",
    "paid_on": 0,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "",
    "promo_uses": 0,
    "integration_errors": "",
    "address_id": 0,
    "carrier": "",
    "service": "",
    "tracking_number": "",
    "is_order": 1,
    "shopify_created_at": 0,
    "is_queued": 0,
    "items": [
      {
        "id": 518501,
        "type": "plan",
        "user_id": 1,
        "customer_id": 227913,
        "invoice_id": 461175,
        "quantity": 1,
        "description": "Subscription to webhook test plan",
        "amount": 0.11,
        "currency": "USD",
        "created_at": "2018-02-07 00:33:49",
        "updated_at": "2018-02-07 00:33:49",
        "deleted_at": null,
        "sku": "455KHU67"
      }
    ]
  },
  "subscription": {
    "user_id": 1,
    "customer_id": 227913,
    "plan_id": 1,
    "widget_id": 0,
    "quantity": "1",
    "cancel_at_period_end": 0,
    "current_period_start": 1517963629,
    "current_period_end": 1517963629,
    "updated_at": "2018-02-07 00:33:49",
    "created_at": "2018-02-07 00:33:49",
    "id": 150700
  },
  "plan": {
    "questions": "[{\"name\":\"checkbox-1513638794611\",\"repeated\":1}]",
    "name": "webhook test plan",
    "billing_amount": "0.01",
    "billing_interval": "1",
    "billing_dates": "[]",
    "billing_frequency": "month",
    "require_shipping": "1",
    "require_tax": "1",
    "trial_days": "5",
    "sku": "455KHU67",
    "setup_fee": "5.05",
    "autorenew_setup_fee": "0",
    "billing_cycle_anchor": "0",
    "billing_cycle_anchor_time": "",
    "currency": "USD",
    "enabled": "1",
    "installments": "0",
    "autorenew_plan": "0",
    "tags": "testplan, masterplan, goodplan?",
    "user_id": 1,
    "file": "",
    "updated_at": "2018-02-07 00:15:13",
    "created_at": "2018-02-07 00:15:13",
    "id": 1
  }
}


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}

Charge Refunded
The JSON object will have the following form:
{ "type": String, "customer": Object, "charge": Object, "invoice": Object, "items": Array.of(Object) }


Example:
{
  "type": "charge.refunded",
  "customer": {
    "id": 34,
    "user_id": 1,
    "first_name": "Awesome",
    "last_name": "Person",
    "email": "awesome+person@paywhirl.com",
    "phone": "4564564566",
    "address": "123 Easy Street",
    "city": "Los Angeles",
    "state": "California",
    "zip": 93003,
    "country": "US",
    "created_at": "2015-11-17 19:52:34",
    "updated_at": "2015-11-21 04:29:45",
    "gateway_reference": "783789y6r890",
    "default_card": 34,
    "gateway_type": "PayPal",
    "gateway_id": 18,
    "currency": "USD",
    "deleted_at": "",
    "utm_source": "Google",
    "utm_medium": "cpc",
    "utm_term": "online payments",
    "utm_content": "logolink",
    "utm_campaign": "spring_sale",
    "utm_group": "users",
    "metadata": ""
  },
  "charge": {
    "id": 361457,
    "user_id": 1,
    "gateway_reference": "5a7a496d74572",
    "amount": 600.11,
    "currency": "USD",
    "customer_id": 227913,
    "description": "Payment for Invoice #461175",
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:39:58",
    "gateway_id": 11203,
    "refunded": 1,
    "refund_reference": "5a7a4ade245e6",
    "fee": 0,
    "bill_fee": 0,
    "fee_item_id": 0,
    "fee_refund_item_id": 0,
    "deleted_at": null,
    "usd": "600.11"
  },
  "invoice": {
    "id": 461175,
    "user_id": 1,
    "customer_id": 227913,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": 361457,
    "additional_charge_id": null,
    "card_id": 273194,
    "shipping": 1,
    "tax": 1,
    "attempted": 1,
    "attempt_count": 1,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 0,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Paid",
    "paid": 1,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 600,
    "tax_total": 0,
    "amount_due": 600.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:53",
    "paid_on": 1517963629,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "123PROMO",
    "promo_uses": 0,
    "integration_errors": "null",
    "address_id": 0,
    "carrier": "UBS",
    "service": "SV",
    "tracking_number": "1Z 999 AA1 01 2345 6784",
    "is_order": 1,
    "shopify_created_at": "2018-02-07 00:33:52",
    "is_queued": 0,
    "items": [
      {
        "id": 518501,
        "type": "plan",
        "user_id": 1,
        "customer_id": 227913,
        "invoice_id": 461175,
        "quantity": 1,
        "description": "Subscription to webhook test plan",
        "amount": 0.11,
        "currency": "USD",
        "created_at": "2018-02-07 00:33:49",
        "updated_at": "2018-02-07 00:33:49",
        "deleted_at": null,
        "sku": "455KHU67"
      }
    ]
  }


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}

Gift Code Sent
The JSON object will have the following form:
{ "type": String, "customer": Object, "giftcode": Object, "invoice": Object, "items": Array.of(Object) }


Example:
{
  "type": "giftcode.sent",
  "customer": {
    id: 34,
    user_id: 1,
    first_name: 'Awesome',
    last_name: 'Person',
    email: 'awesome+person@paywhirl.com',
    phone: '4564564566',
    address: '123 Easy Street',
    city: 'Los Angeles',
    state: 'California',
    zip: 93003,
    country: 'US',
    created_at: '2015-11-17 19:52:34',
    updated_at: '2015-11-21 04:29:45',
    gateway_reference: '783789y6r890',
    default_card: 34,
    gateway_type: 'PayPal',
    gateway_id: 18,
    currency: 'USD',
    deleted_at: '',
    utm_source: 'Google',
    utm_medium: 'cpc',
    utm_term: 'online payments',
    utm_content: 'logolink',
    utm_campaign: 'spring_sale',
    utm_group: 'users',
    metadata: ''
  },
  "giftcode": {
    "id": 2,
    "user_id": 1,
    "customer_id": 34,
    "invoice_item_id": 7880,
    "redeemed_by": null,
    "redeemed_at": null,
    "code": "947-EFC-851",
    "amount": 20.00,
    "remaining": 20.00,
    "currency": "USD",
    "gift_message": "A present for you!",
    "recipient_email": "friend@paywhirl.com",
    "email_template": null,
    "redeem_url": null,
    "send_on": null,
    "sent_at": "2017-10-27 08:22:11",
    "created_at": "2017-10-25 12:05:45",
    "updated_at": "2017-10-27 08:22:11"
  },
  "invoice": {
    "id": 461175,
    "user_id": 1,
    "customer_id": 227913,
    "discount_id": 0,
    "subscription_id": 150700,
    "charge_id": 361457,
    "additional_charge_id": null,
    "card_id": 273194,
    "shipping": 1,
    "tax": 1,
    "attempted": 1,
    "attempt_count": 1,
    "currency": "USD",
    "due_date": 0,
    "next_payment_attempt": 0,
    "period_end": 1517963629,
    "period_start": 1517963629,
    "status": "Paid",
    "paid": 1,
    "subtotal": 0.11,
    "discount": "0.00",
    "shipping_total": 600,
    "tax_total": 0,
    "amount_due": 600.11,
    "webhooks_delivered_at": 0,
    "created_at": "2018-02-07 00:33:49",
    "updated_at": "2018-02-07 00:33:53",
    "paid_on": 1517963629,
    "deleted_at": null,
    "promo_id": 0,
    "promo_code": "123PROMO",
    "promo_uses": 0,
    "integration_errors": "null",
    "address_id": 0,
    "carrier": "UBS",
    "service": "SV",
    "tracking_number": "1Z 999 AA1 01 2345 6784",
    "is_order": 1,
    "shopify_created_at": "2018-02-07 00:33:52",
    "is_queued": 0,
    "items": [
      {
        "id": 518501,
        "type": "plan",
        "user_id": 1,
        "customer_id": 227913,
        "invoice_id": 461175,
        "quantity": 1,
        "description": "Subscription to webhook test plan",
        "amount": 0.11,
        "currency": "USD",
        "created_at": "2018-02-07 00:33:49",
        "updated_at": "2018-02-07 00:33:49",
        "deleted_at": null,
        "sku": "455KHU67"
      }
    ]
  }


The "deleted_at" field will have the same timestamp format as "created_at"
and "updated_at".

The "metadata" field may contain a formatted JSON object:
{
  \"extra_data\":\"something\",
  \"more_extra_data\":1 
}