API Reference

Complete endpoint inventory for the Rach Payments API.

Base URL

https://payments-api-dev-966260606560.europe-west2.run.app

Authentication

Method	Header	When to use
JWT	Authorization: Bearer <token>	Dashboard, account management, KYC
API Key	X-API-Key: <key>	Merchant integrations (checkout, remittance, wallet)

---

Public Endpoints (no auth)

Method	Path	Description
GET	/health	Health check
GET	/docs	Swagger UI
GET	/docs/swagger.yaml	OpenAPI 3.0 spec
GET	/api/v1/rate/check	Check exchange rate (query params: pair or from+to)
POST	/api/v1/wallet/estimate-gas	Estimate gas fee for a transfer
GET	/pay/:uuid	Hosted payment page (rendered HTML)
POST	/api/v1/subscription/crypto-checkout	Subscription crypto checkout (public)

Webhooks (inbound, no auth)

Method	Path	Source
POST	/webhooks/tatum	Tatum blockchain events
POST	/webhooks/stripe	Stripe payment events
POST	/webhooks/verto	Verto virtual account events

---

Auth Endpoints

Method	Path	Auth	Description
POST	/api/v1/auth/register	—	Create account
POST	/api/v1/auth/verify-email	—	Verify email address
POST	/api/v1/auth/login	—	Login, get JWT
POST	/api/v1/auth/refresh	—	Refresh access token
POST	/api/v1/auth/forgot-password	—	Request password reset email
POST	/api/v1/auth/reset-password	—	Set new password
GET	/api/v1/auth/me	JWT	Get current user profile
PUT	/api/v1/auth/profile	JWT	Update profile
POST	/api/v1/auth/workspace/switch	JWT	Switch active workspace
POST	/api/v1/auth/change-password	JWT	Change password
GET	/api/v1/auth/api-key	JWT	Get business API key

---

Two-Factor Authentication

Requires JWT. See 2FA docs →

Method	Path	Description
GET	/api/v1/auth/2fa/status	Get 2FA status
POST	/api/v1/auth/2fa/setup	Initiate TOTP setup (returns QR code)
POST	/api/v1/auth/2fa/enable	Confirm and enable 2FA
POST	/api/v1/auth/2fa/disable	Disable 2FA

---

Team Management

Requires JWT. Permission: team:view / team:invite / team:manage_permissions. See Team docs →

Method	Path	Description
GET	/api/v1/team/invites/verify/:token	Verify invite token (public)
POST	/api/v1/team/register	Register as invited team member (public)
GET	/api/v1/team	List team members
GET	/api/v1/team/roles-permissions	Get available roles and permissions
POST	/api/v1/team/invites	Invite a team member
PUT	/api/v1/team/:id/permissions	Update member permissions
DELETE	/api/v1/team/:id	Remove a team member

---

KYC

Requires JWT.

Method	Path	Permission	Description
POST	/api/v1/kyc/submit	kyc:submit	Submit KYC documents
GET	/api/v1/kyc/status	kyc:view	Get KYC status
GET	/api/v1/kyc/otc/status	kyc:view	Get OTC AML status
PUT	/api/v1/kyc/otc/draft	kyc:submit	Save OTC AML draft
POST	/api/v1/kyc/otc/submit	kyc:submit	Submit OTC AML form

---

Balance & Withdrawal

Requires JWT + KYC approval.

Method	Path	Permission	Description
GET	/api/v1/balance	balance:view	Get crypto balances
POST	/api/v1/balance/swap	balance:swap	Swap between currencies
POST	/api/v1/withdrawal/request	withdrawal:request	Request fiat withdrawal
GET	/api/v1/withdrawal/history	withdrawal:view	Withdrawal history
GET	/api/v1/withdrawal/:id	withdrawal:view	Get single withdrawal

---

Remittance

Requires API key + KYC approval.

Method	Path	Permission	Description
POST	/api/v1/remittance/quote	remittance:quote	Get transfer quote
POST	/api/v1/remittance/transfer	remittance:create	Create transfer (requires HMAC signature)
GET	/api/v1/remittance/transfers/:id	remittance:view	Get transfer details
GET	/api/v1/remittance/transfers	remittance:view	List transfers
GET	/api/v1/remittance/rates	remittance:view	List exchange rates

JWT variant (dashboard):

Method	Path	Permission	Description
POST	/api/v1/remittance/create	remittance:create	Create transfer (JWT + 2FA OTP required)

---

Crypto Checkout

Requires API key + KYC + business account (individuals blocked).

Method	Path	Permission	Description
POST	/api/v1/checkout/create	checkout:manage	Create a checkout session
GET	/api/v1/checkout/verify/:sessionId	checkout:view	Verify a checkout session
GET	/api/v1/checkout/addresses	checkout:view	List deposit addresses
GET	/api/v1/checkout/list	checkout:view	List all checkout payments
GET	/api/v1/checkout/stats	checkout:view	Payment statistics

Public checkout (no auth — for hosted payment page):

Method	Path	Description
GET	/api/v1/checkout/:uuid	Get checkout session (customer-facing)
POST	/api/v1/checkout/:uuid/select-network	Customer selects payment network
GET	/api/v1/checkout/:uuid/verify-now	Trigger immediate verification

---

Rates

Method	Path	Auth	Description
GET	/api/v1/rate/check	—	Check rate (public, query: pair or from+to)
GET	/api/v1/rates/:pair	API key	Get rate for pair (e.g. NGNGBP)

---

Wallet-as-a-Service (WaaS)

Requires API key + KYC + business account. See Wallet Service docs →

Method	Path	Permission	Description
GET	/api/v1/wallet/customers	—	List all customers with wallets
GET	/api/v1/wallet/addresses	—	List all business-level addresses
POST	/api/v1/wallet/customers	—	Create a customer wallet
GET	/api/v1/wallet/:customerID/addresses	—	List addresses for customer
GET	/api/v1/wallet/:customerID/seed	wallet:reveal_seed	Get seed phrase
POST	/api/v1/wallet/:customerID/derive	—	Derive new address for network
POST	/api/v1/wallet/:customerID/export-key	wallet:export_key	Export private key
POST	/api/v1/wallet/:customerID/transfer	wallet:transfer	Send crypto
GET	/api/v1/wallet/:customerID/transactions	—	Transaction history
POST	/api/v1/wallet/estimate-gas	—	Estimate gas (public)

---

Analytics

Requires JWT + KYC. Permission: analytics:view. See Analytics docs →

Method	Path	Description
GET	/api/v1/analytics/overview	Revenue & volume overview
GET	/api/v1/analytics/revenue	Revenue breakdown
GET	/api/v1/analytics/payment-methods	Payment method distribution
GET	/api/v1/analytics/transactions	Transaction list with filters
GET	/api/v1/analytics/fraud-alerts	Fraud alert summary
GET	/api/v1/analytics/dashboard	Combined dashboard data

---

OTC Trading

Requires JWT. Business must have OTC access approved by admin. See OTC docs →

Method	Path	Permission	Description
GET	/api/v1/otc/accounts	otc:view	Available OTC accounts
GET	/api/v1/otc/quote	otc:view	Get OTC quote
POST	/api/v1/otc/orders	otc:trade	Create OTC order
POST	/api/v1/otc/orders/:id/paid	otc:trade	Mark order as paid
GET	/api/v1/otc/orders/:id	otc:view	Get order details
POST	/api/v1/otc/orders/:id/refresh	otc:trade	Refresh quote on order
GET	/api/v1/otc/history	otc:view	OTC trade history

---

Settings

Requires JWT. Permission: settings:manage. See Settings docs →

Webhook Configuration

Method	Path	Description
GET	/api/v1/settings/webhook	Get current webhook config
POST	/api/v1/settings/webhook	Configure webhook endpoint
POST	/api/v1/settings/webhook/rotate-secret	Rotate HMAC signing secret
POST	/api/v1/settings/webhook/test	Send a test webhook event

Settlement Accounts

Method	Path	Description
POST	/api/v1/settings/settlement-accounts	Add settlement account
GET	/api/v1/settings/settlement-accounts	List settlement accounts
PUT	/api/v1/settings/settlement-accounts/:id	Update settlement account
DELETE	/api/v1/settings/settlement-accounts/:id	Remove settlement account

Business Wallet (Internal)

Method	Path	Permission	Description
POST	/api/v1/settings/wallet/generate	wallet:manage	Generate business wallet (requires KYC)
GET	/api/v1/settings/wallet	wallet:manage	Get business wallet
GET	/api/v1/settings/wallet/address/:network	wallet:manage	Get address for network
POST	/api/v1/settings/wallet/seed	wallet:reveal_seed	Export seed phrase (requires KYC + 2FA)

---

API Keys

Requires JWT.

Method	Path	Description
GET	/api/v1/api-keys	List API keys (test + production)
POST	/api/v1/api-keys/initialize	Initialize keys for existing users
POST	/api/v1/api-keys/rotate/test	Rotate test API key
POST	/api/v1/api-keys/rotate/production	Rotate production API key
POST	/api/v1/api-keys/toggle-sandbox	Toggle sandbox mode
GET	/api/v1/api-keys/sandbox/balance	Get sandbox balances
POST	/api/v1/api-keys/sandbox/reset	Reset sandbox balances

---

Push Notifications

Requires JWT. See Notifications docs →

Method	Path	Description
POST	/api/v1/auth/fcm-token	Register FCM device token
DELETE	/api/v1/auth/fcm-token	Unregister FCM device token
GET	/api/v1/auth/notification-preferences	Get notification preferences
PUT	/api/v1/auth/notification-preferences	Update notification preferences

---

Virtual Accounts

Requires JWT + KYC. Permission: virtual_account:manage. See Virtual Accounts docs →

Method	Path	Description
POST	/api/v1/virtual-accounts/create	Create a virtual bank account
GET	/api/v1/virtual-accounts	List virtual accounts

---

Subscription & Billing

Requires JWT. Permission: billing:manage.

Method	Path	Description
GET	/api/v1/subscription/current	Get current plan
GET	/api/v1/subscription/plans	List available plans
POST	/api/v1/subscription/upgrade	Request plan upgrade

---

File Uploads

Requires JWT.

Method	Path	Description
POST	/api/v1/files/upload-url	Get signed GCS upload URL
POST	/api/v1/files/view-url	Get signed GCS view URL

---

Stripe

Method	Path	Auth	Description
POST	/api/v1/stripe/checkout	—	Create Stripe checkout session (email-based)

---

Admin Endpoints

Requires JWT with admin role.

KYC Administration

Method	Path	Description
GET	/api/v1/admin/kyc/pending	List pending KYC submissions
GET	/api/v1/admin/kyc/submissions/:id	Get KYC submission
POST	/api/v1/admin/kyc/submissions/:id/approve	Approve KYC
POST	/api/v1/admin/kyc/submissions/:id/reject	Reject KYC
GET	/api/v1/admin/kyc/statistics	KYC statistics
GET	/api/v1/admin/kyc/otc/pending	Pending OTC AML submissions
POST	/api/v1/admin/kyc/otc/submissions/:id/approve	Approve OTC AML
POST	/api/v1/admin/kyc/otc/submissions/:id/reject	Reject OTC AML

Business Management

Method	Path	Description
GET	/api/v1/admin/businesses	List all businesses
GET	/api/v1/admin/businesses/:id	Get business details
POST	/api/v1/admin/businesses/:id/suspend	Suspend business
POST	/api/v1/admin/businesses/:id/activate	Activate business
GET	/api/v1/admin/businesses/:id/activity	Business activity log

Transaction Monitoring

Method	Path	Description
GET	/api/v1/admin/transactions	All transactions
GET	/api/v1/admin/transactions/failed	Failed transactions

Fraud Management

Method	Path	Description
GET	/api/v1/admin/fraud/alerts	All fraud alerts
GET	/api/v1/admin/fraud/alerts/:id	Get alert detail
POST	/api/v1/admin/fraud/alerts/:id/review	Review alert
GET	/api/v1/admin/fraud/rules/:businessId	Get fraud rules
POST	/api/v1/admin/fraud/rules/:businessId	Update fraud rules

Admin Analytics

Method	Path	Description
GET	/api/v1/admin/analytics/system-overview	Platform-wide metrics
GET	/api/v1/admin/analytics/businesses	Top businesses by volume
GET	/api/v1/admin/analytics/revenue	Revenue by payment method
GET	/api/v1/admin/analytics/fraud-summary	Fraud summary

Other Admin

Method	Path	Description
POST	/api/v1/admin/rates/update	Override exchange rate
POST	/api/v1/admin/rates/config	Set rate config
GET	/api/v1/admin/rates/config	Get rate configs
POST	/api/v1/admin/withdrawal/:ref/settle	Settle a pending withdrawal
POST	/api/v1/admin/sweep/all	Sweep all addresses
POST	/api/v1/admin/sweep/:addressId	Sweep specific address
GET	/api/v1/admin/otc/orders	All OTC orders
POST	/api/v1/admin/otc/orders/:id/complete	Complete OTC order
GET	/api/v1/admin/otc/accounts	List OTC platform accounts
POST	/api/v1/admin/otc/accounts	Create OTC platform account
PATCH	/api/v1/admin/otc/accounts/:id	Update OTC platform account
DELETE	/api/v1/admin/otc/accounts/:id	Delete OTC platform account
POST	/api/v1/admin/notifications/send	Send admin push notification
POST	/api/v1/admin/emails/promotional	Send promotional email

---

Error Format

{
  "error": "Descriptive error message"
}

HTTP Status Codes

Code	Meaning
200	OK
201	Created
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid auth
403	Forbidden — insufficient permissions or KYC not approved
404	Not Found
500	Internal Server Error