Skip to main content

Web (JS)

Quickstart​

This quickstart shows how to integrate CashOver's Web SDK to accept fast, secure payments directly from your HTML or JavaScript applications.

You can also check out our example app on Github.

Before Getting Started​

Make sure you:

  • Have a CashOver merchant account
  • Have created at least one store inside your merchant dashboard
  • Know your merchantUsername and storeUsername

Step 1: Install CashOver Pay SDK​

You can install the CashOver SDK in your web app via CDN. We provide different versions to suit your development and production needs:

For production deployments, use the specific versioned minified script with SRI for enhanced security:

<script 
  src="https://cdn.cashover.money/js-sdk/0.1.0/cashover.min.js"
  integrity="sha384-[SRI_HASH_HERE]"
  crossorigin="anonymous">
</script>

Benefits:

  • Minified for optimal performance
  • Version-locked for stability
  • SRI hash ensures file integrity and security
  • Recommended for all production environments

This will expose a global cashover-pay-button object that you can use to initiate and manage payments.

Step 2: Configure the Payment​

To initiate a CashOver payment, you'll need the following parameters — all available in your merchant dashboard:

ParameterRequiredDescription
merchantUsername✅ YesThe merchant account username where the payment will be received. Example: market.example.
storeUsername✅ YesThe specific store username processing the transaction. Example: store.example.
amount✅ YesThe transaction amount to be charged. Example: 49.99.
currency✅ YesThe currency code for the transaction (e.g., USD, LBP). Always follow the correct precision
webhookIds❌ NoOptional list of webhook IDs to notify upon payment status changes. Example: ['id1', 'id2'].
metadata❌ NoOptional additional information about the transaction in json format.
language❌ NoThe language code for localization (e.g., en).
borderRadius❌ NoOptional UI parameter defining the border radius of the button, we advise to keep in the default format. Example: 8px.
theme❌ NoOptional UI parameter defining theme of the button. Example: light.

⚠️ Make sure the values are accurate. Incorrect usernames or IDs may cause payment failures.

Step 3: Use the Prebuilt Payment Button​

CashOver provides a prebuilt payment button that handles the entire flow:

 <cashover-pay-button
              merchantUsername="drop.market"
              storeUsername="al.beik"
              amount="43.18"
              currency="USD"
              webhookIds="['id1', 'id2']"
              metadata='{"orderId":"A1001", "email":"testEmail@mail.com", "country":"", "postalCode":"1"}'
              language="en"
              theme="light"
              borderRadius="8px"
            >
  </cashover-pay-button>
  • metadata: Useful to tag the payment with contextual data like an orderId or sessionId

Step 4: Handle the Payment Result​

Launching the CashOver App​

After the user clicks the pay button, the CashOver Pay page will open automatically and the user will complete the payment.

Verifying Payment Status​

To determine if a payment was successful, implement webhooks in your backend.

Typical workflow:

  1. Attach metadata (e.g., orderId) when the user initiates a payment.
  2. Your webhook endpoint receives payment status updates from CashOver.
  3. Update your order status in your system based on the webhook payload.
  4. Reflect the updated status in your UI (for example, displaying "Payment Confirmed").

Using webhooks is the most reliable way to synchronize payment data and follows best practices in the payment industry.

Version Management Best Practices​

Production Deployments​

  • Always use specific version numbers (e.g., 0.1.0)
  • Use the minified version (cashover.min.js) for better performance
  • Always include SRI hash for security
  • Test thoroughly before deploying version updates

Development Environment​

  • Use the latest version for access to newest features during development
  • Switch to a specific version before moving to production
  • Monitor our changelog for breaking changes between versions

Available Versions​

Versioncashover.js Hashcashover.min.js Hash
v0.1.0sha384-QAb2Rqrh1oNccLEO0k724DTi+iphADm918RUS5NfAafxvvY/TPvRAPIQ1zILwQ1Tsha384-wsxBQKs56ap0SQmua1ulua0H/FMmsnvAFrkW4wf133dkaHKVq4ExpSEFuybS3XJ2
latestsha384-QAb2Rqrh1oNccLEO0k724DTi+iphADm918RUS5NfAafxvvY/TPvRAPIQ1zILwQ1Tsha384-wsxBQKs56ap0SQmua1ulua0H/FMmsnvAFrkW4wf133dkaHKVq4ExpSEFuybS3XJ2

You're Ready!​

CashOver's Web SDK and prebuilt UI components make it easy to launch reliable, secure payments in your web apps with just a few lines of code.

CashOver Web SDK Screenshot