The Percent Hosted Donation Gateway enables you to create a branded donation experience in your product, using only a few lines of code.
Once live, your users can easily and efficiently donate to the nonprofit of their choice whilst feeling like they’re in your application.
You’ll be able to customize the following:
Here’s a summary of how the hosted donation flow will work:
1. Get your API keys
Before you start your implementation, you’ll need access to the dashboard to retrieve your Percent API keys.
Authenticate your API requests by using these API keys in the request header.
The secret key should be used for server to server requests and the publishable key for requests via your front end to any public API services.
Header parameter name:
Please do not publish your private key in repos or use anywhere in front end.
2: Customize the Hosted Donation Gateway
You can customize the look and feel of the Hosted Donation Gateway:
- A CSS hex colour value representing the primary branding colour for the hosted form e.g.
- A logo or icon that will be displayed on the form, in the event that we don’t have a logo for the non profit.
- For best results, we recommend that your logo is a square image larger than
128 x 128 pixels.
PNGfile types are supported.
You can’t currently customise this yourself (we’re working on it) but in the meantime you can share these with your account manager or send to firstname.lastname@example.org.
3: Implement the hosted donation gateway
Add or update an endpoint on your server to create a
donation session using the Create A Donation Session API using your secret API key.
A donation session represents your user’s session as they donate to a nonprofit. We recommend creating a new donation session each time your user attempts to donate.
The donation session object may enter the following statuses:
open→ the donation session object will be in an
openstatus after creation
completed→ after a donation is successfully made by the user the status of the donation session object will transition to
expired→ if no donation is completed before the
expiresAttime the status will be
expiresAttime is 24 hour after creation after which the user will be unable to complete a session and users loading the donation session will see a message saying the session is expired.
Create a donation session
To create a donation session you must supply the
organisationId of the nonprofit you want your user to be able to donate to.
To get the
organisationId you can use the Search Organisations API, either to build a search experience for your users or to find the nonprofits you want your users to donate to and manually add them to your application.
The nonprofit search API can be filtered by:
→ Country using the
→ Nonprofit name using the
Donation sessions can be created with the following optional parameters:
userId→ to track donations against one of your users, you may create a user using the Users API. Store the userId against your user and send this through when creating a donation session.
successUrl→ URL that the hosted form redirects to after the flow is completed. If this is not provided a success screen will be displayed to the user after a successful donation.
currency→ to set the currency that the payment will be taken in. If this is not provided then the currency will be set based on the user’s location if the language is supported, or it will default to USD.
language→ to set the preferred language for us to present the form in. If this is not provided then the language will be set based on the user’s location if the language is supported, or it will default to English.
Authorization: Secret Key
You will receive a response matching the format of the example below.
After creating the donation session, direct your user to the
url for the hosted donation gateway returned in the response. Your user will receive an email receipt after a successful donation.
4. Track donations & donation sessions
You can query for Donations by
userId and filter by date. The Donation object tracks the lifecycle of a donation.
Donations created from Donation Sessions will be of type
hosted. The Donation object also contains the following fields that are collected from the user as they successfully donate via the Hosted Donation Gateway:
firstName→ user’s first name
lastName→ user’s last name
consentedToBeContactedByOrg→ whether the user consented to be contacted by the benefitting organization
anonymous→ whether the user wants to share their donation publicly or not
For a full reference see Donations API.
Donations of type
hosted may enter the following statuses:
REQUESTED_PAYMENT→ user has submitted a donation amount and we are waiting for the payment to be completed
RECEIVED_PAYMENT→ the payment has been completed
DISBURSED→ the donation has been successfully paid out to the nonprofit
CANCELLED→ if the user abandoned the session after submitting a donation amount, the donation will be automatically cancelled after 24 hours
To receive information about the outcome of a donation in real time, you can subscribe to our webhooks service.
Authorization: Secret Key
Once payment is received for a donation, we will submit a POST request to your designated webhook URL to inform you of the event.
The event type will be
donation.hosted.payment_received and the object will contain information about the donation. For a full reference see Percent webhooks.
5. Test your integration
You can use these details to test your integration. Use the nonprofit details for testing nonprofit search or creating donation sessions and use the test card details for testing donations.
The following organisations are available for making donations in the sandbox. You can use these to test your integration.
Organisation Id (sandbox)
Cardiac Risk in the Young
One Tree Planted
Black Girls Code
Australian Red Cross
Test card details
The following card details can be used to test various different card transaction outcomes in the Hosted Donation Gateway sandbox environment.