Tutorial: Onboard a new client

What you will build

A four-step automated onboarding flow that takes a merchant from signup to payment-ready.

Prerequisites

A valid API key for your parent (reseller) account — see Obtain API credentials
The parent_id of your reseller account

Step 1: Create the client

Create a new merchant account under your reseller.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/clients \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-RESELLER-API-KEY" \
  -d '{
    "dba": "Acme Jewelry",
    "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
    "type": "merchant",
    "admin_contact_details": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone": "+15551234567",
      "time_zone": "America/New_York"
    }
  }'

Client types

Set type to merchant for businesses that process payments, or reseller for ISOs and agents that manage merchants. See Clients and resellers.

Save the id from the response — you need it for all subsequent steps.

Step 2: Create the first user

Add an admin user to the new client account.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/users \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-RESELLER-API-KEY" \
  -d '{
    "client_id": "CLIENT-01KEWXXXXXXXXXXXXXXXXXXXXXXX",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "password": "SecureP@ssw0rd!2026",
    "time_zone": "America/New_York"
  }'

Secure the password

Transmit the initial password to the client through a secure channel (encrypted email, secure portal). Instruct them to change it on first login.

Step 3: Configure a processor integration

Add a TSYS integration so the client can process card transactions. Use the client's API key for this call.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/integrations \
  -H "Content-Type: application/json" \
  -H "APIKEY: CLIENT-API-KEY" \
  -d '{
    "name": "tsys",
    "is_active": true,
    "configuration": {
      "mid": "999000000011",
      "tid": "00000001",
      "industry_type": "e_commerce",
      "settlement_time": "23:59:00"
    }
  }'

Verification checklist

After completing all four steps, verify the onboarding succeeded:

Check	How
Client exists	`GET /v1/clients/{client_id}` returns `200`
User can authenticate	`POST /v1/auth/keys` with Basic Auth succeeds
API key works	Any authenticated request returns `200`
Integration is active	`GET /v1/integrations` shows the integration with `is_active: true`
Test payment works	`POST /v1/transactions` with a test card returns `approved`

Complete automation example

def onboard_merchant(dba: str, parent_id: str, contact: dict, tsys_config: dict) -> dict:
    client = requests.post(f"{BASE}/v1/clients", headers=HEADERS, json={
        "dba": dba, "parent_id": parent_id, "type": "merchant",
        "admin_contact_details": contact,
    }).json()

    user = requests.post(f"{BASE}/v1/users", headers=HEADERS, json={
        "client_id": client["id"],
        "first_name": contact["first_name"],
        "last_name": contact["last_name"],
        "email": contact["email"],
        "password": contact["initial_password"],
        "time_zone": contact.get("time_zone", "America/New_York"),
    }).json()

    creds = base64.b64encode(
        f"{contact['email']}:{contact['initial_password']}".encode()
    ).decode()
    api_key = requests.post(f"{BASE}/v1/auth/keys", headers={
        "Content-Type": "application/json",
        "Authorization": f"Basic {creds}",
    }).json()["key"]

    merchant_headers = {"Content-Type": "application/json", "APIKEY": api_key}
    integration = requests.post(
        f"{BASE}/v1/integrations", headers=merchant_headers, json={
            "name": "tsys", "is_active": True, "configuration": tsys_config,
        }
    ).json()

    return {
        "client_id": client["id"],
        "user_id": user["id"],
        "integration_id": integration["id"],
    }