Create a Pay-in Instance

This endpoint creates a CAD pay-in instance and returns a unique URL for the Tylt-hosted Interac e-Transfer payment flow.

Depending on the selected flow, the merchant may either redirect the customer to the hosted payment URL or provide the required customer information when creating the instance.

---

Endpoint

POST https://api.tylt.money/v2/prime-fiat/cad/instance/payin

---

Authentication

All merchant-initiated API requests must include:

Header	Type	Required	Description
Content-Type	string	Yes	Must be application/json.
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 exact JSON request body using the API Secret Key.

The API Key and API Secret Key are provided during onboarding. The API Secret Key must remain confidential and must never be exposed in frontend or client-side code.

---

Signing the Request

The request body must be signed using HMAC-SHA256.

Signing Process

1. Construct the request-body object.

2. Convert the object into a JSON string using JSON.stringify() or an equivalent compact JSON encoder.

3. Generate an HMAC-SHA256 digest using the API Secret Key.

4. Encode the digest as a lowercase hexadecimal string.

5. Include the generated signature in the X-TLP-SIGNATURE header.

6. Send the exact JSON string used to generate the signature.

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

The JSON string used to generate the signature must be identical to the request body sent to Tylt. Changes to spacing, field order, encoding or serialisation after signing may cause signature validation to fail.

---

Request Body

Field	Type	Required	Description
currencySymbol	string	Yes	Fiat currency symbol. Must be "CAD".
cryptoCurrencySymbol	string	No	Crypto Asset Symbol that is being purchased. Must be USDT, USDC
amount	number	Yes	Amount the customer will pay in CAD.
merchantOrderId	string	Yes	Unique transaction reference generated by the merchant.
callBackUrl	string	Yes	HTTPS endpoint that will receive transaction-status webhooks.
redirectUrl	string	Yes	URL to which the customer will be redirected after the hosted payment flow.
merchantDetails	object	Yes	The merchantDetails object identifies the merchant on whose behalf the transaction is being processed. This information is required for transaction attribution, reconciliation, risk screening, and regulatory reporting. If the integrator is acting as a Merchant of Record, the details of the underlying end merchant must be provided If the integrator is the end merchant, the details of its own business must be provided. The following fields must be provided inside the merchantDetails object: merchantName The legal or DBA name of the merchant. merchantUrl The official website URL of the merchant. This must be a valid HTTPS URL representing the merchant’s active operating website. merchantInternalId A unique internal identifier assigned by the merchant. This identifier is used for reconciliation, reporting, and ongoing transaction tracking and must remain consistent across transactions. All fields within merchantDetails are mandatory. Transactions submitted without this object, or with incomplete merchant details, will be rejected.
isMerchantOnRecord	boolean	No	Set to true when operating under an approved Merchant on Record arrangement.
userDetails	object	No	Custom fields associated with the end user making a payment to the merchant. These fields are echoed back in webhook notifications and other API responses for tracking and reconciliation.You may send an empty object ({}). Reserved keys (auto-populate payment widget) The following keys are reserved. If you include any of them, they will be used to pre-fill the corresponding fields in the hosted payment widget: firstName (string) lastName (string) email (string) country (string) countryOfBirth dob (string, format: YYYY-MM-DD) If a reserved field is not provided, the end user will be prompted to enter that field in the widget (if required by the flow). Use ISO 3166-1 alpha-3 three-letter country codes If autoAcceptTrade is set to 1, the Reserved Keys need to be populated.
userDetails.dob	string	Conditional	Customer’s date of birth in YYYY-MM-DD format.
autoAcceptTrade	number	No	Set to 1 to automatically accept the instance and initiate the Interac e-Transfer request.
transferType	string	No	Settlement destination. Supported values are "internal" and "external". Defaults to "internal".
walletDetails	object	Conditional	Required when transferType is "external".
walletDetails.address	string	Conditional	External wallet address to which the USDC, USDT settlement will be delivered.
walletDetails.network	string	Conditional	Blockchain network associated with the wallet address, such as "ETH" or "SOL".
settlementType	string	No	Settlement schedule. Defaults to "instant". Other approved values may use the T+N format, such as "T+1".

In this API, autoAcceptTrade means that Tylt automatically accepts the pay-in instance and initiates the Interac e-Transfer request. It does not refer to the customer’s bank-level Interac AutoAcceptTrade settings.

---

Example Request

{
  "currencySymbol": "CAD",
  "cryptoCurrencySymbol": "USDT",
  "amount": 250.00,
  "merchantOrderId": "ORD-2026-001",
  "callBackUrl": "https://merchant.example/webhooks/tylt/cad",
  "redirectUrl": "https://merchant.example/payments/return",
  "merchantDetails": {
    "merchantName": "Acme Corp",
    "merchantUrl": "https://merchant.example",
    "merchantInternalId": "MUID-001"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]",
    "country": "CAN",
    "countryOfBirth": "CAN",
    "dob": "1990-05-15"
  },
  "autoAcceptTrade": 1,
  "transferType": "internal",
  "settlementType": "instant"
}

---

JavaScript Example

const crypto = require("crypto");

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

const requestBody = {
  currencySymbol: "CAD",
  amount: 250.00,
  merchantOrderId: "ORD-2026-001",
  cryptoCurrencySymbol: "USDC",
  callBackUrl: "https://merchant.example/webhooks/tylt/cad",
  redirectUrl: "https://merchant.example/payments/return",
  merchantDetails: {
    merchantName: "Acme Corp",
    merchantUrl: "https://merchant.example",
    merchantInternalId: "MUID-001"
  },
  userDetails: {
    firstName: "John",
    lastName: "Doe",
    email: "[e-mail]",
    country: "CAN",
    countryOfBirth: "CAN",
    dob: "1990-05-15"
  },
  autoAcceptTrade: 1,
  transferType: "internal",
  settlementType: "instant"
};

// Sign and send the exact same JSON string.
const rawBody = JSON.stringify(requestBody);

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

const response = await fetch(
  "https://api.tylt.money/v2/prime-fiat/cad/instance/payin",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-TLP-APIKEY": apiKey,
      "X-TLP-SIGNATURE": signature
    },
    body: rawBody
  }
);

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

---

Successful Response

200 OK

{
  "msg": "Instance created successfully",
  "data": {
    "instanceId": "a1b2c3d4-...",
    "url": "https://app.tylt.money/prime-cad-instance/a1b2c3d4-...",
    "ReferenceNumber": "CA1MR7Cmf4hv",
    "TransactionNumber": "TRAN924862",
    "userDetails": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]",
      "country": "CA",
      "dob": "1990-05-15"
    },
    "merchantDetails": {
      "merchantName": "Acme Corp",
      "merchantUrl": "https://merchant.example"
    },
    "fiatAmount": 250.00,
    "fiatCurrencySymbol": "CAD",
    "cryptoAmount": 181.23,
    "cryptoCurrencySymbol": "USDC",
    "merchantOrderId": "ORD-2026-001",
    "rate": 1.3795
  }
}

When autoAcceptTrade is not set to 1, ReferenceNumber and TransactionNumber may initially be null. These values are populated after the Interac payment request is initiated.

---

Response Fields

Field	Type	Description
instanceId	string	Unique identifier generated by Tylt for the pay-in instance.
url	string	Tylt-hosted customer payment URL.
ReferenceNumber	string or null	Interac reference assigned after the payment request is initiated.
TransactionNumber	string or null	External provider transaction number.
userDetails	object	Customer details associated with the transaction.
merchantDetails	object	Merchant information associated with the transaction.
fiatAmount	number	Amount to be paid by the customer in CAD.
fiatCurrencySymbol	string	Fiat currency symbol. Always "CAD".
cryptoAmount	number	Calculated USDC settlement amount.
cryptoCurrencySymbol	string	Settlement cryptocurrency.
merchantOrderId	string	Unique transaction reference supplied by the merchant.
rate	number	Exchange rate applied to the transaction.

---

Error Responses

Missing Required Parameters

{
  "msg": "Missing required parameters!",
  "data": {}
}

Unsupported Currency

{
  "msg": "Currency symbol not supported!",
  "data": {}
}

Invalid Currency

{
  "msg": "Invalid currency symbol!",
  "data": {}
}

Missing Customer Information

Returned when autoAcceptTrade is set to 1 but the required customer fields are missing.

{
  "msg": "Missing required userDetails fields (firstName, lastName, email, country, dob) for autoAcceptTrade.",
  "data": {}
}

Invalid Wallet Address or Network

{
  "msg": "Invalid wallet address! This address is not associated with the given network!",
  "data": {}
}

Wallet Details Required

{
  "msg": "walletDetails (address and network) are required for external transfers.",
  "data": {}
}

Invalid Settlement Type

{
  "msg": "Invalid settlement type format: 'T+ABC'. Expected 'instant' or 'T+N' (e.g. T+1, T+3).",
  "data": {}
}

External Transfers Not Enabled

{
  "msg": "Merchant is not permitted to use external transfers. Contact support to enable this feature.",
  "data": {}
}

Settlement Type Not Enabled

{
  "msg": "Settlement type 'T+3' is not permitted for this merchant. Allowed types: instant, T+1.",
  "data": {}
}

Internal Server Error

{
  "msg": "Internal server error",
  "data": {}
}

A successful instance-creation response does not mean that the customer’s Interac payment has been completed. The payment is successfully completed only when the transaction reaches eventId: 5.