Skip to content

Stripe Services

Jump to bottom
o5faruk edited this page May 2, 2021 · 11 revisions

⚠️⚠️⚠️

This sdk documentation is deprecated and will not be updated. Check out our new docs at https://sdk.buildfire.com/docs/stripe/

⚠️⚠️⚠️

Overview

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

This service requires you to include buildfire/services/stripe/stripe.js with your plugin

From the Control <script src="../../../../scripts/buildfire/services/stripe/stripe.js"></script>

From the Widget <script src="../../../scripts/buildfire/services/stripe/stripe.js"></script>

Running Example

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

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.

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

API Keys

This service requires Buildfire API Public Key and Stripe Publishable key Buildfire API Keys.

Methods

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.

  • options: Object:

    • items: Array - a list of items
      • name*: string - The name for the line item
      • description: string - The description for the line item
      • amount*: integer - The amount to be collected per unit of the line item
      • currency = 'usd': string - Three-letter ISO currency code, in lowercase. Must be a supported, for more details check stripe doc
      • quantity = 1: integer - The quantity of the line item being purchased
    • submitType: string - Describes 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"
    • customerId: string - ID 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.
    • customerEmail: string - If 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): Function

    • err: Object
    • result: Object, The result of the completed stripe checkout session

Example

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

Response Object

Response for success charge
{
    "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

Subscribe to specific stripe plan defined in your stripe dashboard.

  • options: Object:

    • items: Array - a list of items
      • planId*: string - Plan ID for this item
      • quantity = 1: integer - Quantity for this item
    • trialPeriodDays: integer - The number of trial period days before the customer is charged for the first time.
    • customerId: string - ID 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.
    • customerEmail: string - If 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): Function

    • err: Object
    • result: Object, The result of the completed stripe checkout session

Example

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

Response Object

Response for success subscription
{
        "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

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.

  • options: Object:

    • items: Array - a list of items
      • sku*: string - The ID of the SKU that the customer would like to purchase
      • quantity = 1: integer - The quantity of the line item being purchased
    • submitType: string - Describes 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"
    • customerId: string - ID 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.
    • customerEmail: string - If 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): Function

    • err: Object
    • result: Object, The result of the completed stripe checkout session

Example

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

Response Object

Response for success purchase
{
    "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,
}

getSubscription

Get stripe subscription details.

  • options: Object:

    • subscriptionId*: string - stripe subscription id

  • callback(err, result): Function

    • err: Object
    • result: Object - stripe subscription object

Example

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

Response Object

{
        "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

Cancel stripe subscription details.

  • options: Object:

    • subscriptionId*: string - stripe subscription id
    • customerId*: string - stripe customer id

  • callback(err, result): Function

    • err: Object
    • result: Object - stripe subscription object

Example

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

Response Object

{
        "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

Add customer card.

  • options: Object:

    • customerId*: string - stripe customer id
    • customerEmail: string - If 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): Function

    • err: Object
    • result: Object - stripe paymentMethod object

Example

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

Response Object

{  
   "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"
}

portal . twitter . facebook

Clone this wiki locally