Monetary donations
OverviewAPI setupHosted setupProduct donations
OverviewAPI setupHosted setupAdditional fieldsDiscount redemptionOutcome emailsApplications inboxOrganization validation
OverviewCompliance checksEligibility reviewAgent verificationTestingOverview
The Single API setup for impact program validation allows you to collect and submit applications for your program within your app or website and receive a single notification with the success or failure status as soon as Percent has reviewed the application.
If you would prefer Percent to host the UI for your application flow, or are limited in engineering resource, please have a look at our hosted setup.
Below we will outline a typical API implementation that our customers follow when building their impact program flow:
1. Get your API keys
Before you start your implementation, you’ll need access to the dashboard to retrieve your Percent API keys.
Go to the Keys
page in your Partner dashboard to access your Publishable Key
as well as your Secret Key
.
Overview
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: Authorization
Please do not publish your private key in repos or use anywhere in front end.
2. Search for organization or collect organization information
Guide your users to search for their nonprofit or other good cause through your frontend application or website. You can implement this using the Search Organisations endpoint. This API can be authenticated with your publishable key, so the feature can be built entirely in your front end.
FRA
Organizations can be filtered by:
→ Country using the countryCode
parameter;
→ A query
parameter, that searches organization name, registry ID and description, if available
→ Registry ID, such as EIN, using the registryID
parameter;
→ Or other filters listed in Search Organisations endpoint.
Customers most often use a combination of countryCode
and the query
filter to implement search.
A: Organization exists
If the user identifies and selects their organization, you will have an organisationId
field from the search result to submit with the Validation Submission request in Part 3.
B: Organization not found
If the organization search returns no results or the user can’t identify their organization, you’ll need to collect further details about your user’s org and submit them to us in the Validation Submission.
The information that we need to conduct a Validation Request in this case are:
→ organisationName
- the name of the organization
→ registryName
- the registry where the organization is officially registered, e.g. the Internal Revenue Service
→ registryId
- the unique ID of the organization in the above registry (e.g. an EIN in the United States)
→ website
- the URL of the organization’s official website
→ Documentation of the organization’s status, uploaded via the Create Validation Submission Document API.
The validation submission will also require a countryCode
and language
field.
3. Send validation submission
Validation configuration
The checks that are run when a validation submission is sent are defined by a Validation Configuration on your account which has a unique configurationId
.
configurationId
.
The active configurations on your account can be retrieved from the List Validation Submission Configurations API.Each submission may include up to four separate checks:
→ Validation Request (if the request is made with no organisationId
provided)
Create Submission with organisation ID
If you have an organisationId
from your search results, you can create a Validation Submission by posting the ID to the Create Validation Submission endpoint:
POST https://api.poweredbypercent.com/v1/validation-submissions
Authorization: Secret Key
Content-Type: application/json
{
"configurationId": "configuration_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"organisationId": "organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"language": "en-US"
}
configurationId
field is not strictly required, if not specified the API will fall back to a default account configuration. We recommend always passing the configuration to ensure that the correct one is used.
The firstName
, lastName
and email
fields are required if the configuration includes an Agent Verification check, but can be omitted if this check is not included.Create Submission without organisation ID
If the user cannot find their organisation, you can submit their organisation details for validation as follows:
POST https://api.poweredbypercent.com/v1/validation-submissions
Authorization: Secret Key
Content-Type: application/json
{
"configurationId": "configuration_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"organisationName": "organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"registryName": "Charity Registry",
"registryId": "ABC 123",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"website": "https://example.com",
"countryCode": "USA",
"language": "en-US"
}
null
value for the organisationId
on creation but will be assigned one if the details are found to be valid. The ID can be retrieved from webhooks or calling the GET Validation Submission API.Uploading documents
If the organisation is not found in search results, you will also need to collect and upload documentation of status, such as nonprofit registration.
After you have created the Validation Submission, documents can be uploaded via the Create Validation Submission Document API along with the validationSubmissionId
returned by the create request.
Adding metadata to a submission
The Validation Submission API also accepts a metadata
object, which can be used to attach arbitrary information to a submission and retrieve it later.
This is most commonly used to link validation submissions to internal account IDs or to record additional user-supplied information from your application form.
4. Receive and process results
After creating validation submissions, you’ll to be able to process the results for each check. For that, you can subscribe to notifications by creating webhook subscriptions using the Webhook Subscriptions API, and specifying the events you want to get notifications for and the URL where you wish to receive these events.
The three events linked to Validation Submissions are:
→ validation_submission.created
- this is fired as soon as you successfully post to the create API
→ validation_submission.failed
- sent in the event that any of the checks in the configuration fail
→ validation_submission.succeeded
- sent in the event that all of the checks in the configuration pass
Handling webhooks
Before subscribing you will need to create server-side event handlers to trigger any required actions, such as account upgrades.
In the case that a validation submission has failed
status, the associated webhook will include a failureReasons
object with a breakdown of the checks that failed if you wish to record this information in your system or communicate it to your users.
Verifying webhooks
You can verify that the incoming webhook notification is sent by Percent by the following code example (Note: the code example is for a Node/Express app).
const crypto = require('crypto')
const app = require('express')
const endpointSecret = 'sk_xxxxxxxxxxxxxxxxxxxxxxxx'
const verifySignature = (secret, payload, signature) => {
const hmac = crypto.createHmac('sha256', secret)
hmac.write(payload)
hmac.end()
return hmac.read().toString('hex') === signature
}
app.post('/webhook', bodyParser.raw({type: 'application/json'}), (request, response) => {
const payload = request.body
const sig = request.headers['Percent-Signature']
if (!verifySignature(endpointSecret, payload, sig)) {
response.status(403).send()
}
// perform business logic based on event
response.status(202)
})
200
response as soon as you have verified the webhook and stored it for processing. You may wish to use a queue to store the incoming events and process asynchronously.
If the webhook handler responds too slowly, this could lead to a timeout which will mean that we retry the webhook.On this page
- Overview
- 1. Get your API keys
- Overview
- 2. Search for organization or collect organization information
- A: Organization exists
- B: Organization not found
- 3. Send validation submission
- Validation configuration
- Create Submission with organisation ID
- Create Submission without organisation ID
- Uploading documents
- Adding metadata to a submission
- 4. Receive and process results
- Handling webhooks
- Verifying webhooks