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

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 API Key: For live transactions
✅ Test API Key: For sandbox testing

Using API Keys

In Requests

bash

curl 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/crypto' \
  -H 'X-API-Key: rach_live_a1b2c3d4e5f6g7h8i9j0...' \
  -H 'Content-Type: application/json' \
  -d '{...}'

Test vs Production

Test Mode:

Uses testnet blockchains
No real money
Unlimited test transactions
Use test_api_key

Production Mode:

Uses mainnet blockchains
Real transactions
Production limits apply
Use api_key

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 ​

Test vs Production ​

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

Test vs Production

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