Upgrade to managing multiple separated programs with one API key
Some businesses need to run multiple, separate programs through the GiveCard infrastructure -> this means different funding accounts, completely separated reporting, and distinct user permissions. Effectively, a business needs multiple GiveCard accounts for each program -> we call this a SuperBusiness. To upgrade to a SuperBusiness, reach out to your GiveCard integration team.
SuperBusinesses only ever need one API key to manage all of their many programs, but also be able to give 'scoped' api keys for specific programs for things like app integrations (i.e. if you want to use a Salesforce integration with one of your programs, the API key you use for that integration should be scoped to just that program, not everything).
There are 3 types of BusinessScopes:
Normal: This is an average business, an API Key pointed to this can do everything: issue cards, generate reports, etc. This type of business only has one funding account.
Super: This is a SuperBusiness. A SuperBusiness is an organizational unit that has many programs beneath it. A SuperBusiness itself has no cards, no funding accounts and no data to report. But an API Key pointed to a SuperBusiness is able to access all programs created by it, and therefore can issue cards, generate reports, load cards, etc, as long as a programId is supplied where needed to direct the infrastructure what program to issue the cards for, or which funding account to pull funds from for loads.
Program: This is a program, an organizational sub-unit of a SuperBusiness. If you have a program, it means there is also an associated SuperBusiness. Programs have a singular funding account, and can issue cards, generate reports, etc. An API Key pointed at a program can do anything for that program, but it cannot perform operations related to another program within the SuperBusiness, only a SuperBusiness Api Key can do that. Program API keys are great to use for app integrations, or for external developers scoped only to work on one specific program.
Run your API Key against the TestAuthV1 endpoint, and pay attention to the Scope response. If it returns normal then feel free to disregard this guide, but if it returns super or program, then this is relevant.
To Implement a SuperBusiness API Key
Use TestAuthV1 to confirm that you've got a super key here.
First call GetBusinessProgramsV1, this will return an array of your programs with their id and name. On your backend, you should keep a record of the relevant programIds for each of your programs, as this is required for interacting with them.
Next lets try LoadCardsV1: usually, we can just pass in the cardIds and the amount and this would work, and this is still the case for normal and program scoped API keys, but for a super key we must pass in a programId too, so that we know what funding account to draw from. Without passing in a programId, this endpoint will return a 400 error.
Say you've got two programs: Denver and Boston - on your backend you've saved the relevant programIds for each of them. When it comes to loading cards from the Boston program, you need to pull that programId from your end and use that as an input to the LoadCards endpoint.
Comb through all of the GiveCard endpoints you've integrated with and check to see if they take programId as an input, all of these will need to be updated if you aren't already passing in programIds, else they will fail. Some commonly used endpoints that require ProgramIds for SuperBusinesses are: GetCardsV1, LoadCardsV1, OrderAndShipCardsV1, GetBusinessLoadHistoryV1.