Card On File

You are able to store a donor’s credit card allowing for simplified donation actions later on. A few points about our card on file implementation:

Card On File Integration Flow

  • 3rd party website uses /cardonfile REST resource to store a card. A cardOnFileId is returned.
  • Later, 3rd party website uses the cardOnFileId in order to create a donation (instead of all of the card details).

Storing A Card On File: HTTP POST to /cardonfile

Registers a donor’s card for storage under your API keypair. We return an ID number, or “token”, which can be used later to create a donation. Get Query String Input Params:

Note: billToEmail must not contain the special character ‘+’. While it is possible to create a card on file token with email addresses formatted in this way, subsequent attempts to charge those tokens will fail.

Get Response Example: <?xml version=”1.0″ encoding=”UTF-8″?> <firstGivingDonationApi> <firstGivingResponse acknowledgement=”Success”> <cardOnFileId>3c5e29a0-b96e-11e0-a4dd-0800200c9a66</cardOnFileId> </firstGivingResponse> </firstGivingDonationApi>

Storing a Card On File: Hosted Payment Page

You can also use our hosted payment page to exchange card information for a token while limiting PCI scope. Simply embed the iframe in your application and we’ll post back a token, which you can use in lieu of the card details to charge the donor at a later day.

To access the page, use an iFrame with the URL in the following format: {PAGE_ENVIRONMENT_URL}/secure/tokenrequest?{URL_PARAMETERS}

This will post back a token, which you can then process a donation against via the API method here.

Here’s an example of a functional staging URL:

Required URL Parameters

Optional URL Parameters
There are also these additional optional URL parameters which when provided will prepopulate those corresponding form fields:

Additional parameters which allow you to control the look and feel of the iFrame:

Sandbox AVS

When performing integration testing with the Sandbox Donations API environment, the specific CVV of 150 should be used along with the normal test card data as detailed in the primary Donations API documentation in order to guarantee a successful response. Submitting other CVV values may result in an AVS failure response message.

Processing New Donation with Card On File: HTTP POST to /donation/creditcard

In order to trigger a charge against a card which is stored on file, you use the normal /donation/creditcard resource documented on the main Donations API page. However, the difference is that you should omit all of the following fields:

and include:
  • cardOnFileId – The card on file ID number you would like to execute the donation with.
FrontStream Holdings LLC is a registered ISO of Elavon, Inc. Georgia, Chase Paymentech Solutions, LLC, First National Bank of Omaha, Omaha, NE, BMO Harris Bank, N.A., Chicago, IL, Deutsche Bank, USA, New York, NY and Wells Fargo Bank, N.A., Walnut Creek, CA.