Environments
Live and test data use the same API host and separate API keys.
The merchant API has two environments: live and test. The API key selects the environment; the base URL stays https://api.thehalfin.com.
Live vs test#
| Live | Test | |
|---|---|---|
| Key prefix | sk_live_ | sk_test_ |
| Funds | Real funds on mainnet | Test coins on configured testnets |
| Resources | Live invoices, addresses, payouts, and balances | Separate test resources and balances |
| Webhooks | Live endpoints receive live events | Test endpoints receive test events |
| Idempotency | Live key namespace | Separate test key namespace |
The same idempotency-key text may be used independently in live and test. Within an environment, changing API keys does not create a fresh idempotency namespace.
Test an integration#
Use a test key to discover configured currency/network pairs, create an invoice, and pay its address with test coins on the matching testnet. A test transaction still needs to be observed and accepted. There is no merchant API payment simulator or guaranteed deterministic trigger for an underpayment, overpayment, or reversal.
The dashboard can send a signed webhook.ping to test your receiver: open the endpoint in Developers → Webhooks & deliveries and choose Send test. It tests delivery and signature handling, not invoice payment; the outcome and every attempt appear on the Deliveries page.
Currency and rate differences#
Request the currency catalog and rates with the key for the environment you are using. The enabled pairs and confirmation requirements can differ. Rates use a shared reference price for each pair configured in both environments; test does not have a separate price feed. Use testnet explorers for test transactions and mainnet explorers for live transactions.
Supported test assets#
Test currently supports native assets on configured testnets. Live token support does not imply test USDT or USDC support, and conversions are unavailable in test. All four standalone conversion endpoints return 422 not_live for a test key, and conversion.* webhooks are emitted only in live.
The currency and network identifiers stay the same across environments. For example, ETH / ethereum means Ethereum mainnet with a live key and Ethereum Sepolia with a test key. SOL / solana uses Solana Devnet in test, not Testnet. Use only pairs returned for your test key and send funds on the matching physical testnet.
Test invoices, addresses, payouts, refunds, balances, and idempotency outcomes are isolated from live. A resource ID from one environment is not accessible through a key for the other. Webhook endpoints are also scoped to their environment; register your test receiver in test.
API hosts#
There is no separate public sandbox hostname. Internal staging is reserved for the halfin team and is not a merchant test environment. Access to the test contour and enabled rails must be provisioned for your merchant.