Shopify

lomi. Shopify app lets merchants accept Wave, mobile money, cards, and more from the cart page using lomi. hosted checkout. Customers pay on lomi.; Shopify orders are created as draft orders before redirect and completed when payment succeeds.

Requirements

• Shopify store with lomi.. app installed (custom install link from lomi.)
• lomi. merchant account with secret API key and webhook signing secret
• Store currency supported by lomi. (e.g. XOF, USD, EUR)
• HTTPS on the app host (connect.lomi.africa in production)

Distribution is via custom install from the lomi. dashboard (not a public GitHub release).

Step 1, Install the app

From lomi. dashboard (recommended)

1. Go to dashboard.lomi.africa → Settings → Payment channels → Integrations.
2. Toggle Shopify on and enter your store domain (e.g. my-store.myshopify.com).
3. Click Install on Shopify and complete OAuth.

Install URL pattern: https://connect.lomi.africa/install?shop={your-store}.myshopify.com

Step 2, Connect API keys

1. Open the embedded app → Settings.
2. Paste your Test secret key (lomi_sk_test_…) and Test webhook secret (whsec_…).
3. Click Connect to lomi.

The app uses the key prefix to select sandbox vs live API (test keys → sandbox).

Step 3, Check Setup health

The Setup health panel should show:

• API secret key: Configured
• API connection: GET /me succeeded
• Test mode: Sandbox API (test key)

When switching to live, paste a live secret key and matching live webhook secret together.

Step 4, Connect webhooks

1. Copy the Webhook URL from Settings ({app_host}/api/webhooks/lomi/payment-success).
2. In dashboard → Webhooks, create the endpoint.
3. Enable PAYMENT_SUCCEEDED and REFUND_COMPLETED.
4. Paste the signing secret into app Settings.

Step 5, Add the cart block

Online Store → Themes → Customize → Cart → add Pay with lomi. app block → save.

Step 6, Run a test payment

1. Add items to cart and click Pay with lomi.
2. Complete sandbox payment on hosted checkout.
3. Confirm the Shopify draft order is completed.

Go live

Replace test key + webhook secret with live credentials (same Settings screen) and run one small real payment.

Setup checklist (reference)

1. In the app Settings, paste your lomi. secret key and webhook secret.
2. In dashboard.lomi.africa → Webhooks, create an endpoint:
   • URL: {app_host}/api/webhooks/lomi/payment-success (shown in Settings)
   • Event: PAYMENT_SUCCEEDED
   • Signing secret: same value as in the Shopify app Settings
3. Choose shipping mode:
   • Subtotal only: charge cart line items only
   • Subtotal + flat shipping fee: add a fixed shipping amount to the draft order
4. In Online Store → Themes → Customize → Cart, add the Pay with lomi. app block and save.
5. Test with a cart containing one or more items.

Payment flow

1. Customer adds items to cart and clicks Pay with lomi. on the cart page.
2. Theme block reads /cart.js and calls POST /apps/lomi/cart-pay (app proxy, signed by Shopify).
3. App creates a Shopify draft order with all cart line items (and optional flat shipping).
4. App calls POST /checkout-sessions on lomi. with amount = draft order total and metadata (shopify_draft_order_id, shopify_shop, etc.).
5. Customer completes payment on lomi. Checkout.
6. lomi. sends PAYMENT_SUCCEEDED webhook → app completes the existing draft order in Shopify.
7. Customer lands on /shopify/order-complete; cart is cleared and order reference is shown.

Webhooks

Metadata used for reconciliation:

• shopify_shop
• shopify_draft_order_id
• shopify_draft_order_name
• shopify_checkout_session_id

Limitations

• Not a Payments Partner / native checkout payment method (no Shop Pay, no checkout UI gateway).
• Shipping and tax from Shopify checkout are not available on the cart page, use subtotal only or a flat shipping fee in app settings.
• Refunds are handled in lomi. dashboard, not automatically from Shopify Admin.
• Do not submit this cart-bypass flow to the public Shopify App Store (Shopify policy on bypassing checkout).

Go-live QA

Related

• E‑commerce hub
• WooCommerce: reference for hosted checkout + webhook contract
• Webhooks