Use Cases
- You want to display the shopper’s order inside of a checkout webview for mobile devices.
- You want to reduce checkout friction by pre-filling key details (such as the shopper’s name and address) as hints to the checkout webview.
Approach
To display the checkout webview, you must first have an order token created. Then you can query for the order using the following URL:
https://connect.bolt.com/remote_checkout?order_token=<>&req_id=<>&merchant_id=<>&publisher_key=<>&hints=<>
Desktop Webview
If you prefer to use the webview implementation instead of the desktop checkout modal, you can use the following URL for displaying a desktop webview, which does not require the req_id or the publisher_key:
https://connect.bolt.com/remote_checkout?order_token=<>&merchant_id=<>&hints=<>
Required Parameters
| Query Parameter | Description |
|---|---|
| order_token | Token created by sending a POST request to /v1/remote_checkout/orders. Bolt recommends refreshing the token on a new session. |
| req_id | Unique request ID generated by the publisher. |
| merchant_division_id | Bolt’s public ID for the merchant’s division. |
| publisher_key | Unique identifier for the publisher. |
Optional Parameters
| Query Parameter | Description |
|---|---|
| hints | Placeholder for any information to pre-fill checkout inputs. |
Hints
| Hint | Description |
|---|---|
Email of the purchaser; should be encoded (e.g. email=test%40bolt.com). |
|
| phone | Phone of the purchaser; must be in E.164 formatting and should be encoded (e.g. as phone=%2B12025550101). |
| firstName | First name of the ship-to address; this can be different from the purchaser. |
| lastName | Last name of ship-to address; this can be different from the purchaser. |
| addressLine1 | Address line 1 for shipping. |
| addressLine2 | Address line 2 for shipping |
| city | City for shipping |
| state | State for shipping; accepts both abbreviation and long form (e.g. CA, California). |
| zip | Zip code for shipping; accepts short and long (5 and 9 digit) for US. |
cURL Request
curl -X GET \
'https://connect.bolt.com/remote_checkout?order_token=a2b3dDc4cA5e6fg78Bg9hj0kl&req_id=223&merchant_id=123-456&publisher_key=987-543&email=test%40bolt.com&firstName=Bob' \
-H 'X-Nonce: <12-digit-unique-integer>' \
-H 'X-Publisher-Key: <unique-publisher-id>' \
-H 'X-Authorization-Signature: <generated-after-using-secret-and-nonce>'
Response
Upon selecting the link, the shopper opens Bolt’s checkout webview, which pre-loads their order and any additional information passed through the available hint options.
Callbacks
onSuccess
Bolt redirects a shopper to the following destination after they have successfully completed checkout in webview. This URL includes a status of success and a way to pass important data.
"<APP_NAME>://boltPaymentResult?status=success&data=<PAYLOAD>"
Payload Example
In this example, we are passing the transaction_reference, merchant_order_number, and any key metadata along as a payload through the URL.
"transaction_reference": "<< bolt transaction reference of created order >>"
"merchant_order_number": "<< order reference on merchants side >>"
"metadata": "<< metadata passed by publisher in webview >>"
Close
Bolt redirects a shopper to the following destination when they decide to exit the checkout webview before completing their purchase.
"<APP_NAME>://boltPaymentResult?status=close"
onNotify
Publishers can capture event logging through the onNotify callback for all of the following event types.
| CallbackEventNameType | Description |
|---|---|
| “error_invalid_name” | Name input by shopper was invalid. |
| “error_invalid_email” | Email address input by shopper was invalid. |
| “error_invalid_address” | Shopper’s address input by shopper was invalid. |
| “error_giftcard_unsuccessful” | Giftcard was not successfully added to the cart. |
| “error_invalid_giftcertificate” | Gift certificate was not successfully added to the cart. |
| “error_invalid_payment” | Payment method input was not valid. |
| “error_discount_unsuccessful” | Discount code was not successfully added to the cart. |
| “error_remove_discount_unsuccessful” | Discount was not successfully removed from the cart. |
| “error_remove_giftcard_unsuccessful” | Gift card was not successfully removed from the cart. |
| “error_shipping” | Shipping methods weren’t found or available for the input shipping address. |
| “error_tax” | Tax could not be calculated for items in cart. |
| “warn_invalid_address” | Shipping address input is not valid. |
| “info_discount_successful” | Discount code was successfully added to the cart. |
| “info_giftcard_successful” | Giftcard was successfully added to the cart. |
| “info_giftcertificate_successful” | Gift certificate was successfully added to the cart. |
| “info_address_added” | Shipping address was successfully added. |
| “info_address_edited” | Shipping address was successfully updated. |