Payments API: Build Headless Checkouts and Recurring Billing Apps on BigCommerce

We are excited to announce that the Payments API is now available, enabling developers to build end-to-end headless storefronts and recurring billing apps. The Payments API processes payments through a BigCommerce store’s connected payment gateway. This means that BigCommerce assumes the complexity of processing the payment while allowing developers the flexibility to use the BigCommerce payment service from anywhere — whether that’s a headless CMS storefront, a native mobile app, or an embedded ecommerce experience.

The Payments API extends the server-to-server Checkout API by finalizing orders with a payment. Over the last year, we’ve launched a sequence of APIs that make it possible to build purchase flows external to the platform — first, the server-to-server Cart API, and later Checkout. Now with the Payments API, it’s possible to completely process an order from cart to purchase on an external application, powered by the BigCommerce platform.

How Does it Work?

The workflow to process a payment starts with an order in Incomplete status, which can originate from either the Checkout API or the Orders API. Creating an order from the Checkout API suggests that a customer has gone through the storefront purchase funnel (from product page to cart to checkout) to complete the order. Creating an order from the Orders API is typical if the order was created externally on another system (like a POS or subscription app). You might create an order using the Checkout API if you’re building a headless checkout page, or the Orders API if you’re processing a recurring payment.

The API accepts typical payment methods like credit cards in addition to any previously stored credit cards added by the registered customer on the storefront. We then extended the payment method functionality further by allowing you to also store new credit cards while making a payment. You can fetch the list of available payment methods by using the Get Accepted Payment Methods endpoint.

One notable thing about the Payments API is that it actually consists of two API hosts:

• The request to retrieve a payment access token for an order is routed through api.bigcommerce.com, much like our other server-to-server APIs.
• The request to process a payment is routed through a second host: payments.bigcommerce.com. Once you’ve obtained a payment access token for an order, you can pass it as an authorization header in a Process Payment request to finalize the transaction.

The converted order will now show in the Order View section of the control panel where it can be managed like other orders. You can perform a refund or capture funds through the control panel or through your payment gateway’s dashboard, and in the future, we plan to extend these capabilities to our APIs.

Compliance with BigCommerce Trust and Assurance Requirements

The token we expose for stored credit cards is a reference token created by BigCommerce rather than the third party payment provider’s vault token. When designing the Payments API, we’ve been very mindful about the way we approach security and PCI compliance. BigCommerce does not vault credit card data within the platform — instead, we rely on third-party payment providers to do the vaulting on our behalf. However, because the payment provider’s vault token can be used to authorize a purchase, we provide an additional layer of security by creating our own reference token instead of exposing the provider token. To learn more about compliance, review our Payments API developer documentation.

What Can I Build?

The Payments API is a solution for any application or external storefront that needs to process a transaction while leveraging the business logic of BigCommerce’s integrated payment systems. Accepting payments can be a heavy lift for development teams, and while solutions that use the Payments API do fall within the app developer’s PCI scope, the Payments API can dramatically reduce the complexity of handling transactions.

One exciting use case for the Payments API is recurring billing. With recurring billing, a customer can purchase a product on a subscription basis, providing their credit card information a single time and authorizing a convenient monthly charge for ongoing services. It’s a great business model for merchants, who can increase lifetime customer value and stabilize revenue fluctuations, and also a great model for consumers, who get the products they love sent to their door automatically.

Demo: Subscription Billing App

Now that we’ve given you an overview of the Payments API, let’s take a look at a sample app workflow to illustrate what it’s possible to build. We’ll show you how you might build an app that uses the Payments API to process recurring payments for a subscription through BigCommerce stored credit cards.

A subscription begins when a customer purchases a product that’s flagged for recurring billing.

The app that you build will need to know whether an order contains a subscription billing product during the checkout process, to make sure that the shopper has a saved payment instrument on file when the shopper is purchasing a subscription. This will give the app a way of processing the payment when the next subscription installment becomes due. One way to do this is by reading the cart contents with the Checkout API before the shopper finalizes the order. If a particular product is detected in the checkout, the app can vault the credit card, to be used for future purchases. When processing the payment, set the “save_instrument” flag to true to vault the card:

{
    "payment": {
        "instrument": {
        "type": "card",
        "number": "4111111111111111",
        "cardholder_name": "BP",
        "expiry_month": 12,
        "expiry_year": 2020,
        "verification_value": "411"
        },
    "payment_method_id": "authorizenet.card",
    "save_instrument": true
    }
}

When it’s time to process the next payment, you can create an order to process the payment against using the Orders API. This creates a record of the installment entirely on the back end, because this time, the shopper is not initiating the purchase from the storefront. To allow payment, an order’s status can be set to incomplete (status ID 0), and then the order can be processed using a stored instrument from the customer’s account.

{
    "payment": {
        "instrument": {
        "type": "stored_card",
        "token": "vaulted instrument token",
        "verification_value": "123"
        },
    "payment_method_id": "stripe.card"
    }
}

Conclusion

The Payments API allows developers to leverage BigCommerce payment integrations to build external checkout flows and recurring billing solutions. This unlocks the ability to build end-to-end checkouts in the front end of your choice, like a CMS, hosted JavaScript framework, or native mobile app, and to process payments through third-party applications — all without touching the BigCommerce storefront.

During the beta period, we worked with a select group of partners and merchants who have already begun to build out exciting new applications. As we move into the public release of the Payments API, we can’t wait to see how the developer ecosystem innovates on top of this newly opened area of our platform.

Visit our Developer Portal for a full overview and API reference, and let us know how you plan to use the Payments API by commenting below!