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.

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.

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
  • destination_ein - The tax ID of the charity receiving this donation (optional)
  • donation_after_fees - An integer representing the amount of the donation after fees, in cents
  • source (required) - The funding source for this donation; either 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. 

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 Object with an attached source must be provided.

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.

**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 a customer id is passed to a new Donation object
  • default_source - The default source that will be charged when 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

Requirements

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


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.

**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 


To update a Customer Object: 

PUT: https://api.pandapay.io/v1/customers/:customer_id

**Example Request**

curl -X PUT -d '{
"email": "newemail@example.com"
}' 'https://api.pandapay.io/v1/customers/728'
**Example Response**

{
  "id": "cus_ls41pOHb8g_E7r7isjwa7w",
  "object": "customer",
  "email": "newemail@example.com",
  "livemode": false,
  "cards":[]
}


To delete a Customer Object:

DELETE: https://api.pandapay.io/v1/customers/:customer_id

**Example Request**

curl -X DELETE 'https://api.pandapay.io/v1/customers/802'
**Example Response**

{
  "id": "cus_Areyuq-zoZt2HavO1jO7vg",
  "object": "customer",
  "email": "customer+38@email.com",
  "livemode": false,
  "cards": []
}

        _________________________________________________________

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. 

A Grant Object is created automatically if a destination_ein is passed with a Donation Object. A source_transaction is not required, but if one is passed, the Grant Object 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.


To create a Grant Object with a source transaction: 

POST: https://api.pandapay.io/v1/donations/:donation_id/grants

**Example Request**

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

Note that the source_transaction is part of the endpoint URL.

**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
}


To create a Grant Object without a source transaction
(i.e. from your Unallocated Donation Amount): 

POST: https://api.pandapay.io/v1/grants

**Example Request**

curl -X POST -d '{
  "amount" : "100",
  "destination" : "24"
}' 'https://api.pandapay.io/v1/grants'
**Example Response**

{
  id: "gr_9bIDXurB8PCrIqIYvlwiPQ\",
  object: "grant",
  created: "1499455100",
  livemode: false,
  amount: "100",
  status: "pending",
  currency: "usd",
  type: "npo",
  destination: "00-00000024",
  restriction: null
}


Did this answer your question?