Get Started with Whalestack

Create a Whalestack account to unlock the power of cryptocurrency payments for your website.

Enable Custom App Development

Before you can create a custom app for your store, you need to enable custom app development. Only the store owner can enable custom app development.

1. From your Shopify admin, navigate to Settings > Apps and sales channels.
2. Click on Develop apps.
3. Click Allow custom app development.
4. Read the provided warning and information, and then click Allow custom app development.

Create Your Custom App

1. From your Shopify admin, navigate to Settings > Apps and sales channels.
2. Click on Develop apps.
3. Click Create an app.
4. In the modal window, enter the App name (Whalestack) and select an App developer. The app developer can be the store owner or any staff or collaborator account with the Develop apps permission.
5. Click Create app.

Select API Scopes

1. In the app that you just created Apps and Sales channels -> Develop apps -> Whalestack, click the Configure Admin API scopes button
2. Scroll down to the Orders section and activate both write_orders and read_orders.
3. At the bottom of the page, in the Webhook subscriptions section, choose Latest from the dropdown menu.
4. Click Save, and then click Install app at the top of the page and confirm it on the modal popup.

Collect API Access Token

1. In the API credential tab, click on Reveal token once and save it in a secure place.

Create a Webhook

This webhook is a custom callback event that sends notifications to your Whalestack account.

1. In your Shopify account, go to Settings -> Notifications.
2. Scroll to the bottom of the page and find the Webhooks section.
3. Click Create webhook.
4. Choose the following parameters in the popup window:
   • Event: Order creation
   • Format: JSON
   • URL: https://www.whalestack.com/api/v1/shopify-order
   • Webhook API version: Choose Latest
5. Click Save.

Create a New Crypto Payment Method

This payment method becomes an option in your Shopify store.

1. In your Shopify account, go to Settings -> Payments.
2. Scroll down in the list of payment providers to the Manual payment methods section.
3. Click on the dropdown menu for Manual payment methods and choose Create custom payment method.
4. Enter the fields in the popup window as follows:
   • Custom payment method name: Enter Whalestack or Bitcoin via Whalestack. Important: You can customize the name to your liking, but it must include the word Whalestack otherwise we will not be able to capture payments. Also, Bitcoin via Whalestack will be easier to understand for your clients than just Whalestack.
   • Additional details: Enter a short description for Whalestack payment method, for example: Pay with Bitcoin and other digital currencies or stablecoins via Whalestack.
   • Payment instructions: These instructions appear on the order confirmation page and should inform shoppers that they will receive an email to make the payment and finalize the order. Example: Check your email inbox now, you will receive instructions to pay this order securely via the Whalestack checkout page.
5. Click Activate.

Customize the Payment Method Display

• In your Shopify account, go to Settings -> Checkout.
• Scroll to the bottom of the page and find the Order status page section.
• Copy the following Liquid snippet into the textarea:

  <script>
    {% assign gateway = checkout.transactions[0].gateway | downcase %}
    {% if gateway contains 'whalestack' %}
    Shopify.Checkout.OrderStatus.addContentBox(`
      <div class="text-container">
          <h2 style="font-weight:bold;color:red">Payment Instructions</h2>
          <p>Please check your email inbox for instructions from <strong>Whalestack // Service</strong> on how to pay this order securely with Bitcoin, Lightning, Litecoin, XLM, USDC, or EURC.</p>
          <p>Powered by <img src="https://www.whalestack.com/images/ws-logo-blue.svg" width="100px"></p>
          </div>`)
    {% endif %}
  <script>

• Click Save.

Configure Shopify API Credentials in Whalestack

1. Log in to your Whalestack account and navigate to the Shopify API settings page.
2. Fill in the fields as follows:
   • Shopify Store URL: Enter your store URL in the format https://{your-store-name}.myshopify.com.
   • Access Token: Enter the API access token obtained in step 2 (Create a Shopify custom app) of this guide.
   • Webhook Signing Key: Navigate to Settings -> Notifications -> Webhooks. You will find the signing key there.
   • Settlement Asset: The settlement asset in which your account is credited when a checkout completes. Choose "ORIGIN" to be credited in the same asset your customer paid with.
   • Checkout Page Language: The language in which the checkout page, where your customer pays, will be displayed. Choose "auto" to automatically detect the user's language.
3. Click Submit.

Order Confirmation

Upon order confirmation, an email is sent to the user containing a link to securely pay for the order via the Whalestack payment page.

Payment Information

Completed payments will automatically update Shopify orders to Paid.

Refunds

Manage all payments and refunds in your Whalestack account. You will receive email notifications for every new payment.

Payment Page

Customize the checkout page to match your brand's look and feel directly in the Brand Connect settings of your Whalestack account. Configure brand information, images, fonts, colors, and more. Refer to the Brand Connect guide for more details.