> 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/create-a-pay-in-instance.md).
# 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
```html
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.
***
### JavaScript Example
```javascript
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: "john@example.com",
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
{% tabs %}
{% tab title="200" %}
#### Scenario A: Standard Pay-In Request (Without Auto-Accept)
This is the standard response when initializing a payment session where the user will be redirected to the Tylt payment portal. the user will be redirected to the Tylt payment portal.
```json
{
"status": 200,
"msg": "Instance created successfully",
"data": {
"instanceId": "8f3b2cd1-49fa-11ed-bdca-0a58a9feac02",
"url": "https://exchange.tylt.money/review/cad/8f3b2cd1-49fa-11ed-bdca-0a58a9feac02",
"ReferenceNumber": null,
"TransactionNumber": null,
"interacUrl": null,
"userDetails": {
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@example.com"
},
"merchantDetails": {
"customerPlatformId": "user123"
},
"fiatAmount": 100.0,
"fiatCurrencySymbol": "CAD",
"cryptoAmount": 65.5,
"cryptoCurrencySymbol": "USDC",
"merchantOrderId": "ORDER-999238",
"rate": 1.4975
}
}
```
{% endtab %}
{% endtabs %}
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** |
| ----------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `status` | number | HTTP-style response status code returned by Tylt. A value of `200` indicates that the instance was created successfully. |
| `msg` | string | Human-readable message describing the result of the API request. |
| `data` | object | Object containing the newly created pay-in instance details. |
| `data.instanceId` | string | Unique identifier generated by Tylt for the pay-in instance. |
| `data.url` | string | Tylt-hosted customer payment URL used to review and continue the Interac payment flow. |
| `data.ReferenceNumber` | string or null | Interac reference number assigned after the payment request is initiated. Returns `null` before initiation. |
| `data.TransactionNumber` | string or null | External payment provider transaction number. Returns `null` until assigned by the provider. |
| `data.interacUrl` | string or null | Interac-hosted payment request URL. Returns `null` until the Interac payment request has been generated. |
| `data.userDetails` | object | Customer details 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 | Merchant-specific information associated with the transaction. |
| `data.merchantDetails.customerPlatformId` | string | Merchant-defined identifier for the customer on the merchant's platform. |
| `data.fiatAmount` | number | Amount to be paid by the customer in fiat currency. |
| `data.fiatCurrencySymbol` | string | Fiat currency symbol. For the Canada Interac flow, this is `"CAD"`. |
| `data.cryptoAmount` | number | Calculated cryptocurrency amount to be settled for the transaction. |
| `data.cryptoCurrencySymbol` | string | Cryptocurrency used for settlement, such as `"USDC"`. |
| `data.merchantOrderId` | string | Unique transaction reference supplied by the merchant. |
| `data.rate` | number | Base exchange rate applied to the transaction. |
| `data.effectiveRate` | number | Effective exchange rate applied after incorporating applicable pricing, fees, or spread. |
***