---
updatedAt: 2026-03-31T09:17:22.000Z
agentTools:
  projectIndex: https://docs.zerohash.com/llms.txt
---

# Fiat Account Link

Use this developer guide for an efficient integration to the Fiat account link SDK

> 📘 Requires SDK version >= 2.12.5

## Acquire Access Token

To invoke the Fiat Account Link SDK, you'll need to acquire an access token requesting the fiat account link permission. Please see our detailed [guide](https://docs.zerohash.com/reference/retrieving-access-token) for instructions on how to setup calls to our endpoints. After this,  you should request an access token specifying:

| Field              | Description                                                                                                                                                                                                                          | Example Value            | Required? |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------- | :-------- |
| `participant_code` | The 6-digit alpha numeric code associated with the Customer that is looking to withdraw (the response of the original [POST /participants/customers/new](https://docs.zerohash.com/reference/post_participants-customers-new)  call) | CUST01                   | Y         |
| `permissions`      | The array of permissions that will be granted to the returned JWT token                                                                                                                                                              | `["fiat-acccount-link"]` | Y         |

Example `POST /client_auth_token` request:

```c JSON
 {
    "participant_code": "CUST01",
    "permissions": ["fiat-account-link"]
}
```

After obtaining the access token, you can start using the SDK.

## Web Application

We recommend to first read our [Overview](https://docs.zerohash.com/reference/sdk-overview), [Installation](https://docs.zerohash.com/reference/sdk-instalation) and [Getting Started](https://docs.zerohash.com/reference/sdk-getting-started) guides.

Example using React:

```typescript
import React from 'react';
import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';

const App = () => {
  const sdk = new ZeroHashSDK({
    zeroHashAppsURL: "https://web-sdk.cert.zerohash.com", //prod: https://web-sdk.zerohash.com
    fiatAccountLinkJWT: "<JWT_TOKEN_HERE>" 
  });

  sdk.openModal({ appIdentifier: AppIdentifier.FIAT_ACCOUNT_LINK }) // This enum maps to "fiat-account-link"
  return <></>;
}

export default App;
```

For a line by line explanation on how to integrate, please take a look at the following guide:

[block:tutorial-tile]
{
  "backgroundColor": "#00fa97",
  "emoji": "🌐",
  "id": "66d70c0c9431d7003a1a7c16",
  "link": "https://docs.zerohash.com/v1.0/recipes/web-sdk-integration",
  "slug": "web-sdk-integration",
  "title": "Web SDK Integration"
}
[/block]

<br />

## Events (postMessage)

Below you can see the list of events our SDK might emit depending on the situation.

| Message                                     | Meaning                                                                                                                                                |
| :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| FIAT\_ACCOUNT\_LINK\_APP\_LOADED            | The SDK is loaded and visible to the customer.                                                                                                         |
| FIAT\_ACCOUNT\_LINK\_CLOSE\_BUTTON\_CLICKED | The close (X) button was clicked in the top right corner of the UI.                                                                                    |
| FIAT\_ACCOUNT\_LINK\_COMPLETED              | The account was created successfully with our 3rd party provider.                                                                                      |
| FIAT\_ACCOUNT\_LINK\_FAILED                 | There was an error when linking the account. The user can still retry linking his account in the same session if if this event is fired.               |
| SDK\_MOBILE\_READY                          | The SDK is ready to receive postMessage events (e.g OPEN\_MODAL) -- Useful for Native mobile integrations (Flutter, Swift, etc.)                       |
| TOKEN\_EXPIRED                              | The token is expired and needs to be refreshed. See [Acquire Access Token](https://docs.zerohash.com/reference/retrieving-access-token) to refresh it. |

## Mobile Application (WebView)

To use our SDK on mobile apps, you don't need to install or include `zh-web-sdk` as a dependency in your project. We use a proxy server that calls the SDK internally to make it work for mobile applications. For more info, head to our [Integration with Mobile Apps](https://docs.zerohash.com/reference/sdk-integration-with-mobile-apps) page and select the platform you're using to build your app.

### Events

We forward events from the UI to the native app using the postMessage API. You can handle these events from the WebView component. The events are listed at the **Events** section.

### Messages

To control the WebView, you can also send messages using the postMessage API after receiving `SDK_MOBILE_READY` from WebView. Currently, the accepted messages are:

#### Open Modal

Opens the modal with the JWT provided for identifier provided.

```json
{type: "OPEN_MODAL", payload: {jwt: "<JWT_HERE>", appIdentifier: "fiat-account-link"}}
```

#### Close Modal

Closes the modal for identifier provided.

```json
{type: "CLOSE_MODAL", payload:{appIdentifier: "fiat-account-link"}}
```

For more details on how to use our SDK with WebViews, please refer to [Integration with Mobile Apps](https://docs.zerohash.com/zerohash/reference/sdk-integration-with-mobile-apps)