​
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

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):

{
  "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

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):

{
  "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.

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.