Alternative Hosted iFrame 2.0

The hosted page allows you to open the MiFinity payment cashier in a separate window via a provided unique URL. Rather than loading the Javascript widget to open the page after retrieving the token, in the hosted page we will simply return the URL which you will need to open on your end. When the customer finishes, their browser returns to the redirectUrl you send in the request.

How it works

1. Create a session. POST to init-iframe with entry set to hosted and your redirectUrl.
2. Open the cashier. Send the customer's browser to iframeEntrypoint from the response. That URL already includes the token.
3. Customer pays on the hosted page.
4. Customer returns. The browser is sent to redirectUrl. That only means the session ended.
5. Confirm the payment. Your server receives a callback on returnUrl or errorUrl. Then call Payment Status with the validationKey from this request. Credit the customer only when that status is successful.

Hosted and embedded

returnUrl and errorUrl work the same in both flows. They are where MiFinity posts the payment result. redirectUrl is only the page the customer's browser comes back to.

Initialize the session

This call creates the session. It does not open the cashier.

The response includes iframeEntrypoint. Send the customer's browser there. On demo that host is demo.mifinity.com. In production, use the iframeEntrypoint from the response (secure.mifinity.com). Do not POST to the cashier URL.

Fields for the hosted page

These two fields select the hosted cashier. Every other field matches iFrame Initialization.

Nested objects

Request example

entry and redirectUrl are the hosted-page fields.

{
  "traceId": "50764c56-7b7f-4424-906d-1ddc5d1c4ae1",
  "money": {
    "amount": 20,
    "currency": "EUR"
  },
  "description": "Deposit to Test Merchant",
  "validationKey": "validation_keyc6d2a2d4-e00a-4c0f-82d8-8f9e8a103157",
  "returnUrl": "https://merchant.example.com/payments/callback",
  "errorUrl": "https://merchant.example.com/payments/callback",
  "destinationAccountNumber": "5001000000000001",
  "brandId": "001",
  "address": {
    "addressLine1": "Swords Enterprise Park",
    "addressLine2": "",
    "countryCode": "DE",
    "postalCode": "123456",
    "city": "Dublin"
  },
  "client": {
    "dob": "1990-12-01",
    "firstName": "Sherlock",
    "lastName": "Holmes",
    "nationality": "DE",
    "emailAddress": "[email protected]",
    "phone": "871234567",
    "dialingCode": "353"
  },
  "clientReference": "client-1001",
  "entry": "hosted",
  "redirectUrl": "https://merchant.example.com/cashier/return"
}

Response

The field to use in the browser is iframeEntrypoint. initializationToken is the same token the embedded widget would use. You do not need to build the cashier URL yourself.

{
  "payload": [
    {
      "traceId": "50764c56-7b7f-4424-906d-1ddc5d1c4ae1",
      "initializationToken": "2_sg8fuVRHS34FkdVTHgxRC905pj_P5y7aQCEyNAj83R_…DRmZ8vyc=",
      "client": {
        "dob": "1990-12-01",
        "firstName": "Sherlock",
        "lastName": "Holmes",
        "dialingCode": "353",
        "phone": "871234567",
        "nationality": "DE",
        "emailAddress": "[email protected]"
      },
      "address": {
        "addressLine1": "C1 Swords Enterprise Park",
        "addressLine2": "",
        "countryCode": "DE",
        "postalCode": "123456",
        "city": "Dublin"
      },
      "iframeEntrypoint": "https://demo.mifinity.com/iframe2#initToken=2_sg8fuVRHS34FkdVTHgxRC905pj_P5y7aQCEyNAj83R_…DRmZ8vyc="
    }
  ]
}

The live initializationToken and iframeEntrypoint are long. The example above is shortened.

Redirect the browser to iframeEntrypoint. After the customer finishes, MiFinity sends that browser to redirectUrl.

After the customer returns

Show a waiting or return page on redirectUrl. Then settle the payment on your server:

1. Receive the callback on returnUrl (success) or errorUrl (failure). See Payment Status Callback.
2. Match traceId and validationKey to the values you sent in init-iframe.
3. Call Payment Status with that validationKey.
4. Update the customer's balance only when the status is successful.