Pay-In

Pay-In Overview

The pay-in process allows you to accept fiat payments from your clients and convert them into cryptocurrency or fiat balances on your account. This feature ensures seamless transactions for your business needs.

Pay-In Processing Lifecycle

For a visual representation of the pay-in lifecycle, refer to the diagram below:

Pay-in Stages

The typical flow of a pay-in transaction involves the following stages:

1. active

   • The transaction has been created and is awaiting payment from the client.
   • Once the client makes the payment, the system typically processes and closes the transaction automatically within seconds.

2. closed

   • The transaction has been successfully completed.
   • Funds have been received from the client and credited to your account.

3. canceled

   • The transaction was canceled because the client failed to complete the payment within the allotted time frame.
   • You can configure the payment window (time limit for payment) in your settings.

4. dispute

   • A dispute has been raised for the transaction, typically by providing a payment receipt.
   • The transaction enters an appeal process handled by support specialists.

5. checking

   • The transaction is under review as part of the dispute process.
   • This stage involves verification by one of the parties managing the payment details.

6. re_calculation

   • The transaction has successfully passed the dispute phase.
   • The fiat amount has been recalculated and adjusted based on the actual payment details.

Initiate transaction

To initiate a pay-in transaction, use the [POST] /payment/trading/pay-in endpoint. During the request, you’ll specify either fiatAmount or fiatAmountRange. In response, you’ll immediately receive the cryptoAmount, payment requisite, currency rate, and the merchantFee for the transaction.

info

• Bank Selection:
  • If you do not specify the bank property when creating a transaction, the system will assign requisites from a randomly available bank.
  • If you specify the bank property, requisites from the selected bank will be provided.

You can retrieve the list of all available banks via the API endpoint: [GET] /payment/trading/banks.

Example Request:

POST /payment/trading/pay-in
Host: {{api-url}}
x-signature: d3b07384d113edec49eaa6238ad5ff00
Content-Type: application/json

{
  "fiatAmount": 5000,
  "extra": {
    "payerInfo": {
      "ip": "192.168.1.1",
      "userId": "65535",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/655.1.15 (KHTML, like Gecko) Version/16.4 Mobile/148 Safari/04.1",
      "fingerprint": "fbb77b9f4265b18538e66cac5a37c6410dc2cdd7f0cddfde6eda25aa10df669b",
      "registeredAt": 1728388185326
    },
    "externalTransactionId": "txn_123456789"
  }
}

Example Response:

{
  "id": "43ba8793-66ad-482f-9e74-54381d3aea25",
  "fiatAmount": "5000.00",
  "cryptoAmount": "60835352",
  "merchantFee": "5171005",
  "currencyRate": "99.12",
  "type": "pay-in",
  "status": "active",
  "bank": "RAIFFEISEN",
  "fiatCurrency": "EUR",
  "cryptoCurrency": "usdt",
  "cryptoNetwork": "trc20",
  "payoutInvoicesUrl": [],
  "disputeMerchantCheckUrl": null,
  "disputeTraderCheckUrl": null,
  "disputeMerchantFiatAmount": "0.00",
  "disputeTraderFiatAmount": "0.00",
  "requisite": {
    "id": "13edb294-2f1e-4679-a62a-ea12fdab1c9c",
    "bank": "RAIFFEISEN",
    "ownerName": "123123123123",
    "sbpNumber": null,
    "requisites": "123123123123123",
    "fiatCurrency": "EUR"
  },
  "extra": {
    "payerInfo": {
      "ip": "192.168.1.1",
      "userId": "65535",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_6_1 like Mac OS X) AppleWebKit/655.1.15 (KHTML, like Gecko) Version/16.4 Mobile/148 Safari/04.1",
      "fingerprint": "fbb77b9f4265b18538e66cac5a37c6410dc2cdd7f0cddfde6eda25aa10df669b",
      "registeredAt": 1728388185326
    },
    "externalTransactionId": "txn_123456789"
  },
  "createdAt": "2024-11-08T17:00:16.583Z"
}

Key Workflow Notes

info

Initial Status: Once a pay-in request is successfully created, its status will be active.

note

Payment Window: Each request has a payment window, configured in the settings. If payment is not completed within this window, the request will be automatically canceled, and you will receive a notification via your webhook.

info

Completed Payment: If the customer successfully completes the payment within the specified window, the transaction will automatically be marked as closed.

UTR Flow For INR Pay-Ins

For INR pay-in trades, the platform supports payment confirmation by utr in addition to the standard receipt upload flow.

• UTR confirmation is available only for pay-in trades where fiatCurrency = INR.
• The utr value must be unique across pay-in trades. Reusing the same value for another trade is rejected.
• Merchant API confirmation expects a 12-digit numeric utr.
• On the payment page, the customer can submit either invoiceKey or utr, but never both in the same request.

How To Work With It

1. Create the pay-in trade as usual.
2. If the trade uses INR, let the payer provide their UTR after they complete the bank transfer.
3. Confirm the trade by calling POST /payment/trading/pay-in/:id/confirm-utr from your backend, or let the payer submit the UTR on the hosted payment page.
4. Store the trade id and the confirmed utr in your system so you can reconcile callbacks, support requests, and bank-side investigations.

Result Of Successful UTR Confirmation

• The trade is moved from active to paid.
• Merchant callback creation and user trade update notifications are triggered.
• If the UTR is invalid for this flow, duplicated, or used on a non-INR trade, the request is rejected.

If an INR trade has already timed out and moved to canceled, operators can still restore it from backoffice by attaching the UTR there. This is an internal recovery flow, so merchant integrations should treat it as an operational exception rather than a primary API path.

Handling High Volume and Requisites

For cases where a large number of pay-in requests are created with identical amounts, it’s possible that requisites may temporarily be unavailable. To manage this, we recommend using fiatAmountRange instead of a fixed fiatAmount. This allows the system to select a suitable amount within the specified range, improving request fulfillment rates.

Optional Parameters

• Method: By default, if method is not specified, the system will randomly assign an available payment method.
• Bank: If left unspecified, the platform will assign any available bank.

Importance of Extra Parameters

Providing additional parameters in extra—such as user information and a transaction ID from your system—helps to improve security and payment reliability. The platform’s fraud prevention system leverages this information to detect and prevent unauthorized transactions, maintaining stability and integrity in the payment process.