Tickets - Login

webhooks

  • How to Verify Webhooks

    All requests made by Bolt to your ecommerce Merchant API will be signed to ensure the authenticity of our requests. Your implementation should always verify the signature to make sure that it’s always Bolt calling your endpoint.

    Bolt signs the payload and includes the HMAC signature in the request header X-Bolt-Hmac-Sha256. There are two ways to verify the payload with this signature.


  • What is Bolt?

    When we talk about Bolt as a cohesive product experience, it’s important to understand all of the separate technical pieces that must be implemented to use Bolt with a custom cart platform. Those pieces are the following:

    • The Checkout Modal
    • The Bolt API
    • The Merchant API
    • Transaction Status Webhooks


  • How Bolt Interacts

    Now that we’ve covered the general components of Bolt in Part One of our Developer’s Guide, let’s dive into some specifics about how Bolt is communicating with your e-commerce platform. This article is a high-level framework tackling information found in our Bolt API Reference and Merchant API Reference.


  • How to Connect Unlinked Transactions

    Creating orders through the frontend (rather than through a pre-auth endpoint) can occasionally prevent an order from linking to a Bolt ID. This disconnect is typically caused by internet disruptions, browser crashes, and similar occurrences on the shopper’s end.

    To handle unlinked transactions, make sure that the pending transaction hook is capable of converting an existing cart order_reference into an order.


  • Environment Details

    Accounts

    Bolt provides two account environments: Sandbox and Production. Each environment includes a unique Merchant Dashboard. All transactions that flow through Bolt’s checkout can be found in your Merchant Dashboard.

    Each merchant account has a unique API Key and Signing Secret that Bolt uses to accurately verify and associate transactions with the account’s divisions.

    Divisions

    A Bolt merchant account can have one or many divisions. A division represents a uniquely configured instance of Bolt Checkout to fit a specific use case or workflow (e.g., storefront and back office). Division setup often includes enabling different features and creating separate webhooks for every division.

    Common Divisions

    • Pay by Link
    • Back Office
    • NetSuite ERP

    Each merchant division has a unique Publishable Key that is used to access your transaction data outside of the Bolt Merchant Dashboard.

    Collaborating with many developers across multiple sandboxes does not require multiple divisions. Simply add each URL to your Approved Domains list.

    Account Types

    Merchant account types are associated to individual processors. Because each processor has unique workflows and setup requirements, switching your payment processor requires setting up a new Bolt merchant account that aligns with the newly chosen processor.

    API & Webhooks

    About Keys

    KEY PURPOSE
    API Key Used for calling Bolt API from your backend server
    Signing Secret Used for signature verification on requests received from bolt
    Publishable Key Embedded on your website and used by Bolt to identify your website


  • Error Codes

    You may choose to pass these error codes back to Bolt in Merchant API Responses to trigger appropriate messages for the shopper.


  • Authorization Response Codes

    Authorization codes for payment processing vary depending on your Bolt Merchant Account setup. Bolt recommends reviewing authorization codes specific to your payment processor or gateway. External Resources Adyen Authorization Codes Braintree Authorization Codes Cybersource Authorization Codes NMI Authorization Codes Paypal Authorization Codes For WorldPay authorization codes, reach out to your customer success manager.


  • Manage Users & Notifications

    Admins and Developers can manage users of their Merchant Account from the Bolt Merchant Dashboard.


  • Pre-Authorization Server Failures

    Issue My server is sending server errors to Bolt and I use the pre-authorization sequence for my integration. Reason If Bolt’s pre-auth order creation request receives a server error from the shopping cart platform, Bolt falls back to the following legacy flow: Bolt processes the authorization of payment Bolt creates the order via a webhook request Usually, our legacy checkout flow is be able to create the orders on-the-fly and there is no noticeable error on a merchant’s end.


  • Review Webhook Failures

    Webhook failure notifications provide you a means of tracking and resolving a crucial part of your Bolt integration.


  • Test Card References

    You can use the following card numbers to simulate scenarios in a sandbox. The type of test cards used vary depending on the processor or gateway set up with your merchant account.

    Bolt Payments

    • Expiration: Any month/year in the future
    • CVV: Any 3 digits
    • Type: Visa
    Scenario Number Behavior
    Reviewed and approved by Bolt 4111 1111 1111 1111
    Reviewed and irreversibly rejected by Bolt 4457 0101 4000 0141 Shopper reaches order confirmation but is notified via email that there was an issue completing the order.
    Reviewed and reversibly rejected by Bolt 4457 0102 0000 0247
    Bolt rejection before authorization 4100 2003 1000 0002 Shopper receivesan error and does not proceed to order confirmation.
    Place in review 4457 0002 0000 0008
    Processor rejection 3743 133042 11118 Shopper receivesan error and does not proceed to order confirmation.


  • Webhook Setup

    Bolt provides developers the ability to leverage webhooks events to handle checkout events according to the business rules of your ecommerce store. Once configured, the Webhook endpoint will be used by Bolt to update your external server asynchronously on the occurrence of an event that you have subscribed to.