Introduction

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

               
                

Authentication

To connect to the API, you need to pass your API key and secret in the headers of each request. If you're using one of the PayWhirl libraries, you can pass the credentials directly into the class constructor.

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
Last Updated: Jul 27, 2017

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
Last Updated: Jun 06, 2017

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 NodeJS SDK
Last Updated: Jul 06, 2017

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

//set api credentials
$api_key = "XXXXXXXXXX";
$api_secret = "XXXXXXXXXX";

//init $payWhirl
$payWhirl = new \PayWhirl\PayWhirl($api_key,$api_secret);
//include PayWhirl Python SDK
import PayWhirl

//set api credentials
api_key = "XXXXXXXXXX"
api_secret = "XXXXXXXXXX"

//init payWhirl
payWhirl = PayWhirl.PayWhirl(api_key,api_secret)

//paywhirl = require('paywhirl')();

//set api credentials in paywhirl/package.json under _options/headers
api_key = "XXXXXXXXXX"
api_secret = "XXXXXXXXXX"

  			

GET /customers

Get a list of customers

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 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
//get a list of customers
$payWhirl->getCustomers($data);//get a list of customers
payWhirl.getCustomers(data)//get a list of customers
paywhirl.Customers.getCustomers(data, callback);


//Example Response
[
  {
    "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": null,
    "utm_source": "",
    "utm_medium": "",
    "utm_term": "online payments",
    "utm_content": "",
    "utm_campaign": "",
    "utm_group": ""
  },
  {
    "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": null,
    "utm_source": "",
    "utm_medium": "",
    "utm_term": "",
    "utm_content": "",
    "utm_campaign": "",
    "utm_group": ""
  }
]

  			

GET /customer/{id}

Get a single customer

Parameters

id
integer Customer ID

NOTE: You can optionally substitue the id in the URL with the customer's email address.
//get a customer
$payWhirl->getCustomer($id);//get a customer
payWhirl.getCustomer(id)//get a customer
paywhirl.Customers.getCustomer(id, callback);


//Example Response
{
  "id": "1",
  "user_id": "1",
  "first_name": "Fred",
  "last_name": "Flintstone",
  "email": "fred@paywhirl.com",
  "phone": "8052843895",
  "address": "4447 Cain Cir",
  "city": "Tucker",
  "state": "Georgia",
  "zip": "30084",
  "country": "US",
  "created_at": "2015-10-23 18:48:26",
  "updated_at": "2015-11-02 02:36:45",
  "gateway_reference": "cus_7GazY7Xk3CFCrv",
  "default_card": "55",
  "gateway_type": "Stripe",
  "gateway_id": "1",
  "currency": "USD",
  "deleted_at": null
}

  			

POST /create/customer

Create a new customer

Parameters

first_name
string First name (required)
last_name
string Last name (required)
email
string Email address (required)
password
string Password (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.
currency
string Currency code of this user's currency (ex. USD, GBP, AUD, CAD, EUR, etc) (required)
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
//create a customer
$payWhirl->createCustomer($data);//create a customer
payWhirl.createCustomer(data)//create a customer
paywhirl.Customers.create(data, callback);


//Example Response
{
    "id": "38",
    "user_id": "1",
    "first_name": "Test",
    "last_name": "Guy",
    "email": "testguy@paywhirl.com",
    "phone": "9877899879",
    "address": "123 Easy Street",
    "city": "Ventura",
    "state": "California",
    "zip": "93003",
    "country": "US",
    "created_at": "2015-11-20 00:10:36",
    "updated_at": "2015-11-23 15:22:44",
    "gateway_reference": "cus_7No5XKCkuGKwEd",
    "default_card": "38",
    "gateway_type": "StripeConnect",
    "gateway_id": "1",
    "currency": "USD",
    "deleted_at": null,
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_term": "Billing System",
    "utm_content": "Best billing system",
    "utm_campaign": "California_campaign",
    "utm_group": "State Ads"
}		

  			

POST /update/customer

Update an existing customer

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
//update a customer
$payWhirl->updateCustomer($data);//update a customer
payWhirl.updateCustomer(data)//update a customer
paywhirl.Customers.update(id, data, callback);


//Example Response
{
    "id": "38",
    "user_id": "1",
    "first_name": "Test",
    "last_name": "Guy",
    "email": "testguy@paywhirl.com",
    "phone": "9877899879",
    "address": "123 Easy Street",
    "city": "Ventura",
    "state": "California",
    "zip": "93003",
    "country": "US",
    "created_at": "2015-11-20 00:10:36",
    "updated_at": "2015-11-23 15:22:44",
    "gateway_reference": "cus_7No5XKCkuGKwEd",
    "default_card": "38",
    "gateway_type": "StripeConnect",
    "gateway_id": "1",
    "currency": "USD",
    "deleted_at": null,
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_term": "Billing System",
    "utm_content": "Best billing system",
    "utm_campaign": "California_campaign",
    "utm_group": "State Ads"
}		

  			

GET /questions

Get a list of profile questions

Parameters

limit
integer Number of records to return (optional)
//get a list of questions
$payWhirl->getQuestions();//get a list of questions
payWhirl.getQuestions()//get a list of questions
paywhirl.Customers.getQuestions(data, callback);


//Example Response
[
 {
   "type": "select",
   "required": true,
   "label": "Gender",
   "name": "select-1477033168104",
   "values": [
     {
       "label": "Male",
       "value": "Male"
     },
     {
       "label": "Female",
       "value": "Female"
     }
   ]
 },
 {
   "type": "checkbox-group",
   "required": false,
   "label": "How did you hear about us?",
   "description": "",
   "name": "checkbox-group-1477033209341",
   "values": [
     {
       "label": "Radio",
       "value": "Radio"
     },
     {
       "label": "Google \\/ Search Engine",
       "value": "Google \\/ Search Engine"
     },
     {
       "label": "Other",
       "value": "Other"
     }
   ]
 }
]

  			

POST /update/answer

Add or update a customer's answer to a profile question

Parameters

question_name
string Question Name (required)
customer_id
integer PayWhirl customer id (required)
address_id
integer Customer address id (required)
answer
string Value of answer (required)
//update customer's answer
$payWhirl->updateAnswer($data);//update customer's answer
payWhirl.updateAnswer(data)//update customer's answer
paywhirl.Customers.updateAnswer(data, callback);


//Example Response
[
  {
    "name": "select-1477033168104",
    "label": "Gender",
    "answer": "Male"
  },
  {
    "name": "checkbox-group-1477033209341",
    "label": "How did you hear about us?",
    "answer": "Radio"
  }
]

  			

GET /answers

Get a customer's answers to profile questions

Parameters

customer_id
integer Customer ID (required)
//get a customer's answers
$payWhirl->getAnswers($data);//get a customer's answers
payWhirl.getAnswers(data)//get a customer's answers
paywhirl.Customers.getAnswers(cust_id, callback);


//Example Response
[
  {
    "name": "select-1477033168104",
    "label": "Gender",
    "answer": "Male"
  },
  {
    "name": "checkbox-group-1477033209341",
    "label": "How did you hear about us?",
    "answer": "Radio"
  }
]

  			

GET /plans

Get a list of plans

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
//get a list of plans
$payWhirl->getPlans($data);//get a list of plans
payWhirl.getPlans(data)//get a list of plans
paywhirl.Plans.getPlans(data, callback);


//Example Response
[
  {
    "id": "13",
    "user_id": "1",
    "name": "6-month Plan",
    "setup_fee": "0.00",
    "installments": "0",
    "require_shipping": "1",
    "active": "0",
    "image": "",
    "starting_day": "0",
    "description": "",
    "metadata": "{\"3\":{\"place_orders\":\"all\"}}",
    "created_at": "2015-12-01 22:27:43",
    "updated_at": "2015-12-02 21:30:55",
    "billing_amount": "150.00",
    "billing_interval": "6",
    "billing_frequency": "month",
    "billing_dates": "",
    "trial_days": "0",
    "sku": "456456",
    "currency": "USD",
    "require_tax": "1",
    "billing_cycle_anchor": "0",
    "deleted_at": null,
    "file": "",
    "autorenew_plan": "0",
    "tags": "",
    "enabled": "0",
    "questions": ""
  },
  {
    "id": "6",
    "user_id": "1",
    "name": "Super Order Plan",
    "setup_fee": "0.00",
    "installments": "3",
    "require_shipping": "1",
    "active": "0",
    "image": "",
    "starting_day": "0",
    "description": "",
    "metadata": "{\"3\":{\"place_orders\":\"last\"}}",
    "created_at": "2015-11-19 17:20:42",
    "updated_at": "2015-12-02 01:26:09",
    "billing_amount": "10.00",
    "billing_interval": "1",
    "billing_frequency": "day",
    "billing_dates": "",
    "trial_days": "0",
    "sku": "e456456",
    "currency": "USD",
    "require_tax": "0",
    "billing_cycle_anchor": "0",
    "deleted_at": null,
    "file": "",
    "autorenew_plan": "0",
    "tags": "",
    "enabled": "0",
    "questions": ""
  },
  {
    "id": "52",
    "user_id": "1",
    "name": "Specific Dates Plan",
    "setup_fee": "0.00",
    "installments": "0",
    "require_shipping": "1",
    "active": "0",
    "image": "",
    "starting_day": "0",
    "description": "",
    "metadata": "{\"3\":{\"place_orders\":\"last\"}}",
    "created_at": "2017-01-30 17:20:42",
    "updated_at": "2017-01-31 01:26:09",
    "billing_amount": "10.00",
    "billing_interval": "1",
    "billing_frequency": "dates",
    "billing_dates": "[\"2017-04-01\", \"2017-08-01\"]",
    "trial_days": "0",
    "sku": "1234",
    "currency": "USD",
    "require_tax": "0",
    "billing_cycle_anchor": "0",
    "deleted_at": null,
    "file": "",
    "autorenew_plan": "0",
    "tags": "",
    "enabled": "0",
    "questions": ""
  }
]
  			

GET /plan/{id}

Get a single plan

Parameters

id
integer Plan ID
//get a plan
$payWhirl->getPlan($id);//get a plan
payWhirl.getPlan(id)//get a plan
paywhirl.Plans.getPlan(plan_id, callback);


//Example Response
{
  "id": "1",
  "user_id": "1",
  "name": "My Test Plan (with anchor)",
  "setup_fee": "12.00",
  "installments": "0",
  "require_shipping": "1",
  "active": "0",
  "image": "",
  "starting_day": "0",
  "description": "",
  "metadata": "",
  "created_at": "2015-10-24 02:56:45",
  "updated_at": "2015-11-01 21:58:09",
  "billing_amount": "20.00",
  "billing_interval": "3",
  "billing_frequency": "day",
  "trial_days": "0",
  "sku": "455KYUH5",
  "currency": "USD",
  "require_tax": "1",
  "billing_cycle_anchor": "4",
  "deleted_at": null
}
  			

POST /create/plan

Create a plan

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
array Array of tags to be added to the plan (default: empty)
//create a plan
$payWhirl->createPlan($planData);//create a plan
payWhirl.createPlan(planData)//create a plan
paywhirl.Plans.createPlan(data, callback);


//Example Response
{
  "id": "6",
  "user_id": "1",
  "name": "Super Order Plan",
  "setup_fee": "0.00",
  "installments": "3",
  "require_shipping": "1",
  "active": "0",
  "image": "",
  "starting_day": "0",
  "description": "",
  "metadata": "{\"3\":{\"place_orders\":\"last\"}}",
  "created_at": "2015-11-19 17:20:42",
  "updated_at": "2016-03-10 00:14:37",
  "billing_amount": "10.00",
  "billing_interval": "1",
  "billing_frequency": "day",
  "trial_days": "0",
  "sku": "e456456",
  "currency": 0,
  "require_tax": "0",
  "billing_cycle_anchor": "0",
  "deleted_at": null,
  "file": "",
  "autorenew_plan": "0",
  "tags": "",
  "enabled": "0",
  "questions": ""
}
  			

POST /update/plan

Update a 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
array Array of tags to be added to the plan
//update a plan
$payWhirl->updatePlan($planData);//update a plan
payWhirl.updatePlan(planData)//update a plan
paywhirl.Plans.updatePlan(data, callback);


//Example Response
{
  "id": "6",
  "user_id": "1",
  "name": "Super Order Plan",
  "setup_fee": "0.00",
  "installments": "3",
  "require_shipping": "1",
  "active": "0",
  "image": "",
  "starting_day": "0",
  "description": "",
  "metadata": "{\"3\":{\"place_orders\":\"last\"}}",
  "created_at": "2015-11-19 17:20:42",
  "updated_at": "2016-03-10 00:14:37",
  "billing_amount": "10.00",
  "billing_interval": "1",
  "billing_frequency": "day",
  "trial_days": "0",
  "sku": "e456456",
  "currency": 0,
  "require_tax": "0",
  "billing_cycle_anchor": "0",
  "deleted_at": null,
  "file": "",
  "autorenew_plan": "0",
  "tags": "",
  "enabled": "0",
  "questions": ""
}
  			

GET /subscriptions/{id}

Get a list of subscriptions for a customer

Parameters

id
integer Customer ID
//get a list of subscriptions for a customer
$payWhirl->getSubscriptions($customer_id);//get a list of subscriptions for a customer
payWhirl.getSubscriptions(customer_id)//get a list of subscriptions for a customer
paywhirl.Subscriptions.getSubscriptions(cust_id, callback);


//Example Response
[
  {
    "id": "100",
    "user_id": "1",
    "customer_id": "89",
    "plan_id": "2",
    "quantity": "1",
    "cancel_at_period_end": "0",
    "current_period_start": "1457409530",
    "current_period_end": "1458619130",
    "trial_start": "1457409530",
    "trial_end": "1458619130",
    "installment_plan": "0",
    "installments_left": "0",
    "created_at": "2016-03-08 03:58:50",
    "updated_at": "2016-03-08 03:58:50",
    "deleted_at": null,
    "plan": {
      "id": "2",
      "user_id": "1",
      "name": "Monthly Subscription",
      "setup_fee": "5.00",
      "installments": "0",
      "require_shipping": "1",
      "active": "0",
      "image": "",
      "starting_day": "0",
      "description": "",
      "metadata": "{\"3\":{\"place_orders\":\"all\"}}",
      "created_at": "2015-11-10 04:08:46",
      "updated_at": "2016-03-04 15:45:32",
      "billing_amount": "50.00",
      "billing_interval": "1",
      "billing_frequency": "month",
      "billing_dates": "",
      "trial_days": "14",
      "sku": "474545456",
      "currency": "USD",
      "require_tax": "1",
      "billing_cycle_anchor": "0",
      "deleted_at": null,
      "file": "",
      "autorenew_plan": "0",
      "tags": "",
      "enabled": "1",
      "questions": "[\"3\"]"
    }
  },
  {
    "id": "101",
    "user_id": "1",
    "customer_id": "89",
    "plan_id": "1",
    "quantity": "1",
    "cancel_at_period_end": "0",
    "current_period_start": "1457409719",
    "current_period_end": "1460088119",
    "trial_start": "0",
    "trial_end": "0",
    "installment_plan": "0",
    "installments_left": "0",
    "created_at": "2016-03-08 04:01:57",
    "updated_at": "2016-03-08 04:01:59",
    "deleted_at": null,
    "plan": {
      "id": "1",
      "user_id": "1",
      "name": "Monthly Untra Subscription",
      "setup_fee": "0.00",
      "installments": "0",
      "require_shipping": "1",
      "active": "0",
      "image": "",
      "starting_day": "0",
      "description": "",
      "metadata": "{\"3\":{\"place_orders\":\"all\"}}",
      "created_at": "2015-11-10 02:14:31",
      "updated_at": "2016-03-04 15:45:16",
      "billing_amount": "40.00",
      "billing_interval": "1",
      "billing_frequency": "month",
      "billing_dates": "",
      "trial_days": "0",
      "sku": "4563456",
      "currency": "USD",
      "require_tax": "1",
      "billing_cycle_anchor": "0",
      "deleted_at": null,
      "file": "https://s3-us-west-1.amazonaws.com/paywhirl2/uploads/qa/565e1e8d7d5bf-badge.png",
      "autorenew_plan": "0",
      "tags": "international,free-shipping",
      "enabled": "1",
      "questions": "[\"1\"]"
    }
  }
]
  			

GET /subscription/{id}

Get a single subscription

Parameters

id
integer Subscription ID
//get a subscription
$payWhirl->getSubscription($id);//get a subscription
payWhirl.getSubscription(id)//get a subscription
paywhirl.Subscriptions.getSubscription(subscription_id, callback);


//Example Response
{
  "id": "34",
  "user_id": "1",
  "customer_id": "2",
  "plan_id": "1",
  "quantity": "1",
  "cancel_at_period_end": "0",
  "current_period_start": "1446344697",
  "current_period_end": "1446344697",
  "trial_start": "0",
  "trial_end": "0",
  "installment_plan": "0",
  "installments_left": "0",
  "created_at": "2015-11-01 02:24:57",
  "updated_at": "2015-11-01 02:24:57",
  "deleted_at": null
}
  			

POST /subscribe/customer

Create a new subscription for a customer

Parameters

customer_id
integer Customer ID
plan_id
integer Plan ID
quantity
integer Quantity (Default: 1)
promo_id
integer ID of promo code to apply
trial_end
integer UNIX timestamp in the future
//subscribe customer
$payWhirl->subscribeCustomer($customer_id,$plan_id,$trial_end);//subscribe customer
payWhirl.subscribeCustomer(customer_id,plan_id,trial_end)//subscribe customer
paywhirl.Subscriptions.subscribeCustomer(data, callback);


//Example Response
{
  "id": "34",
  "user_id": "1",
  "customer_id": "2",
  "plan_id": "1",
  "quantity": "1",
  "cancel_at_period_end": "0",
  "current_period_start": "1446344697",
  "current_period_end": "1446344697",
  "trial_start": "0",
  "trial_end": "0",
  "installment_plan": "0",
  "installments_left": "0",
  "created_at": "2015-11-01 02:24:57",
  "updated_at": "2015-11-01 02:24:57",
  "deleted_at": null
}
  			

POST /update/subscription

Update a customer's existing subscription

Parameters

subscription_id
integer Subscription ID
plan_id
integer Plan ID
//update subscription
$payWhirl->updateSubscription($subscription_id,$plan_id);//update subscription
payWhirl.updateSubscription(subscription_id,plan_id)//update subscription
paywhirl.Subscriptions.updateSubscription(data, callback);


//Example Response
{
  "id": "34",
  "user_id": "1",
  "customer_id": "2",
  "plan_id": "1",
  "quantity": "1",
  "cancel_at_period_end": "0",
  "current_period_start": "1446344697",
  "current_period_end": "1446344697",
  "trial_start": "0",
  "trial_end": "0",
  "installment_plan": "0",
  "installments_left": "0",
  "created_at": "2015-11-01 02:24:57",
  "updated_at": "2015-11-01 02:24:57",
  "deleted_at": null
}
  			

POST /unsubscribe/customer

Cancel a customer's existing subscription

Parameters

subscription_id
integer Subscription ID
//unsubscribe customer
$payWhirl->unsubscribeCustomer($subscription_id);//unsubscribe customer
payWhirl.unsubscribeCustomer(subscription_id)//unsubscribe customer
paywhirl.Subscriptions.subscribeCustomer(subscription_id, callback);


//Example Response
{
  "status": "success",
}
  			

GET /subscribers

Get a list of active subscribers

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
//get a list of active subscribers
$payWhirl->getSubscribers($data);//get a list of active subscribers
payWhirl.getSubscribers(data)//get a list of active subscribers
payWhirl.Subscriptions.getSubscribers(data)


//Example Response
[
  {
    "subscription_id": "639",
    "user_id": "1",
    "first_name": "Brandon",
    "last_name": "Swift",
    "email": "brandon@paywhirl.com",
    "customer_id": "1170",
    "plan_id": "1",
    "quantity": "1",
    "current_period_start": "1460580930",
    "current_period_end": "1463172930",
    "installment_plan": "0",
    "installments_left": "0",
    "created_at": "2016-04-13 20:55:29",
    "updated_at": "2016-04-13 20:55:30",
    "profile": [
      {
        "question": "Gender",
        "answer": "Male"
      }
    ]
  }
]
  			

GET /invoice/{id}

Get a single invoice

Parameters

id
integer Invoice ID
//get an invoice
$payWhirl->getInvoice($id);//get an invoice
payWhirl.getInvoice(id)//get an invoice
paywhirl.Invoices.getInvoices(id, callback);


//Example Response
{
  "id": "50",
  "user_id": "1",
  "customer_id": "2",
  "discount_id": "0",
  "subscription_id": "14",
  "charge_id": "0",
  "shipping": "1",
  "tax": "1",
  "attempted": "0",
  "attempt_count": "0",
  "currency": "USD",
  "due_date": "0",
  "next_payment_attempt": "1447944778",
  "period_end": "1447944778",
  "period_start": "1447339978",
  "status": "Subscribed",
  "paid": "0",
  "subtotal": "32.00",
  "shipping_total": "15.00",
  "tax_total": "1.50",
  "amount_due": "48.50",
  "webhooks_delivered_at": "0",
  "created_at": "2015-10-29 14:52:58",
  "updated_at": "2015-10-29 14:52:58",
  "paid_on": "0",
  "deleted_at": null,
  "promo_id": "0",
  "promo_code": "",
  "promo_uses": "0",
  "items": [
    {
      "id": "69",
      "type": "plan",
      "user_id": "1",
      "customer_id": "2",
      "invoice_id": "50",
      "subscription_id": "0",
      "quantity": "1",
      "description": "Subscription to Test Plan 2",
      "amount": "25.00",
      "currency": "USD",
      "created_at": "2015-10-29 14:52:58",
      "updated_at": "2015-10-29 14:52:58",
      "deleted_at": null
    },
    {
      "id": "70",
      "type": "fee",
      "user_id": "1",
      "customer_id": "2",
      "invoice_id": "50",
      "subscription_id": "0",
      "quantity": "1",
      "description": "Setup Fee",
      "amount": "7.00",
      "currency": "USD",
      "created_at": "2015-10-29 14:52:58",
      "updated_at": "2015-10-29 14:52:58",
      "deleted_at": null
    }
  ],
  "profile": [
      {
        "question": "Are you a US Resident?",
        "answer": "Yes"
      },
      {
        "question": "Gender",
        "answer": "Male"
      }
    ]
}
  			

GET /invoices/{id}

Get a list of upcoming invoices for a customer

Parameters

id
integer Customer ID
//get a list of upcoming invoices for a customer
$payWhirl->getInvoices($customer_id);//get a list of upcoming invoices for a customer
payWhirl.getInvoices(customer_id)//get a list of upcoming invoices for a customer
paywhirl.Invoices.getInvoice(id, callback);


//Example Response
[{
  "id": "50",
  "user_id": "1",
  "customer_id": "2",
  "discount_id": "0",
  "subscription_id": "14",
  "charge_id": "0",
  "shipping": "1",
  "tax": "1",
  "attempted": "0",
  "attempt_count": "0",
  "currency": "USD",
  "due_date": "0",
  "next_payment_attempt": "1447944778",
  "period_end": "1447944778",
  "period_start": "1447339978",
  "status": "Subscribed",
  "paid": "0",
  "subtotal": "32.00",
  "shipping_total": "15.00",
  "tax_total": "1.50",
  "amount_due": "48.50",
  "webhooks_delivered_at": "0",
  "created_at": "2015-10-29 14:52:58",
  "updated_at": "2015-10-29 14:52:58",
  "paid_on": "0",
  "deleted_at": null,
  "promo_id": "0",
  "promo_code": "",
  "promo_uses": "0",
  "items": [
    {
      "id": "69",
      "type": "plan",
      "user_id": "1",
      "customer_id": "2",
      "invoice_id": "50",
      "subscription_id": "0",
      "quantity": "1",
      "description": "Subscription to Test Plan 2",
      "amount": "25.00",
      "currency": "USD",
      "created_at": "2015-10-29 14:52:58",
      "updated_at": "2015-10-29 14:52:58",
      "deleted_at": null
    },
    {
      "id": "70",
      "type": "fee",
      "user_id": "1",
      "customer_id": "2",
      "invoice_id": "50",
      "subscription_id": "0",
      "quantity": "1",
      "description": "Setup Fee",
      "amount": "7.00",
      "currency": "USD",
      "created_at": "2015-10-29 14:52:58",
      "updated_at": "2015-10-29 14:52:58",
      "deleted_at": null
    }
  ],
  "profile": [
      {
        "question": "Are you a US Resident?",
        "answer": "Yes"
      },
      {
        "question": "Gender",
        "answer": "Male"
      }
    ]
}
]
        

GET /gateways

Get a list of payment gateways

Parameters

//get a list of gateways
$payWhirl->getGateways();//get a list of gateways
payWhirl.getGateways()//get a list of gateways
paywhirl.Gateways.getGateways(callback);


//Example Response
[
  {
    "id": "3",
    "user_id": "1",
    "name": "Authorize.Net",
    "created_at": "2015-11-15 23:31:08",
    "updated_at": "2016-03-25 01:35:09",
    "type": "AuthorizeNet",
    "error_message": "",
    "expires": "0",
    "metadata": ""
  },
  {
    "id": "11",
    "user_id": "1",
    "name": "Braintree Sandbox",
    "created_at": "2015-11-17 04:25:19",
    "updated_at": "2015-11-17 04:25:19",
    "type": "Braintree",
    "error_message": "",
    "expires": "0",
    "metadata": ""
  }
]
  			

GET /gateway/{id}

Get a single payment gateway

Parameters

id
integer Gateway ID
//get a gateway
$payWhirl->getGateway($id);//get a gateway
payWhirl.getGateway(id)//get a gateway
paywhirl.Gateways.getGateway(cust_id, callback);


//Example Response
{
  "id": "4",
  "user_id": "1",
  "name": "Stripe",
  "params": {
    "secretKey": "sk_test_xxxxxxxxxxxxxxxxxxxxxx",
    "publishableKey": "pk_test_xxxxxxxxxxxxxxxxxxxxxx"
  },
  "created_at": "2015-10-26 02:52:32",
  "updated_at": "2015-10-29 02:56:10",
  "type": "Stripe",
  "error_message": ""
}
  			

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)
//Create an invoice with a single charge
$payWhirl->createCharge($data);//Create an invoice with a single charge
payWhirl.createCharge(data)//Create an invoice with a single charge
paywhirl.Charges.createCharge(data, callback);


//Example Response
{
  "id": "2504",
  "user_id": "1",
  "customer_id": "1216",
  "discount_id": "0",
  "subscription_id": "0",
  "charge_id": "0",
  "shipping": "0",
  "tax": "0",
  "attempted": "0",
  "attempt_count": "0",
  "currency": "USD",
  "due_date": "0",
  "next_payment_attempt": "1475432796",
  "period_end": "1475432796",
  "period_start": "0",
  "status": "Scheduled",
  "paid": "0",
  "subtotal": "35.00",
  "shipping_total": "0.00",
  "tax_total": "0.00",
  "amount_due": "35.00",
  "webhooks_delivered_at": "0",
  "created_at": "2016-10-02 18:26:36",
  "updated_at": "2016-10-02 18:26:36",
  "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",
  "items": [
    {
      "id": "2675",
      "type": "fee",
      "user_id": "1",
      "customer_id": "1216",
      "invoice_id": "2504",
      "subscription_id": "0",
      "quantity": "1",
      "description": "Charge",
      "amount": "35.00",
      "currency": "USD",
      "created_at": "2016-10-02 18:26:36",
      "updated_at": "2016-10-02 18:26:36",
      "deleted_at": null,
      "sku": ""
    }
  ]
}
  			

GET /charge/{id}

Get a single charge

Parameters

id
integer Charge ID
//get a charge
$payWhirl->getCharge($id);//get a charge
payWhirl.getCharge(id)//get a charge
paywhirl.Charges.getCharge(id, callback);


//Example Response
{
  "id": "34",
  "user_id": "1",
  "gateway_reference": "ch_171eGCKsdBylqCDiM5uJj5rY",
  "amount": "20.30",
  "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",
  "refund_reference": ""
}
  			

GET /cards/{customer_id}

Get a list of customer cards

Parameters

customer_id
integer Customer ID
//get a list of cards
$payWhirl->getCards($customer_id);//get a list of cards
payWhirl.getCards(customer_id)//get a list of cards
paywhirl.Cards.getCards(cust_id, callback);


//Example Response
[
  {
    "id": "1339",
    "user_id": "1",
    "gateway_reference": "card_17x19KBeuvaFqYUwUoVYTLCx",
    "brand": "Visa",
    "funding": "credit",
    "country": "US",
    "customer_id": "1194",
    "last4": "4242",
    "created_at": "2016-04-05 20:54:09",
    "updated_at": "2016-04-05 20:54:09",
    "gateway_id": "39"
  }
]
  			

GET /card/{id}

Get a single card

Parameters

id
integer Card ID
//get a card
$payWhirl->getCard($id);//get a card
payWhirl.getCard(id)//get a card
paywhirl.Cards.getCard(id, callback);


//Example Response
{
  "id": "55",
  "user_id": "1",
  "gateway_reference": "card_172YBEKsdBylqCDiCu5Ryq6s",
  "brand": "Visa",
  "funding": "credit",
  "country": "US",
  "customer_id": "1",
  "last4": "4242",
  "created_at": "2015-11-02 02:36:44",
  "updated_at": "2015-11-02 02:36:44",
  "gateway_id": "1"
}

  			

POST /create/card

Create a card. Depending on your gateway, you would either supply card data or a token.

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.

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
exp_month
string Expiration Month
exp_year
string Expiration Year
first_name
string First name on card
last_name
string Last name on card
address
string Billing street address
city
string Billing city
state
string Billing state / region
zip
string Billing zip / postal code
country
string Billing country
//create a card
$payWhirl->createCard($data);//create a card
payWhirl.createCard(data)//create a card
paywhirl.Cards.createCard(data, callback);


//Example Response
{
  "id": "55",
  "user_id": "1",
  "gateway_reference": "card_172YBEKsdBylqCDiCu5Ryq6s",
  "brand": "Visa",
  "funding": "credit",
  "country": "US",
  "customer_id": "1",
  "last4": "4242",
  "created_at": "2015-11-02 02:36:44",
  "updated_at": "2015-11-02 02:36:44",
  "gateway_id": "1"
}

  			

POST /delete/card

Delete a card

Parameters

id
integer Card ID
//delete a card
$payWhirl->deleteCard($id);//delete a card
payWhirl.deleteCard(id)//delete a card
paywhirl.Cards.deleteCard(id, callback);


//Example Response
{
  "status": "success",
}

  			

GET /promo/{id}

Get a promo code

Parameters

id
integer Promo Code ID
//get a promo code
$payWhirl->getPromo($id);//get a promo code
payWhirl.getPromo(id)//get a promo code
paywhirl.Promo.getPromo(id, callback);


//Example Response
{
  "id": "2",
  "user_id": "1",
  "code": "50OFF",
  "amount_off": "0",
  "percent_off": "50",
  "duration": "forever",
  "duration_uses": "0",
  "redeem_by": "1448496000",
  "max_redemptions": "0",
  "times_redeemed": "3",
  "is_valid": "1",
  "created_at": "2015-11-02 21:29:27",
  "updated_at": "2015-11-02 22:48:33"
}

  			

GET /email/{id}

Get a single email template

Parameters

id
integer Email Template ID
//get an email template
$payWhirl->getEmailTemplate($id);//get an email template
payWhirl.getEmailTemplate(id)//get an email template
paywhirl.Emails.getEmailTemplate(id, callback);


//Example Response
{
  "id": "1",
  "user_id": "1",
  "type": "",
  "name": "Welcome Email",
  "from_name": "",
  "subject": "Welcome Aboard!",
  "template": "Hello {{ customer.first_name }}!",
  "error_message": "",
  "created_at": "2015-11-01 01:56:25",
  "updated_at": "2015-11-01 02:02:28"
}
  			

GET /account

Get information about the authenticated account

//get authenticated user's account
$account = $payWhirl->getAccount();//get authenticated user's account
account = payWhirl.getAccount()//get authenticated user's account
paywhirl.Account.getAccount(callback);


//Example Response
{
  "id": "1",
  "first_name": "Brandon",
  "last_name": "Swift",
  "company_name": "Brandon's Site ",
  "country": "US",
  "email": "brandon@paywhirl.com",
  "created_at": "2015-10-23 02:57:27",
  "updated_at": "2015-11-02 03:02:27",
  "phone": "8054444444",
  "address": "123 Easy St",
  "city": "Atlanta",
  "state": "Georgia",
  "zip": "30084",
  "currency": "USD",
  "slug": "brandonswift",
  "email_settings": {
    "test_mode": "on",
    "welcome_email": "13",
    "new_subscription": "default",
    "new_card": "default",
    "payment_receipt": "default",
    "payment_problem": "default",
    "payment_request": "default",
    "email_via": "paywhirl",
    "host": "smtp.gmail.com",
    "username": "",
    "password": "",
    "from_address": "",
    "from_name": "",
    "port" : ""
  },
  "application_fee_percent": "0.00",
  "send_reminders": "3",
  "plan": "ultimate",
  "pw_id": "40",
  "trial_end": "1448496000",
  "subscription_id": "54",
  "active": "1",
  "deleted_at": null,
  "stripe_pk": "pk_test_mI2jPU9iaLS17XtvaXXXXXXXX",
  "stripe_sk": "sk_test_lkdaQUPOnGYPe6KKXXXXXXXX",
  "stripe_client_id": "ca_7PjldqIun7x9r2idrBTBnbeXXXXXXXX",
  "last_login": "2016-09-06 17:33:19",
  "badge": "on",
  "editor": "editor",
  "logo": "https://s3-us-west-1.amazonaws.com/paywhirl2/uploads/qa/574739778088c-56e34572030da-Logo.png",
  "reg_enabled": "1",
  "login_enabled": "1",
  "promo_codes": "1",
  "retry_days": "7",
  "account_manager": "",
  "auth_token": "16b6e763cd6a394ed75613250c131c6fa05ba789",
  "auth_token_expires": "2016-09-07 16:08:51"
}

  			

GET /stats

Get authenticated user's account stats

//get authenticated user's account stats
$account = $payWhirl->getStats();//get authenticated user's account stats
account = payWhirl.getStats()//get authenticated user's account stats
payWhirl.Account.getStats(callback);


//Example Response
{
  "plan": "ultimate",
  "company_name": "Brandon's Site ",
  "logo": "https://s3-us-west-1.amazonaws.com/paywhirl2/uploads/qa/574739778088c-56e34572030da-Logo.png",
  "active": "1",
  "trial_end": "2015-11-26 00:00:00",
  "customers": 60,
  "invoices": 355,
  "revenue_today": "35.00",
  "revenue_month": "762.36",
  "revenue_total": "10831.64"
}

        

GET /shipping/{id}

Get a shipping rule

Parameters

id
integer Shipping Rule ID
//get a shipping rule
$payWhirl->getShippingRule($id);//get a shipping rule
payWhirl.getShippingRule(id)//get a shipping rule
paywhirl.Shipping.getShippingRule(id, callback);


//Example Response
{
  "id": "1",
  "name": "International Shipping",
  "type": "out_location",
  "plan_id": "0",
  "min_price": "0.00",
  "max_price": "0.00",
  "country": "US",
  "state": "Georgia",
  "zip": "",
  "shipping_price": "15.00",
  "created_at": "2015-10-24 20:37:16",
  "updated_at": "2015-10-25 02:25:59",
  "user_id": "1"
}

  			

GET /tax/{id}

Get a tax rule

Parameters

id
integer Tax Rule ID
//get a tax rule
$payWhirl->getTaxRule($id);//get a tax rule
payWhirl.getTaxRule(id)//get a tax rule
paywhirl.Shipping.getTaxRule(id, callback);


//Example Response
{
  "id": "1",
  "name": "Georgia Sales Tax",
  "country": "US",
  "state": "Georgia",
  "zip": "",
  "tax_price": "6.00",
  "tax_shipping": "0",
  "created_at": "2015-10-25 18:55:22",
  "updated_at": "2015-10-25 19:17:04",
  "user_id": "1"
}

  			

POST /multiauth

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

Once you retrieve your MultiAuth token, you can pass it into your embed code as an option:

paywhirl('widget',{multiauth: 'Tzo4OiJzdGRDbGFzcyI6Mjp7czoyOiJpZCI7cmV4cGlyZXMiO3M6MTA6IjE0NTk3MTYxNTIiO30%3D', domain:'paywhirl-1234' ,uuid:'2f663745-5d5e-4676-af61-59drr14dda1e'},'pw_56fc3a89ea864'); 

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.
//get a multiauth token
$payWhirl->getMultiAuthToken($data);//get a multiauth token
payWhirl.getMultiAuthToken(data)//get a multiauth token
paywhirl.MultiAuth.getMultiAuthToken(data, callback);


//Example Response
{
  "multiauth_token": "Tzo4OiJzdGRDbGFzcyI6Mjp7czoyOiJpZCI7cmV4cGlyZXMiO3M6MTA6IjE0NTk3MTYxNTIiO30%3D",
  "email": "customer.email@paywhirl.com",
  "id": "1191"
}

  			

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.

Events

type:
customer.created Customer is created
type:
customer.updated Customer is updated
type:
plan.created Plan is created
type:
plan.updated Plan is updated
type:
card.added Card is added to customer
type:
card.deleted Card is removed from customer
type:
subscription.created Customer is subscribed to a plan
type:
subscription.deleted Customer is removed from a plan
type:
invoice.created Invoice is created
type:
invoice.processed Attempted to process an invoice
type:
invoice.paid Invoice is marked as paid
type:
charge.succeeded Charge is successful
type:
charge.failed Charge is not successful
type:
charge.refunded Charge is refunded to customer
					
{
    "type": "invoice.paid",
    "customer": {
        "id": "10",
        "user_id": "1",
        "first_name": "Webhook",
        "last_name": "Customer",
        "email": "webhooks@paywhirl.com",
        "phone": "6737883887",
        "address": "123 Easy St",
        "city": "Atlanta",
        "state": "Georgia",
        "zip": "30084",
        "country": "US",
        "created_at": "2015-10-31 16:25:23",
        "updated_at": "2015-10-31 18:10:43",
        "gateway_reference": "cus_7GayqrTijUlgPA",
        "default_card": "50",
        "gateway_type": "Stripe",
        "gateway_id": "1",
        "currency": "USD"
    },
    "invoice": {
        "id": "93",
        "user_id": "1",
        "customer_id": "10",
        "discount_id": "0",
        "subscription_id": "0",
        "charge_id": "0",
        "shipping": "1",
        "tax": "1",
        "attempted": "1",
        "attempt_count": "1",
        "currency": "USD",
        "due_date": "0",
        "next_payment_attempt": 0,
        "period_end": "0",
        "period_start": "0",
        "status": "Paid",
        "paid": 1,
        "subtotal": "40.00",
        "shipping_total": "10.00",
        "tax_total": "2.40",
        "amount_due": "52.40",
        "webhooks_delivered_at": "0",
        "created_at": "2015-10-31 18:21:03",
        "updated_at": "2015-10-31 18:22:10",
        "items": [
            {
                "id": "126",
                "type": "custom",
                "user_id": "1",
                "customer_id": "10",
                "invoice_id": "93",
                "subscription_id": "0",
                "quantity": "2",
                "description": "My new added invoice item",
                "amount": "20.00",
                "currency": "USD",
                "created_at": "2015-10-31 18:21:03",
                "updated_at": "2015-10-31 18:21:03"
            }
        ]
    }
}