Creating a PayIn

Create PayIn Order

POST https://api-processing.crypto-chief.com/v1/payments/order/create

This endpoint initializes a payment session. To use it correctly, you must first choose your Business Logic Mode.

1. The Two Payment Mechanics

The system operates in two fundamentally different modes defined by the mode parameter.

🏛️ Mode: FIAT

"I want to receive the equivalent of 100 USD."

• Logic: You set a fixed price in fiat currency (USD, EUR, INR).

• Exchange Rate: The system calculates the crypto amount dynamically at the moment of payment.

• Volatility: The system handles the exchange rate risk.

• Best For: E-commerce shops, SaaS subscriptions, goods priced in fiat.

⛓️ Mode: CRYPTO

"I want to receive exactly 50.5 USDT."

• Logic: You set a fixed amount of tokens.

• Exchange Rate: Ignored. 1 Token = 1 Token.

• Volatility: You receive exactly what was requested, regardless of dollar value.

• Best For: Wallet top-ups, crypto-native services, transfers.

---

2. Common Parameters (Required for Both)

These parameters must be included in every request.

Headers

Name	Value
Content-Type	application/json
Signature	Signed request body
Merchant	Merchant ID

Body

Name	Type	Required	Description
order_id	string	true	Unique external ID (Idempotency key).
user_id	string	true	Internal user identifier.
mode	string	true	"fiat" or "crypto"
to_address	string	false	If provided, the system detects the network and attempts to lock the payment method automatically.
lifetime_sec	int	false	Order expiration time Default: 1800
url_callback	string	false	Webhook URL for status updates
url_success	string	false	Client redirect URL after successful payment.
url_error	string	false	Client redirect URL after failed/expired payment.
additional_data	string	false	Custom string with metadata.
accuracy_payment_percent	int	false	Allowed underpayment/overpayment percentage (e.g., 2 for 2%). Min: 0 Max: 5 Default: 5

3. Workflow A: FIAT Mode

Requirement: mode = "fiat"

In this mode, you define the value in traditional currency. The user can pay in various cryptocurrencies, and the system ensures you get the requested value.

Specific Parameters in Body

Name	Type	Required	Description
amount_fiat	string	true	The cost in fiat (e.g., "100.50")
currency	CURRENCY	true	The fiat code (e.g., "USD", "EUR")
course_source	DATA_SOURCE	false	The service from which exchange rates are taken for recalculation in the order. Default: any
assets	ASSETS_POLICY	false	Define which coins are allowed or excluded

Example Request

Invoice for 100 USD

{
  "order_id": "ord-fiat-01",
  "user_id": "u-1",
  "mode": "fiat",
  "amount_fiat": "100.00",
  "currency": "USD"
}

4. Workflow B: CRYPTO Mode

Requirement: mode = "crypto"

In this mode, you define the value in tokens. No conversion takes place. The user must send exactly this amount.

Specific Parameters in Body

Name	Type	Required	Description
amount_crypto	string	true	The cost in fiat (e.g., "100.50")
asset	ASSET	true	Define which coin is allowed

Example Request

Charge exactly 50.5 USDT on TRON network.

{
  "order_id": "ord-crypto-01",
  "user_id": "u-1",
  "mode": "crypto",
  "amount_crypto": "50.5",
  "asset": {
    "coin": "USDT",
    "network": "TRON"
  }
}

5. Response Handling & Next Steps

The API response tells you the current state of the order. Your next step depends on your integration type: Hosted Page (simplest) or Host-to-Host (custom UI).

Status: waiting_asset_select

Meaning: The order is created, but the specific cryptocurrency is not yet chosen. The coins array contains the list of available options.

👉 Next Step depends on your integration:

• Option A: Hosted Payment Page

  • Action: Redirect the user to the payment_link URL provided in the response.

  • Logic: Our system handles the UI. The user will select the coin on our page. No further API calls required.

• Option B: Host-to-Host (White Label)

  • Action: Render the list of coins to the user.

  • Logic: When the user clicks on a specific coin/network, you must call the Select Asset Endpoint to lock the choice and generate the address.

  • Method: SELECT ASSET

---

Status: pending

Meaning: The payment method is locked. The wallet address has been assigned.

👉 Next Step depends on your integration:

• Option A: Hosted Payment Page

  • Logic: The user will see the QR code and address on our page. No further API calls required.

• Option B: Host-to-Host (White Label)

  • Action: Display the payment details directly in your UI.

  • Data to use: payment_network, payment_coin , to_address and amount_crypto.

Response

200

{
    "type": "PayIn",
    "uuid": "a15eadd9-d68f-4ddf-8004-5311f0e2b576",
    "order_id": "ord-crypto-1",
    "user_id": "user-1",
    "mode": "crypto",
    "is_test": true,
    "status": "pending",
    "lifetime": 1800,
    "expired_at": "2026-01-15T13:13:11.965064135Z",
    "is_expired": false,
    "can_cancel": true,
    "amount_fiat": null,
    "currency": null,
    "amount_crypto": "0.005",
    "fact_amount_fiat": null,
    "fact_amount_crypto": null,
    "accuracy_payment_percent": 5,
    "to_address": "0x72ddc7ea48f6edb6ee63ca9bd995b9235cd4ffc3",
    "memo": null,
    "from_address": null,
    "txid": null,
    "coins": [
        {
            "chain_family": "EVM",
            "coin": "BNB",
            "network": "BSC_TESTNET"
        }
    ],
    "has_choices": false,
    "url_success": null,
    "url_error": null,
    "url_callback": null,
    "confirmations": 0,
    "required_confirmations": 20,
    "paid_at": null,
    "confirmed_at": null,
    "additional_data": null,
    "created_at": "2026-01-15T12:43:12.049213Z",
    "payment_link": "https://crypto-terminal.crypto-chief.com/pay/a15eadd9-d68f-4ddf-8004-5311f0e2b576",
    "payment_coin": "BNB",
    "payment_network": "BSC_TESTNET",
    "convert": {
        "auto_convert": false,
        "coin": "BNB",
        "convert_coin": null,
        "convert_network": null,
        "course_source": "any",
        "network": "BSC_TESTNET",
        "rate": null
    }
}

400

---

Asset Object

Name	Type	Required	Description
coin	COIN	true	The cryptocurrency ticker symbol (e.g., "USDT", "BTC", "ETH").
network	CHAIN	true	The blockchain network code (e.g., , ETH_MAINNET , TRON_MAINNET). Use "ANY" to indicate all available networks for this coin.

JSON Example:

{
  "coin": "USDT",
  "network": "TRON_MAINNET"
}

ASSETS_POLICY Object

Used in the assets parameter to filter the payment methods shown to the user.

Name	Type	Required	Description
allow	ASSET []	false	Whitelist. An array of Asset objects. If provided, the user will see only these assets. All others are hidden.
exclude	ASSET []	false	Blacklist. An array of Asset objects. These specific assets will be hidden from the user.

JSON Example:

{
  "allow": [
    { "coin": "USDT", "network": "ANY" }
  ],
  "exclude": [
    { "coin": "BTC", "network": "ANY" }
  ]
}