* When connecting to Coinbase via OAuth, the Mesh API key permissions have been mapped to the OAuth permissions. Therefore, the permissions shown to the user in Coinbase's Oauth window will also reflect there properly.
* However, Mesh API key permissions are not currently mapped to other broker integrations beyond Coinbase. For example, if a Read-only Mesh API key is used to link a user’s Binance account to a client app, that Binance authentication still provides both Read & Write capabilities.
* Rest assured, even though the Binance connection to the client-app does support both Read & Write permissions, any calls to the Mesh API will respect the Mesh API key permissions (in this example, a trade or transfer call to the linked Binance account would return a `403` response from the Mesh API).
* This mapping is also not yet in place for other OAuth integrations beyond Coinbase. To discuss this further, please email [support@meshconnect.com](mailto:support@meshconnect.com).
# How to view & configure API key access scopes
* You can create Mesh API keys by going to Accounts —> [API keys](https://dashboard.meshconnect.com/company/keys).
* When creating a new production API key, you will have the option to enable permissions as shown below.
* We strongly recommend naming keys in a meaningful and logical way. For example, you can use the format: `
# null
Source: https://docs.meshconnect.com/guides/error-dictionary
## Possible Ineligibility Reasons
Here are the reasons why holdings cannot be transferred in some cases.
## Configure Transfer Errors
| Error Code | Description | Level Found |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| NoEligibleNetworks | None of the networks supported by Source and Target accounts can be used for the transfer. Individual reasons specifying why a particular network cannot be used may vary. | Holdings |
| SymbolDoesNotMatch | The symbol that was requested for the transfer is different from the holding’s symbol | Holdings |
| NotSupportedForTransferByTarget | None of the networks for that token are eligible to transfer TO the source. This is often due to the **client** not supporting the token for transfer. | Holdings |
| NotSupportedForTransferBySource | None of the networks for that token are eligible to transfer FROM the source. This is often due to **Mesh or the integration** not supporting the token for transfer. | Holdings |
| AmountNotSufficient | The (amount to be transferred + the gas fee) is more than the available balance | Network |
| NoTargetNetworkFound | Target addresses/institution do not contain the corresponding network, so this network cannot be used for the transfer | Network |
| GasFeeAssetBalanceNotEnough | The amount of the asset is sufficient, but there’s not enough balance of the gas fee’s asset (e.g. not enough ETH to send USDC) | Network |
## Preview Transfer Errors
Statuses:
* Succeeded
* Failed
### Error messages (when status = failed)
| Error Code | Error Message |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NetworkIdMissing | (TransferToAddress.NetworkId) field was not provided. |
| AddressMissing | (TransferToAddress.Address) field was not provided. |
| SymbolMissing | (TransferToAddress.Symbol) field was not provided. |
| UnsupportedSymbolByNetwork | Network does not currently support the requested symbol. |
| InvalidAddressPattern | Target address does not match network '{0}' address pattern. |
| NetworkNotFound | Network not found. |
| NetworkDisabled | Network '{0}' is currently disabled and cannot be used. |
| InsufficientFunds | Insufficient '{0}' funds. |
| InsufficientFeeFunds | Insufficient '{0}' funds for transfer fees. |
| EmptyWalletSymbolBalance | Source wallet '{0}' balance is empty. |
| KycRequired | The provided '{0}' account requires KYC to be completed to perform transfers. |
| DepositAmountTooLow | The requested amount is lower than the minimum amount that can be accepted by the target institution. |
| WrongPreviewRequestFromAuthTokenMissing | (PreviewTransferRequest.FromAuthToken) is a mandatory field and should be provided. |
| WrongPreviewRequestNoSymbol | (PreviewTransferRequest.Symbol) is a mandatory field and should be provided. |
| WrongPreviewRequestInvalidToAuthToken | (PreviewTransferRequest.ToAuthToken) is invalid. |
| WrongPreviewRequestToData | Either (PreviewTransferRequest.ToAuthToken) with (PreviewTransferRequest.ToType) or (PreviewTransferRequest.ToAddress) should be provided. |
| WrongPreviewRequestAmount | Both (PreviewTransferRequest.AmountInFiat) and (PreviewTransferRequest.Amount) can not be provided. |
| WrongPreviewRequestNoAmount | Either (PreviewTransferRequest.AmountInFiat) or (PreviewTransferRequest.Amount) should be provided. |
| WrongPreviewRequestUnsupportedSymbolBySourceWallet | Symbol to transfer not supported by the source wallet over the requested network. |
| WrongPreviewRequestUnsupportedSymbolByTargetWallet | Symbol to transfer not supported by the target wallet over the requested network. |
| WrongPreviewRequestNetwork | Requested network is not supported by the source wallet. |
| PriceNotFound | Could not fetch '{0}' price. |
| AmountMoreThanWithdrawMaximum | Could not preview the transfer. The requested amount (previewRequest.Amount) (requestDto.Request.Symbol) is greater than the maximum allowed amount (minimumMaximumAmount.WithdrawMaximumAmount requestDto.Request.Symbol). |
| AmountLessThanWithdrawMinimum | Could not preview the transfer. The requested amount (previewRequest.Amount) (requestDto.Request.Symbol) is below the minimum allowable threshold (minimumMaximumAmount.WithdrawMinimumAmount requestDto.Request.Symbol). |
## Execute Transfer Errors
Statuses:
* Succeeded
* Failed
* MfaRequired
* EmailConfirmationRequired
* DeviceConfirmationRequired
* MfaFailed
* AddressWhitelistRequired
### Error messages (when status = failed)
| Error Code | Error Message |
| -------------------- | ------------------------------------- |
| PreviewExpired | The preview is expired. |
| TransferIsRequested | The transfer is already requested. |
| PreviewNotFound | Could not find the preview. |
| AddressNotRegistered | The target address is not registered. |
# Getting Started
Source: https://docs.meshconnect.com/guides/getting-started
We’re building fintech’s modern connection layer and are excited to help you on your journey toward a single, unified API.
###
### 
* \[Optional] Pass fundingOptions object in linkToken to ensure users can buy more crypto or convert existing crypto in a
transfer flow. This extends Transfer options when a user is paying for a good or
service but doesn’t have enough of the request token. Refer to Account
* Pass a unique transactionId with every transfer initiated in Link Modal
* Pass a transferType key value pay for every linkToken transfer request. Values are: deposit | onramp | payment
* \[Optional] Allow users to send assets over L2’s to save on gas
* \[Recommended] Listen for Mesh transfer webhooks to receive real-time updates
on the transfer lifecycle, including statuses such as pending, succeeded, or failed.
* Completed transfers will include a transaction hash in the response object of the GET Mesh transfers endpoint.
* Mesh monitors transactions on the blockchain for up to 2 hours to obtain a transaction hash. If the hash is not received within this timeframe, an alert is triggered for our on-call team to investigate.
* \[Recommended]
Listen to Client side SDK events: Each SDK provides client-side events to help you
understand the workflow behavior of every Link session. This allows you to push real-time
user experience data to your observability and business intelligence tools (e.g.,
Mixpanel). - \[Optional] Leverage our guides for [handling access tokens](https://docs.meshconnect.com/guides/handling-auth-tokens)
* \[Optional] Error Handling: familiarize yourself with [Mesh Error types](https://docs.meshconnect.com/guides/error-dictionary)
and add retry logic and error handling as necessary
### **Testing**
* Conduct end-to-end testing in the sandbox environment. Please note, Mesh does not support testnets for self-custody wallets. All API and Modal behavior is simulated
* Test webhook data connectivity to your endpoint
* \[Recommnded] Share application build with Mesh to provide any final guidance and feedback
### **Pre-Launch:**
* Notify Mesh team of planned launch
* Upgrade to the latest SDK build and perform functional and UAT testing
### Post-launch
* Notify your Mesh Account Executive and Implementation Specialist
* [Subscribe](https://status.meshconnect.com/) to Mesh status page
### Links
* [Mesh API Docs](https://docs.meshconnect.com/guides/getting-started)
* [Interactive Demo](https://dashboard.getfront.com/docs/interactive-demo)
* [Mesh Workshop](https://workshop.meshconnect.com)
# Link Utilization and Use cases
Source: https://docs.meshconnect.com/guides/link-initialization
## Overview
Mesh Link SDK allow client applications to connect users to their accounts across brokerages, centralized exchanges, and self-custody wallets. Mesh Link UI handles credential validation, multi-factor authentication, and error handling when connecting to each account.
After an end user authenticates with their account credentials, clients will be passed authentication tokens to provide access to the account which allows client applications to read account information such as holdings, transactions, and balances, and initiate trades and transfers on behalf of the end user.
## Getting Your API Keys
You can generate two different API keys (one for Sandbox and another for Production) on the [Mesh Dashboard](https://dashboard.meshconnect.com/company/keys), you should **store the API keys immediately** after generating them as they will no longer be viewable after leaving the page.
> ❗️ These API keys should never be stored on your client-side application, always store them securely on your applications backend, following security best practices.
## LinkToken Endpoint
This [endpoint](/api-reference/managed-account-authentication/get-link-token-with-parameters) provides a short-lived, one-time-use token for initializing a Link session, when passed to one of the client side SDKs. Depending on the payload of the API call, the Link UI will load into different workflows, such as user authentication, or asset transfer.
The LinkToken endpoint should always be called from your backend, since it requires an API secret.
## Link UI Use Cases
In the next section we will go trough the different ways Link UI can be initialized:
## Account Authentication
### Basic Account Authentication
The most basic way to initialize Link is to simply pass the `UserId` body param. The `UserId` is a unique ID representing the end user. This identifier is a map to reference which customers you are logging in through Mesh Link.
```json
{
"UserId": "EndUserId",
}
```
POST /api/v1/linktoken body
### Direct to Exchange or Brokerage Integration
Many of our customers and UI/UX designers want to launch link directly to a specific integration (eg. Binance or Coinbase) and skip our Full Catalogue. This is easily achieved by including the `IntegrationId` param.
The `IntegrationId` of the integration you wish to connect can be obtained by calling the **[Retrieve the list of all available integrations.](/api-reference/managed-transfers/get-integrations)** endpoint and referencing the `id` field.
```json
{
"UserId": "EndUserId",
"IntegrationId": "9226e5c2-ebc3-4fdd-94f6-ed52cdce1420"
}
```
POST /api/v1/linktoken body
### Direct to Self Custody Wallet
Many of our customers and UI/UX designers want to load up Link directly to a specific wallet (eg. Metamask) and skip our Full Catalogue. This is easily achieved by including the `IntegrationId` param.
The `IntegrationId` of the integration you wish to connect can be obtained by calling the **[Retrieve the list of all available integrations.](/api-reference/managed-transfers/get-integrations)** endpoint and referencing the `id` field.
```json
{
"UserId": "EndUserId",
"IntegrationId": "34aeb688-decb-485f-9d80-b66466783394"
}
```
POST /api/v1/linktoken body
### Restricting User to Connect only One Account
By default, Link UI lets users authenticate with more than one provider in one session. This is great for portfolio management use cases or when a user wants to transfer from one provider to another within your application. To limit the authentication to one provider, set the RestrictMultipleAccounts param to true.
```json
{
"UserId": "EndUserId",
"RestrictMultipleAccounts": true
}
```
POST /api/v1/linktoken body
## Deposits
### Sending Assets to a Single Crypto Address
You can include as many `toAddresses` object items, but the most streamlined way for users to transfer assets is to include a single token/network/address combo. Please remember that for each item in the 'toAddresses' array, you must provide the Mesh UID for the network to which you are sending the supported token. The comprehensive list of tokens, networks and integrations that can Mesh supports can be found here: [Tokens](/api-reference/managed-transfers/get-supported-tokens-list) | [Networks](/api-reference/managed-transfers/get-networks) | [Integrations](/api-reference/managed-transfers/get-integrations)
> 👍 If only one destination address is provided, the Link UI skips the ‘Select asset’ and ‘Select network’ screens to streamline the user experience.
```json
{
"UserId": "EndUserId",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
]
}
}
```
POST /api/v1/linktoken body - single network and token
### Configuring for Multiple Crypto Tokens or Networks
You can include as many `toAddresses` object items as needed to enable your users to perform transfers. Each item, represents the symbol they can transfer and the network it could be sent over. Please remember that for each item in the 'toAddresses' array, you must provide the Mesh UID for the network to which you are sending the supported token. The comprehensive list of tokens, networks and integrations that can Mesh supports can be found here: [Tokens](/api-reference/managed-transfers/get-supported-tokens-list) | [Networks](/api-reference/managed-transfers/get-networks) | [Integrations](/api-reference/managed-transfers/get-integrations)
```json
{
"UserId": "EndUserId",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDC",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDT",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "7436e9d0-ba42-4d2b-b4c0-8e4e606b2c12",
"Symbol": "MATIC",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
]
}
}
```
POST /api/v1/linktoken body - multiple networks/tokens
### Sending Assets to a Previously Connected User Account
In the case if the end user has an already connected integration, and you want to move some funds between the users accounts, you can pass the `auth_token` when initializing the SDK.
#### `accessTokens` Code Example
`transferDestinationTokens`
The `transferDestinationTokens` are used for crypto transfers flow. It is an alternative way of providing target addresses for crypto transfers by using previously obtained integration `auth_tokens`.
The type of the `transferDestinationTokens` parameter is an array of `IntegrationAccessToken`.
See the type definition on our [GitHub](https://github.com/FrontFin/mesh-web-sdk/blob/main/packages/link/src/utils/types.ts).
```json
const transferDestinationTokens =
[
{
accountId: 'accountId',
accountName: 'accountName',
accessToken: 'accessToken',
brokerType: 'brokerType',
brokerName: 'brokerName',
},
]
const meshLink =
createLink({
clientId: 'clientId',
onIntegrationConnected: (payload) => {},
onExit: (error) => {},
onTransferFinished: (transferData) => {},
onEvent: (ev) => {},
accessTokens: [],
transferDestinationTokens: transferDestinationTokens // Provide a previously obtained integration auth_tokens to use as destination address
})
```
In this case you need to provide an **empty** `toAddresses` array to the LinkToken endpoint, to indicate that you wish to use the transfers workflow.
```json
{
"UserId": "EndUserId",
"TransferOptions": {
"ToAddresses": []
}
}
```
POST /api/v1/linktoken body
## Payments
### Transferring for a Specific Amount
If you’d like to initialize Mesh Link with the transfer amount pre-populated with a supplied destination address, include the assets you want to let the user pay with, plus the destination addresses of those tokens. In the example below, the user can pay with Solana or USDC over Ethereum networks (notice how the network IDs are different).
You can achieve this by providing the `AmountInFiat` parameter when calling the LinkToken endpoint
By providing a unique `TransactionID`, you'll be to map a payments to a specific identifier, similar to an order number.
```json
{
"UserId": "EndUserId",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Amount": 0.0032,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDC",
"Amount": 10,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDT",
"Amount": 10,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "7436e9d0-ba42-4d2b-b4c0-8e4e606b2c12",
"Symbol": "MATIC",
"Amount": 22.8,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"TransactionId": "TransactionId"
}
}
```
POST /api/v1/linktoken body - multiple networks/tokens
> 👍 If `AmountInFiat` is included and only a single network/token/address combo is included, Link will skip directly to the preview page, making even more streamlined for a user to complete their transfer.
```json
{
"UserId": "EndUserId",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"AmountInFiat": 10,
"TransactionId": "TransactionId"
}
}
```
POST /api/v1/linktoken body - single network and token
#### Adding a Fee for a Payment
If you’d like to charge a client fee for processing a transfer, you can append the `ClientFee` field to the above JSON object examples. This fee should only be used for **Payments** (when the transfer destination is an address owned by your company), and not for Deposits (when the transfer destination is an address owned by the end-user).
A percentage fee (input as a ratio, eg. 0.02500 = 2.500%) added onto your users' gross transfer to your company.
This will override any default fee entered in your Mesh dashboard for an individual transaction.
```json
{
"UserId": "EndUserId",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDC",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDT",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "7436e9d0-ba42-4d2b-b4c0-8e4e606b2c12",
"Symbol": "MATIC",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"AmountInFiat": 10,
"ClientFee": 0.025
}
}
```
POST /api/v1/linktoken body - multiple networks/tokens
```json
{
"UserId": "EndUserId",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"AmountInFiat": 10,
"TransactionId": "TransactionId"
"ClientFee": 0.025
}
}
```
POST /api/v1/linktoken body - single network and token
# Mesh Link SDK Events
Source: https://docs.meshconnect.com/guides/link-ui-events
## Overview
Mesh Link UI offers an event tracking system, allowing you to gain insights into user interactions within the Link UI. These events can be used for analytics and understanding user behavior. The event data can be obtained directly from the SDKs and includes various user actions, such as initiating a connection, completing authentication, completing an asset transfer, or encountering errors.
The way in which these events are captured and transmitted varies slightly across different platforms (Web, iOS, Android, and React Native). For detailed instructions, see the page for your specific platform.
# SDK Callback Functions
| **SDK callback function** | **Description of callback function** | **Payload details** |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`onIntegrationConnected()`** | A callback function that allows you (Mesh client) to run specific business logic when the user has successfully completed connecting an account. | • **`accessToken`**: the access and refresh tokens to the connected account with some basic metadata about the account and tokens.• **`brokerBrandInfo`**: links to icons and logos for the connected integration | | **`onTransferFinished()`** | A callback function that allows you (Mesh client) to run specific business logic when the user has successfully completed a transfer. | • **`status`**: pending / succeeded / failed
• **`txId`**: A unique client identifier
• **`transferId`**: A unique Mesh identifier
• **`txHash?`**: A unique blockchain identifier
• **`fromAddress`**: Address transfer is sent from
• **`toAddress`**: Address transfer is sent to
• **`symbol`**: Symbol of asset being transferred
• **`amount`**: Amount being transferred
• **`amountInFiat`**: Fiat equivalent of transfer amount
• **`totalAmountInFiat`**: Total amount transferred, including transfer-related fees
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name
• **`refundAddress`**: The address that the user can receive back to | | **`onExit()`** | A callback function that allows you (Mesh client) to run specific business logic when the user has exited Link at some point. | • **`errorMessage`**: Descriptive error message, if applicable
• **`summary`**: // optional
• **`page`**: the page the user was on when they exited
• **`selectedIntegration`**: Name and Id of integration
• **`transfer`**: previewId and other details about the transfer preview | | **`onEvent()`** | A general callback function that allows you (Mesh client) to run specific business logic in more granular scenarios, like when the user exits Link from specific parts in the user journey.
The events that can be used in this callback function are listed below. | Different payload structure for different events | # SDK Events | **SDK Event Type** | **Description of Occurrence** | **Payload Details** | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`pageLoaded`** | Triggered when the first page is fully loaded. The first page the user sees may differ based on use case. | No additional payload. | | **`close`** | Triggered when the user exits the Mesh Link modal. | • **`page`**: the page the user was on when they exited.
• Note: In the context of a transfer flow, `page: 'transferExecutedPage’` would indicate the full flow was successful because the user exited from the Success page. And if the page is anything else, then the flow was not successfully completed. | | **`integrationSelected`** | Triggered when a user selects an integration from the catalog list. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`userSearched?`**: true/false if the user searched selected this integration from search results or not. | | **`legalTermsViewed`** | Triggered if a user views the terms of use page in Link. | No additional payload. | | **`credentialsEntered`** | Triggered when a user submits exchange login credentials. | No additional payload. | | **`integrationMfaRequired`** | Triggered when the user is prompted to enter MFA in an exchange authentication flow. | No additional payload. | | **`integrationMfaEntered`** | Triggered when the user enters their MFA code in an exchange authentication flow. | No additional payload. | | **`integrationOAuthStarted`** | Triggered when an exchange’s OAuth window is launched in authentication flow. | No additional payload. | | **`integrationAccountSelectionRequired`** | Triggered if user is prompted to select a specific account within linked exchange. | No additional payload. | | **`integrationConnected`** | Triggered when a user successfully connects to an integration. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• \*\*`accessToken`\*\*payload: The access token to the user account and relevant metadata about the integration | | **`integrationConnectionError`** | Triggered when there is an error in connecting to an integration. | • **`errorMessage`**: Descriptive error message. | | **`transferStarted`** | Triggered when the user begins the transfer flow. This means they have successfully connected an account and have moved on to either configuring or previewing their transfer. It does NOT mean they have initiated a transfer of assets. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration. | | **`transferAssetSelected`** | Triggered when the user selects an asset to transfer. This does not relate to assets used for funding operations. This is about the asset being transferred. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`symbol`**: Currency symbol | | **`transferNetworkSelected`** | Triggered when the user selects a network to transfer on. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`symbol`**: Currency symbol
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name | | **`transferAmountEntered`** | Triggered when the user enters an amount to transfer. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`symbol`**: Currency symbol
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name
• **`amount`**: Amount the user enters for transfer | | **`transferNoEligibleAssets`** | Triggered when there are no assets in the user’s account eligible for the transfer, or Mesh cannot use the assets in the account to fund the transfer. | • **`arrayOfTokensHeld`**: A list of tokens held in the user’s account
• **`symbol`**: Currency symbol
• **`amount`**: Amount of holding
• **`amountInFiat`**: Amount of holding in fiat
• **`ineligibilityReason`**: Why the token is ineligible.
• **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`noAssetsType`**: | | **`transferConfigureError`** | This may happen if the session linkToken expires during the configuration flow of a transfer. Very rare. | • **`errorMessage`**: Descriptive error message.
• **`requestId`**: | | **`transferPreviewed`** | Triggered when a user previews the details of a pending transfer. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`symbol`**: Currency symbol
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name
• **`amount`**: Crypto amount of the transfer
• **`amountInFiat`** (optional): Amount in fiat currency
• **`fiatCurrency`**: fiat currency symbol for the **`amountInFiat`** value.
• **`toAddress`**: Destination address
• **`fees`**:
• `institutionTransferFee`
• `estimatedNetworkGasFee`
• `customClientFee`
• **`fiatPurchaseStrategy`**: an enumeration of a fiat funding option used to fund this transaction plus any applicable `tradingFee`.
• **`cryptocurrencyFundingOptionType`**: an enumeration of any funding options used to fund this transactionplus any applicable `cryptocurrencyConversionFee` or `depositFee`.
• **`previewId`**: Unique ID for the preview | | **`transferPreviewError`** | Triggered when there is an error in building a transfer preview. | • **`errorMessage`**: Descriptive error message. | | **`fundingOptionsViewed`** | Triggered when the user views the funding options page. | No additional payload. | | **`fundingOptionsUpdated`** | Triggered when the user makes updates to the selected funding options and clicks save (ie. saves a new funding strategy). | No additional payload. When a user saves a new funding strategy, it would build a new Preview, which would fire a new **`transferPreviewed`** event with new funding options enumerated. | | **`transferInitiated`** | Triggered when the user clicks to Proceed from the Preview screen. This will send a request to transfer to the exchange or wallet, which the user then needs to approve (via 2FA for exchange, or signing for wallet). | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`symbol`**: Currency symbol
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name
• **`amount`**: Crypto amount of the transfer
• **`amountInFiat`** (optional): Amount in fiat currency
• **`fiatCurrency`**: fiat currency symbol for the **`amountInFiat`** value.
• **`toAddress`**: Destination address
• **`fees`**:
• `institutionTransferFee`
• `estimatedNetworkGasFee`
• `customClientFee`
• **`fiatPurchaseStrategy`**: an enumeration of a fiat funding option used to fund this transaction plus any applicable `tradingFee`.
• **`cryptocurrencyFundingOptionType`**: an enumeration of any funding options used to fund this transactionplus any applicable `cryptocurrencyConversionFee` or `depositFee`. | | **`executeFundingStep`** | Triggered when there is a success or error on a funding operation before a transfer. | • **`fundingOptionType`**: The operation that has completed or failed.
• **`status`**: Outcome of the funding operation.
• **`errorMessage`**: Descriptive error message. | | **`gasIncreaseWarning`** | Triggered after funding operations and before initiation of transfer if the cost of gas has gone higher than the buffered estimate shown to the user on the Preview page. | No additional payload. | | **`transferMfaRequired`** | Triggered when the user is prompted to enter an MFA code to perform an exchange transfer. | No additional payload. | | **`transferMfaEntered`** | Triggered when the user submits their MFA code to perform an exchange transfer. | No additional payload. | | **`transferKycRequired`** | Triggered when the user has not completed KYC in the linked account, is prompted to do so before being able to transfer assets. | No additional payload. | | **`transferExecuted`** | Do not use. Obsolete. | Do not use. Obsolete. | | **`transferCompleted`** | Triggered when the user views the Success page at the conclusion of the transfer flow.
It is recommended to use the **`onTransferFinished()`** callback function to properly handle the user experience returning to your app after a successful transfer. | **`transferFinished`** payload:
• **`status`**: pending / succeeded / failed
• **`txId`**: A unique client identifier
• **`transferId`**: A unique Mesh identifier
• **`txHash?`**: A unique blockchain identifier
• **`fromAddress`**: Address transfer is sent from
• **`toAddress`**: Address transfer is sent to
• **`symbol`**: Symbol of asset being transferred
• **`amount`**: Amount being transferred
• **`amountInFiat`**: Fiat equivalent of transfer amount
• **`totalAmountInFiat`**: Total amount transferred, including transfer-related fees
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name
• **`refundAddress`**: The address that the user can receive back to | | **`transferExecutionError`** | Triggered when there is an error in executing a transfer. | • **`errorMessage`**: Descriptive error message. | | **`seeWhatHappenedClicked`** | Triggered when the user clicks the See what happened link on the Transfer Success screen | No additional payload. | | **`connectionUnavailable`** | Triggered when a timeout occurs when attempting to open a wallet on mobile, most likely because the DeFi wallet app is not installed on the device. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`reason`**: string | | **`connectionDeclined`** | Triggered when the user rejects a connection request in their wallet, or some error causes an auto-rejection. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`reason`**: string.
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name
• **`toAddress`**: Address transfer is sent to.
• **`errorMessage`**: Descriptive error message. | | **`transferDeclined`** | Triggered when the user rejects the transfer request in their wallet, or some error causes an auto-rejection. | • **`integrationType`**: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’.
• **`integrationName`**: Name of the selected integration.
• **`reason`**: string
• **`networkId`**: Selected network identifier
• **`networkName`**: Selected network name
• **`toAddress`**: Address transfer is sent to
• **`symbol`**: Symbol of asset being transferred
• **`amount`**: Amount being transferred
• **`status`**: pending / succeeded / failed | | **`walletMessageSigned`** | Triggered when a user signs a message in their wallet to verify ownership. | • **`address`**: wallet address that signed the message
• **`isVerified`**: true / false indicator of whether the user has signed the exact message sent for signature from this address
• **`message`**: Message that was signed
• **`signedMessageHash`**: The hash of the message signed by the wallet
• **`timeStamp`**: Time stamp of when the signature happened | | **`verifyDonePage`** | Triggered when the user views the Success page after successfully completing the wallet verification flow. | No additional payload. | | **`verifyWalletRejected`** | Triggered when the user rejects the message signature request in their wallet, or some error causes an auto-rejection. | No additional payload. | | **`done`** | Triggered when the user exits Link after successfully completing a read-only account connection flow (ie. for Mesh Verify) or after successfully completing the wallet verification flow (ie. for Mesh Verify). | • **`page`**: the page the user was on when they exited.
• Note: In wallet verification (ie. Mesh Verify) flow, `page: verifyDonePage` would indicate successful completion of the flow. And in a read-only (ie Mesh Portfolio) flow, `page: integrationConnectedPage` would indicate successful completion of the flow. | | **`registerTransferError`** | Shown when we are unable to receive the transfer hash from a self-custody wallet at the conclusion of a transfer flow. | • **`errorMessage`**: Descriptive error message. | # Account Authentication Source: https://docs.meshconnect.com/guides/quickstart-auth # Authenticating Accounts via Link This guide details the various methods for authenticating users with Link, enabling secure connections to their external accounts. We will cover basic user identification and advanced routing for streamlined integration experiences. ## Basic User Identification via `UserId` The fundamental approach to initiating a Link flow involves simply providing the `UserId`. This method allows the user to navigate the full Link integration catalog. **Request Body:** ```json { "UserId": "unique_end_user_identifier" } ``` * **`UserId`**: A string representing the unique identifier for the end user within your application. ## Direct Integration Launch via `IntegrationId` For optimized user flows targeting specific platforms, Link supports direct launch into a designated integration (e.g., Binance, Coinbase). This bypasses the full integration catalog, improving user experience for focused connection scenarios. **Implementation:** 1. **Retrieve `IntegrationId`**: Obtain the unique identifier for the target integration by querying the [Retrieve the list of all available integrations](https://docs.meshconnect.com/api-reference/managed-account-authentication/retrieve-the-list-of-all-available-integrations) endpoint. The `id` field within the integration object represents the `IntegrationId`. 2. **Include `IntegrationId` in Link Token Request:** ```json { "UserId": "unique_end_user_identifier", "IntegrationId": "specific_integration_uuid" } ``` * **`IntegrationId`**: The `uuid` of the target integration. ## Direct Self-Custody Wallet Launch via `IntegrationId` Similar to direct exchange/brokerage launch, you can route users directly to the connection flow for a specific self-custody wallet (e.g., MetaMask) using the `IntegrationId`. **Implementation:** The process mirrors direct exchange/brokerage launch: 1. **Retrieve `IntegrationId`**: Utilize the "Retrieve the list of all available integrations" endpoint to identify the `id` of the desired self-custody wallet integration. 2. **Include `IntegrationId` in Link Token Request:** ```json { "UserId": "unique_end_user_identifier", "IntegrationId": "specific_wallet_integration_uuid" } ``` * **`IntegrationId`**: The `uuid` of the target self-custody wallet integration. ## Enforcing Single Account Connection via `RestrictMultipleAccounts` By default, Link allows users to connect multiple provider accounts within a single session. To enforce a single account connection, the `RestrictMultipleAccounts` parameter can be set to `true`. **Implementation:** ```json { "UserId": "unique_end_user_identifier", "RestrictMultipleAccounts": true } ``` * **`RestrictMultipleAccounts`**: A boolean flag. When set to `true`, the Link UI will prevent the user from connecting additional provider accounts after a successful connection. ## Request Structure All the above configurations are passed within the JSON body of a `POST` request to the `/api/v1/linktoken` endpoint. Ensure that your `X-Client-Id` and `X-Client-Secret` are correctly included in the request headers for API authentication. # Deposits Source: https://docs.meshconnect.com/guides/quickstart-deposits # Configuring Crypto Deposits with Link This guide explains how to configure Link to enable your users to deposit cryptocurrency assets into specified addresses. You'll learn how to define the destination addresses and streamline the deposit experience. ## Understanding Deposit Configuration via `toAddresses` The `toAddresses` array within the `TransferOptions` object of your link token request is the primary mechanism for configuring where users can deposit their cryptocurrency assets. Each object in this array defines a specific cryptocurrency, the network it resides on, and the receiving address. **Key Requirement:** For each item in the `toAddresses` array, you **must** provide the Mesh-specific Unique Identifier (UID) for the target network. You can find a comprehensive list of supported tokens, networks, and their corresponding Mesh UIDs here: [Tokens](/api-reference/managed-transfers/get-supported-tokens-list) | [Networks](/api-reference/managed-transfers/get-networks) | [Integrations](/api-reference/managed-transfers/get-integrations). ## Streamlined Deposits to a Single Crypto Address For the most direct user experience, especially when you intend users to deposit a specific asset to a specific address, configure a single entry in the `toAddresses` array. This will instruct the Link UI to skip the asset and network selection screens, taking the user directly to the connection and authorization steps. **Link Token Request Body:** ```json { "UserId": "unique_end_user_identifier", "TransferOptions": { "ToAddresses": [ { "NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", "Symbol": "ETH", "Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6" } ] } } ``` * **`NetworkId`**: The Mesh UID of the target network (e.g., Ethereum Mainnet in this case). * **`Symbol`**: The symbol of the cryptocurrency being deposited (e.g., ETH). * **`Address`**: The receiving cryptocurrency address. ## Offering Deposits for Multiple Crypto Tokens or Networks To provide users with more flexibility in their deposit options, you can include multiple objects within the `toAddresses` array. Each object will represent a specific token and the network it can be deposited over. **Link Token Request Body:** ```json { "UserId": "unique_end_user_identifier", "TransferOptions": { "ToAddresses": [ { "NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", "Symbol": "ETH", "Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6" }, { "NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", "Symbol": "USDC", "Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6" }, { "NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", "Symbol": "USDT", "Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6" }, { "NetworkId": "7436e9d0-ba42-4d2b-b4c0-8e4e606b2c12", "Symbol": "MATIC", "Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6" } ] } } ``` * Each object in the `ToAddresses` array defines a specific deposit option (Network and Symbol). ## Seamless Return Customer Experience **Step 1: Retrieving the Access Token** During the initial connection, you'll use the `onIntegrationConnected` SDK event (more information about UI Events can be found [here](/guides/link-ui-events)) to capture and save the `accessToken`. You will need to construct the `accessToken` object prior to sending it back to Mesh for the reconnection. Here's how: ```jsx const meshLink = await createLink({ clientId: clientId, linkToken: linkToken, onIntegrationConnected: async (payload) => { var accessToken = [ { "accessToken": payload.accessToken.accountTokens[0].accessToken, "brokerType": payload.accessToken.brokerType, "accountId": payload.accessToken.accountTokens[0].account.accountId, "accountName": payload.accessToken.accountTokens[0].account.accountName, "brokerName": payload.accessToken.brokerName } ] // Store the accessToken // IMPORTANT: Store the accessToken securely on your server or in a secure storage location. }, // ... other options }); ``` **Key Points:** * **Saving the Access Token:** The most crucial step is to securely save the `accessToken`. Never store it directly in client-side code (e.g., local storage) for production applications. * **User Association:** Associate the `accessToken` with the corresponding user in your application's database. **Step 2: Using the Access Token for Reconnections** The next time you initialize `createLink` for the same user, include the stored `accessToken` in the `accessTokens` property: ```jsx const meshLink = await createLink({ clientId: clientId, linkToken: linkToken, accessTokens: accessToken, // Use the stored accessToken // ... other options }); ``` **Connecting Multiple Accounts** If a user has connected multiple accounts, you can store an array of `accessTokens` and pass them to the `accessTokens` property: ```jsx const meshLink = await createLink({ clientId: clientId, linkToken: linkToken, accessTokens: [accessToken1, accessToken2, ...], // Array of accessTokens // ... other options }); ``` 🚨 **IMPORTANT** — You will need a feature flag enabled on your backend to enable your user to select their desired account from the catalog. Please speak with your Mesh team to enable the feature. ```jsx const fetchLinkToken = async () => { const response = await fetch(baseUrl + "/api/v1/linktoken", { method: "POST", headers: { "Content-Type": "application/json", "X-Client-Id": clientId, "X-Client-Secret": apiSecret, }, body: JSON.stringify({ userId: "Mesh", transferOptions: { toAddresses: [], } // ... other options }), }); }; ``` **Important Reminders:** * **Integration ID**: Be sure to not include the **integrationId** when creating the linkToken for the reconnection. This will cause the Link UI to ignore the `accessTokens` provided. * **Expiration:** Access tokens have an expiration time (`expiresInSeconds`). You'll need to handle token refreshes or re-authentication before the tokens expire. * **Security:** Always prioritize security when storing and handling access tokens. **Workflow:** 1. The user initiates a deposit within your application. 2. You fetch a link token with an empty `ToAddresses` array. 3. On the client-side, you initialize `createLink` . 4. When the user goes through the Link flow, they will be presented with their previously connected accounts as potential deposit destinations. # SDK Overview Source: https://docs.meshconnect.com/guides/quickstart-guide-with-link-sdks This page will help you get started using Mesh SDKs to authenticate and make server side calls. ## What is Link SDK? Mesh Link is a collection of client side SDKs, that allows your users to connect to their financial institutions and perform transactions using a user interface provided by Mesh. Link will handle credential validation, multi-factor authentication, and error handling for each institution that Mesh supports. Link can also provide a user interface for asset transfers, deposits or payment methods. You can read more about Link use cases in [this document](/guides/link-initialization). Mesh provides client side SDKs for all modern platforms: 1. [Web Link SDK](/guides/web-sdk) 2. [iOS Link SDK](/guides/ios-sdk) 3. [Android Link SDK](/guides/android-sdk) 4. [React Native SDK](/guides/react-native-sdk) ## Authentication + Call Flow Overview The starting point for any integration with Mesh is with an account connection, which using the fastest way to get started is by using Link SDKs or cloning the [Quickstart React app](https://github.com/FrontFin/mesh-web-sdk/tree/main/examples/react-example). After generating Sandbox and Production [API keys](https://dashboard.meshconnect.com/company/keys), you’ll start by leveraging Link SDKs to facilitate end user authentication. 1. Call [/api/v1/linktoken](/api-reference/managed-account-authentication/get-link-token-with-parameters) to create a `linktoken`. This endpoint provides a short-lived, one-time-use token for initializing a Link session 2. Pass the `linktoken` to the appropriate Link SDK. The exact implementation details for passing the `linktoken` will vary by platform. For detailed instructions, see the page for your specific platform 3. Your user will be able to filter and search for the account they want to connect. Mesh will manage the authentication flow and handle MFAs for all supported integrations. 4. After successful authentication on the Link UI, `auth_token` will be passed to the SDK. 1. 🚨 You should **securely store** the `auth_token` (and `refresh_token`) for use in subsequent server requests The diagram below shows the model of how Link is used to obtain the `auth_token` and `refresh_token` which can be used for subsequent server requests.
Here is a more detailed call flow diagram for user authentication using Link SDK:
### Link Initialization and Use Cases
Depending on the `linktoken` API call payload, Link's functionality can be tailored to suit various user flows. From Authentication, Transfers to Deposits, the primary use cases can be [found here](/docs/link-initialization-and-use-cases).
* [Account Authentication](/docs/link-initialization-and-use-cases#account-authentication)
* [Deposit Use Cases](/docs/link-initialization-and-use-cases#deposits)
* [Payment Use Cases](/docs/link-initialization-and-use-cases#payments)
### Troubleshooting
For details on dealing with common problems, see the [Troubleshooting section](/docs/link-troubleshooting).
### Security Measures for Handling Authentication Tokens
**Secure Storage of Authentication Tokens**
* **Backend Storage:** It is **highly recommended** that `auth_token` and `refresh_token` obtained through Mesh Link should be securely stored on your backend server. Storing tokens on the server side enhances security by reducing the exposure of sensitive data to client-side vulnerabilities.
* **Mobile SDK Secure Storage:** For mobile applications, Mesh provides secure storage solutions within the iOS and Android SDKs. The iOS SDK leverages the Secure Enclave, a hardware-based key manager, and for Android devices, Mesh SDK utilizes secure storage mechanisms provided by the Android Keystore system. Utilizing these secure storage options ensures that tokens are stored in a manner compliant with the best practices of each platform.
**Handling User Credentials**
* **No Storage of User Credentials:** Mesh's backend infrastructure is designed to never store user credentials. This approach aligns with best practices in data security, ensuring that sensitive user information remains confidential and reducing the risk of data breaches.
Learn more about about [Security at Mesh](https://www.meshconnect.com/security)
### Event Tracking in UI
Mesh Link UI offers an event tracking system, allowing you to gain insights into user interactions within the Link UI. These events can be used for analytics and understanding user behavior. The event data can be obtained directly from the SDKs and includes various user actions, such as initiating a connection, completing authentication, completing an asset transfer, or encountering errors.
The way in which these events are captured and transmitted varies slightly across different platforms (Web, iOS, Android, and React Native). For detailed instructions, see the page for your specific platform.
The following document [list of UI Events](/guides/link-ui-events#list-of-events) details all of the events supported by Mesh SDKs.
# Paylinks
Source: https://docs.meshconnect.com/guides/quickstart-paylinks
# Introduction
This document explains how to use Paylinks, which allows merchants to redirect customers to a pre-built page for completing payments or asset transfers. This approach simplifies the payment process by eliminating the need for merchants to integrate the Mesh SDK directly into their systems.
Paylinks is a feature that enables clients to externalize the Link functionality to a Mesh-hosted webpage. Instead of integrating the Mesh SDK directly into their application, merchants can generate a Paylink URL and redirect their customers to this URL. The customer can then complete the payment or transfer process on the Mesh-hosted page.
This approach is particularly useful in several scenarios:
* **Simplified Integration:** For merchants who want to quickly enable payment functionality without extensive development work.
* **Third-Party Platforms:** When integrating with platforms where direct SDK integration is not feasible or desirable.
* **Specific Use Cases:** Situations where a simple redirect-based payment flow is preferred.
# Prerequisites
Before using Paylinks, ensure you have the following:
* Mesh Client ID and Client Secret
# Implementation
## 1. Generate a Paylink URL
To create a Paylink, send a `linkToken` request to the Mesh API. This will generate a URL that you can then provide to your customer.
* **Method:** `POST`
* **URL:** `https://integration-api.meshconnect.com/api/v1/linkToken`
* **Headers:**
* `X-Client-Id`: Your Mesh Client ID. This identifies your application to the Mesh API.
* `X-Client-Secret`: Your Mesh Client Secret. This is a secret key used to authenticate your requests to the Mesh API.
Include these headers in your request to authorize it.
* **Body:** The request body needs to be in JSON format and include the following information:
* `userId`: A unique identifier for the user making the payment or transfer. This should be a value that identifies the user in your system.
* `transferOptions`: This object contains the details of the transaction:
* `toAddresses`: An array of one or more recipient addresses. For each recipient, provide:
* `symbol`: The symbol of the asset being transferred (e.g., "ETH", "BTC").
* `networkId`: The ID of the blockchain network being used for the transfer.
* `address`: The blockchain address of the recipient.
* `isInclusiveFeeEnabled`: A boolean value that specifies whether the transaction fee is included in the transfer amount. Set to `true` if the amount your user enters includes the fee, `false` otherwise.
* `transferType`: The type of transfer. Use "deposit" if the user is sending funds to your platform, "payment" if the user is paying for something.
* `transactionId`: A unique identifier for this transaction in your system. This allows you to track the transaction and reconcile it later.
* `fundingOptions`: An object indicating if SmartFunding is enabled
* `generatePayLink`: Set this value to `true`. This tells the Mesh API to generate a Paylink URL in the response. **This is required to ensure Paylinks works.**
**Important:** You **must** provide a `transactionId` in your request body when `generatePayLink` is set to `true`. If it is not provided, the API will return an error. The `transactionId` should be a unique string generated by your system for each transaction. This ID is used to correlate the Paylink transaction with your internal records. For example, you could use an order ID, a payment ID, or a unique hash. This value should be unique and persistent so you can reliably look up the transaction in your database.
**Example Request (JSON):**
```json
{
"userId": "USER_IDENTIFIER_123",
"transferOptions": {
"amountInFiat": "100.00",
"toAddresses": [
{
"symbol": "ETH",
"networkId": "NETWORK_ID_GOES_HERE",
"address": "0xRecipientAddressGoesHere"
}
],
"generatePayLink": true,
"isInclusiveFeeEnabled": false,
"transferType": "payment",
"transactionId": "YOUR_TRANSACTION_ID",
"fundingOptions": {
"enabled": true
}
}
}
```
Replace the placeholder values (e.g., `USER_IDENTIFIER_123`, `NETWORK_ID_GOES_HERE`) with actual data
## 2. Retrieve the Paylink URL from the Response
After sending the `linkToken` request, the API will respond with a JSON object. If the request was successful, the response will contain a `paymentLink` field.
**Example Response (JSON):**
```json
{
"content": {},
"linkToken": "aHR0cHM6Ly93ZWlubWVzaGNvbm5lY3QuY29tL2lyYi1pZnJhk...",
"paymentLink": "https://paylink.meshconnect.com?linkToken=aHR0cHM6Ly...",
"status": "ok",
"message": "",
"errorType": ""
}
```
The `paymentLink` value is the URL that you will provide to your customer.
## 3. Redirect Your Customer to the Paylink URL
Redirect your customer to the URL provided in the `paymentLink` field. This can be done in several ways, depending on your application (e.g., using a redirect in your web server code, or providing the link in an email or message).
Once the user clicks the link, they will be taken to a Mesh-hosted page where they can complete the payment or transfer.
# Error States
This section describes potential errors that your customers may encounter when using Paylinks, and how to handle them:
* **Paylink was already used**: This error occurs when a user attempts to use the same Paylink URL more than once. Paylinks are designed to be used only once for security reasons.
* **Merchant Action**: When this happens, your user will need to initiate a new payment or transfer and obtain a new Paylink. You should provide clear messaging to the user explaining that the Paylink can only be used once and that they need to generate a new one.
* **Previous Paylink was unused, but expired**: This error occurs when a user tries to use a Paylink that has expired. Paylinks are typically valid for a limited time (e.g., 30 minutes).
* **Merchant Action**: Similar to the previous error, your user will need to generate a new Paylink. Inform them that the previous link has expired and they should start the payment or transfer process again.
**Recommended User Experience**: In both cases, it is strongly recommended that you redirect the user back to the payment initiation page on your site where they can click a button (e.g., "Pay" or "Transfer") to generate a new Paylink. This will provide a seamless experience for the user and allow them to complete their transaction.
# Payments
Source: https://docs.meshconnect.com/guides/quickstart-payments
# Configuring Payments with Mesh Link
This guide explains how to configure Link to facilitate cryptocurrency payments within your application. You'll learn how to define accepted payment assets, amounts, and how to apply fees.
**Understanding Payment Configuration**
When using Link to process payments, you'll utilize the `TransferOptions` object within your link token request to specify the parameters of the payment transaction. This includes defining the acceptable cryptocurrencies, their respective destination addresses, and the payment amount.
## Specifying Payment Assets and Destination Addresses
The `ToAddresses` array within `TransferOptions` allows you to define the cryptocurrencies users can pay with and the corresponding receiving addresses. Each object in this array represents a payment option.
**Important:** For each entry in the `ToAddresses` array, you must provide the Mesh-specific Unique Identifier (UID) for the network on which the supported token resides. Refer to the Mesh Connect documentation for a comprehensive list of supported tokens, networks, and their Mesh UIDs: [Tokens](/api-reference/managed-transfers/get-supported-tokens-list) | [Networks](/api-reference/managed-transfers/get-networks) | [Integrations](/api-reference/managed-transfers/get-integrations)
## Accepting Payments with Multiple Cryptocurrencies
To allow users to pay with a variety of cryptocurrencies, include multiple objects within the `ToAddresses` array. For each object, specify the network, symbol, and destination address.
**Link Token Request Body:**
```json
{
"UserId": "unique_end_user_identifier",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Amount": 0.0032,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDC",
"Amount": 10,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDT",
"Amount": 10,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "7436e9d0-ba42-4d2b-b4c0-8e4e606b2c12",
"Symbol": "MATIC",
"Amount": 22.8,
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"TransactionId": "unique_transaction_identifier"
}
}
```
* `NetworkId`: The Mesh UID of the network.
* `Symbol`: The cryptocurrency symbol.
* `Amount`: The amount the user is expected to pay, in the cryptocurrency specified by the Symbol.
* `Address`: The recipient's cryptocurrency address.
* `TransactionId`: A unique identifier for this payment transaction. This is crucial for mapping payments to orders or other internal systems.
## Streamlined Payments with a Single Asset and Amount
If you want to pre-define a single payment option (one cryptocurrency and amount), Link can streamline the user flow. When you provide `AmountInFiat` and a single network/token/address combination, Link will bypass asset and network selection, taking the user directly to the payment preview.
**Link Token Request Body:**
```json
{
"UserId": "unique_end_user_identifier",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"AmountInFiat": 10,
"TransactionId": "unique_transaction_identifier"
}
}
```
* `AmountInFiat`: The payment amount in fiat currency (e.g., USD).
* Other parameters are the same as in Scenario 1.
## Adding Payment Processing Fees
You can apply a client fee to payment transactions using the `ClientFee` parameter in the link token request.
**Important:**
* The `ClientFee` will override any default fee configured in your Mesh dashboard for the transaction.
**Link Token Request Body (with Client Fee):**
```json
// Multiple Payment Options with Fee
{
"UserId": "unique_end_user_identifier",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDC",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "USDT",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
},
{
"NetworkId": "7436e9d0-ba42-4d2b-b4c0-8e4e606b2c12",
"Symbol": "MATIC",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"AmountInFiat": 10,
"ClientFee": 0.025 // 2.5% fee (represented as a ratio)
}
}
// Single Payment Option with Fee
{
"UserId": "unique_end_user_identifier",
"TransferOptions": {
"ToAddresses": [
{
"NetworkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611",
"Symbol": "ETH",
"Address": "0x9Bf6207f8A3f4278E0C989527015deFe10e5D7c6"
}
],
"AmountInFiat": 10,
"TransactionId": "unique_transaction_identifier",
"ClientFee": 0.025 // 2.5% fee (represented as a ratio)
}
}
```
* `ClientFee`: A decimal representing the fee percentage (e.g., `0.025` for 2.5%).
## Enabling SmartFunding
Sometimes your user doesn’t have enough of the token you want to get paid in. And sometimes your user doesn’t have any of it. SmartFunding enables auto-top-ups of / auto-conversions to the payment token within in the user’s account before initiating the transfer.
To give your users the flexibility to fund their transfers using cryptocurrency, you need to include `"FundingOptions": { "Enabled": true }` during the initial setup of the Link UI. You do this by including the following setting in your Link initialization code:
```json
"userId": "example_user123",
"restrictMultipleAccounts": true,
"transferOptions": {
"transactionId": "example_tx123",
"transferType": "payment", // payment or onRamp
// Enable SmartFunding
"fundingOptions": {
"enabled": true
},
"isInclusiveFeeEnabled": false,
"toAddresses": [
{
"symbol": "USDT",
"address": "0x314838D6783865908456257c0b07Ea4Bc272cF98",
"networkId": "18fa36b0-88a8-43ca-83db-9a874e0a2288",
"amount": 99.99 // pass an amount when enabling SmartFunding
}
]
},
"integrationId": "9226e5c2-ebc3-4fdd-94f6-ed52cdce1420"
```
> 👍 This is best suited for `payment` or `onRamp` transfer types and operate best with a single token and a passed amount parameter
With this option enabled, if a user doesn't have enough balance for a transfer, Mesh can guide them through using the balances in their account, and payment methods linked to their account to top up their balance.
# Testnets for Wallets (Sandbox)
Source: https://docs.meshconnect.com/guides/quickstart-testnet-sandbox
# What It Is
Mesh now supports testnet transactions in our sandbox environment, allowing developers to validate on-chain transactions without risking real funds.
# Why It's Important
Previously, our sandbox environment did not support wallet transactions, requiring customers to use real funds for testing. With testnets, developers can now configure transfers using Sepolia testnet and obtain test tokens from a [faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia), ensuring a risk-free and seamless integration experience.
## What Are Testnets and Test Tokens?
* **Testnets** are blockchain networks used for testing purposes, replicating mainnet functionality without real economic consequences.
* **Test Tokens** are tokens issued on testnets that simulate real assets, allowing developers to conduct transactions, test smart contracts, and validate integrations before deploying on the mainnet.
By enabling testnet support, we remove a major barrier to integration, speeding up contract signing and reducing implementation friction for prospective PSP clients.
# How to Use It
1. Reference our updated sandbox documentation: [Sandbox Documentation](https://docs.meshconnect.com/guides/sandbox)
2. Access our demo environment: [Mesh Demo Environment](https://dashboard.meshconnect.com/demos/mesh-deposit)
3. Configure a transfer using the following:
* **Token:** Sepolia ETH
* **Network:** Sepolia
4. **Obtaining testnet tokens:** There are two ways in which customers can obtain testnet tokens:
**Acquire test tokens from a faucet**: Customers can obtain Sepolia ETH from a public faucet for testing. e.g. [https://cloud.google.com/application/web3/faucet/ethereum/sepolia](https://cloud.google.com/application/web3/faucet/ethereum/sepolia)
## Additional Notes
* Expanding testnet coverage is part of our future roadmap.
* Please reach out to product with any additional testnet expansion request.
* Currently, only MetaMask and Rainbow wallets are supported
* Please reach out to product to enable additional wallet support
* Sales and CS teams should proactively inform customers about this feature to accelerate integration timelines.
* For further assistance, customers should reach out to their assigned CS representative.
## Reference Docs
[https://docs.meshconnect.com/guides/sandbox](https://docs.meshconnect.com/guides/sandbox)
# React Native SDK
Source: https://docs.meshconnect.com/guides/react-native-sdk
## Installation
With `npm`:
`npm install --save @meshconnect/react-native-link-sdk`
With `yarn`:
`yarn add @meshconnect/react-native-link-sdk`
💡 This package requires `react-native-webview` to be installed in your project. Although it is listed as direct dependency, some times it is not installed automatically (This is a known [npm issue](https://stackoverflow.com/questions/18401606/npm-doesnt-install-module-dependencies)). You should install it manually via following command in this case:
```
npm install --save react-native-webview
# or with yarn
yarn add react-native-webview
```
## Get Link token
Link token should be obtained from the POST `/api/v1/linktoken` endpoint. API reference for this request is available here. The request must be performed from the server side because it requires the client's secret. You will get the response in the following format:
```json
{
"content": {
"linkToken": "{linkToken}"
},
"status": "ok",
"message": ""
}
```
## Launch Link
```javascript
import React from 'react';
import {
LinkConnect,
LinkPayload,
TransferFinishedPayload,
TransferFinishedSuccessPayload,
TransferFinishedErrorPayload
} from '@meshconnect/react-native-link-sdk';
export const App = () => {
return (
Alternatively, you can start interacting with various Sandbox endpoints following the [API reference](https://docs.meshconnect.com/api-reference/)
1. **Create Sandbox API keys:**
* Create a new key in your [Dashboard](https://dashboard.meshconnect.com/company/keys)
2. **Use the Dedicated API Endpoint:**
* `https://sandbox-integration-api.meshconnect.com`
3. **Authenticate Using API Credentials:**
* Use the newly created Sandbox API keys, separate from your Production credentials.
4. **Test Your Integration:**
* Execute API calls, validate responses, and ensure your application behaves as expected.
5. **Move to Production:**
* Once testing is complete, update your integration to point to the Production API.
***
## Frequently Asked Questions
* When registering an endpoint, you’ll be prompted to store your secret key, as you won’t be able to view it again.
* You can only save one production URI and one Sandbox URI, but you can deactivate one and save a new one at any time.
### How to respond to a Mesh webhook event
* Please respond with a **`200`** response in \< 200ms to confirm receipt of the event.
* If Mesh does not receive a **`200`** response in \< 200ms, the webhook will retry (you will receive the event again with all duplicate information except for a different **`Id`**).