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.bitzone.space
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": "SBER",
  "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": "SBER",
    "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.

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.