Join Now

Click here to join our
growing community:

JOIN LOGIN



Docs

Welcome Tour
Handbook
Extensions
Pro Modules
Developers



Copyright © 2020
Terms of Use
Privacy Policy
BoltWire

Pro Modules

Card

Stripe is a fantastic payment processor for online websites, and BoltWire provides a powerful integration with it's api to easily enable credit card capabilities on your site. And to connect it to any BoltWire processes you wish.

Let's talk about how to get stripe working quickly.

Setup Steps

The first thing you need to do is create a free Stripe account, and get it connected with your bank so it knows where to send any payments you receive.

Second, you need to grab the Stripe api keys, and enter them in site.config. Click the Developer link in your Stripe dashboard. and then click API Keys. There you should see a live public key and a live secret key. If you switch to test mode, you will see a test public key, and a test secret key. You'll need all four.

Enter the into your site.config page, using these ids for your fields. Make sure you line them up correctly!

stripeLivePublic
stripeLiveSecret
stripeTestPublic
stripeTestSecret

Third you should enable the "card" and "store" plugin on site.config as these two plugins work together. Your lines should look like:

enableCard
enableStore

Here are two additional config settings you may wish to reset if you are not working with USD/$ for your currency.

stripeCurrency: USD
currencySymbol: $

You can get a list of available currency codes at Stripe, along with helpful documentation. And I found this list of currency symbols for your reference. We do not currently provide transaction specific currency settings, only sitewide settings.

That's about all you need to do to get this plugin working...

Testing

By default, the Stripe integration is set to work in demo mode. This gives you time to play around with and test your payment processes safely. To turn everything live, you'll just need to set stripeMode: live on site config. Don't do that now--come back later, once you are satisfied everything is working properly.

In addition, the superadmin account is always set to "demo" mode, meaning when you are logged in as the super admin, you can test all the site processes without worrying about triggering actual payments.

Note: this is not true of regular admins. Only the superadmin account.

Third, if you want to test a specific payment process, you can set mode=demo in the card and charge functions, and it will switch to demo mode for that transaction. This can be useful when testing processes that allow guest purchases. Note that for logged in users, you can only store one card at a time, and a "live" card used on a "demo" charge will always fail.

Last, I've set the card update buttons to add "(DEMO)" to the label when in demo mode. That disappears when the button is in live mode. This helps you to know what mode your page is in before testing some transaction.

When working in test mode, stripe offers various fake card numbers you can use to test various features on your site. You can use it to test both successful and faulty transactions. Here's a link to their documentation:

Test Cards

All card transactions (card updates, purchases, declined cards, errors, etc) are logged on info.card.log. You can check this from the site admin area, by going to the store section and clicking logs.

Card Functions

This module provides two functions: a "card" function with several modes. And then a "charge" function. Here is a bit of technical information on how these work:

Card Function
The card function gives you six modes: mode, info, cart, error, update, and catch. Here's what they do:

mode
To verify the mode on the current page just put <(card mode)>. It will return live or demo.

info
To display some basic information about the users current card stored on file use <(card info)>. Basically it displays a line describing the card type, last 4 digits, and expiration date. You can also be more specific, by adding id, brand, last4, or expy as an additional parameter.

cart
This returns the cart location for the current page.

error
This returns the most recent error message for the current cart.

update
This creates a button that opens up a stripe input form a user can use to enter their card information. Normally this reloads the page where the card information is then "caught" (see below). To allow users to make payments when not logged in, set a next parameter forwarding them to a charge page immediately upon submitting their card.

catch
Use this line to "catch" new card information from an update action. This mode saves that information in your mbase directory for future transactions (if they are logged in). Once their card info is saved, and there is a valid cart, you simply forward them to a charge page to process the transaction.

Charge Function
The charge function is used to actually triggers a payment. It requires a valid "cart" of some sort (see the store module), and card information (either in mbase or submitted via the card update function). It returns true or false. And it can accept the following parameters:

type: used for special cart types. By default, {p1} is used.
success: a page the user is forwarded to on transaction success.
error: a page the user is forwarded to on transaction failure.
script: run a special script based on the transaction results.

This function is most powerful when a script is define. Basically, it taps into BoltWire's built-in script function, which allows you to process special "script" forms automatically without user input. By simply forwarding a user to a page containing a "charge" function with a script define, the payment is triggered automatically and any actions you want to take can be performed.

Let's take a simple example. Once a person has entered their information for a store purchase, and click the purchase button, they are sent to a store "charge" page (store.checkout.charge) with this code:

One moment while we charge your card...

<(charge script=purchase)>

The script function calls page code.script.charge.purchase which contains this content:

[[#true]]
[command nextpage store.checkout.thanks]

[[#false]]
[command nextpage store.checkout.error]

Basically, the script processes the transaction, and then calls the appropriate section of the script, sending them either to the error page, or the success page depending on whether or not the transaction was successful.

But you can do much more with this. Let's say for example you wanted to enroll someone in a class upon successful payment of a some fee. You would simply create a custom charge script, and then call it on the charge page for that transaction.

Here's the code on the charge page for purchase offer types:

One moment while we charge your card...

<(charge script=offer)>

The script function calls a different script: code.script.charge.offer. Here is what that page looks like:

[[#true]]
[command nextpage offer.{p2}.thanks]
[command class enroll]
[command mailer drip={p2} if='exists code.drip.{p2}']

[[#false]]
[command nextpage offer.{p2}.error]

Similar to the previous script, it has separate destinations depending on whether or not the transaction is successful. But if it is successful, there are two additional steps taken. First, they are enrolled in the class, and they are started on a drip sequence (assuming a drip for the class exists).

These are just the most simple examples however. You could for example, send a message to their inbox welcoming them to the class. You could send a message to yourself alerting you to their enrollment. You could add them to a group, or drop them. Or make an announcement in your activity log or on a news feed. Basically, anything else you can do with a form.

How it Works

I won't explain all the ins and outs of how this plugin works here, only to say in general, it works with the store module to create various kinds of "carts" with member information and card information. When the charge is processed, that cart is turned into a receipt.

In the site admin area, there is a "Card" page you can explore for more information about what is happening financially on your site. There, you can review all your abandoned carts, see all recent receipts, review any existing charge scripts, and examine a log of all card activity including any error messages. Stop in often to make sure everything is working like it is supposed to!