Givinga Payments API (1.0)

Download OpenAPI specification:Download

Payment Processing

For tax purposes, processing of donations is handled by the Givinga Foundation, our 501(c)(3) sponsoring organization, and partner. This ensures that all funds processed are considered a charitable donation as described by the IRS. For this reason, a separate API with a different set of endpoints are used for processing transactions versus other activities within the Givinga Platform.

Base URL's

Development:

https://qa-payments.givingafoundation.org/api/

Production:

https://payments.givingafoundation.org/api/

Authenticate

Retrieves a jwt token for authenticating calls to the payments API and a public key for instantiating a Stripe session.

path Parameters
accountId
required
number <double>

a unique string for the identification used to lookup the secret key. Account Ids look like acct_1FN1dIBtcm2gJE5F

Request Body schema: application/json
hmac
string

SHA256 HMAC hash generated using your Secret Key and an epoch timestamp that is less than 1 minute old.

hashEpoch
number

An epoch timestamp that is less than one minute old.

Responses

Request samples

Content type
application/json
{
  • "hmac": "4692cfbb32ebcbe307bfcb26c0a3f2a4f90cb4833d99ea6c87a1b40e9ea3e848",
  • "hashEpoch": 1622657001
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJ0bmVySWQiOjIsImFjY291bnRJZCI6ImFjY3RfMUgzNGJSRWZMdzc5WFFZMyIsInJvbGVJZCI6MSwibmFtZSI6IkdpdmluZ2EgVGVzdCBQYXJ0bmVyIiwiaWRlbXBvdGVuY3lLZXkiOiI2OTI3MGE4Ny1iNmEyLTRjZDAtYmM4Ny0wNTczY2U4MjkyN2QiLCJleHAiOjE2MzQyMjQ3NjcuNDM0LCJpYXQiOjE2MzQyMTY5Njd9.z5kJ4PUVq-_CqpzZfHqRcPcW0iezHumdtU-O__EggcI",
  • "publicKey": "pk_live_UKrGXd5PlOllJHvaG2ggkxWe"
}

Retrieve a list of customers

Returns all customers linked to the partner account.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Customer in Stripe

Create a customer

Request Body schema: application/json
firstName
string

Customer first name

lastName
string

Customer last name

email
string

Customer email

externalId
string

An identifier used to link the customer to your own system.

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "[email protected]",
  • "externalId": "2jk4h2n3un4"
}

Response samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe",
  • "customerId": "cus_12345",
  • "partnerId": 1,
  • "email": "[email protected]",
  • "externalId": "2jk4h2n3un4"
}

Retrieve a Customer by ID

Returns the customer associated with a given identifier.

path Parameters
customerId
required
string

the Stripe customer ID of the Givinga user.

Responses

Response samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe",
  • "customerId": "cus_12345",
  • "partnerId": 1,
  • "email": "[email protected]",
  • "externalId": "2jk4h2n3un4"
}

Update a Customer

Update the Stripe Customer associated with a given Stripe customer ID.

path Parameters
customerId
required
string

Stripe customer ID attached to the customer object in Givinga.

Request Body schema: application/json
firstName
string

Customer first name

lastName
string

Customer last name

email
string

The customer email

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe",
  • "customerId": "cus_12345",
  • "partnerId": 1,
  • "email": "[email protected]",
  • "externalId": "2jk4h2n3un4"
}

Retrieve a Customer by External ID

Returns the customer associated with a given external identifier.

path Parameters
customerExternalId
required
string

the external ID of the Givinga user.

Responses

Response samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe",
  • "customerId": "cus_12345",
  • "partnerId": 1,
  • "email": "[email protected]",
  • "externalId": "2jk4h2n3un4"
}

Donate or fund an account via Charges supports ACH

Donate from or fund an account via Charges supports ACH

path Parameters
customerId
required
string

The Stripe customer ID attached to the customer object in Givinga. If not included in the path, a guest checkout session will be generated.

Request Body schema: application/json
amount
required
number

The dollar amount (in cents) of the donation.

paymentMethodId
required
string

The payment method id associated with the Stripe customer making the donation.

tip
number

An optional value (in cents) added as a tip atop the amount total.

charityId
number

The Givinga-assigned ID of the charity the donation should be directed to. Only present if donating directly to a charity.

subaccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to employeeAccountNumber. Only present if funding an individual users balance.

givingaAccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to donorAccountNumber. Only present if donating directly to a charity.

masterAccountUsername
string

The Givinga API username included in your basic auth credentials when accessing the Givinga API. This is used to look up your master account information. Only present when funding the corporate account balance.

carbonOffset
string

Boolean flag used when purchasing carbon offset credits. Only present when purchasing carbon offset credits.

campaignId
string

The number of the Givinga campaing the donation is being made too. Only present when donating to a campaign.

currency
string

The currency the payment is being made in.

matchRequested
boolean

True, if the donor is requesting a match from their organization.

customerCoveringFee
boolean

True, if the donor is covering the fees associated with processing fee.

customerCoveringPartnerCut
boolean

True, if the donor is covering the partners cut of the donation.

description
string

An optional string that will appear on the payment object in Stripe as the payment description.

statementDescriptor
string

An optional string that will appear as the statement description on the customers bank or credit card statement. Please note, statement descriptions have a 22 character limit.

notes
string

An optional note from the donor to the charity.

activityId
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId2
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId3
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

anonymity
string

One of Full Transparency, Partial Transparency, or Anonymous. If not provided, defaults to Anonymous.

Array of objects (KeyVal)

an array of {key:: String, value:: String} pairs that get added as metadata to the Stripe webhook object. Note, the value field has a 500 character limit.

Responses

Request samples

Content type
application/json
{
  • "amount": 2000,
  • "paymentMethodId": "ba_xx123xx",
  • "tip": 1000,
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "carbonOffset": true,
  • "campaignId": true,
  • "currency": "USD",
  • "matchRequested": false,
  • "customerCoveringFee": false,
  • "customerCoveringPartnerCut": false,
  • "description": "Testing!",
  • "statementDescriptor": "Givinga Donation",
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string",
  • "metadata": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "Success",
  • "chargeId": "ch_xxx"
}

List Customer Payments

List Customer Payments from Stripe

path Parameters
customerId
required
string

The Stripe customer ID attached to the customer object in Givinga.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Donate from or fund an account via Stripe Checkout

Donate from or fund an account via Stripe Checkout

path Parameters
customerId
required
string

The Stripe customer ID attached to the customer object in Givinga. If not included in the path, a guest checkout session will be generated.

Request Body schema: application/json
amount
number

The dollar amount (in cents) of the donation. Required if an item is not provided. Quantity and ProductName required when provided

tip
number

An optional value (in cents) added as a tip atop the amount total.

currency
required
string

The currency the payment is being made in.

cancelURL
required
string

The url to return to when canceled

successURL
required
string

The url to return to on success

paymentMethodId
string

The payment method id associated with the Stripe customer making the donation.

charityId
number

The Givinga-assigned ID of the charity the donation should be directed to. Only present if donating directly to a charity.

subaccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to employeeAccountNumber. Only present if funding an individual users balance.

givingaAccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to donorAccountNumber. Only present if donating directly to a charity.

masterAccountUsername
string

The Givinga API username included in your basic auth credentials when accessing the Givinga API. This is used to look up your master account information. Only present when funding the corporate account balance.

carbonOffset
string

Boolean flag used when purchasing carbon offset credits. Only present when purchasing carbon offset credits.

campaignId
string

The number of the Givinga campaing the donation is being made too. Only present when donating to a campaign.

matchRequested
boolean

True, if the donor is requesting a match from their organization.

customerCoveringFee
boolean

True, if the donor is covering the fees associated with processing fee.

customerCoveringPartnerCut
boolean

True, if the donor is covering the partners cut of the donation.

description
string

An optional string that will appear on the payment object in Stripe as the payment description.

statementDescriptor
string

An optional string that will appear as the statement description on the customers bank or credit card statement. Please note, statement descriptions have a 22 character limit.

notes
string

An optional note from the donor to the charity.

activityId
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId2
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId3
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

anonymity
string

One of Full Transparency, Partial Transparency, or Anonymous. If not provided, defaults to Anonymous.

Array of objects (KeyVal)

an array of {key:: String, value:: String} pairs that get added as metadata to the Stripe webhook object. Note, the value field has a 500 character limit.

mode
string

One of payment or subscription. Flag to determine whether this will create a one time payment or a recurring subscriptions. Note subscriptions created this way take a bit of time to propagate back to the Givinga servers

Array of objects (SubscriptionItem)

We can provide a list of existing prices or custom prices as seperate line items on the checkout invoice, for subscription mode the prices have to have a recurring interval, intervals must be the same

tipInterval
string

Provided when we want a recurring tip. Must be one of 'day', 'week', 'month', 'year', it must be the same interval as all of items. If not provided for subscription mode it a one time tip will be executed at the beginning of the subscription

productName
string

Provided for payment mode. Shows up as the description in the checkout invoice

quantity
number

Number of units we want to purchase for payment mode

Responses

Request samples

Content type
application/json
{
  • "amount": 2000,
  • "tip": 1000,
  • "currency": "USD",
  • "cancelURL": "string",
  • "successURL": "string",
  • "paymentMethodId": "ba_xx123xx",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "carbonOffset": true,
  • "campaignId": true,
  • "matchRequested": false,
  • "customerCoveringFee": false,
  • "customerCoveringPartnerCut": false,
  • "description": "Testing!",
  • "statementDescriptor": "Givinga Donation",
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string",
  • "metadata": [
    ],
  • "mode": "string",
  • "items": [
    ],
  • "tipInterval": "string",
  • "productName": "string",
  • "quantity": 0
}

Response samples

Content type
application/json
{
  • "id": "cs_test_ItzzAymToyCGuqYqkhHoMqKfCisFKvEm7SPLiVYaOEgLdqArwg4GOB1M"
}

Donate or fund an account via Payment Intents

Donate from or fund an account via Payment Intents

path Parameters
customerId
required
string

The Stripe customer ID attached to the customer object in Givinga. If not included in the path, a guest checkout session will be generated.

Request Body schema: application/json
amount
required
number

The dollar amount (in cents) of the donation.

tip
number

An optional value (in cents) added as a tip atop the amount total.

charityId
number

The Givinga-assigned ID of the charity the donation should be directed to. Only present if donating directly to a charity.

subaccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to employeeAccountNumber. Only present if funding an individual users balance.

givingaAccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to donorAccountNumber. Only present if donating directly to a charity.

masterAccountUsername
string

The Givinga API username included in your basic auth credentials when accessing the Givinga API. This is used to look up your master account information. Only present when funding the corporate account balance.

carbonOffset
string

Boolean flag used when purchasing carbon offset credits. Only present when purchasing carbon offset credits.

campaignId
string

The number of the Givinga campaing the donation is being made too. Only present when donating to a campaign.

currency
string

The currency the payment is being made in.

paymentMethodId
string

The payment method id associated with the Stripe customer making the donation.

matchRequested
boolean

True, if the donor is requesting a match from their organization.

customerCoveringFee
boolean

True, if the donor is covering the fees associated with processing fee.

customerCoveringPartnerCut
boolean

True, if the donor is covering the partners cut of the donation.

description
string

An optional string that will appear on the payment object in Stripe as the payment description.

statementDescriptor
string

An optional string that will appear as the statement description on the customers bank or credit card statement. Please note, statement descriptions have a 22 character limit.

notes
string

An optional note from the donor to the charity.

activityId
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId2
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId3
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

anonymity
string

One of Full Transparency, Partial Transparency, or Anonymous. If not provided, defaults to Anonymous.

Array of objects (KeyVal)

an array of {key:: String, value:: String} pairs that get added as metadata to the Stripe webhook object. Note, the value field has a 500 character limit.

persistPaymentMethod
boolean

Boolean flag provided when the the paymentMethodId is not provided. This signals that the payment method created in the Stripe intent flow will be persisted to the customer for future use.

Responses

Request samples

Content type
application/json
{
  • "amount": 2000,
  • "tip": 1000,
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "carbonOffset": true,
  • "campaignId": true,
  • "currency": "USD",
  • "paymentMethodId": "pm_x123x",
  • "matchRequested": false,
  • "customerCoveringFee": false,
  • "customerCoveringPartnerCut": false,
  • "description": "Testing!",
  • "statementDescriptor": "Givinga Donation",
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string",
  • "metadata": [
    ],
  • "persistPaymentMethod": false
}

Response samples

Content type
application/json
{
  • "clientSecret": "pi_1Iy1DzL2ZCJnwBDaXSSHhos9_secret_6zTShsHW9pgQ5GgPHM0Lfy7pk"
}

Store Customer Payment information

Call the create setup intent method. This is used to set up payment methods on a customer. Note payment methods can be set up through the payment intents endpoints.

path Parameters
customerId
required
string

The Stripe customer ID attached to the customer object in Givinga. If not included in the path, a guest checkout session will be generated.

Responses

Response samples

Content type
application/json
"seti_xxx"

Retrieve Payment methods associated with a Stripe Customer

Retrieves the saved payment methods for a particular customer based on their Stripe Customer Id.

path Parameters
customerId
required
string

The Stripe customer ID attached to the customer object in Givinga.

Responses

Get existing products for subscribing a user to a donation or funding event.

Subscriptions are made up of three parts: price, product and interval. A subscription can have multiple prices associated with different intervals. Subscription intervals include day, week month and year.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a product for subscribing a user to a donation or funding event.

Subscriptions are made up of three parts: price, product and interval. A subscription can have multiple prices associated with different intervals. Subscription intervals include day, week month and year. To create a subscription we must first create a product.

Request Body schema: application/json
name
string

The name of the product

Responses

Request samples

Content type
application/json
{
  • "name": "My first product!"
}

Response samples

Content type
application/json
{
  • "productId": "prod_Hk...",
  • "name": "My first product!"
}

Get a list of existing prices associated with the product

Once we have created our product we need to define a price. We can define multiple prices and intervals for the same product. Note: if you are configuring a product for one-time purchase do not provide an interval in the request payload.

path Parameters
productId
required
string

The Stripe ID of the product we are assigning the price and interval to.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a price interval and assign it to a product

Once we have created our product we need to define a price. We can define multiple prices and intervals for the same product. Note: if you are configuring a product for one-time purchase do not provide an interval in the request payload.

path Parameters
productId
required
string

The Stripe ID of the product we are assigning the price and interval to.

Request Body schema: application/json
interval
string

The interval by which the customer should be charged (do not provide interval for one-time product purchases). Options include day, week, and month.

unitAmount
number

The price (in cents) associated with the product.

currency
string

The currency the customer should be charged in.

Responses

Request samples

Content type
application/json
{
  • "interval": "month",
  • "unitAmount": 5000,
  • "currency": "USD"
}

Response samples

Content type
application/json
{
  • "priceId": "price_123...",
  • "isCustomAmount": true,
  • "currency": "USD",
  • "recurringInterval": "day",
  • "productId": "prod_Hk...",
  • "type": "one_time"
}

View a partners subscriptions

View all of the subscriptions associated with a given partner.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a subscription by stripe subscription id

Get a subscriptions by stripe subscription id.

path Parameters
subscriptionId
required
string

The Stripe subscription ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "subscriptionId": "sub_123",
  • "startDate": "2021-10-20T16:09:09.880Z",
  • "endDate": "2021-10-20T16:09:09.880Z",
  • "customerId": "cus_123",
  • "paused": false,
  • "resumes": "2021-10-20T16:09:09.880Z",
  • "tip": 100,
  • "tipInterval": "USD",
  • "tipCurrency": "USD",
  • "oneTimeTip": 100,
  • "oneTimeTipCurrency": "USD",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "subscriptionItems": [
    ],
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string"
}

Subscribe a user to a product

Once we have products with associated prices / subscription intervals we can now subscribe a user to our subscriptions.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

Request Body schema: application/json
tip
number

An optional value (in cents) added as a tip atop the amount total.

tipCurrency
string

The currency the tip is being made in.

paymentMethodId
string

The payment method id associated with the Stripe customer making the donation.

charityId
number

The Givinga-assigned ID of the charity the donation should be directed to. Only present if donating directly to a charity.

subaccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to employeeAccountNumber. Only present if funding an individual users balance.

givingaAccountNumber
string

The number of the Givinga account the donation should be attributed to. Maps to donorAccountNumber. Only present if donating directly to a charity.

masterAccountUsername
string

The Givinga API username included in your basic auth credentials when accessing the Givinga API. This is used to look up your master account information. Only present when funding the corporate account balance.

carbonOffset
string

Boolean flag used when purchasing carbon offset credits. Only present when purchasing carbon offset credits.

campaignId
string

The number of the Givinga campaing the donation is being made too. Only present when donating to a campaign.

matchRequested
boolean

True, if the donor is requesting a match from their organization.

notes
string

An optional note from the donor to the charity.

activityId
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId2
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId3
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

anonymity
string

One of Full Transparency, Partial Transparency, or Anonymous. If not provided, defaults to Anonymous.

description
string

An optional string that will appear on the payment object in Stripe as the payment description.

Array of objects (KeyVal)

an array of {key:: String, value:: String} pairs that get added as metadata to the Stripe webhook object. Note, the value field has a 500 character limit.

Array of objects (SubscriptionItem)

We can provide a list of existing prices or custom prices as seperate line items on the checkout invoice, for subscription mode the prices have to have a recurring interval, intervals must be the same

tipInterval
string

Provided when we want a recurring tip. Must be one of 'day', 'week', 'month', 'year', it must be the same interval as all of items. If not provided for subscription mode it a one time tip will be executed at the beginning of the subscription

Responses

Request samples

Content type
application/json
{
  • "tip": 1000,
  • "tipCurrency": "USD",
  • "paymentMethodId": "ba_xx123xx",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "carbonOffset": true,
  • "campaignId": true,
  • "matchRequested": false,
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string",
  • "description": "Testing!",
  • "metadata": [
    ],
  • "items": [
    ],
  • "tipInterval": "string"
}

Response samples

Content type
application/json
{
  • "subscriptionId": "sub_123",
  • "startDate": "2021-10-20T16:09:09.880Z",
  • "endDate": "2021-10-20T16:09:09.880Z",
  • "customerId": "cus_123",
  • "paused": false,
  • "resumes": "2021-10-20T16:09:09.880Z",
  • "tip": 100,
  • "tipInterval": "USD",
  • "tipCurrency": "USD",
  • "oneTimeTip": 100,
  • "oneTimeTipCurrency": "USD",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "subscriptionItems": [
    ],
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string"
}

View a customers subscriptions

View all of the subscriptions associated with a given Stripe Customer.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

Responses

Response samples

Content type
application/json
{
  • "subscriptionId": "sub_123",
  • "startDate": "2021-10-20T16:09:09.880Z",
  • "endDate": "2021-10-20T16:09:09.880Z",
  • "customerId": "cus_123",
  • "paused": false,
  • "resumes": "2021-10-20T16:09:09.880Z",
  • "tip": 100,
  • "tipInterval": "USD",
  • "tipCurrency": "USD",
  • "oneTimeTip": 100,
  • "oneTimeTipCurrency": "USD",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "subscriptionItems": [
    ],
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string"
}

Manage subscriptions

We provide one catch-all endpoint for all subscription management needs. Through this endpoint you can pause, cancel or restart a subscription, add additional items, change the interval or associated metadata and update the customers payment method that the subscription is tied to.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

subscriptionId
required
string

The Stripe subscription.

Request Body schema: application/json
cancelAtPeriodEnd
boolean

If true, cancels the subscription at period end.

billingCycleAnchor
string

now or unchanged changes the execute date of the subscription

prorationBehaviour
string

Used in conjecture with billingCycleAnchor or price changes one of 'none' charges no prorate amount, 'always_invoice' charges full amount, or 'create_proration' which prorates based on the amount of time passed.

cancelAt
number

Unix timestamp in milliseconds marking when the subscription should be cancelled.

pause
boolean

Pauses the subscription when true and voids invoices until subscription starts. Set to false to unpause.

resumesAt
number

Unix timestamp in milliseconds marking when to resume the subscription.

Array of objects (SubscriptionItem)

Product(s) we are subscribing the user to

tip
number

An optional value (in cents) added as a tip atop the amount total.

tipInterval
string

The interval the recurring tip executes on, one of 'day', 'week', 'month', 'year'

tipCurrency
string

The currency the tip is being made in.

charityId
number

The Givinga-assigned ID of the charity the donation should be directed to. Only present if donating to a charity.

subaccountNumber
string

The number of the Givinga account the donation should be attributed to. Should be the employeeAccountNumber if funding an individual users balance.

givingaAccountNumber
string

The number of the Givinga account the donation should be attributed to. Should be the donorAccountNumber when making a donation directly to a charity.

masterAccountUsername
string

The Givinga API username included in your basic auth credentials when accessing the Givinga API. This is used to look up your master account information. Should only be provided when funding the corporate account balance.

carbonOffset
string

Boolean flag used when purchasing carbon offset credits. Only present when purchasing carbon offset credits.

campaignId
string

The number of the Givinga campaing the donation is being made too. Only present when donating to a campaign.

paymentMethodId
string

The payment method id associated with the Stripe customer making the donation.

description
string

An optional string that will appear on the payment object in Stripe as the payment description.

notes
string

An optional note from the donor to the charity.

activityId
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId2
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId3
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

anonymity
string

One of Full Transparency, Partial Transparency, or Anonymous. If not provided, defaults to Anonymous.

Array of objects (SubscriptionItem)

an array of {key:: String, value:: String} pairs that get added as metadata to the Stripe webhook object. Note, the value field has a 500 character limit.

Responses

Request samples

Content type
application/json
{
  • "cancelAtPeriodEnd": true,
  • "billingCycleAnchor": "string",
  • "prorationBehaviour": "string",
  • "cancelAt": 0,
  • "pause": true,
  • "resumesAt": 0,
  • "items": [
    ],
  • "tip": 1000,
  • "tipInterval": "USD",
  • "tipCurrency": "USD",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "carbonOffset": true,
  • "campaignId": true,
  • "paymentMethodId": "pm_x123x",
  • "description": "Testing!",
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string",
  • "metadata": [
    ]
}

Response samples

Content type
application/json
{
  • "subscriptionId": "sub_123",
  • "startDate": "2021-10-20T16:09:09.880Z",
  • "endDate": "2021-10-20T16:09:09.880Z",
  • "customerId": "cus_123",
  • "paused": false,
  • "resumes": "2021-10-20T16:09:09.880Z",
  • "tip": 100,
  • "tipInterval": "USD",
  • "tipCurrency": "USD",
  • "oneTimeTip": 100,
  • "oneTimeTipCurrency": "USD",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "subscriptionItems": [
    ],
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string"
}

Cancel Subscription

Immediately cancel a subscription .

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

subscriptionId
required
string

The Stripe subscription.

Responses

Response samples

Content type
application/json
{
  • "subscriptionId": "sub_123",
  • "startDate": "2021-10-20T16:09:09.880Z",
  • "endDate": "2021-10-20T16:09:09.880Z",
  • "customerId": "cus_123",
  • "paused": false,
  • "resumes": "2021-10-20T16:09:09.880Z",
  • "tip": 100,
  • "tipInterval": "USD",
  • "tipCurrency": "USD",
  • "oneTimeTip": 100,
  • "oneTimeTipCurrency": "USD",
  • "charityId": 123456,
  • "subaccountNumber": "123456",
  • "givingaAccountNumber": "11420157",
  • "masterAccountUsername": "myusername",
  • "subscriptionItems": [
    ],
  • "notes": "string",
  • "activityId": "string",
  • "activityId2": "string",
  • "activityId3": "string",
  • "anonymity": "string"
}

Retrieve a Plaid Link Token

First, fetch a linkToken for authorizing the Plaid Link flow. Then, use the Integrate with Plaid Link section in the Stripe documentation to add the necessary Javascript to support the Plaid verification flow.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

Responses

Response samples

Content type
application/json
{
  • "environment": "string",
  • "clientName": "string",
  • "linkToken": "string"
}

Connect a Stripe customer to an ACH payment method from Plaid

Post the public_token and metadata.accounts[0].id from the onSuccess result in the Plaid Link.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

Request Body schema: application/json
values
string

the public_token from the onSuccess result in the Plaid Link flow.

accountId
string

the metadata.accounts[0].id from the onSuccess result in the Plaid Link flow.

Responses

Request samples

Content type
application/json
{
  • "values": "string",
  • "accountId": "string"
}

Connect a Stripe customer to an ACH payment method from Stripe

Post the stripe token retrieved from stripe.js library when generating an ACH account, will need to be verified by the verify endpoint.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

Request Body schema: application/json
token
string

the public_token retrieved from the Stripe.js library.

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Verify an ACH payment method from Stripe

Post the the micro deposits to verify the bank account.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

paymentMethodId
required
string

The id of the payment method to be verified.

Request Body schema: application/json
values
Array of numbers

a list of the two micro deposits.

Responses

Request samples

Content type
application/json
{
  • "values": [
    ]
}

Set the payment method to the default payment method on the customer.

Set the payment method to the default payment method on the customer.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

paymentMethodId
required
string

The id of the payment method to be verified.

Responses

Delete the payment method.

Delete the payment method.

path Parameters
customerId
required
string

The Stripe customer ID of the Givinga user.

paymentMethodId
required
string

The id of the payment method to be verified.

Responses

Retrieve a list of Stripe Connected Accounts

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve details on a connected account

path Parameters
accountId
required
string

The Stripe Connect account Id of the processor account

Responses

Response samples

Content type
application/json
{
  • "paymentProcessorAccountId": "acct_1H...",
  • "percentageCut": 20,
  • "description": "My test account"
}