Modem Pay’s inline integration allows you to seamlessly add a payment option directly to your website, enabling your customers to make payments without leaving the page. This integration provides a smooth and efficient checkout process, ideal for businesses looking to enhance user experience and maximize conversion rates.

By using this integration, you can implement a “Pay Now” button that triggers a payment flow directly on your site, avoiding pop-ups or redirects. This is especially useful for scenarios like product purchases, service subscriptions, or event ticket sales.

​
Example: Setting Up Inline Payment

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Modem Pay</title>
    <link rel="stylesheet" href="https://api.modempay.com/dist/main.css" />
    <script src="https://api.modempay.com/js/v1.js"></script>
  </head>
  <body>
    <h1>Inline Payment Example</h1>
    <button type="button" onclick="makePayment()" id="start-payment-button">
      Pay Now
    </button>

    <script>
      function makePayment() {
        const modal = ModemPayCheckout({
          amount: 450,
          public_key:
            "pk_test_e073bbf9db47b09cebfdf2f7ec147d02116b69ea55135e1747a0bc8d47612f69",
          payment_methods: "wallet,card,bank",
          callback: (transaction) => {
            console.log("Payment completed:", transaction);
            // Handle post-payment actions
            modal.close();
          },
          onClose: (cancelled) => {
            if (cancelled) {
              console.log("Payment was cancelled.");
              // Handle payment cancellation
            }
          },
        });
      }
    </script>
  </body>
</html>

​
Calling the ModemPayCheckout() Function

Let’s examine the parameters provided when invoking ModemPayCheckout() in detail:

FieldDescriptionExample
amountThe amount to be charged.450 (for GMD 450.00)
currencyThe transaction currency (default: GMD)."GMD"
payment_methodsAvailable payment methods (card, wallet, bank)."card,wallet,bank"
titleA short title describing the transaction."Course Payment"
descriptionDetailed description of the transaction."Access to Premium Content"
customerA unique identifier for the customer."7e1908bb-bd62-4d20-9af7-3463a150fd98"
customer_emailCustomer’s email address."customer@example.com"
customer_nameFull name of the customer."John Doe"
customer_phoneCustomer’s phone number."7000000"
metadataA JSON object for additional payment information.{ "order_id": "98765" }
return_urlURL to redirect to after successful payment."https://yourwebsite.com/success"
cancel_urlURL to redirect to if the payment is canceled."https://yourwebsite.com/cancel"
callbackFunction to handle post-payment actions.(transaction) => { ... }
onCloseFunction to handle when the modal is closed or payment is canceled.(cancelled) => { ... }

Public Key

Keep in mind that this is client-side code, so it utilizes your public key rather than your secret key.

​
How Callbacks and onClose Work

Here’s an example that demonstrates how to use both the callback and onClose functions. The callback function sends a verification request to the backend in the background. Meanwhile, the onClose function handles the modal closure by displaying a “verifying” message if the background request is still in progress, or a thank-you message if the verification succeeds. If the verification fails, the user is prompted to retry or contact support.

View: https://codepen.io/mercury-sms/embed/EaYNGOv

​
callback: Handling Successful Payments

The callback function allows you to perform actions after a successful payment. For instance, you can verify the transaction, send a confirmation email, or update your database. The transaction parameter contains essential information about the payment.

The redirect_url takes priority over the callback. If both are provided, the redirect_url will be used.

javascript
function makePayment() {
  const modal = ModemPayCheckout({
    public_key:
      "pk_test_e073bbf9db47b09cebfdf2f7ec147d02116b69ea55135e1747a0bc8d47612f69",
    // ...
    callback: function (transaction) {
      // Handle the transaction success and verify on backend
      verifyTransactionOnBackend(transaction.id, modal);
    },
  });
}

Always verify the payment on your server after the transaction, even if a callback was used.

Keep in mind that the callback function is triggered after the payment is completed, even while the modal remains open. For an enhanced user experience, you can combine the callback with the onClose handler.

​
onClose: Handling Payment Cancellations

The onClose function is invoked when the customer cancels the payment by closing the modal. This is particularly useful for logging or notifying users of incomplete transactions.

javascript
function makePayment() {
  const modal = ModemPayCheckout({
    public_key:
      "pk_test_e073bbf9db47b09cebfdf2f7ec147d02116b69ea55135e1747a0bc8d47612f69",
    // ...
    onClose: function (cancelled) {
      if (cancelled) {
        // handle cancellation
      }
    },
  });
}

​
Precedence Between callback, return_url, and onClose

  • return_url vs callback:
    If both are provided, the return_url will take precedence, and the user will be redirected to the specified URL after the payment instead of executing the callback function.

  • cancel_url vs onClose:
    If a cancel_url is provided, it overrides the onClose function, and the user will be redirected to the specified URL upon cancellation.

​
Webhooks

If you have configured webhook notifications for your account, we will send a webhook when the payment is completed, as well as for any failed payment attempts. Here’s an example of the webhook payload:

{
  "event": "charge.succeeded",
  "payload": {
    "id": "23419194-7324-4c2b-a74b-d8fba736e692",
    "type": "payment",
    "amount": 2500,
    "currency": "GMD",
    "payment_method": "qmoney",
    "customer": "0f6e0912-2f2f-4d8b-bd68-ac8c97c44ae6",
    "metadata": {},
    "status": "completed",
    "payment_link_id": null,
    "custom_fields_values": {},
    "business_id": "a10a51ae-05c8-406e-968c-7b1d309a77e0",
    "account_id": "7788dd90-3801-47a6-8597-b46eaa0a7d7d",
    "test_mode": true,
    "customer_name": "Caleb Okpara",
    "customer_phone": "7024725",
    "customer_email": "calebchibuike110@gmail.com",
    "createdAt": "2024-12-15T09:34:17.036Z",
    "updatedAt": "2024-12-15T09:34:43.306Z",
    "payment_account": ".... 9944",
    "payment_metadata": {
      "os": "MacOS",
      "browser": "Firefox",
      "ipAddress": "196.223.149.183",
      "timestamp": "2024-12-15T09:34:43.266Z",
      "deviceType": "Desktop",
      "urlIPAddress": "https://db-ip.com/196.223.149.183",
      "screenResolution": "1600x900"
    },
    "payment_intent_id": "273ac751-369d-4198-8340-da480208bded",
    "transaction_reference": "VOAO1CFEN7",
    "payment_method_id": "4dbaaec5-7a16-4908-8fd9-c3d2bd24f739"
  }
}

​
Why Use Inline Payments?

Inline payment integrations provide a frictionless experience by letting users complete payments without leaving your page. This approach minimizes drop-offs during checkout and enhances customer satisfaction.

Perfect for:

  • E-commerce Sites: Add quick payment buttons on product pages.
  • Subscription Services: Charge for recurring services effortlessly.
  • Event Ticketing: Allow customers to book and pay on the same page.

By incorporating features like callback and onClose, you gain full control over the payment flow and can provide a seamless experience tailored to your users’ needs.