Settings

Business configuration endpoints for outgoing webhooks, settlement accounts, and your internal business wallet.

Auth required: JWT
Permission required: settings:manage
Base path: /api/v1/settings

---

Webhook Configuration

Configure where Rach sends payment event notifications.

Get current config

GET /api/v1/settings/webhook
Authorization: Bearer <token>

Response

{
  "url": "https://yoursite.com/webhooks/rach",
  "events": ["payment.confirmed", "withdrawal.completed"],
  "is_active": true
}

Configure webhook

POST /api/v1/settings/webhook
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://yoursite.com/webhooks/rach",
  "events": ["payment.confirmed", "payment.failed", "withdrawal.completed"]
}

Rotate signing secret

Generates a new HMAC-SHA256 signing secret. Update your server immediately — the old secret stops working.

POST /api/v1/settings/webhook/rotate-secret
Authorization: Bearer <token>

Send test event

POST /api/v1/settings/webhook/test
Authorization: Bearer <token>

Sends a dummy payment.test event to your configured URL so you can verify your handler is working.

Verifying webhook signatures

All outgoing webhooks include an X-Rach-Signature header. Verify it:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

---

Settlement Accounts

Bank accounts where your withdrawn funds are sent.

Add account

POST /api/v1/settings/settlement-accounts
Authorization: Bearer <token>
Content-Type: application/json

{
  "account_name": "My Business Ltd",
  "account_number": "12345678",
  "sort_code": "20-00-00",
  "bank_name": "Barclays",
  "currency": "GBP",
  "country": "GB"
}

List accounts

GET /api/v1/settings/settlement-accounts
Authorization: Bearer <token>

Update account

PUT /api/v1/settings/settlement-accounts/:id
Authorization: Bearer <token>
Content-Type: application/json

Remove account

DELETE /api/v1/settings/settlement-accounts/:id
Authorization: Bearer <token>

---

Business Wallet (Internal WaaS)

Your business's own crypto wallet, separate from customer wallets managed via the WaaS API.

Generate wallet

One-time setup. Requires KYC approval.

POST /api/v1/settings/wallet/generate
Authorization: Bearer <token>
Permission: wallet:manage

Get wallet

GET /api/v1/settings/wallet
Authorization: Bearer <token>
Permission: wallet:manage

Get address for a specific network

GET /api/v1/settings/wallet/address/:network
Authorization: Bearer <token>
Permission: wallet:manage

Replace :network with BSC, ETH, TRON, SOL, BTC, etc.

Export seed phrase

Requires KYC + active 2FA (TOTP code must be provided).

POST /api/v1/settings/wallet/seed
Authorization: Bearer <token>
Permission: wallet:reveal_seed
Content-Type: application/json

{
  "otp_code": "123456"
}