Create a custom checkout

This outlines how to correctly pass a single item or a cart of items over to Kindful so the objects can be processed in Kindful. A common example is event registration, sponsorships, memberships, and other custom transaction flows.

Creating a Cart with a Single Donation Value Example

<div class="row">
  <div class="donate-options">
    <label>
      <input type="radio" value="25" name="donate-amount"/> $25
    </label>
    <label>
      <input type="radio" checked value="50" name="donate-amount"/> $50
    </label>
    <label>
      <input type="radio" value="100" name="donate-amount"/> $100
    </label>
  </div>
</div>
function calculateRegistration(){
  var amount = parseInt($('input[name="donate-amount"]:checked').val());
  var donationAmount = (isNaN(amount)) ? 0 : amount;
  return donationAmount
}

function buildUrl(){
  var items = 0;
  var donation_amount = calculateRegistration();
	var campaign_id = 0000 (substitute the Kindful campaign id you want the transaction to be tied to)
  
  var url = "https://testorg.kindful.com/widget?campaign_id=" + campaign_id;
  url += "&schedule=0" 
  url += "&success_action=GET"
  url += "&success_url=http%3A//testorg.org/"
  url += "&cart[desc]=Test Donation";
  
  if (donation_amount > 0){
    url += "&cart[items]["+items+"][amount]="+donation_amount;
    url += "&cart[items]["+items+"][desc]=Online Donation"
    url += "&cart[items]["+items+"][product_id]=online_donation"
    url += "&cart[items]["+items+"][quantity]=1";
    items ++;
  }
  if (items > 0){
    window.location.href = url;
  }else{
    alert('Please select a donation amount')
  }
}

}

//NOTES: schedule=0 sets the recurrence to be a one-time donation. if you'd like it to be recurring, please look at the different recurrence options in the "Top Level and Cart Params" table a little bit further down the page.
//cart_item desc and cart_item product_id can be changed to be whatever you'd like the product name and product id to be. Online Donation is just an example. Kindful will dynamically create the product in our system if it doesn't already exist under your organization.

In addition to dynamically-building the URL with Javascript, a static URL can be placed as a link anywhere on the web. A great example is a "donate" button on your main website.

Note: Be sure to use the full, original URL in any links you publish. During the process of testing your links, you are redirected to the Kindful checkout with a one-time-use URL which includes a randomly-generated ID. A common mistake is to publish this link instead of the longer URL which will forward any user on to the checkout.

For URLs short enough for a GET request, you can use this format:

https://org_subdomain.kindful.com/widget?campaign_id=9999&arg_2=test&arg_3=etc

If you have a large number of params, or a few with very long values, please POST all params instead to:
https://org_subdomain.kindful.com/set_widget_session

You'll get a response of: 
{"widget_session_key" => session key to access the params}

On success, redirect user to checkout flow via the widget endpoint above, with the params widget_session_key=#{data['widget_session_key']} and check_widget_session=true
https://org_subdomain.kindful.com/widget?widget_session_key=#{5555555555}&check_widget_session=true

NOTE: you must be on a Kindful subdomain to execute the POST request.

Cart of Products
(recommended), consists of cart items

cart - consists of cart_items
  desc - cart's description
  max_times_donate - set max times the donation will run (optional)
  cart_item
    product_id - source's id for product
    quantity - amount purchased for product
    amount - cost of one product unit
    desc - product's description
    non_tax_deductible - (optional)
    
    
cart as hash
 NOTE: Rails: turn hash to url query string - cart_hash.to_query
 	"cart"=>
  {
    "desc"=>"My Cart Description",
    "items"=>
    {
      "1"=> {"product_id"=>"1", "desc"=>"Test1", "quantity"=>"1", "amount"=>"100"},
      "2"=> {"product_id"=>"2", "desc"=>"Test2", "quantity"=>"2", "amount"=>"100", "non_tax_deductible" => "40"}
    }
  }
 
 
cart when converted to url format would show up as below:
	cart[desc]=description&cart[items][1][amount]=100&cart[items][1][desc]=Test1&cart[items][1][product_id]=1&cart[items][1][quantity]=1&cart[items][2][amount]=100&cart[items][2][desc]=Test2&cart[items][2][product_id]=2&cart[items][2][quantity]=2&cart[items][2][non_tax_deductible]=40


Cart item 1's parameters in above example is
	cart[items][1][amount]=100&cart[items][1][desc]=Test1&cart[items][1][product_id]=1&cart[items][1][quantity]=1

And cart item 2's
	cart[items][2][amount]=100&cart[items][2][desc]=Test2&cart[items][2][product_id]=2&cart[items][2][quantity]=2&cart[items][2][non_tax_deductible]=40

Top Level and Cart Params

Parameter
Description
Required

cart[desc]

Public facing title of cart
(appears on checkout flow and in the activity trail)

yes

campaign_id

Campaign the product should be associated with (when logged in as admin go to Settings > Campaigns and click edit. Choose last number in url)

yes

schedule

Recurrence period option id for Kindful*

0 - single donation
1 - monthly on 1st
2 - monthly on 5th
3 - monthly on 10th
4 - monthly on 20th
5 - means weekly.
7 - means yearly (B.I.*)
8 - means biweekly (B.I.)
9 - quarterly (B.I.)
43 - every six months (B.I.)

to bill monthly on today's date, set 'schedule' to 1 and add the param and value: bill_today=true B.I. stands for "Billed Immediately"

no, defaults to "0", but allows users to choose recurring donation, if desired.

bill_today

To bill monthly on today's date, set 'schedule' to 1 and add this param with a value of "true"

ie: bill_today=true

no

cancel_at_end=true

This allows you to set up a recurring transaction, like a membership, to be canceled at the end of the recurrence period. Usually used with max_times_donate.

no

max_times_donate

The max number of times the recurring transaction should run

no

source_id

Indicates outside system in Kindful (optional) (integer) This is useful for tracking multiple lead generation sources

no

order_id

Sources unique order identifier (optional) submitted back on success url

paid_amount

Use this when having a user only pay for part of the full transaction. Set the value to be the amount they are paying today. (Cart item prices should remain the full price, to calculate the remaining balance)

(ie: paying a deposit amount, see photo #1)

no

team_donate_id

Set this param to give to the team donate flow. Set the value to the id of the team you'd like to donate to.

no

success_url

URL to redirect user to after successful donation.

yes

success_action

By default, the user is redirected to the success_url via a POST. You can change this action to a GET request, by setting success_action to GET.

ie: "&success_action=GET"

no

summary_title

By default, the checkout page has a header of "Donation Summary".

The value you enter will replace the word "Donation"

no

submission_title

Change the text of the checkout page's submit button. By default it is set to "Donate"

no

checkout_title

Changes the name of the campaign on the checkout flow page (usually defaults to cart[desc]), but you can use this param if you'd like to have the cart description be labeled differently than the checkout flow.

no

is_donation=false

This will change all language in the Kindful system to payment instead of donation. When it's a recurring donation, it will use the cart's description as it's title.

no

user_editable=false

This should only used for non-donation recurring transactions, and prevents the user from being able to edit their recurring transaction

no

additional_data["your_key_here"]

Additional data allows you to store additional data on the cart level OR the cart_item level.

no

group_id

Kindful Group id you want the person creating the transaction to be added to.

no

locale

Approved locale value to display the donation flow in a language other than English.
(See Internationalization docs.)

no

custom_answers

Set to true if passing in custom field values for transaction. Note: cart[] attributes must be passed in for custom answers to take effect.

no

custom1

Text value of existing select campaign custom answer in Kindful or free-text value for text custom field

no

custom1_id

Integer ID of existing campaign custom answer in Kindful

no

custom2

Text value of existing select campaign custom answer in Kindful or free-text value for text custom field

no

custom2_id

Integer ID of existing campaign custom answer in Kindful

no

custom3

Text value of existing select campaign custom answer in Kindful or free-text value for text custom field

no

custom3_id

Integer ID of existing campaign custom answer in Kindful

no

Cart Item Params

Param
Description
Required

amount

cost of one cart item

yes

quantity

number of the product to purchase

yes

desc

product's name/description

yes

product_id

source id for product

ie: "child_sponsorship")

yes

non_tax_deductible

By default, all transactions are tax-deductible. Set this to be whatever amount of the transaction is non tax deductible.

For example, an event ticket that cost $20 would have the params:

&cart[items][1][amount]=20
&cart[items][1][non_tax_deductible]=20

no

full_amount

If a product has a discount code, you can put the discounted price as the cart item's amount and set this param as the full amount, that way, orgs can keep track of why the price is different for the same products.

no

additional_data["your_key_here"]

Additional data allows you to store additional data that can be mapped to the person.

We have product actions that can be set up on the admin side to be able to map these fields to person_fields or person_custom_fields.

ie: &additional_data["registrant_first_name"]=John&additional_data["registrant_last_name"]=Doe

no

Setting up Pledges

GET 'https://org_subdomain.kindful.com/pledges/widget'
will redirect to the pledge checkout flow

See EndPoint Key for information on posting the params to widget session if they are long. Same practice applies to the 'pledges/widget'

Single Product Params

Parameter
Description
Required

amount

amount to charge donor

(ie: "20")

yes

item_ID

unique identifier for source product

(ie: "child_sponsorship")

yes

item_title

set name of product

(ie: "Child Sponsorship")

yes

max_times_donate

max number of times the donation will run

(defaults to 1 if one time donation and is not set if recurring donation)

no

Pledge Specific Params

pledge_summary_title

By default, the checkout page has a header of "Pledge Summary".

The value you enter will replace the word "Pledge"

no

pledge_submission_title

Change the text of the checkout page's submit button. By default it is set to "Submit Pledge"

no