---
updatedAt: 2026-08-19T12:30:00.000Z
agentTools:
  projectIndex: https://mifinity.readme.io/llms.txt
---

# iFrame Initialization

Initialize the MiFinity eWallet iFrame to collect payments from your customers.

Initialize the eWallet iFrame to present your customers with a hosted payment interface. This endpoint returns an `initializationToken` that you use to render the iFrame on your page.

<Callout icon="🔗" theme="info">
  **POST** `https://demo.mifinity.com/api/gateway/init-iframe/`
</Callout>

## Headers

| Parameter     | Type   | Description        |
| :------------ | :----- | :----------------- |
| Content-Type  | String | `application/json` |
| Accept        | String | `application/json` |
| x-api-version | String | `1`                |
| Key           | String | Your API key       |

***

## Request Parameters

| Name                     | Type                                  | Required | Description                                                                                                                                                                                                                                                                                                             |
| :----------------------- | :------------------------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| returnUrl                | URL                                   | Yes      | Callback URL for successful transfers. Receives a JSON `ApiSGPGPaymentResponse` object. Results are sent asynchronously once the remote processor executes the transfer (this can happen after the iFrame closes). Execution time varies by processor.                                                                  |
| errorUrl                 | URL                                   | No       | Callback URL for failed transfers. Receives a JSON `ApiSGPGErrorResponse` object. Results are sent asynchronously once the remote processor executes the transfer (this can happen after the iFrame closes). Execution time varies by processor.                                                                        |
| validationKey            | String                                | Yes      | Secret key to validate the payment response and retrieve payment status. Generate this on your end — it must be unique per request. Min 48, max 255 characters.                                                                                                                                                         |
| client                   | [SGPGPlatformUser](#sgpgplatformuser) | Yes      | Object containing client information. All fields except `emailAddress` can be edited within the iFrame.                                                                                                                                                                                                                 |
| clientReference          | String                                | Yes      | Your internal client identifier. Max 48 characters.                                                                                                                                                                                                                                                                     |
| address                  | [SGPGAddress](#sgpgaddress)           | Yes      | Object containing the client's address. Editable within the iFrame.                                                                                                                                                                                                                                                     |
| traceId                  | String                                | Yes      | Your unique identifier for this call. Max 48 characters.                                                                                                                                                                                                                                                                |
| money                    | [Money](#money)                       | Yes      | Object containing the transfer amount and currency.                                                                                                                                                                                                                                                                     |
| description              | String                                | Yes      | Transfer description. Max 255 characters (Sofort/Klarna deposits are limited to 27 characters).                                                                                                                                                                                                                         |
| destinationAccountNumber | String                                | Yes      | Your MiFinity account number to collect the payment.                                                                                                                                                                                                                                                                    |
| iframeId                 | EntityId                              | No       | Specify if you have multiple iFrames with different types.                                                                                                                                                                                                                                                              |
| brandId                  | String                                | Yes      | A 3-digit ID provided by MiFinity indicating which brand the call is made through.                                                                                                                                                                                                                                      |
| languagePreference       | String                                | No       | 2–5 character language code for the iFrame. Defaults to English (`EN`). Supported values: `BR`, `PT_BR`, `CN`, `ZH_CN`, `DE`, `DK`, `DA`, `DA_DK`, `EN`, `ES`, `FI`, `FR`, `GR`, `EL`, `EL_GR`, `HR`, `IT`, `JP`, `JA`, `JA_JP`, `LA`, `ES_LA`, `NL`, `NO`, `PL`, `PT`, `RU`, `SV`, `SE`, `SV_SE`, `ZH`, `TW`, `ZH_TW`. |
| logoUrl                  | URL                                   | No       | URL of a logo to display below the iFrame header (centered). The logo container has a max height of 45px — the image is resized to fit while preserving aspect ratio. Use small images to minimize load time.                                                                                                           |
| paymentMethod            | String                                | No       | Payment method to initialize the iFrame with. Required when using the Split Gateway feature.                                                                                                                                                                                                                            |

***

## Nested Objects

<Accordion title="SGPGPlatformUser" icon="fa-info-circle">
  <a id="sgpgplatformuser"></a>

  | Name         | Type      | Required | Description                         |
  | :----------- | :-------- | :------- | :---------------------------------- |
  | dob          | LocalDate | Yes      | Date of birth. Format: `YYYY-MM-DD` |
  | firstName    | String    | Yes      | First name. 1–20 characters.        |
  | lastName     | String    | Yes      | Last name. 1–20 characters.         |
  | phone        | String    | Yes      | Phone number.                       |
  | dialingCode  | String    | Yes      | International dialing code.         |
  | nationality  | String    | Yes      | ISO 3166-1 alpha-2 country code.    |
  | emailAddress | String    | Yes      | Email address. Max 50 characters.   |
</Accordion>

<Accordion title="SGPGAddress" icon="fa-info-circle">
  <a id="sgpgaddress"></a>

  | Name         | Type   | Required | Description                                |
  | :----------- | :----- | :------- | :----------------------------------------- |
  | addressLine1 | String | Yes      | Building name/number. Max 200 chars.       |
  | addressLine2 | String | No       | Street name. Max 60 chars.                 |
  | countryCode  | String | Yes      | ISO 3166-1 alpha-2 country code (2 chars). |
  | postalCode   | String | No       | Postal code. Max 50 chars.                 |
  | state        | String | No       | State code. Max 2 chars.                   |
  | city         | String | Yes      | City name. Max 30 chars.                   |
</Accordion>

<Accordion title="Money" icon="fa-info-circle">
  <a id="money"></a>

  | Name     | Type       | Required | Description                       |
  | :------- | :--------- | :------- | :-------------------------------- |
  | amount   | BigDecimal | Yes      | Transfer amount.                  |
  | currency | String     | Yes      | Currency code in ISO 4217 format. |
</Accordion>

***

## Request Example

```json Request Body
{
  "returnUrl": "https://your-site.com/payment/success",
  "errorUrl": "https://your-site.com/payment/error",
  "validationKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "client": {
    "dob": "1985-10-10",
    "firstName": "John",
    "lastName": "Smith",
    "dialingCode": "353",
    "phone": "81234567890",
    "nationality": "GB",
    "emailAddress": "john.smith@example.com"
  },
  "clientReference": "client-ref-12345",
  "address": {
    "addressLine1": "Baker str 212B",
    "countryCode": "IE",
    "postalCode": "123456",
    "city": "London"
  },
  "traceId": "traceIdutTn7_14bQWAsAARrdUeV",
  "money": {
    "amount": 100.00,
    "currency": "EUR"
  },
  "description": "Deposit to account",
  "destinationAccountNumber": "1001001",
  "brandId": "001",
  "languagePreference": "EN"
}
```

***

## Response

### Success Response Fields

| Name                | Type                                  | Description                                          |
| :------------------ | :------------------------------------ | :--------------------------------------------------- |
| traceId             | String                                | The trace ID submitted with the request.             |
| initializationToken | String                                | Encoded token used to render the iFrame.             |
| client              | [SGPGPlatformUser](#sgpgplatformuser) | Object containing the submitted client information.  |
| address             | [SGPGAddress](#sgpgaddress)           | Object containing the submitted address information. |

```json Successful Response (200)

  "payload": [
    {
      "traceId": "traceIdutTn7_14bQWAsAARrdUeV",
      "initializationToken": "75lh4Lh_M5SCrA_k4Yse-Z_5NYk95eq6jKcovrOhoSS291nXBhv7EQAgZeBvaZ5SSaHI8aYibqSOPuWRaliSyCmp2JhWQw1PNhA0Rs0PKnti8tY-rG_k_rFpO636m0oX5yx446YyBNO0IOcvFvTHQPdGTBXQM1rFqpyk3hELFI3q0FKcIqqjzoGqjcFzuO6pSwUM1BsBxnRL6JUcVtsCm_EOlk2W_iyD0Ek_Myv-WRQxyHLxpfb_oOwVvKF8CVmhmlwBMEevnkjokQfUmiXzeUdjzjGzLTcbYzQnkoF5INCyxxzRCZSs-hJ0nLEUkFtqAALTA7Wrlh-wtcf-2Bsj75DenzDkvGUjiB_mVYlFrKHvVF8onm3WZgt3dOmD9BkdTkeVhuWUtAGa_3AnuarcmYG59NqPWyt__BjtBCErwd_i_H8dQSw0ClkOWcNzvrpUlr_tHucUMZQRERW1CzC5OF8o1-UKxYkn4TIPJIu6RxqZhe_A35RqzsgmJptuzedNMuL5uZ12y_yE-xgCidD5MdjO-_4kn2b75FdMRhIcQp5AQEfUaZWyB7J1PQiCpBzEwVZ9QZMprpAhxhrw03Ad3_PsckmqeSRAuMx8bodldaa3GjrYQZnBRauK5S2aNJEv9cvkU74t0sr4R1ITSTWG7ge4xQQYg_h2ZnA58Qeus3cp32wM7o4OreznS1gvJhnqojVyIHR3LGu-4hfMgsV93SPL4Ao-DCZAGXjSufBYzlURT9lon376fmmNvIUdjnOuniYLPf9cA1gQOx_w81TG_iUDDDo9RA2Oe3Ouj_wzd6lD2eIn8Id9FEtUZ4RA8QGCnpCPuqjeyo4XGnMHUzfOgC_aqPQuJZTevYyfvcDOVium_jS1hSpZ3lWqhTaekQO8Dqjb8pi8HTcUgd1yH02ybaeCBB-k7g_kXmNJb1o2ZfdTrOjm88uy_-GsdM2D0Md7jvZHFZEWXmZCRZXfTDgAPVO5Z7RhMM-AU7tpodEXsLHjAyHKvQwjQTI0yCFZf-2oc_k5RdO7cPqiPHyrlX530n3YufapockDQXNG41opFzjdDT5swe4wOfE7zLcFIXnyV6_535UFKqP6UOYj0LlGc4f3osp70sfR2o-67kOpgcSeTwFPWTsdfmu4llTqv813_GvLa4aQ2s_ottTF7XmaXZ5HcNugmbDpwKJ8dxbvBIDl2fYlxyLG7XXcpSx0mJYOOUQeZgIsyIm6ogf6wQd7HWe81a7ofDO8AkDbZ6T_w75jmZJR8rolPWa8nfHenHMDGbnfFTThHbffWCZpSL7fQtRLNmpeXuQlgymPDK0I_U1_c7W5drXi9UQ08pz0KTuoBuah7dkdKaBDLNa-lopTTa6_lKI-PaknpOBBiFjMfeOtUDYQ6jlqWcZkk-XU7WbtnqNAWXNi5De_mSNNo3BOJwn_JEFPr0IZz7GUdNJs7e3ra_LtERLGQB_HtPE0_nEoEvd923RXFrVrZQSQkZBBu9MB8UMr95L7Dws0IvgnDGUTk5ct6sRssY7otR0ZxcFSaa-tfyHdLyCSkK0xH3MSMPPaDM6YYaCRsDFZ8-UauyQdDeqmvSFpsEzpqtsnI2rEjXi5StMf-N_1PbUXm7gavKBYWSU_e4--BQDzmel6EJ8Rz_ovuNaCOSUEH3owHGGN9s6tUszkTsn9-5e0xYHqq6O6CsX3PagkOYtrnhhPr81mMUO5KS72u_472utM2A8ZJQYuLcZ6bd1fmA7QN1p3YGMb9bOtoN8M9VwmXX8ovwyaI8DLYjwImy2FDiSn127docOecnU1IZ5s1UQFSIpbf4lsgb_bmeQmWFdsOaOfeV8R-zZsUJ2w_jvlelK9n9688tO97Ei2tlUTM6-ptM_nRBld4YcHm9gOfx7qSH0lktvcYTQqnqB25mpj6vyj8py8rXPC_KZiFuhjOfgqX2AW45JQ4sLlk2kRdXX8SNohvGfMuENWIUVJ5jUcxOLb4s6knDp7zRuC_UE0I-Z0jxuT1k71FRw0_bAo9MHCOc9XVQ7vg92Gzj6CICzajg_Uc4NW0ZDKVXkvts2AqHrGRM146DQbu18kk9UUqC3RC33_INvWMzd2iwet9-JVEh7_y2MBl0pHM8AzZO8ROYooeEpoRLXCagtPoV3v594seHzww0I23m1H80DFhCfj24cWBgYdPtu9788WoD81-ewpAaB6LQlIyu8c33Szqo7SXnDy-3s=",
      "client": {
        "dob": "1985-10-10",
        "firstName": "John",
        "lastName": "Smith",
        "dialingCode": "353",
        "phone": "81234567890",
        "nationality": "GB",
        "emailAddress": "tmifinity+ashah2@gmail.com"
      },
      "address": {
        "addressLine1": "Baker str 212B",
        "countryCode": "IE",
        "postalCode": "123456",
        "city": "London"
      }
    }
  ]
}
```