# Get Pay-In Transaction Information This endpoint allows you to retrieve detailed information about a specific Pay-In transaction. The `orderId` is required, and it corresponds to the unique identifier generated by Tylt for the transaction. #### Endpoint **`GET`**`https://api.tylt.money/transactions/merchant/getPayinTransactionInformation?`orderId={orderId} #### Example Request **`GET`**`https://api.tylt.money/transactions/merchant/getPayinTransactionInformation?orderId=a49579dd-7711-11ef-8277-02d8461243e9` **Request Headers** {% tabs %} {% tab title="Headers" %}
NameTypeExampleDescription
X-TLP-APIKEYstring93ee3c5e133697251b5362bcf9cc8532476785t8768075616f58d88Your Tylt API Key, used to identify your account in API requests.
X-TLP-SIGNATUREstringd0afef3853dfc8489c8b9affa5825171fdd7y7685675e4966a05f66ed2b3eaf9462b3c9c0HMAC SHA-256 signature generated using the API Secret Key to secure the request.
{% endtab %} {% endtabs %} {% hint style="info" %} When using the API, ensure to include your API Key and generate the signature for the request payload using your API Secret. The tables provided above contain example values for illustration purposes only. Please refer to the code snippets for detailed instructions on how to sign the request and generate the signature properly. {% endhint %} **Code Snippet** {% tabs %} {% tab title="Node JS" %} ```javascript const axios = require('axios'); const crypto = require('crypto'); const params = { orderId: 'a49579dd-7711-11ef-8277-02d8461243e9' }; const queryString = new URLSearchParams(params).toString(); const url = `https://api.tylt.money/transactions/merchant/getPayinTransactionInformation?${queryString}`; const apiKey = 'your-api-key'; const secretKey = 'your-secret-key'; const signaturePayload = JSON.stringify(params); const signature = crypto.createHmac('sha256', secretKey) .update(signaturePayload) .digest('hex'); const config = { method: 'get', url: url, headers: { 'X-TLP-APIKEY': apiKey, 'X-TLP-SIGNATURE': signature } }; axios.request(config) .then((response) => { console.log(JSON.stringify(response.data)); }) .catch((error) => { console.error(error); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests import hashlib import hmac import json url = "https://api.tylt.money/transactions/merchant/getPayinTransactionInformation" params = { 'orderId': 'a49579dd-7711-11ef-8277-02d8461243e9' } api_key = 'your-api-key' secret_key = 'your-secret-key' query_string = '&'.join([f"{key}={value}" for key, value in params.items()]) body_string = json.dumps(params, separators=(',', ':'), ensure_ascii=False) signature = hmac.new(secret_key.encode(), body_string.encode(), hashlib.sha256).hexdigest() headers = { 'X-TLP-APIKEY': api_key, 'X-TLP-SIGNATURE': signature } response = requests.get(url, headers=headers, params=params) print(response.text) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const crypto = require('crypto'); const params = { orderId: 'a49579dd-7711-11ef-8277-02d8461243e9' }; const queryString = new URLSearchParams(params).toString(); const url = `https://api.tylt.money/transactions/merchant/getPayinTransactionInformation?${queryString}`; const apiKey = 'your-api-key'; const secretKey = 'your-secret-key'; const signaturePayload = JSON.stringify(params); const signature = crypto.createHmac('sha256', secretKey) .update(signaturePayload) .digest('hex'); const requestOptions = { method: 'GET', headers: { 'X-TLP-APIKEY': apiKey, 'X-TLP-SIGNATURE': signature }, redirect: 'follow' }; fetch(url, requestOptions) .then(response => response.text()) .then(result => console.log(result)) .catch(error => console.error('error', error)); ``` {% endtab %} {% endtabs %} **Response** {% tabs %} {% tab title="200" %} ```json { "msg": "", "data": { "orderId": "a49579dd-7711-11ef-8277-02d8461243e9", "merchantOrderId": "b73b73b-87wtbc-q36gbc-331n3", "baseAmount": 1, "baseCurrency": "USDT", "baseAmountRecieved": 10 "settledCurrency": "USDT", "settledAmountRequested": 1, "settledAmountReceived": 0, "settledAmountCredited": 0, "commission": 0.01, "network": "BSC", "depositAddress": "0xdbfc3d80de367906ccb456fe2eed57c39f05f63c", "status": "Expired", "paymentURL": "https://app.tylt.money/pscreen/a49579dd-7711-11ef-8277-02d8461243e9", "callBackURL": "", "transactions": [], "createdAt": "2024-09-20T05:31:53Z", "expiresAt": "2024-09-20T06:31:53Z", "updatedAt": "2024-09-20T06:31:56Z", "isFinal": 1, "isCredited": 0, "customerName": "TradingLeagues", "comments": "Description testing 234" } } ``` {% endtab %} {% tab title="Response Fields" %} | **Field Name** | **Type** | **Description** | | ------------------------ | -------- | -------------------------------------------------------------------------------------------- | | `orderId` | string | The order ID generated by TL Pay, used as a global identifier for the transaction. | | `merchantOrderId` | string | The order ID provided by the Merchant, used for local reference (optional). | | `baseAmount` | number | The base value of the good/service being supplied. | | `baseCurrency` | string | The base currency of the good/service being supplied. | | `baseAmountReceived` | number | The amount of cryptocurrency/token received from the customer expressed in the baseCurrency. | | `settledCurrency` | string | The cryptocurrency/token in which the payment is to be made by the customer. | | `settledAmountRequested` | number | The amount of cryptocurrency/token requested from the customer. | | `settledAmountReceived` | number | The amount of cryptocurrency/token received from the customer. | | `settledAmountCredited` | number | The amount of cryptocurrency/token credited to the merchant's balance (net). | | `commission` | number | The commission deducted for the transaction. | | `network` | string | The cryptocurrency network over which the payment is made. | | `depositAddress` | string | The address for receiving the payment. | | `status` | string | The status of the transaction (e.g., Expired, Pending, Completed). | | `paymentURL` | string | The payment link that needs to be used by the customer to make the payment. | | `callBackURL` | string | The callback URL for post-payment notifications (if applicable). | | `transactions` | array | Details of the transactions resulting in the payment (if any). | | `createdAt` | string | The timestamp when the transaction was created. | | `expiresAt` | string | The timestamp when the transaction expires. | | `updatedAt` | string | The timestamp when the transaction was last updated. | | `isFinal` | number | Indicates if the transaction is complete (1) or still processing (0). | | `isCredited` | number | Indicates if the payment has been credited to the merchant account (1: Yes, 0: No). | | `customerName` | string | The name of the customer provided by the merchant (optional). | | `comments` | string | Comments provided by the merchant about the transaction (optional). | {% endtab %} {% endtabs %} ### Understanding and Handling Transactions Based on Status The response field **`status`** represents the current state of a transaction. Applications should interpret and handle transactions according to the following possible states: | Status | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------- | | Pending | The transaction is awaiting payment or confirmation. | | Completed | The transaction is successfully completed and settled. The customer has paid **exactly** the `settledAmountRequested`. | | Under Payment | The transaction is completed and settled, but the customer paid **less** than the `settledAmountRequested`. | | Over Payment | The transaction is completed and settled, but the customer paid **more** than the `settledAmountRequested`. | | Expired | The transaction expired without any payment being received from the customer. | *** ## Understanding and Handling Over-Payment and Under-Payment How a merchant handles over-payments and under-payments depends on their **business model**, **use case**, and **internal policies**. Broadly, practices differ between industries that **accept deposits** and those that **sell goods or services**. *** ### 1. Industries Accepting Deposits *(e.g., iGaming, Trading, Forex, Wallet Services, Insurance)* In these industries, payments are treated as **deposits into a user account/wallet**. The user’s balance is updated based on either: * **baseCurrencyReceived** → The fiat or local equivalent value at the time of receipt (e.g., BRL, AED). * **settledCurrencyReceived** → The actual crypto amount received in the settlement currency (e.g., USDT). #### Under-Payment * Merchant may accept the partial payment and **credit proportionally**. * Merchant may choose to **refund the entire amount**. {% hint style="warning" %} **Refund can be initiated by using the** [**Creating a Payout Request API**](https://docs.tylt.money/tylt-cpg-crypto-payment-gateway/api-reference/make-crypto-payouts/creating-a-payout-request) {% endhint %} #### Over-Payment * Merchant may **refund the excess**. * Merchant may accept the full amount and **credit the total received**. {% hint style="warning" %} **Refund can be initiated by using the** [**Creating a Payout Request API**](https://docs.tylt.money/tylt-cpg-crypto-payment-gateway/api-reference/make-crypto-payouts/creating-a-payout-request) {% endhint %} *** **Example A: Deposit Requested in Crypto (USDT)** * **Requested**: 100 USDT * **Received**: 95 USDT (under-payment) → Merchant credits **95 USDT** to user wallet. * **Received**: 105 USDT (over-payment) → Merchant credits **105 USDT** to user wallet. Since both the **baseCurrency** and **settledCurrency** are the same (USDT), the merchant may use either `baseCurrencyReceived` or `settledCurrencyReceived` to handle the business logic. *** **Example B: Deposit Requested in Fiat (FX-Denominated)** * **Requested**: 500 BRL equivalent 1. **Received**: 95 USDT → At settlement, worth **475 BRL**. * Merchant may credit: * **475 BRL** (using `baseCurrencyReceived`), OR * **95 USDT** (using `settledCurrencyReceived`). 2. **Received**: 105 USDT → At settlement, worth **525 BRL**. * Merchant may credit: * **525 BRL** (using `baseCurrencyReceived`), OR * **105 USDT** (using `settledCurrencyReceived`). {% hint style="warning" %} **Response Records:** * `baseCurrencyReceived = 475 BRL / 525 BRL` * `settledCurrencyReceived = 95 USDT / 105 USDT` This **dual recording** ensures flexibility: deposits can be credited in either **fiat terms** or **crypto terms**, depending on merchant policy. {% endhint %} *** ### 2. Industries Accepting Payments for Sale of Merchandise *(e.g., Retail, eCommerce, SaaS, Subscriptions)* Here, payments correspond to a **specific invoice** for goods or services. Merchants may settle either in **fiat equivalent value** or in the **crypto amount received**. #### Under-Payment * Merchant may **hold the order** until the missing balance is paid. * Merchant may **accept partial payment** and adjust/store credit accordingly. #### Over-Payment * Merchant may **refund the excess amount**. * Merchant may **apply the excess as store credit**. {% hint style="warning" %} **Refund can be initiated by using the** [**Creating a Payout Request API**](https://docs.tylt.money/tylt-cpg-crypto-payment-gateway/api-reference/make-crypto-payouts/creating-a-payout-request) {% endhint %} *** #### 📌 Example A: Invoice Requested in Crypto (USDT) * **Invoice**: 100 USDT 1. **Received = 95 USDT (under-payment)** * (a) Hold order until extra 5 USDT is received. * (b) Accept 95 USDT and adjust/store credit. **Response Records:** * `baseCurrencyReceived = 95 USDT` * `settledCurrencyReceived = 95 USDT` 2. **Received = 105 USDT (over-payment)** * (a) Ship order and refund 5 USDT. * (b) Apply 5 USDT as store credit. **Response Records:** * `baseCurrencyReceived = 105 USDT` * `settledCurrencyReceived = 105 USDT` *** #### 📌 Example B: Invoice Requested in Fiat (AED) * **Invoice**: 1,000 AED 1. **Received = 95 USDT → 950 AED (under-payment)** * (a) Hold order until missing 50 AED is received. * (b) Process order for 950 AED value. * (c) Refund the entire amount. **Response Records:** * `baseCurrencyReceived = 950 AED` * `settledCurrencyReceived = 95 USDT` 2. **Received = 105 USDT → 1,050 AED (over-payment)** * (a) Ship order for 1,000 AED and refund 50 AED. * (b) Apply 50 AED as store credit. * (c) Refund the entire 1,050 AED. **Response Records:** * `baseCurrencyReceived = 1,050 AED` * `settledCurrencyReceived = 105 USDT` {% hint style="warning" %} **Response Records:** * `baseCurrencyReceived = 1,050 AED / 950 AED` * `settledCurrencyReceived = 95 USDT / 105 USDT` This **dual recording** ensures flexibility: deposits can be credited in either **fiat terms** or **crypto terms**, depending on merchant policy. {% endhint %} ***