Docs / Plugin guide / Shopify

This plugin guide should tell you exactly what to prove before a Shopify checkout sends live order traffic into Payvra.

The Shopify integration is a self-hosted bridge between Shopify checkout and Payvra settlement. Use this page to validate the deployment model, signed webhook contract, sandbox rehearsal path, and the exact settings you switch when you promote the store to live funds.

Create free sandbox Review webhook docs

Keep the rollout boring: install the app on HTTPS infrastructure, verify one sandbox order from checkout to paid state, then swap only the Payvra key and webhook secret when you go live.

What this guide proves

Checkout handoff

Confirm Shopify can call the app, the app can create a Payvra payment, and the shopper lands on the hosted checkout without losing order context.

Signed delivery

Verify Payvra webhooks arrive at the app, the signature is checked, and the Shopify order moves from pending to paid only after the signed event is accepted.

Sandbox rehearsal

Use test credentials first so the full payment lifecycle can be observed without real blockchain funds or live customer traffic.

Operator facts

Runtime model

Self-hosted Express app deployed on your infrastructure.

Checkout route

Shopify checkout -> app endpoint -> Payvra hosted checkout.

Store requirement

Public HTTPS URL for the app plus a Shopify Partners app.

Live promotion

Replace only the Payvra API key and webhook secret after the sandbox path is stable.

Overview

Treat this page as an operator checklist. Each section below maps one part of the plugin path you should verify before you promote checkout traffic to live funds.

Checkout handoff

Confirm Shopify can call the app, the app can create a Payvra payment, and the shopper lands on the hosted checkout without losing order context.

Signed delivery

Verify Payvra webhooks arrive at the app, the signature is checked, and the Shopify order moves from pending to paid only after the signed event is accepted.

Sandbox rehearsal

Use test credentials first so the full payment lifecycle can be observed without real blockchain funds or live customer traffic.

Requirements

Make sure the store, hosting, and account prerequisites are in place before you install the plugin path.

•

Node.js 18 or later.

•

A Shopify Partners account with a custom app ready to install.

•

A Payvra account with sandbox credentials.

•

A public HTTPS deployment target such as Railway, Render, Fly.io, or your own infrastructure.

Setup

Get the plugin or bridge installed first. Then verify that the store can hand checkout traffic to Payvra before you spend time on live credentials.

Create the Shopify app container

In the Shopify Partners dashboard, create a custom app and record the API key, API secret, and payment-related scopes. Keep those values separate from the Payvra credentials so operators can tell which platform owns each secret.

Clone the repository and install the Shopify app

The bridge lives under plugins/shopify in the main repository. Install it in isolation and keep the deploy target pointed at that app directory.

Terminal

1git clone https://github.com/Payvra/main-app.git payvra
2cd payvra/plugins/shopify
3npm install

Configure environment variables

Start with sandbox credentials. The same deployment stays in place later when you swap the Payvra key and webhook secret to live values.

.env

1# Shopify Payments App credentials
2SHOPIFY_API_KEY=your_shopify_api_key
3SHOPIFY_API_SECRET=your_shopify_api_secret
4SHOPIFY_SCOPES=write_payment_gateways,write_orders,read_orders
5
6# Public URL for the app (HTTPS required)
7APP_URL=https://your-app.example.com
8PORT=3456
9
10# Payvra credentials
11PAYVRA_API_KEY=sk_test_...
12PAYVRA_WEBHOOK_SECRET=whsec_test_...

Deploy to HTTPS and verify the health endpoint

Deploy the app so APP_URL matches the public HTTPS origin exactly. Before you touch Shopify checkout, confirm GET /health returns {"status":"ok"}.

Install the app on the target store

Start the OAuth flow with the store hostname you are validating first. Use a development store for rehearsal, then repeat the install on production only after the sandbox path is stable.

Install URL

1https://your-app.example.com/auth?shop=yourstore.myshopify.com

Store listing

The exact distribution surface operators reach for when they install the plugin. The card below mirrors the listing fields shoppers and merchants verify before adopting a payment path.

Shopify Partners appSource-distributed

Distributed by Payvra. Self-hosted Express bridge published in the Shopify Partners dashboard.

Payvra Shopify Bridge

Operators clone the Shopify bridge from the Payvra main app repository and deploy it on infrastructure they control.
The bridge is registered as a custom Shopify Partners app, so the install URL is stamped against the merchant's store hostname.
Public HTTPS origin doubles as the OAuth callback host and the Payvra webhook destination, which keeps the secret scope tight.

Open the Shopify bridge source

Listing facts

Distribution: GitHub source
Bridge runtime: Node.js 18+
Install pattern: Custom app + OAuth
App scopes: write_payment_gateways, write_orders, read_orders
Cost: Free

Configuration

Keep the runtime settings explicit so operators can tell which key, secret, and settlement target a store is using at a glance.

Payvra API key

Use sk_test_... until the whole path is proven. Only move to sk_live_... once the signed webhook flow and order updates are predictable.

Webhook secret

Store the Payvra signing secret separately from the Shopify app secret. Operators should be able to rotate the webhook secret without touching the Shopify OAuth config.

Settlement currency

Choose the merchant settlement target the store should receive after Payvra processes the payment and any conversion path.

Sandbox toggle

Leave sandbox enabled while you prove the lifecycle. The production deploy should only change the Payvra mode and secret material, not the installation pattern.

Webhook setup

The plugin path is only production-safe once signed delivery is verified and the store can reconcile the final payment state automatically.

In the Payvra dashboard, create a webhook that points to the app callback and subscribe to the payment events that should change the Shopify order state.

Webhook endpoint

1https://your-app.example.com/webhooks/payvra

Subscribe only to the order-facing events

Keep the initial event set narrow so operators can audit every state transition. Start with payment.confirmed, payment.completed, payment.failed, payment.expired, refund.completed, and refund.failed.

Verify the signature before the order update path runs

The app should reject unsigned or stale requests before it attempts to mark an order as paid. If the event is accepted, the heavier Shopify order mutation can run after the signed delivery is already persisted.

Platform webhook quirks

Shopify-side checkout handoff and Payvra-side webhook delivery share one public origin. These are the platform-specific gotchas operators usually trip on.

Origin parity

APP_URL, the Shopify Partners app URL, the OAuth callback host, and the Payvra webhook endpoint all resolve to the same public HTTPS origin. A single mismatch between any of these breaks both the install path and signed delivery.

OAuth scope changes

Adding or removing app scopes forces every store to re-authenticate. Until the merchant accepts the new prompt the bridge cannot create payments, even if the deployment looks healthy.

Custom-app-only callbacks

Public app review is not part of this distribution. Webhooks only land in stores where the merchant installed the custom app from the Partners dashboard, not from the Shopify App Store.

Replay tolerance

The bridge enforces the same five-minute Payvra replay window used elsewhere. If your deployment terminates TLS through a cache or CDN, lower the cache TTL so /webhooks/payvra is never served from cache.

Testing in sandbox

Run one full rehearsal with test credentials and confirm the checkout handoff, payment confirmation, and order update path end to end.

Order creation

Place one sandbox order and confirm Shopify hands the shopper into the Payvra hosted checkout without dropping the order reference.

Payment lifecycle

In sandbox mode Payvra simulates a deposit after a few seconds and confirms it shortly after. Watch the hosted checkout and the webhook logs together.

Order state

The Shopify order should move to paid only after the signed webhook is accepted, not before the customer is redirected back to the store.

Promote to live

Only switch the credentials and webhook secret after the sandbox route is boring and repeatable.

Generate a production Payvra key and replace the sandbox sk_test_... value with sk_live_....

Create a live webhook that points to the same callback URL and store the live whsec_... secret in the app config.

Disable sandbox mode only after the webhook log and Shopify order updates are both stable in rehearsal.

Install the app on the production Shopify store after the development-store path is boring and repeatable.

Refunds

Confirm the store-side refund action maps back to Payvra before you announce the plugin internally.

Open the Shopify order and trigger the refund from the admin refund action rather than handling it as an off-platform support step.

Confirm the app calls the Payvra refund route and that the original payment reference is preserved for reconciliation.

Check both the Payvra dashboard and the Shopify order timeline so operators can confirm the refund cleared on both sides.

Troubleshooting

Use these checks when the plugin path stalls. Each item points to the fastest place to confirm whether the problem is in storefront setup, Payvra delivery, or the operator config.

OAuth or installation fails

Re-check SHOPIFY_API_KEY, SHOPIFY_API_SECRET, and the store hostname used in the install URL. Most install failures come from a mismatch between the deployed app origin and the app settings in Shopify.

Orders do not update after payment

Confirm Payvra is posting to /webhooks/payvra, not the Shopify-facing callback. Then check the Payvra webhook delivery log and the app logs together to see whether the signature failed or the order mutation did.

Deployment looks healthy but checkout still fails

Test GET /health and the payment creation route directly from the deployed origin. If those work but Shopify checkout does not, the gap is usually in the app installation or store permission scope.

HTTPS or callback URL mismatch

Shopify requires HTTPS for every app origin. Make sure the deployed APP_URL, OAuth callback, webhook endpoint, and Partners dashboard configuration all point to the same public origin.

Ready to validate the Shopify path?

Start with sandbox credentials, verify one signed order lifecycle from checkout to paid state, and then promote the exact same app to live mode with only the Payvra secrets swapped.

Get sandbox keys Back to docs

This plugin guide should tell you exactly what to prove before a Shopify checkout sends live order traffic into Payvra.

Keep the rollout boring: install the app on HTTPS infrastructure, verify one sandbox order from checkout to paid state, then swap only the Payvra key and webhook secret when you go live.

1# Shopify Payments App credentials 2SHOPIFY_API_KEY=your_shopify_api_key 3SHOPIFY_API_SECRET=your_shopify_api_secret 4SHOPIFY_SCOPES=write_payment_gateways,write_orders,read_orders 5 6# Public URL for the app (HTTPS required) 7APP_URL=https://your-app.example.com 8PORT=3456 9 10# Payvra credentials 11PAYVRA_API_KEY=sk_test_... 12PAYVRA_WEBHOOK_SECRET=whsec_test_...