Bolt Developer

Welcome to the Bolt developer hub. You'll find comprehensive guides and documentation to help you start working with Bolt as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Docs

4. API Hook Integration

What is an API hook?

An API hook is an end point on your e-commerce website that Bolt will call for any transaction update asynchronously.

Some of the most important use cases of hook

  • Notify your e-commerce store when a transaction has been approved or rejected by Bolt
  • Notify your e-commerce store with the transaction_id which is necessary for backoffice integration
  • Verify order amount

Hook requirements

The hook you implement must meet the following requirements

  • The hook should accept a payload of the format given below
  • The hook should return a HTTP 200 only if it has successfully processed the notification by Bolt
  • The hook should verify the authenticity of the payload by verifying the signature as indicated in our Verifying Hook Request Guide
  • The hook should save the transaction_id in the payload for operations like void, refund, capture etc.
  • Any failure to process the notification should not return a HTTP 200
  • The hook should be able to create an order if one does not exist for a given order_reference.

Hook payload

Given below is the format for a hook payload

  {
    "id": "abcd",                               // transaction id
    "reference": "AAA-AAA-AAA-AAA",             // transaction reference 
    "order": "1234",                            // merchant order number if provided during checkout. Will be empty for refunds
    "type": "auth",                             // see below for a description of the hook types
    "amount": 12345,                            // transaction amount (in cents)
    "currency": "USD",                          // currency
    "status": "completed" ,                     // see below for a description of the transactions statuses
    "display_id": "66666",                      // if provided. Will be empty for refunds
    "source_transaction_id": "mnhku",           // original transaction id, shown only for refunds
    "source_transaction_reference": "uujkg"     // original transaction reference, shown only for refunds
  }

Hook types

  • pending a transaction occurred. it is pending review.
  • payment a sale occurred (auth+capture)
  • credit a credit/refund was issued
  • capture a capture occurred
  • void a void occurred
  • auth an authorization was issued
  • rejected_reversible a transaction was rejected but decision can be overridden.
  • rejected_irreversible a transaction was rejected and decision can not be overridden.

Transaction statuses

  • pending transaction is pending review
  • completed payment is completed
  • cancelled transaction was cancelled
  • failed transaction was declined / permanently rejected
  • authorized transaction is authorized, ready for capture or void
  • rejected_reversible transaction was rejected but decision can be overridden
  • rejected_irreversible transaction was rejected and decision can not be overridden.

Retry policy

If the response to a webhook request is not HTTP 200 OK or response body is not a valid JSON, Bolt will keep retrying with exponential back-off. After certain time period, you can still fetch the transaction manually at /v1/merchant/transaction/reference to reconcile your internal state.

Hook Responses

There are 2 parts to API hook responses:
HTTP response code
HTTP response body contents.
The response body to a hook request must contain a JSON object. The general structure of a hook response body is shown below.

{
  "status": "success"|"failure", // required in all responses
  "created_objects": {           // required when http status code = 201
    "merchant_order_ref": "xyz123",
  },
  "error": {...}                 // required when http status code >= 400
}

Note that Bolt assumes a JSON response body irrespective of the value in Content-Type response header.

Success Response
Use this success response to indicate that a new order was created in this request. Bolt annotates the Bolt order with the provided merchant order reference.
Example:
HTTP status code: 201 Created
Response body:

{
  "status": "success",
  "created_objects": {
    "merchant_order_ref": "xyz123",
  },
}

Failure responses
All error responses should have HTTP status codes >= 400. The general structure of the error response body is given below:

{
  "status": "failure",
  "error": {
    "code": 60XX,                  // An integer code representing the error.
    "message": "Unable to do XYZ", // A string describing the error (optional)
  },
}

Orphaned transaction

When we call the webhook for a transaction but there is no order created on your e-commerce website, this is basically an orphaned transaction. This can happen for a lot of reasons

  • Internet connection was lost during checkout
  • Customers browser crashed
  • Customer accidentally or deliberately closed the browser while processing the transaction

In order to handle these, make sure that the hook is capable of converting an existing cart into an order and associate it with the transaction.

Checkpoint

Ensure that all the following are true

  • Register the hook with Bolt to start sending notifications
  • Add some items to the cart and checkout successfully
    • Make sure that you receive a hook notification from Bolt
    • Make sure that you successfully process that notification and return a HTTP 200
  • Create an order with total $8017.04 or using credit card number 4100 2003 1000 0002 and try to checkout
    • The transaction should fail and there should be no hook notification
Authorize only
  • Set the cart.authCapture to false in your frontend.
  • Create an order with total $8017.01 or using credit card number 4111 1111 1111 1111 and try to checkout
    • The transaction should be processed and the hook notification should be of type pending
    • This notification should be successfully processed and the hook should return a HTTP 200
    • Wait for 2-3 minutes for Bolt to approve this order
    • A hook notification of type auth should be sent
    • This notification should be successfully processed and the hook should return a HTTP 200
  • Create an order with total $8017.03 or using credit card number 4457 0102 0000 0247 and try to checkout
    • The transaction should be processed and the hook notification should be of type pending
    • This notification should be successfully processed and the hook should return a HTTP 200
    • Wait for 2-3 minutes for Bolt to reversibly reject this order
    • A hook notification of type rejected_reversible should be sent
    • This notification should be successfully processed and the hook should return a HTTP 200
  • Create an order with total $8017.02 or using credit card number 4457 0101 4000 0141 and try to checkout
    • The transaction should be processed and the hook notification should be of type pending
    • This notification should be successfully processed and the hook should return a HTTP 200
    • Wait for 2-3 minutes for Bolt to irreversibly reject this order
    • A hook notification of type irrejected_reversible should be sent
    • This notification should be successfully processed and the hook should return a HTTP 200
  • Create an order with total $8017.05 or using credit card number 4100 2003 0001 3007 and try to checkout
    • The transaction should be processed and the hook notification should be of type auth
    • This notification should be successfully processed and the hook should return a HTTP 200
Authorize + Capture
  • Set the cart.authCapture to true in your frontend.
  • Create an order with total $8017.01 or using credit card number 4111 1111 1111 1111 and try to checkout
    • The transaction should be processed and the hook notification should be of type pending
    • This notification should be successfully processed and the hook should return a HTTP 200
    • Wait for 2-3 minutes for Bolt to approve this order
    • A hook notification of type payment should be sent
    • This notification should be successfully processed and the hook should return a HTTP 200
  • Create an order with total $8017.04 or using credit card number 4100 2003 1000 0002 and try to checkout
    • The transaction should be processed and the hook notification should be of type payment
    • This notification should be successfully processed and the hook should return a HTTP 200
Orphaned Transaction
  • Start your checkout with Bolt and fill out all the fields.
  • As soon as you click "Pay", close your browser tab to simulate an customer internet outage
  • A notification will be sent to your hook
  • This notification should be successfully processed, an order should be created by the hook
  • The hook should return a HTTP 200

4. API Hook Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.