A Step-by-Step Guide to Accepting Lightning Payments using Galoy API

screenshot taken from galoy.io

Lightning payments are a new way to send and receive Bitcoin payments. They are cheaper and faster, and more scalable than the usual Bitcoin transactions. By using a network of nodes, payments can be routed between users without needing to broadcast the transaction on the bitcoin network

This article presents a step-by-step guide on how to accept lightning payments using Galoy apis. Galoy is an open source core banking platform designed for launching enterprise-scale Bitcoin and Lightning applications. Galoy provides simplified rails for cryptocurrency payments.

This article assumes you are interested in enabling bitcoin lightning payments in a javascript based application.

Objectives:

• How to Initiate a lightning payment request with the Galoy API
• How to Check the status of a payment with the Galoy API

Prerequisites:

Get Authorization Token with a Galoy Account

Interacting with the Galoy API requires an authorization token. To get the token, a galoy account with an active phone number is needed. Check here for quick instructions

Get Test Satoshis

This step is optional, but to make a test payment, an account funded with test satoshis is needed. Follow this guide.

Install Dependencies (optional)

Galoy apis have GraphQL based endpoints. You can install the below libraries in your application to handle the calls. Sample codes in the next steps make use of them.

yarn - yarn add graphql graphql-request
npm - npm install graphql graphql-request

Retrieve Galoy BTC Wallet ID

Your Galoy account at setup is created with two wallets, one for USD and the other for BTC. Since we are creating a BTC lightning payment, we will need to get the BTC wallet ID as shown below via postman.

url: https://api.staging.galoy.io/graphql
Method: POST

Query
query me {
    me {
        username
        defaultAccount {
            defaultWalletId
            wallets {
                id
                walletCurrency
                balance
            }
        }
    }
}

Variables
{}

Get BTC wallet id

Initiate a lightning payment request with the Galoy API

For a user of your application to make payment over lightning, you need to issue them either a standard BTC lightning invoice or a USD lightning invoice payment request. In this step, we are going to see how to initiate a BTC lightning invoice request.

Step 1: The Graphql mutation

const query = gql`
mutation lnInvoiceCreateInput($input: LnInvoiceCreateInput!) {
  lnInvoiceCreate(input: $input) {
    invoice {
      paymentRequest
      paymentHash
      paymentSecret
      satoshis
    }
    errors {
      message
    }
  }
}
`;

Explanation:

This query sends a lightning invoice request to the Galoy graphQL server to create a standard btc bolt11 lightning invoice.

Step 2: The mutation variables

const variables = {
  input: { walletId:"wallet-id", amount:"amount-in-satoshis", memo: "memo"},
};

Explanation:

The query variables is an input object with the following variables:

• walletId: BTC wallet id.
• amount: amount of bitcoin requested in satoshis
• memo (optional)

Step 3: The request headers:

const requestHeaders = {
  Authorization: `Bearer auth-token`,
};

Explanation:

An authorization token is required to make a request to the Galoy API. You should have one if you followed the earlier instruction otherwise, check how.

Step 4: The lightning invoice request function

const createLightningInvoice = async (requestAmount, description) => {
  try {
    const client = new GraphQLClient('https://api.staging.galoy.io/graphql');
    const query = gql`
    mutation lnInvoiceCreateInput($input: LnInvoiceCreateInput!) {
    lnInvoiceCreate(input: $input) {
        invoice {
          paymentRequest
          paymentHash
          paymentSecret
          satoshis
        }
        errors {
          message
        }
      }
    }
    `;
    
    const variables = {
      input: { walletId: wallet-id, amount: requestAmount, memo: description},
    };
    
    const requestHeaders = {
      Authorization: `Bearer auth-token`,
    };
    
    const invoiceData = await client.request(query, variables, requestHeaders);
    
    const errors = invoiceData.lnInvoiceCreate?.errors;
    if (errors && errors.length > 0) {
      throw new Error(errors.join(', '));
    }
    const invoice = invoiceData?.lnInvoiceCreate?.invoice;
    if (!invoice) {
      throw new Error('Lightning payment address could not be generated');
    }
    
    return invoice.paymentRequest
  } catch (error) {
    console.error(error);
    throw error;
  }
}

Step 5: Make a call to get a lightning invoice payment request.

const lnInvoice = await createLightningInvoice(1000, "some description")

You can now display or send the returned lnInvoice to your user to make payment from their lightning enabled wallet.

Checking the status of a payment with the Galoy API

Step 1: The Graphql query

const query = gql`
query LnInvoicePaymentStatus($input: LnInvoicePaymentStatusInput!) {
  lnInvoice: lnInvoicePaymentStatus(input: $input) {
    status
  }
}
`;

Step 2: The Graphql variables

const variables = {
  input: {
    paymentRequest: lightningInvoice,
  },
};

Step 3: The request headers

const requestHeaders = {
  Authorization: `Bearer auth-token`,
};

Step 4. The function to check payment status of a lightning invoice

const checkPaymentStatus = async (lightningInvoice) => {
  try {
    const client = new GraphQLClient('https://api.staging.galoy.io/graphql');
    
    const query = gql`
     query LnInvoicePaymentStatus($input: LnInvoicePaymentStatusInput!) {
      lnInvoice: lnInvoicePaymentStatus(input: $input) {
        status
      }
     }
    `;

    const variables = {
      input: {
        paymentRequest: lightningInvoice,
      },
    };

    const requestHeaders = {
      Authorization: `Bearer auth-token`,
    };

    const invoiceData = await client.request(query, variables, requestHeaders);

    const errors = invoiceData.lnInvoice?.errors;
    if (errors && errors.length > 0) {
      return false;
    }

    const status = invoiceData.lnInvoice?.status;
    return status === 'PAID'
    } catch (error) {
      console.error(error);
      throw error;
    }
  }

With this, the Galoy service can be constantly polled till a confirmation (truth value) is returned.

Conclusion

The Galoy API is a powerful service that makes it extremely easy to accept Lightning payments from across the world and this article covered how to achieve that. Checkout the below resources for more information on Galoy APIs and services.

https://guide.bolt.fun/guide/web-services/galoy/lightning
https://studio.apollographql.com/public/galoy-hackathon/variant/current/home
https://dev.galoy.io/docs/reference/api-reference/core-api-reference

You can get support to use Galoy by joining on their chat channel https://chat.galoy.io/