Concepts
Payouts
Send funds from merchant balance
Reference
A payout sends funds from your merchant balance to an external blockchain address. New payouts enter pending_approval and require approval before execution.
| State | Meaning |
|---|---|
pending_approval | Created, awaiting dashboard approval |
processing | Submitted for blockchain execution |
completed | Confirmed on-chain |
failed | Failed and funds were released |
Usage
Create payouts from trusted server-side code only.
curl -X POST https://api.halfin.xyz/api/v1/payouts \
-H "Content-Type: application/json" \
-H "X-API-Key: $HALFIN_API_KEY" \
-d '{"currency":"BTC","amount":"0.01000000","destination":"bc1qexampleaddress000000000000000000000000"}'import { createHalfin, createPayout } from '@halfin/sdk-merchant';
const client = createHalfin({ apiKey: process.env.HALFIN_API_KEY });
const { data } = await createPayout({
client,
body: {
currency: 'BTC',
amount: '0.01000000',
destination: 'bc1qexampleaddress000000000000000000000000',
},
});# Python SDK coming soon. Use the cURL example for now.Pitfalls
- Validate destination addresses before creating a payout.
- Keep payout keys more restricted than invoice keys.
Troubleshooting
403 forbidden usually means the API key lacks payouts:write.
Payout stuck in pending approval means it has not yet been approved in the dashboard.