Skip to main content

Stripe

buildfire.services.stripe#

This is a built in API that allows your control or widget to integrate with Stripe Checkout.

With stripe checkout you can start accepting payments for your products and create subscription for your services, with buildfire stripe service we made it super easy and simple for you to integrate with it. The new version of stripe checkout is a smart payment page hosted by Stripe that creates payments or subscriptions.

Enable checkout in your dashboard#

To begin using Checkout, log into the Stripe Dashboard and navigate to the Checkout settings. From here you can enable the client integration and customize the look and feel of your checkout page. please check stripe docs for more details.

important

Make sure to add buildfire.com and pluginserver.buildfire.com to the Domains section in Checkout settings page before you go LIVE.

Running Example#

https://github.com/BuildFire/simpleBuildFireJSExamples/tree/master/exampleStripeCheckout

Requirements#

Keys#

This service requires Buildfire API Public Key and Stripe Publishable Key

Widget#

Include stripe.js file in widget header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../scripts/buildfire/buildfire.min.js"></script>
<script src="../../../scripts/buildfire/services/stripe/stripe.js"></script>
</head>

Control#

Include stripe.js file in control header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../../scripts/buildfire/buildfire.min.js"></script>
<script src="../../../../scripts/buildfire/services/stripe/stripe.js"></script>
</head>

Methods#

charge()
#

buildfire.services.stripe.charge(options, callback)

Add dynamic product catalog and pricing and charge the customer. This is best used when you want to be able to charge customers without setting up Products in the Stripe dashboard. So it will be a dynamic amount that can be charged in realtime. If you'd like to have predefined items with fixed pricing per item then check out the Purchase method.

buildfire.services.stripe.charge(
{
items: [
{
name: "Test Stripe Product",
description: "This product has been generated from Buildfire SDK",
amount: "1000", //equals 10 USD
},
],
},
(err, result) => {
if (err) return console.error(err);
if (result) {
console.log("Payment Success");
}
}
);

options#

NameTypeRequiredDescriptionDefault
items[object]yesAn array of items
submitTypestringnoDescribes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. Supported values are "auto", "book", "donate", or "pay"
customerIdstringnoID of an existing customer, if one exists. If blank, Checkout will create a new customer object based on information provided during the session. The email stored on the customer will be used to prefill the email field on the Checkout page. If the customer changes their email on the Checkout page, the Customer object will be updated with the new email.
customerEmailstringnoIf provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once a session is complete, use the customer field.
captureMethodstringnoControls when the funds will be captured from the customer’s account. Possible enum values ["automatic", "manual"]"automatic"

options.items#

NameTypeRequiredDescriptionDefault
namestringyesThe name for the line item
descriptionstringyesThe description for the line item
amountnumberyesThe amount to be charged in cents
currencystringnoThree-letter ISO currency code, in lowercase. Must be a supported, for more details check stripe docs"usd"

callback(err, result)#

NameTypeDescription
errstringerror string, null when operation is successful
resultObjectThe result of the completed stripe checkout session

Example result#

{
"id": "checkout_session_id",
"object": "checkout.session",
"billing_address_collection": null,
"cancel_url": "http://app.buildfire/payments/cancel",
"success_url": "http://app.buildfire/payments/success"
"client_reference_id": "unqiue_key_provided_by_buildfire",
"customer": "customer_id",
"customer_email": "customer_email_if_provided",
"display_items": [
{
"amount": 1000,
"currency": "usd",
"custom": {
"description": null,
"images": null,
"name": "Test Product"
},
"quantity": 1,
"type": "custom"
}
],
"livemode": false,
"locale": null,
"payment_intent": "payment_intent_id",
"payment_method_types": [
"card"
],
"submit_type": null,
"subscription": null,
}

subscribe()
#

buildfire.services.stripe.subscribe(options, callback)

Subscribe to specific stripe plan defined in your stripe dashboard.

buildfire.services.stripe.subscribe(
{
items: [
{
planId: "YOUR_PLAN_ID",
},
],
trialPeriodDays: 2,
},
(err, result) => {
if (result) {
console.log("Success Subscription");
}
}
);

options#

NameTypeRequiredDescriptionDefault
items[object]yesAn array of items
trialPeriodDaysintegernoThe number of trial period days before the customer is charged for the first time.
customerIdstringyesID of an existing customer, if one exists. If blank, Checkout will create a new customer object based on information provided during the session. The email stored on the customer will be used to prefill the email field on the Checkout page. If the customer changes their email on the Checkout page, the Customer object will be updated with the new email.
customerEmailstringyesIf provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once a session is complete, use the customer field.

options.items#

NameTypeRequiredDescriptionDefault
planIdstringyesPlan ID for this item
quantitynumbernnoQuantity for this item1

callback(err, result)#

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectThe result of the completed stripe checkout session

Example response#

{
"id": "checkout_session_id",
"object": "checkout.session",
"billing_address_collection": null,
"cancel_url": "http://app.buildfire/payments/cancel",
"success_url": "http://app.buildfire/payments/success",
"client_reference_id": "app_id_123_123",
"customer": "customer_id",
"customer_email": "customer_email_if_provided",
"display_items": [
{
"amount": 1300,
"currency": "gbp",
"plan": {
"id": "plan_id",
"object": "plan",
"active": true,
"aggregate_usage": null,
"amount": 1300,
"billing_scheme": "per_unit",
"created": 1564005954,
"currency": "gbp",
"interval": "month",
"interval_count": 1,
"livemode": false,
"metadata": {},
"nickname": "Monthly",
"product": "product_id",
"tiers": null,
"tiers_mode": null,
"transform_usage": null,
"trial_period_days": null,
"usage_type": "licensed"
},
"quantity": 1,
"type": "plan"
}
],
"livemode": false,
"locale": null,
"payment_intent": null,
"payment_method_types": ["card"],
"submit_type": null,
"subscription": "subscription_id"
}

purchase()
#

buildfire.services.stripe.purchase(options, callback)

Purchase stripe products defined in your stripe dashboard. This method is best used when you have a predefined list of products and prices in the Stripe dashboard that you can reference per sku and not worry about pricing being passed in by the client.

buildfire.services.stripe.purchase({
items: [{
sku: "PRODUCT_SKU_ID",
quantity: 2
}]
}, (err, result) => {
if (err) return console.error(err);
if (result) {
console.log("Success Purchase");
}
});

options#

NameTypeRequiredDescriptionDefault
items[object]yesAn array of items
submitTypestringnoDescribes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. Supported values are "auto", "book", "donate", or "pay"
customerIdstringyesID of an existing customer, if one exists. If blank, Checkout will create a new customer object based on information provided during the session. The email stored on the customer will be used to prefill the email field on the Checkout page. If the customer changes their email on the Checkout page, the Customer object will be updated with the new email.
customerEmailstringyesIf provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once a session is complete, use the customer field.

options.items#

NameTypeRequiredDescriptionDefault
skustringyesThe ID of the SKU that the customer would like to purchase
quantitynumbernnoQuantity for this item1

callback(err, result)#

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectThe result of the completed stripe checkout session

getSubscription()
#

buildfire.services.stripe.getSubscription(options, callback)

Get stripe subscription details.

buildfire.services.stripe.getSubscription(
{
subscriptionId: "SUBSCRIPTION_ID",
},
(err, result) => {
if (result) {
console.log("subscription object", result);
}
}
);

options#

NameTypeRequiredDescriptionDefault
subscriptionIdstringyesStripe subscription id

callback(err, result)#

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectThe result of the completed stripe checkout session

Example response#

{
"id": "SUBSCRIPTION_ID",
"object": "subscription",
"application_fee_percent": null,
"billing": "charge_automatically",
"billing_cycle_anchor": 1565625862,
"billing_thresholds": null,
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"collection_method": "charge_automatically",
"created": 1565193862,
"current_period_end": 1565625862,
"current_period_start": 1565193862,
"customer": "CUSTOMER_ID",
"days_until_due": null,
"default_source": null,
"default_tax_rates": [],
"discount": null,
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "ID",
"object": "subscription_item",
"billing_thresholds": null,
"created": 1565193863,
"metadata": {},
"plan": {
"id": "PLAN_ID",
"object": "plan",
"active": true,
"nickname": "Monthly",
"product": "PRODUCT_ID",
"transform_usage": null,
"trial_period_days": null
},
"quantity": 1,
"subscription": "SUBSCRIPTION_ID",
"tax_rates": []
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/subscription_items?subscription=SUBSCRIPTION_ID"
},
"livemode": false,
"metadata": {},
"pending_setup_intent": null,
"plan": {
"id": "PLAN_ID",
"object": "plan",
"active": true,
"nickname": "Monthly",
"product": "PRODUCT_ID"
},
"quantity": 1,
"schedule": null,
"start": 1565193862,
"start_date": 1565193862,
"status": "trialing",
"tax_percent": null,
"trial_end": 1565625862,
"trial_start": 1565193862
}

cancelSubscription()
#

buildfire.services.stripe.cancelSubscription(options, callback)

Cancel stripe subscription details.

buildfire.services.stripe.cancelSubscription(
{
subscriptionId: "SUBSCRIPTION_ID",
customerId: "CUSTOMER_ID",
},
(err, result) => {
if (result) {
console.log("subscription object", result);
}
}
);

options#

NameTypeRequiredDescriptionDefault
subscriptionIdstringyesStripe subscription id
customerIdstringyesStripe customer id

callback(err, result)#

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectThe result of the completed stripe checkout session

Example response#

{
"id": "SUBSCRIPTION_ID",
"object": "subscription",
"application_fee_percent": null,
"billing": "charge_automatically",
"billing_cycle_anchor": 1565625862,
"billing_thresholds": null,
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": 1565216551,
"collection_method": "charge_automatically",
"created": 1565193862,
"current_period_end": 1565625862,
"current_period_start": 1565193862,
"customer": "CUSTOMER_ID",
"days_until_due": null,
"default_source": null,
"default_tax_rates": [],
"discount": null,
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "ID",
"object": "subscription_item",
"billing_thresholds": null,
"created": 1565193863,
"metadata": {},
"plan": {
"id": "PLAN_ID",
"object": "plan",
"active": true,
"nickname": "Monthly",
"product": "PRODUCT_ID",
"transform_usage": null,
"trial_period_days": null
},
"quantity": 1,
"subscription": "SUBSCRIPTION_ID",
"tax_rates": []
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/subscription_items?subscription=SUBSCRIPTION_ID"
},
"livemode": false,
"metadata": {},
"pending_setup_intent": null,
"plan": {
"id": "PLAN_ID",
"object": "plan",
"active": true,
"nickname": "Monthly",
"product": "PRODUCT_ID"
},
"quantity": 1,
"schedule": null,
"start": 1565193862,
"start_date": 1565193862,
"status": "canceled",
"tax_percent": null,
"trial_end": 1565625862,
"trial_start": 1565193862
}

addCustomerCard()
#

buildfire.services.stripe.addCustomerCard(options, callback)

Adds customer card

buildfire.services.stripe.addCustomerCard(
{
customerId: "CUSTOMER_ID",
customerEmail: "CUSTOMER_EMAIL",
},
(err, result) => {
if (result) {
console.log("paymentMethod object", result);
}
}
);

options#

NameTypeRequiredDescriptionDefault
customerIdstringyesStripe customer id
customerEmailstringnoIf provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once a session is complete, use the customer field.

callback(err, result)#

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectThe result of the completed stripe checkout session

Example response#

{
"id": "pm_intent_id",
"object": "payment_method",
"billing_details": {
"address": {
"city": null,
"country": "US",
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"email": "your_billing_email",
"name": "Test Stripe Card",
"phone": null
},
"card": {
"brand": "visa",
"checks": {
"address_line1_check": null,
"address_postal_code_check": null,
"cvc_check": "pass"
},
"country": "US",
"exp_month": 9,
"exp_year": 2032,
"fingerprint": "finger_print_code",
"funding": "credit",
"generated_from": null,
"last4": "4242",
"three_d_secure_usage": {
"supported": true
},
"wallet": null
},
"created": 1567626561,
"customer": "customer_id",
"livemode": false,
"metadata": {},
"type": "card"
}

capturePayment()
#

buildfire.services.stripe.capturePayment(options, callback)

Capture payment

buildfire.services.stripe.capturePayment(
{
paymentIntentsId: "PAYMENT INTENT ID",
amountToCapture: 1000,
},
(err, result) => {
if (result) {
console.log("capturePayment object", result);
}
}
);

options#

NameTypeRequiredDescriptionDefault
paymentIntentsIdstringyesStripe payment intents id
amountToCapturenumbernoThe amount to capture from the PaymentIntent, which must be less than or equal to the original amount. Any additional amount will be automatically refunded. Defaults to the full.

callback(err, result)#

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectThe result of the payment intent object