How to build a custom payment app for processing FSA/HSA eligible transactions?

3 0 4

Hello Guys,

We need to create a custom payment app which is supposed to process the transaction of FSA/HSA eligible products. We have our hosted payment page ready that receives base64 encoded data of Order ID and merchant key from merchant store website and process the transaction.

So our requirement here in shopify is : Our proposed payment app should create a payload and send it to our 'createOrder' API endpoint. Then API will send back a Redirect URL in response which consists link to our gateway's hosted page along with base64 encoded data(Order ID and Merchant Key) as query parameter.

We come to  know that we need Shopify's 'Offsite Payment Extension' method to develop this custom payment gateway. For this we need to configure Session Payment URL to which Shopify will send Order, Payment, Billing and Shipping Info as HTTP POST. So we assume this is the page (Session Payment page URL) where we can build payload for our 'createOrder' API and send it to API. But somehow We are not able to  access Merchant Key and Order items detail on this page. So we need Order Item's meta data like GTIN, EAN etc for payload building.

Please guide us how can we get Order Item details , merchant key on this session payment URL so that we can proceed further.




Replies 2 (2)

3 0 4
Hi connor_at_rally,

Thank you so much for your step-by-step guidance on creating a custom
payment gateway which is supposed to redirect customers to our Hosted
Payment Page in order to complete transactions.

Here we want to add some points and need your comments on these points.

1) We need a custom payment option on store's checkout page, so that if
customer selects this payment option and click on 'Payment Now' button then
only order, billing and shipping data will be passed from shopify to
"Payment session URL", which is configured in offsite payment extension.

2) In order to put that custom payment option on checkout page we are
calling one of Shopify's REST API i.e.
and the payload that we submit to this endpoint is something like :

const paymentGateway = {
payment_gateway: {
name: 'Custom Payment Method',
test: true,
active: true,
settings: [
name: 'API Key',
name: 'API Secret',

3) We get response status code 200 for this API call. Response data
contains some HTML code which again contains an URL. After retrieving that
URL from response data, if we redirect to that URL then it asks permission
for the store (where the custom payment method is supposed to be displayed)
and then heads to a page and get stuck there. On this page we see this
error message:

Due to an unexpected technical problem, Shopify is temporarily unavailable.
Please check back in a few minutes – we'll be up and running in no time!

4) We want to know if we are moving in the right direction. If so then how
to get rid of the issue that we have explained above.

Shopify Partner
1 0 1

I'm tying to create a similar app, mine is a bit simpler but still I've not found a clear path to develop this custom payment app for shopify. 

I don't understand why the documentation is very general on this topic.