The PandaPay API allows developers to quickly and easily integrate charitable giving experiences into any digital platform, making donations to every public charity a breeze. Its chief functionality relies on Donation objects, Customer objects, and Grant objects.

Donation Objects

A Donation Object possesses the following attributes:

  • id
    Unique id, prefixed with ch_
  • object
    Set to "donation"
  • created
    Timestamp when the object was created
  • livemode
    True if a live key was used, False is a test key was used
  • currency (required)
    Only “usd” is available at this time
  • charge_amount
    An integer representing the total amount charged to the credit card in cents
  • donation_after_fees
    An integer representing the amount of the donation after fees, in cents
  • source (required)
    The funding source for this donation in the form of a Panda.js card token or a Customer id with a valid payment source
  • grants
    A list of any Grant objects that were created with the funds from this donation
  • receipt_email (required)
    The email which should receive a donation receipt
  • restricted (default:null)
    Use this parameter to set the plain text name of a program or project at your destination_ein, to which you’d like to designate funds. More on restricting funds here.

To create a Donation object:
POST: https://api.pandapay.io/v1/donations

This creates a Donation object. If a destination_ein is provided, a Grant object is automatically created for the full amount. If one is not provided, the donated funds are added to the account's balance, and can be withdrawn by manually creating a Grant object.

Requirements

Donation objects require amount and currency attributes. A receipt_email is also required, but this can be copied from the Customer object if the provided source has an associated email address. For payment, either a source or a Customer with an attached source must be provided.

Notes on secret and publishable keys

Publishable API keys are used to identify your account with PandaPay, they are not secret. In other words, they can safely be published in places like your Panda.js JavaScript code, or in an Android or iPhone app. Publishable keys only have the power to create tokens in PandaJS.

Secret API keys should be kept confidential and only stored on your own servers. Your account's secret API key can perform any API request to PandaPay without restriction.


**Example Request**

curl https://api.pandapay.io/v1/donations \
       -u sk_test_abcdefghijklmnopqrstuvwx \     # Test API secret key
       -d amount=5000 \                          # Donation amount in cents
       -d currency="usd" \
       -d source=a1s2d3f4g5h6j7k8l9 \            # Panda.js card token
       -d receipt_email="test@pandapay.io" \     # Email to receive receipt
       -d platform_fee=100 \                     # Platform fee in cents
       -d destination_ein=12-3456789             # Recipient charity EIN
    

Note: If for some reason destination_ein fails to produce the intended behaviour, try using the parameter destination in your request.


**Example Response**

{
  "id": "ch_ks2QQXr9daUruVnz-n7k3Q",
  "object": "donation",
  "created": 1481066097,
  "livemode": false,
  "charge_amount": 5000,
  "platform_fee": 100,
  "donation_after_fees": 4675,
  "currency": "usd",
  "payment_token": "GfWZp9ALQ6bzWKaHdmCKlXzSghT",
  "customer": null,
  "grants": [],
  "receipt_email": "test@pandapay.io",
  "destination": "12-3456789",
  "restriction": null
}

Customer Objects

A Customer Object possesses the following attributes:

  • id
    Unique id, prefixed with cus_
  • object
    Set to "customer"
  • created
    Timestamp when the object was created
  • livemode
    True if a live key was used, False if a test key was used
  • email (required)
    The email address that will receive a receipt when only a customer id is passed to a new Donation object
  • default_source
    The default source that will be charged when only a customer id is passed to a new Donation object
  • sources
    A list of payment sources belonging to the customer, which can be either Bank or Card objects

To create a Customer object:
POST: https://api.pandapay.io/v1/customers

This creates a Customer object. To save a card, use a Panda.js token to create a Customer. Then the Customer can be passed to the Donation create endpoint as a source.

Requirements

Customer objects require an email attribute. Either a source or a Customer with an attached source must be provided.


**Example Request**

curl https://api.pandapay.io/v1/customers \
       -u sk_test_abcdefghijklmnopqrstuvwx \     # Test mode secret key
       -d email="test@pandapay.io" \             # Email address that receives receipt
       -d source=a1s2d3f4g5h6j7k8l9              # Panda.js token 

Grant Objects

A Grant Object possess the following attributes:
  • id
    Unique id, prefixed with gr_
  • object
    Set to "grant"
  • created
    Timestamp when the object was created
  • livemode
    True if a live key was used, False is a test key was used
  • amount (required)
    An integer representing the amount of the grant in cents
  • destination_ein (required)
    The tax ID of the charity receiving this grant
  • source_transaction
    The donation id from which these funds were drawn, if any
  • restricted (default:null)
    Use this parameter to set the plain text name of a program or project at your destination_ein, to which you’d like to designate funds. More on restricting funds here.

To create a Grant object:
POST: https://api.pandapay.io/v1/donations/:donation_id/grants

This creates a Grant. This object is created automatically if a destination_ein is passed to a Donation object. A source_transaction is not required, but if one is passed, the Grant will be added to the grants attribute on the original Donation object.

Requirements

A Grant object requires amount and destination_ein attributes. The amount must not exceed the unallocated donation amount in your Dashboard.


**Example Request**

curl https://api.pandapay.io/v1/grants/ch_abcdefghijklmnop \
       -u sk_test_abcdefghijklmnopqrstuvwx \     # Test API secret key
       -d amount=4725 \                          # Amount to grant
       -d destination_ein=12-3456789 \           # Recipient charity EIN
       

**Example Response**

{
  "id": "gr_hGxhS9V79wgsoQkGSNu_KA",
  "object": "grant",
  "created": 1465943248,
  "livemode": false,
  "amount": 500,
  "status": "pending",
  "currency": "usd",
  "type": "npo",
  "destination": "77-0714052",
  "restriction": null
}