iFrame JavaScript Widget

Integrate MiFinity's payment widget into your website using the iFrame JavaScript snippet.

Widget URLs

Environment	URL
Demo	`https://demo.mifinity.com/widgets/sgpg.js?58190a411dc3`
Production	`https://secure.mifinity.com/widgets/sgpg.js?58190a411dc3`

Integration

Once you have the initializationToken, add the following JavaScript to your page:

<script src="https://demo.mifinity.com/widgets/sgpg.js?58190a411dc3"></script>
<div id="widget-container"></div>
<script>
    var widget = showPaymentIframe("widget-container", {
        token: "initializationToken_example",
        complete: function() {
            // Close the widget after 5 seconds
            setTimeout(function() {
                widget.close();
            }, 5000);
        }
    });
</script>

The token parameter accepts the initializationToken returned from the initialization API. This token contains encrypted payment info used to render the iFrame.

Callback Functions

The showPaymentIframe function supports three callback functions:

Callback	Description
`complete`	Called when the payment flow finishes, regardless of outcome (success or failure). In the example above, the iFrame closes after 5 seconds.
`success`	Called when the payment succeeds. Use this to redirect the client to a success page.
`fail`	Called when the payment fails. Use this to redirect the client to a failure page.

⚠️
Do not trust client-side callbacks (success and fail) to move funds or update balances. These run in the browser and can be manipulated. Wait for a server-side notification on your returnUrl and call the /payment-status endpoint instead.

Payment Verification

When the payment is processed, MiFinity sends a POST request to your returnUrl with a JSON payload. Follow these steps to verify the transaction:

Wait for the notification on your returnUrl.
Verify the transaction authenticity by checking the traceId and validationKey you passed to the init-iframe API call.
Call the /payment-status endpoint to confirm the result.
Update the client's balance only after verification.

✅
Always verify the transaction using traceId and validationKey before updating the client's balance.