VenPAY

Checkout

JavaScript checkout SDK

Embed a card checkout widget on your page. The shopper pays on the VenPays hosted card page — card numbers never touch your site or this SDK.

This version is card only. Benefit, BenefitPay, and Apple Pay are not available in the widget yet; use hosted checkout for those methods.

Credentials

CredentialWhere it livesWhat it does
Secret (sk_…) or existing unprefixed keyYour serverCreates the checkout session and sets the amount
Publishable (pk_…)BrowserActivates the widget and selects sandbox vs live from the prefix. Cannot charge, refund, or set the amount

Never put a secret or legacy key in frontend JavaScript. The publishable key only identifies your merchant. Restrict it to your checkout origins in the dashboard if you want.

1. Create a session on your server

POST /v1/sdk/checkout
Host: init-vpay.venlabs.link
X-API-KEY: sk_test_…
Content-Type: application/json

{ "amount": 12.500, "currency": "BHD" }

Live host: merchant.venpays.com. Use a secret or legacy key, not the publishable key.

The response includes track_id. Pass that id to your checkout page.

2. Load the widget

Install from npm:

npm install @venpays/checkout

Or load the script (same file for sandbox and live; the key picks the API host):

<div id="venpays-checkout"></div>
<script src="https://init-vpay.venlabs.link/js-sdk/venpays-checkout.js"></script>
<script>
  VenPays.init({
    publishableKey: "pk_test_…",
    trackId: "TRACK_ID_FROM_YOUR_SERVER",
  }).then(function (checkout) {
    checkout.mount("#venpays-checkout");
  });
</script>
Publishable keyEngine the SDK calls
pk_test_…Sandbox (init-vpay.venlabs.link)
pk_live_…Live (merchant.venpays.com)

init checks the publishable key, then loads the session. The shopper clicks pay and is redirected to the card page.

A dedicated public CDN (js.venpays.com) is the planned long-term script host so you are not tied to either engine URL for the <script> tag.

3. Confirm on your server

After the shopper returns, treat the browser status as a hint only. Fulfill the order from a webhook or POST /merchant/payment-status with your secret key. See Payment status and Webhooks.

Optional browser poll after return:

const result = await VenPays.complete({ publishableKey: "pk_test_…" });
// reads track_id from the query string

What the publishable key cannot do

  • Create a session or set the amount
  • Call initiate, refund, or status APIs
  • Substitute for X-API-KEY on your server

If you send a publishable key as X-API-KEY, the Payment Engine rejects the request.

Next
Return URLs