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

Payload

Content type

application/json

{"hmac": "4692cfbb32ebcbe307bfcb26c0a3f2a4f90cb4833d99ea6c87a1b40e9ea3e848",
"hashEpoch": 1622657001
}

Response samples

200

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

200

Content type

application/json

[{"firstName": "John",
"lastName": "Doe",
"customerId": "cus_12345",
"partnerId": 1,
"email": "[email protected]",
"externalId": "2jk4h2n3un4"
}
]

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

Payload

Content type

application/json

{"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"externalId": "2jk4h2n3un4"
}

Response samples

200

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

200

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

Payload

Content type

application/json

{"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
}

Response samples

200

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

200

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

Payload

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": [{"key": "string",
"value": "string"
}
]
}

Response samples

200

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

200

Content type

application/json

[{"paymentId": "ch_123",
"paymentSourceId": "pm_123",
"accountId": "acct_123",
"status": "Success",
"givingaFeeCut": 10,
"partnerCut": 500,
"partnerFeeCut": 10,
"tip": 100,
"createDate": "2021-10-20T16:09:09.879Z",
"amount": 1000,
"customerId": "cus_xxx"
}
]

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

Payload

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": [{"key": "string",
"value": "string"
}
],
"mode": "string",
"items": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD"
}
],
"tipInterval": "string",
"productName": "string",
"quantity": 0
}

Response samples

200

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

Payload

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": [{"key": "string",
"value": "string"
}
],
"persistPaymentMethod": false
}

Response samples

200

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

201

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

200

Content type

application/json

[{"productId": "prod_Hk...",
"name": "My first product!"
}
]

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

Payload

Content type

application/json

{"name": "My first product!"
}

Response samples

200

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

200

Content type

application/json

[{"priceId": "price_123...",
"isCustomAmount": true,
"currency": "USD",
"recurringInterval": "day",
"productId": "prod_Hk...",
"type": "one_time"
}
]

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

Payload

Content type

application/json

{"interval": "month",
"unitAmount": 5000,
"currency": "USD"
}

Response samples

200

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

200

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": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD",
"subscriptionId": "sub_123"
}
],
"notes": "string",
"activityId": "string",
"activityId2": "string",
"activityId3": "string",
"anonymity": "string"
}
]

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

200

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": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD",
"subscriptionId": "sub_123"
}
],
"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

Payload

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": [{"key": "string",
"value": "string"
}
],
"items": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD"
}
],
"tipInterval": "string"
}

Response samples

200

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": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD",
"subscriptionId": "sub_123"
}
],
"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

200

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": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD",
"subscriptionId": "sub_123"
}
],
"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

Payload

Content type

application/json

{"cancelAtPeriodEnd": true,
"billingCycleAnchor": "string",
"prorationBehaviour": "string",
"cancelAt": 0,
"pause": true,
"resumesAt": 0,
"items": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD"
}
],
"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": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD"
}
]
}

Response samples

200

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": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD",
"subscriptionId": "sub_123"
}
],
"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

200

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": [{"quantity": 1,
"priceId": "string",
"customPriceAmount": 1000,
"customPriceInterval": "month",
"customPriceProductId": "string",
"customPriceCurrency": "USD",
"subscriptionId": "sub_123"
}
],
"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

200

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

Payload

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

Payload

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

Payload

Content type

application/json

{"values": [0
]
}

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.

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

200

Content type

application/json

[{"paymentProcessorAccountId": "acct_1H...",
"percentageCut": 20,
"description": "My test account"
}
]

Retrieve details on a connected account

path Parameters

accountId

required

string

The Stripe Connect account Id of the processor account

Responses

Response samples

200

Content type

application/json

{"paymentProcessorAccountId": "acct_1H...",
"percentageCut": 20,
"description": "My test account"
}