Custom Donation Flow - Cart of Products

(recommended), consists of cart items

Cart Params Example:

  • cart - consists of cart_items
  • desc - cart's description
  • max_times_donate - set max times the donation will run (optional)
  • cart_item
COPY
# 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 Numerical campaign ID the product should be associated with (when logged in as admin go to Settings > Campaigns and click edit. Choose last number in url) yes
person_attributes[first_name] First name of the registrant (needs to be URL encoded) no
person_attributes[last_name] Last name of the registrant (needs to be URL encoded) no
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 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 its title. no
user_editable=false This should only used for non-donation recurring transactions. It 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

Parameter 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