Authentication

Complete guide to authentication and account management on Rach Payments.

Overview

Rach Payments uses two authentication methods:

JWT Tokens - For account management, KYC submission, dashboard access
API Keys - For payment operations, transfers, wallet management

Account Creation & Onboarding

Complete Onboarding Flow

mermaid

graph TD
    A[Register] --> B[Verify Email]
    B --> C[Submit KYC/KYB]
    C --> D[KYC Review]
    D -->|Approved| E[Account Activated]
    D -->|Rejected| C
    E --> F[Get API Keys]
    F --> G[Start Using Products]
    
    style E fill:#90EE90
    style D fill:#FFE4B5

Step 1: Register Your Business

Create your business account on Rach Payments.

Endpoint

POST /api/v1/auth/register

Request Parameters

Field	Type	Required	Description
Business Info
email	string	✅	Business email
password	string	✅	Strong password (8+ chars)
business_name	string	✅	Legal business name
country	string	✅	2-letter country code
business_type	string	❌	llc, corporation, sole_proprietor
Personal Info
first_name	string	✅	Owner's first name
last_name	string	✅	Owner's last name
phone	string	✅	Phone with country code
date_of_birth	string	❌	YYYY-MM-DD format
Address
address_line1	string	❌	Street address
city	string	❌	City
state	string	❌	State/Province
postal_code	string	❌	ZIP/Postal code

Example Request

cURLJavaScriptPython

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john@acmecorp.com",
    "password": "SecurePass123!",
    "business_name": "Acme Corporation",
    "country": "US",
    "business_type": "llc",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "date_of_birth": "1990-01-15",
    "address_line1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001"
  }'

javascript

const response = await fetch('https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'john@acmecorp.com',
    password: 'SecurePass123!',
    business_name: 'Acme Corporation',
    country: 'US',
    business_type: 'llc',
    first_name: 'John',
    last_name: 'Doe',
    phone: '+1234567890'
  })
});

const data = await response.json();
console.log('Business UUID:', data.business_uuid);
console.log('Verification Token:', data.verification_token);

python

import requests

response = requests.post(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/register',
    json={
        'email': 'john@acmecorp.com',
        'password': 'SecurePass123!',
        'business_name': 'Acme Corporation',
        'country': 'US',
        'business_type': 'llc',
        'first_name': 'John',
        'last_name': 'Doe',
        'phone': '+1234567890'
    }
)

data = response.json()
print(f"Business UUID: {data['business_uuid']}")

Response

json

{
  "user_uuid": "usr_abc123def456",
  "business_uuid": "biz_xyz789ghi012",
  "business_slug": "acme-corporation-1234",
  "verification_token": "a1b2c3d4e5f6...", // DEV MODE ONLY
  "message": "Registration successful. Please check your email to verify your account."
}

Development Mode

In development mode, the verification_token is returned in the response for testing. In production, it's only sent via email.

Step 2: Verify Your Email

Verify your email address to activate your account.

Endpoint

POST /api/v1/auth/verify-email

Methods

Method 1: Email Link (Production)

Check your inbox for verification email
Click the link in the email
You'll be redirected to the dashboard

Method 2: API (Development/Testing)

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/verify-email' \
  -H 'Content-Type: application/json' \
  -d '{"token": "YOUR_VERIFICATION_TOKEN"}'

Response

json

{
  "message": "Email verified successfully",
  "next_step": "kyc_submission"
}

Authenticate and get JWT tokens.

Endpoint

POST /api/v1/auth/login

Request

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john@acmecorp.com",
    "password": "SecurePass123!"
  }'

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "john@acmecorp.com",
    "role": "owner",
    "is_verified": true
  },
  "business": {
    "id": 1,
    "name": "Acme Corporation",
    "kyc_status": "not_submitted",
    "onboarding_status": "email_verified",
    "is_active": false
  }
}

Save these tokens:

access_token: Valid for 24 hours
refresh_token: Valid for 7 days

Step 4: Submit KYC/KYB Documents

Complete Know Your Business (KYB) verification to activate your account.

What You Need

For Businesses:

✅ Certificate of Incorporation
✅ Director's ID (Passport/Driver's License)
✅ Proof of Address (Utility bill, bank statement)
✅ Bank statement (optional)
✅ Tax ID documentation

For Sole Proprietors:

✅ Government-issued ID
✅ Proof of Address
✅ Selfie with ID (optional)

Upload Documents

First, upload documents to your storage (Google Cloud Storage, AWS S3, etc.) and get public URLs.

Endpoint

POST /api/v1/kyc/submit

Request

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/kyc/submit' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_type": "business",
    "business_registration": "https://storage.example.com/cert-inc.pdf",
    "director_id": "https://storage.example.com/director-id.pdf",
    "proof_of_address": "https://storage.example.com/proof-address.pdf",
    "bank_statement": "https://storage.example.com/bank-stmt.pdf",
    "tax_id": "12-3456789"
  }'

Response

json

{
  "submission_id": 123,
  "status": "pending",
  "message": "KYC submitted successfully. Our team will review it shortly."
}

Review Time: Usually 24-48 hours

Step 5: Check KYC Status

Monitor your KYC submission status.

Endpoint

GET /api/v1/kyc/status

Request

bash

curl 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/kyc/status' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

json

{
  "submission_id": 123,
  "status": "approved", // or "pending", "rejected"
  "submitted_at": "2025-12-22T10:00:00Z",
  "reviewed_at": "2025-12-23T14:30:00Z",
  "rejection_reason": null
}

Statuses:

pending: Under review
approved: ✅ Account activated!
rejected: ❌ Needs resubmission

Step 6: Get Your API Keys

Once KYC is approved, retrieve your API keys.

Endpoint

GET /api/v1/auth/api-key

Request

bash

curl 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/api-key' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

json

{
  "api_key": "rach_live_a1b2c3d4e5f6g7h8i9j0...",
  "test_api_key": "rach_test_k1l2m3n4o5p6q7r8s9t0...",
  "business_uuid": "biz_xyz789ghi012",
  "business_name": "Acme Corporation",
  "is_active": true,
  "kyc_status": "approved",
  "message": "Use this API key in X-API-Key header for payment endpoints"
}

You now have:

✅ Production key (live_sk_...) — mainnet transactions, real funds
✅ Test key (test_sk_...) — testnet addresses, no real funds

Using API Keys

In Requests

bash

# Production
curl 'https://api.rachfinance.com/api/v1/checkout/create' \
  -H 'X-API-Key: live_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{...}'

# Test / Sandbox
curl 'https://api.rachfinance.com/api/v1/checkout/create' \
  -H 'X-API-Key: test_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{...}'

How Environment Isolation Works

The key prefix is the environment — there is no separate mode toggle to set:

Key prefix	Environment	Blockchain	Real funds
`test_sk_`	Sandbox	Testnets	No
`live_sk_`	Production	Mainnets	Yes

When you send a request, the server reads the prefix from your key and locks that mode onto every resource created during that request — including checkout sessions and wallet operations. The mode cannot drift mid-flow even if you later change your dashboard sandbox toggle. This means:

A checkout session created with live_sk_ always uses mainnet addresses, regardless of any setting you change afterward.
A checkout session created with test_sk_ always uses testnet addresses.

Same code, different key

Use the same code in test and production. The only thing that changes is the key you inject from your environment:

javascript

const RACH_API_KEY = process.env.NODE_ENV === 'production'
  ? process.env.RACH_LIVE_KEY   // live_sk_...
  : process.env.RACH_TEST_KEY;  // test_sk_...

Dashboard sandbox toggle

The "sandbox mode" toggle in the dashboard only affects legacy keys (those without a test_sk_ / live_sk_ prefix, issued before June 2026). If you use prefixed keys — which all new accounts get — the toggle has no effect.

Refresh Tokens

Access tokens expire after 24 hours. Use refresh tokens to get new ones.

Endpoint

POST /api/v1/auth/refresh

Request

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/refresh' \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

Response

json

{
  "access_token": "NEW_ACCESS_TOKEN"
}

Password Reset

Forgot your password? Reset it via email.

Step 1: Request Reset

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/forgot-password' \
  -H 'Content-Type: application/json' \
  -d '{"email": "john@acmecorp.com"}'

Step 2: Use Reset Token

bash

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/auth/reset-password' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "RESET_TOKEN_FROM_EMAIL",
    "new_password": "NewSecurePass123!"
  }'

Security Best Practices

API Key Security

Never expose API keys

❌ Don't commit to Git
❌ Don't log API keys
❌ Don't share publicly
✅ Store in environment variables
✅ Use backend only
✅ Rotate regularly

JWT Token Security

Store in httpOnly cookies (web apps)
Clear on logout
refreshexpired tokens
Implement CSRF protection

Account Security

Use strong, unique passwords
Enable 2FA (coming soon)
Monitor account activity
Whitelist IP addresses (enterprise)

Next Steps

✅ Account Created & Verified ✅ KYC Approved ✅ API Keys Obtained

Now you can:

View all API endpoints →

Authentication ​

Overview ​

Account Creation & Onboarding ​

Complete Onboarding Flow ​

Step 1: Register Your Business ​

Endpoint ​

Request Parameters ​

Example Request ​

Response ​

Step 2: Verify Your Email ​

Endpoint ​

Methods ​

Response ​

Step 3: Login ​

Endpoint ​

Request ​

Response ​

Step 4: Submit KYC/KYB Documents ​

What You Need ​

Upload Documents ​

Endpoint ​

Request ​

Response ​

Step 5: Check KYC Status ​

Endpoint ​

Request ​

Response ​

Step 6: Get Your API Keys ​

Endpoint ​

Request ​

Response ​

Using API Keys ​

In Requests ​

How Environment Isolation Works ​

Refresh Tokens ​

Endpoint ​

Request ​

Response ​

Password Reset ​

Step 1: Request Reset ​

Step 2: Use Reset Token ​

Security Best Practices ​

API Key Security ​

JWT Token Security ​

Account Security ​

Next Steps ​

Authentication

Overview

Account Creation & Onboarding

Complete Onboarding Flow

Step 1: Register Your Business

Endpoint

Request Parameters

Example Request

Response

Step 2: Verify Your Email

Endpoint

Methods

Response

Step 3: Login

Endpoint

Request

Response

Step 4: Submit KYC/KYB Documents

What You Need

Upload Documents

Endpoint

Request

Response

Step 5: Check KYC Status

Endpoint

Request

Response

Step 6: Get Your API Keys

Endpoint

Request

Response

Using API Keys

In Requests

How Environment Isolation Works

Refresh Tokens

Endpoint

Request

Response

Password Reset

Step 1: Request Reset

Step 2: Use Reset Token

Security Best Practices

API Key Security

JWT Token Security

Account Security

Next Steps