Get Instance Information

This endpoint retrieves the latest information for a CAD pay-in instance.

The authenticated userId and merchantId are resolved from the JWT-based API key. They must not be included in the query parameters.

The merchant may retrieve an instance using either:

• The merchant-generated merchantOrderId; or

• The Tylt-generated instanceId.

Using merchantOrderId is recommended because it corresponds to the unique reference generated by the merchant when the pay-in instance was created.

---

Endpoint

Retrieve by Merchant Order ID

GET https://api.tylt.money/v2/prime-fiat/cad/instance/details?merchantOrderId=<MERCHANT_ORDER_ID>

Retrieve by Instance ID

GET https://api.tylt.money/v2/prime-fiat/cad/instance/details?instanceId=<INSTANCE_ID>

---

Authentication

Header	Type	Required	Description
X-TLP-APIKEY	string	Yes	JWT-based API key issued by Tylt. The authenticated user and merchant are resolved from this credential.
X-TLP-SIGNATURE	string	Yes	HMAC-SHA256 signature generated from the JSON-serialised query-parameter object using the API Secret Key.

---

Signing a GET Request

For a GET request, construct an object containing the query parameters included in the request.

Example Using merchantOrderId

const params = {
  merchantOrderId: "ORD-2026-001"
};

Convert the object into a JSON string:

const signaturePayload = JSON.stringify(params);

The value signed is:

{"merchantOrderId":"ORD-2026-001"}

Generate the signature:

signature = HMAC-SHA256(
    API_SECRET_KEY,
    JSON.stringify(params)
)

The resulting lowercase hexadecimal digest must be submitted in the X-TLP-SIGNATURE header.

The query parameters used to generate the signature must be identical to the query parameters sent in the request URL.

---

Query Parameters

Field	Type	Required	Description
merchantOrderId	string	Conditional	Unique transaction reference supplied by the merchant when creating the instance.
instanceId	string	Conditional	Unique instance identifier generated and returned by Tylt.

Submit either merchantOrderId or instanceId.

---

JavaScript Example

const crypto = require("crypto");

const apiKey = process.env.TYLT_API_KEY;
const apiSecret = process.env.TYLT_API_SECRET;

const params = {
  merchantOrderId: "ORD-2026-001"
};

const signaturePayload = JSON.stringify(params);

const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(signaturePayload)
  .digest("hex");

const queryString = new URLSearchParams(
  params
).toString();

const response = await fetch(
  `https://api.tylt.money/v2/prime-fiat/cad/instance/details?${queryString}`,
  {
    method: "GET",
    headers: {
      "X-TLP-APIKEY": apiKey,
      "X-TLP-SIGNATURE": signature
    }
  }
);

const result = await response.json();
console.log(result);

Example Request

GET https://api.tylt.money/v2/prime-fiat/cad/instance/details?merchantOrderId=ORD-2026-001
X-TLP-APIKEY: <YOUR_API_KEY>
X-TLP-SIGNATURE: <GENERATED_HMAC_SHA256_SIGNATURE>

---

Successful Response

200 OK

{
  "msg": "Instance details fetched successfully.",
  "data": {
    "instanceId": "a726cfda-8298-476e-bc3f-ffd0cf591ecf",
    "isBuying": 1,
    "eventId": 1,
    "eventDescription": "Instance Created",
    "fiatAmount": 250,
    "fiatCurrencySymbol": "CAD",
    "rate": 1.4052,
    "cryptoAmount": 177.91,
    "cryptoCurrencySymbol": "USDC",
    "fees": 0.25,
    "callBackUrl": "https://merchant.example/webhooks/tylt/cad",
    "redirectUrl": "https://merchant.example/payments/return",
    "userDetails": {
      "dob": "1990-05-15",
      "email": "[e-mail]",
      "country": "CA",
      "lastName": "Doe",
      "firstName": "John"
    },
    "merchantDetails": {
      "merchantUrl": "https://merchant.example",
      "merchantName": "Acme Corp"
    },
    "ReferenceNumber": null,
    "TransactionNumber": null,
    "walletDetails": {
      "address": null,
      "network": null
    },
    "transferType": "internal",
    "recipientDetails": null,
    "payeeDetails": null,
    "expiresAt": "2026-08-03T09:00:14Z",
    "kycStatus": "NOT STARTED",
    "kycDetails": {
      "firstName": "John",
      "lastName": "Doe",
      "DOB": "",
      "countryOfResidence": "",
      "email": "[e-mail]",
      "amlStatus": null
    }
  }
}

---

Response Fields

Field	Type	Description
instanceId	string	Unique identifier generated by Tylt for the payment instance.
isBuying	number	Indicates whether the transaction is a pay-in. A value of 1 represents a pay-in.
eventId	number	Numeric code representing the current transaction lifecycle state.
eventDescription	string	Human-readable description of the transaction status.
fiatAmount	number	Amount paid by the customer in CAD.
fiatCurrencySymbol	string	Fiat currency symbol. Always "CAD".
rate	number	Exchange rate applied to the transaction.
cryptoAmount	number	Calculated USDC settlement amount.
cryptoCurrencySymbol	string	Cryptocurrency used for settlement.
fees	number	Total fees recorded for the transaction.
callBackUrl	string	Merchant endpoint configured to receive webhook notifications.
redirectUrl	string	URL to which the customer is redirected after the hosted payment flow.
userDetails	object	Customer information associated with the transaction.
merchantDetails	object	Merchant information associated with the transaction.
merchantOrderId	string	Unique transaction reference supplied by the merchant.
ReferenceNumber	string or null	Interac reference assigned after the payment request is initiated.
TransactionNumber	string or null	External provider transaction number.
expiresAt	string	Expiry timestamp for the payment instance in ISO 8601 format.

The eventId should be used to determine the current transaction state.