> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-crossramp-fiat-crypto-solutions/canada-intrac/canada-interac-e-transfer-on-ramp/get-instance-information.md). # 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 ```http GET https://api.tylt.money/v2/prime-fiat/cad/instance/details?merchantOrderId= ``` #### Retrieve by Instance ID ```http GET https://api.tylt.money/v2/prime-fiat/cad/instance/details?instanceId= ``` *** ### 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` ```javascript const params = { merchantOrderId: "ORD-2026-001" }; ``` Convert the object into a JSON string: ```javascript const signaturePayload = JSON.stringify(params); ``` The value signed is: ```json {"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 ```javascript 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 ```http GET https://api.tylt.money/v2/prime-fiat/cad/instance/details?merchantOrderId=ORD-2026-001 X-TLP-APIKEY: X-TLP-SIGNATURE: ``` *** ### Successful Response #### `200 OK` {% tabs %} {% tab title="External" %} ```json { "status": 200, "msg": "Instance details fetched successfully.", "data": { "instanceId": "8f3b2cd1-49fa-11ed-bdca-0a58a9feac02", "isBuying": 1, "merchantOrderId": "ORDER-999238", "interacUrl": "https://gateway-web.fit.interac.ca/acceptPaymentRequest.do?rID=CA3L9X21B&src=email", "eventDetails": { "eventId": 7, "description": "Settlement Completed" }, "accounts": { "fiatCurrency": "CAD", "fiatAmount": 100.0, "cryptoCurrency": "USDC", "cryptoAmount": 66.7, "toReleaseAmount": 65.5, "effectiveRate": 1.4975, "rate": 1.4975, "fees": 1.2, "MDR": 0.01 }, "cryptoSettlementDetails": { "Status": "Settlement Completed", "hash": "0x349bf29...", "address": "0xYourConsumerWalletAddress...", "Network": "TPNK", "type": "external", "settlementDate": "T+1", "settlementTime": "2026-08-11T12:00:00Z" }, "callBackUrl": "https://webhook.yourplatform.com/notify", "redirectUrl": "https://app.yourplatform.com/success", "userDetails": { "firstName": "John", "lastName": "Doe", "email": "johndoe@example.com" }, "merchantDetails": { "internalPlatformId": "acc-998" }, "ReferenceNumber": "CA3L9X21B", "TransactionNumber": "9876543210", "expiresAt": "2026-08-10T12:00:00Z", "kycStatus": "APPROVED", "kycDetails": { "firstName": "John", "lastName": "Doe", "DOB": "1990-01-01", "countryOfResidence": "CA", "email": "johndoe@example.com", "amlStatus": "approved" } } } ``` {% endtab %} {% tab title="Internal" %} ```json { "status": 200, "msg": "Instance details fetched successfully.", "data": { "instanceId": "8f3b2cd1-49fa-11ed-bdca-0a58a9feac02", "isBuying": 1, "merchantOrderId": "ORDER-999238", "interacUrl": "https://gateway-web.fit.interac.ca/acceptPaymentRequest.do?rID=CA3L9X21B&src=email", "eventDetails": { "eventId": 2, "description": "Order Created / Payment Pending" }, "accounts": { "fiatCurrency": "CAD", "fiatAmount": 100.0, "cryptoCurrency": "USDC", "cryptoAmount": 66.7, "toReleaseAmount": 65.5, "effectiveRate": 1.4975, "rate": 1.4975, "fees": 1.2, "MDR": 0.01 }, "cryptoSettlementDetails": { "Status": null, "hash": null, "address": null, "Network": "TPNK", "type": "internal", "settlementDate": "T+1", "settlementTime": null }, "callBackUrl": "https://webhook.yourplatform.com/notify", "redirectUrl": "https://app.yourplatform.com/success", "userDetails": { "firstName": "John", "lastName": "Doe", "email": "johndoe@example.com" }, "merchantDetails": { "internalPlatformId": "acc-998" }, "ReferenceNumber": "CA3L9X21B", "TransactionNumber": "9876543210", "expiresAt": "2026-08-10T12:00:00Z", "kycStatus": "APPROVED", "kycDetails": { "firstName": "John", "lastName": "Doe", "DOB": "1990-01-01", "countryOfResidence": "CA", "email": "johndoe@example.com", "amlStatus": "approved" } } } ``` {% endtab %} {% endtabs %} *** ### Response Fields | **Field** | **Type** | **Description** | | --------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | number | HTTP-style response status code returned by Tylt. A value of `200` indicates a successful request. | | `msg` | string | Human-readable message describing the result of the API request. | | `data` | object | Object containing the payment instance details. | | `data.instanceId` | string | Unique identifier generated by Tylt for the payment instance. | | `data.isBuying` | number | Indicates the transaction direction. A value of `1` represents a pay-in / crypto purchase transaction. | | `data.merchantOrderId` | string | Unique transaction reference supplied by the merchant when creating the payment instance. | | `data.interacUrl` | string | Hosted Interac e-Transfer payment request URL that the customer uses to complete the payment. | | `data.eventDetails` | object | Object containing the current lifecycle status of the transaction. | | `data.eventDetails.eventId` | number | Numeric code representing the current transaction lifecycle state. | | `data.eventDetails.description` | string | Human-readable description of the current transaction status. | | `data.accounts` | object | Object containing the fiat, crypto, rate, and fee details for the transaction. | | `data.accounts.fiatCurrency` | string | Fiat currency used for the transaction. For the Canada Interac flow, this is `CAD`. | | `data.accounts.fiatAmount` | number | Amount payable or paid by the customer in fiat currency. | | `data.accounts.cryptoCurrency` | string | Cryptocurrency used for the purchase or settlement, such as `USDC`. | | `data.accounts.cryptoAmount` | number | Gross cryptocurrency amount calculated for the transaction before applicable deductions. | | `data.accounts.toReleaseAmount` | number | Net cryptocurrency amount to be released or settled after applicable fees or deductions. | | `data.accounts.effectiveRate` | number | Effective fiat-to-crypto conversion rate after applying the transaction pricing logic. | | `data.accounts.rate` | number | Exchange rate applied to calculate the cryptocurrency amount. | | `data.accounts.fees` | number | Total transaction fees recorded for the transaction. | | `data.accounts.MDR` | number | Merchant Discount Rate applied to the transaction. | | `data.cryptoSettlementDetails` | object | Object containing details of the cryptocurrency settlement associated with the transaction. | | `data.cryptoSettlementDetails.Status` | string | Current status of the cryptocurrency settlement. | | `data.cryptoSettlementDetails.hash` | string or null | Blockchain transaction hash for an external on-chain settlement. May be `null` or unavailable until the transaction is broadcast. | | `data.cryptoSettlementDetails.address` | string or null | Destination wallet address to which the cryptocurrency is settled for an external transfer. | | `data.cryptoSettlementDetails.Network` | string | Blockchain network used for the cryptocurrency settlement. | | `data.cryptoSettlementDetails.type` | string | Settlement type. `external` represents settlement to an external wallet address; `internal` represents settlement to an internal Tylt or merchant balance. | | `data.cryptoSettlementDetails.settlementDate` | string | Settlement schedule or settlement convention applicable to the transaction, for example `T+1`. | | `data.cryptoSettlementDetails.settlementTime` | string or null | Actual or scheduled settlement timestamp in ISO 8601 format. | | `data.callBackUrl` | string | Merchant endpoint configured to receive webhook notifications for transaction status changes. | | `data.redirectUrl` | string | URL to which the customer is redirected after completing the hosted payment flow. | | `data.userDetails` | object | Object containing customer information associated with the transaction. | | `data.userDetails.firstName` | string | Customer's first name. | | `data.userDetails.lastName` | string | Customer's last name. | | `data.userDetails.email` | string | Customer's email address. | | `data.merchantDetails` | object | Object containing merchant-specific information associated with the transaction. | | `data.merchantDetails.internalPlatformId` | string | Merchant-defined internal identifier associated with the customer, account, wallet, or transaction. | | `data.ReferenceNumber` | string or null | Interac reference number assigned to the payment request after it is initiated. | | `data.TransactionNumber` | string or null | External payment provider's transaction identifier. | | `data.expiresAt` | string | Expiry timestamp for the payment instance in ISO 8601 format. | | `data.kycStatus` | string | Current KYC status of the customer associated with the transaction, for example `APPROVED`. | | `data.kycDetails` | object | Object containing KYC and AML information associated with the customer. | | `data.kycDetails.firstName` | string | First name recorded as part of the customer's verified KYC information. | | `data.kycDetails.lastName` | string | Last name recorded as part of the customer's verified KYC information. | | `data.kycDetails.DOB` | string | Customer's date of birth in `YYYY-MM-DD` format. | | `data.kycDetails.countryOfResidence` | string | Customer's country of residence, represented using the ISO 3166-1 alpha-2 country code. | | `data.kycDetails.email` | string | Email address associated with the customer's KYC profile. | | `data.kycDetails.amlStatus` | string | Current AML screening status for the customer, for example `approved`. | The `eventId` should be used to determine the current transaction state.