Direct API

FlipGive provides a means for fundraisers to raise money through donations, selling merchant offers (such as electronic gift cards, vouchers, and certificates) as well as referral shopping trips to online ecommerce websites.

This document focuses on how online shopping works as a fundraising mechanism. FlipGive shopping works much like existing affiliate referral programs out in the market today. An online shopping offer is setup, with the merchant agreeing to give a % of purchases online (before taxes and after discounts) to someone running a FlipGive fundraising campaign. The overall process works like this:

1. Fundraisers get supporters to visit their fundraising page, they are provided a shop link to visit a merchant’s website.
2. This link embeds a supporter’s ID and the related fundraising campaign information and passes this to the merchant’s website.
3. The merchant captures this information, and on checkout the supporter’s purchase amount is then passed back to FlipGive along with the supporter ID and campaign information.
4. FlipGive then calculates the contribution amount to the fundraiser and updates their goal meters accordingly.
5. FlipGive captures a breakdown of each transaction and financial reconciliation is then handled on a monthly basis.

This document outlines the process by which a shop referral option is setup and integrated with a merchant e-commerce website; as well as how payments are reconciled.

Shop Offer Setup

A shop offer is setup & configured in the FlipGive administration by FlipGive staff, with the details based on contractual terms with the merchant. In the FlipGive system, a shop offer consists of:

• Offer details - description of offer displayed to supporters explaining how they can help the fundraising campaign by shopping online
• Currency - CAD or USD is currently supported
• Landing page URL - the merchant’s landing page; this can be the merchant’s homepage or a custom landing page greeting fundraising supporters to start shopping
• Revenue % splits - that occur when a purchase is made. It is setup in the FlipGive administration panel based on the contract.
• Subsequent period duration (optional) – fundraising campaigns in FlipGive have a fixed-length duration, typically a month. Shopping can take place not only during the campaign duration but as a bonus can also take place after the campaign ends, allowing supporters to continue giving. This “subsequent period” is how long (in days) post-campaign a shopping offer will continue to be available; this is useful if a merchant wants to continue to promote additional shopping trips over a longer period of time.
• Subsequent period % splits (optional) – shopping during the “subsequent period” can have different revenue splits. Typically subsequent shopping trips contribute a smaller percent to the fundraiser.

FlipGive To Merchant

The next part of the integration is passing the user from the FlipGive team to the merchant’s website with related fundraiser information, and updating the merchant’s website to capture this information to the buyer’s account.

FlipGive will send the user to the merchant landing page with a secure token, when the user clicks on the Shop Now button.

Details of the API integration can be found here: https://api.flipgive.com/

Secure Token

When a customers shops with FlipGIve, a unique token is passed through to the merchant website. The merchant website can then call the FlipGive API with this token will return the set of data in JSON using the “Show” method.

Note: Secure merchant access credentials to API at https://api.flipgive.com will be provided by your FlipGive account manager.

A secondary call using the secure token will need to be made to FlipGive using the “Show” method to retrieve the following information:

• Campaign ID: 12345 – unique ID of the fundraising campaign
• Campaign Name: “Help my basketball team get to the playoffs” – name of the fundraising campaign for display purposes
• Fundraiser ID (optional): 12345 – the unique fundraiser ID
• Fundraiser Name (optional): “John Smith” – name of the fundraiser for display purposes
• Shop ID: 12345 – unique ID of the shopping offer that is being used
• Shop Percentage: 20 - % revenue split to fundraising campaign; used to calculate a contribution amount at checkout for display purposes, i.e. “20” would calculate 20% of sub-total after discounts and before taxes to show the contribution amount
• Shop Offer Name: “20% back for online purchases” – name of shop offer for display purposes
• Buyer ID (optional): 12345 – if the customer AKA supporter was logged in when they clicked the shop option, their FlipGive user ID will also be passed. This is so that a link can be made between their FlipGive and merchant account ID
• Buyer First Name (optional): “John” - First name of the Buyer if available.
• Buyer Last Name (optional): “Smith” - Last name of the Buyer if available.
• Intent ID: 12345 - the intent ID which allows us to map the number of shopping visits to a single click made from FlipGive to merchant site; this ID only changes if they go back to FlipGive and initialize another shop action
• Active Campaign Share Percent - percentage of funds giving to the campaign while it is active
• Active Campaign Share Percent Ends On - When the active campaign share percentage will no longer be used.
• Subsequent Campaign Share Percent - The percentage of funds giving after the “Active Campaign Share Percent Ends On” date.
• Subsequent Campaign Share Percent Ends On - The date when the “Subsequent Campaign Share Percent” will no longer be used.
• Campaign Image - The image of the campaign being used.
• Fundraiser Image (optional) - The image of the fundraiser that belongs to the campaign.

The merchant website can then store this information in the user’s shopping session along with the date/time the shop event was initiated; in the event that the user signs in, this information should be saved to their user account so that this information can be used for multiple shopping trips. In the event that the user comes from FlipGive supporting a different fundraiser, this information will need be updated on their user account.

Notifications (Optional)

We recommend notifying the buyer to confirm their cash back earnings to encourage them to checkout - we’ve found this increases the conversion rate of their shopping trip from FlipGive 5-10%. There are two ways to do this:

1. Popup notification: a notification shown to the buyer as soon as they land on your website - this is typically done on a specific landing page or across your product catalog. This helps “handoff” the customer and ensures them that their shopping trip will reward them with cashback to their FlipGive team.

2. During checkout: once in the checkout process, showing a confirmation of their cashback amount during the checkout confirmation ; displaying the campaign and fundraiser names the buyer will be contributing to, as well as the contribution amount.

Merchant checkout. The display fields for Campaign Name (cn), Fundraiser Name (fn), and Shop Name (sn) are shown along with the calculated contribution portion from the Shop percentage (sp).

Additional data to capture (Optional)

When the customer checks out, there are other optional datapoints to capture the following information to pass back to FlipGive:

1. An “Anonymous” option which will affect whether we display the buyer’s information on the fundraising page after the shop transaction is posted back to us.
2. A supporter message to the fundraiser - this is a public message posted to the fundraiser’s campaign page.
3. The ability for the shopper to change the supported fundraising campaign for their checkout. If this is desired, there is a Campaigns API which allows you to provide an option for customers to search and select a different campaign to attribute their purchases to.

An example of a supporter with a message posted, and an anonymous supporter.

Post-Checkout

Upon completion of checkout, the merchant will need to call the FlipGive create shop API call “Create” to record the completed transaction. The following parameters would need to be passed:

• Secure token – this is the original secure token that was passed from the user’s visit, and will contain all the reference information required to link the transaction the associated fundraising campaign.
• Type - Must be “Sale”
• Purchase subtotal cents: 4999 – this is the amount purchased (after any discounts, and before taxes) which will be used to calculate the contribution amount to the fundraising campaign.
• Merchant order at: “2013­-03-­13T13:59:59Z” – the date/time the purchase was made; in the event these calls are not made real-time
• Merchant order number: “2343” - order number of the purchase. Used to link orders back to between the two systems.
• Merchant customer ID (optional): 12345 – in the event that the user was signed into a FlipGive account when they clicked over to shop, if a customer ID at the merchant site is passed, we will be able to link the two accounts together which will be available in future reconciliation reports.
• Buyer first name: “John” - in the event that the buyer did not sign up on the FlipGive site, we will show this display information instead on the supporter listing.
• Buyer last name: “Smith” - in the event that the buyer did not sign up on the FlipGive site, we will show this display information instead on the supporter listing.
• Buyer Email (optional): “[email protected]” - Email of the buyer
• Buyer Phone Number (optional): “1-234-234-2345” - Phone number of the buyer.
• Anonymous (optional): true/false - an option which enables the fundraiser’s information to be hidden on the fundraiser page
• Message (optional): “Good luck with your fundraiser!” - a supporting message from the buyer to the fundraiser to be displayed publicly on their fundraising page.

Successful posts to the FlipGive API will result in a 200 response, which will also return a transaction ID to be stored in your database for reference - we strongly recommend storing this value as it is required to post refunds, and will help with customer service issues.

In the event that there are any issues with the data passed back, FlipGive will respond with 422 or 401 / provide validation errors.

Repeat Checkouts

If the customer who originated from FlipGive decides to purchase again, you can implement subsequent gives to their campaign by passing the same secure token multiple times to FlipGive, using the same create Shop API call, to give again.

Phone Orders

Phone orders can be handled by integrating with the API’s search feature and calling create_phone_order method once the phone order has been placed.

The API search functionality allow users to find campaigns using the campaign name, organization name, a person’s name or email belonging to the campaign. Once the particular campaign fundraiser is found the campaign ID must be noted for the next API call. The following parameters are required:

• Overall_search: “John Smith” or “[email protected]” - the text to search for

Once your phone order is created, you would call our create_phone_order method to attribute the phone order with either a Fundraiser ID or a Campaign ID. The following attributes are required.

• Campaign_id: 1234 - the campaign id you found using the search.
• Fundraiser_id: 1234 (optional) - the fundraiser id associated with the campaign if a specific fundraiser needs to be credited.
• Purchase subtotal cents: 4999 – this is the amount purchased (after any discounts, and before taxes) which will be used to calculate the contribution amount to the fundraising campaign.
• Merchant order at: “2013­-03-­13T13:59:59Z” – the date/time the purchase was made; in the event these calls are not made real-time
• Merchant order number: “2343” - order number of the purchase. Used to link orders back to between the two systems.
• Merchant customer ID (optional): 12345 – in the event that the user was signed into a FlipGive account when they clicked over to shop, if a customer ID at the merchant site is passed, we will be able to link the two accounts together which will be available in future reconciliation reports.
• Buyer first name: “John” - in the event that the buyer did not sign up on the FlipGive site, we will show this display information instead on the supporter listing.
• Buyer last name: “Smith” - in the event that the buyer did not sign up on the FlipGive site, we will show this display information instead on the supporter listing.
• Buyer Email (optional): “[email protected]” - Email of the buyer
• Buyer Phone Number (optional): “1-234-234-2345” - Phone number of the buyer.
• Anonymous (optional): true/false - an option which enables the fundraiser’s information to be hidden on the fundraiser page
• Message (optional): “Good luck with your fundraiser!” - a supporting message from the buyer to the fundraiser to be displayed publicly on their fundraising page.

Successful posts to the FlipGive API will result in a 200 response, which will also return a transaction ID to be stored in your database for reference - we strongly recommend storing this value as it is required to post refunds, and will help with customer service issues. In the event that there are any issues with the data passed back, FlipGive will respond with 422 or 401 / provide validation errors.

Refunds & Adjustments

In the event that a customer refunds a portion or all of their order, a call should be made to FlipGive using “Refund” (full amount) or “Adjust” (partial amount) so that we can adjust the payouts accordingly. To issue a refund, you will need the original transaction ID passed to you when you successfully posted a shop to us, as well as the refund amount.

• Transaction ID: 1234 - this is the FlipGive transaction ID that was sent back when the original shop transaction was successfully posted.
• Refund amount cents: 4999 – this is the amount that you wish to refund (after any discounts, and before taxes) which will be deducted from payouts to the various constituents from the original transaction.

Successful posts to the FlipGive API will result in a 200 response. In the event that there are any issues with the data passed back, FlipGive will respond with 422 or 401 / provide validation errors.

Please note: upon posting a successful refund, payouts will be adjusted so that you will not be responsible for the previously posted shop. This will be reflected in our accounting and in the payout reports to the fundraiser; however at this time we do not adjust the fundraiser’s goal meter and page details due to problems that occur when goal meters are reduced - fundraising goals could be tripped more than once, etc.

Payout & Reconciliation

FlipGive will be doing the payouts to the fundraisers based on their campaign completion dates. During this time, all shopping transactions sent via the API will be accounted for, and FlipGive will do the following:

1. Sum portion (based on % split) to the fundraiser’s beneficiary & cut them a check for this portion.
2. Sum portion (based on % split) to the merchant and send an invoice for the amount owed.
3. Sum portion (based on %split) to FlipGive
4. Sum portion (based on %split) to any secondary beneficiaries (as defined per contract) and cut them a check for this portion.

The interval which this takes place is usually on a monthly basis, but is defined in the contract. In the merchant’s admin console, there is an ability to export all transaction for any given month to a comma separated (CSV) format for further bookkeeping & reconciliation purposes.

Get Started

To get started with the shop integration, please view the detailed API documentation to see how the exact JSON fields & formatting work. The detailed API docs to start integration with our test environment are available at https://api.flipgive.com.

Please contact your FlipGive account representative to get an API key so that you can start setting up your shop integration.