E2E Testing Guide

End-to-end tests for the Unigox Partner API. These tests run against local Docker services and validate the full request flow through the API gateway to backend services.

Prerequisites

Running Services

All services must be running via Docker on the unigox-network:

Service	Container Name	Port	Image
PostgreSQL	shared-postgres	5432	postgres:17.3
MongoDB	shared-mongodb	27017	mongo:8.0.4
Redis	shared-redis	6379	redis:8.4-alpine
Account	account	8081	account_management / account-dev
Verification	verification-service	8083	verification-service
Trades	trades-service	8085	trades-service
Escrow	escrow	8082	escrow
Currencies	currencies	8087	currencies-dev
Offers	offers	8084	offers-dev
API Gateway	api	8080	api-gateway

Start infrastructure first:

cd unigox-dev-infra && docker compose up -d

Then start services:

docker start account trades-service verification-service api

API Gateway Environment

The API gateway must point to local services. When creating the container, pass:

ACCOUNT_SERVICE_URL=http://account:8081
VERIFICATION_SERVICE_URL=http://verification-service:8083
TRADES_SERVICE_URL=http://trades-service:8085
CURRENCIES_SERVICE_URL=http://currencies:8087
OFFERS_SERVICE_URL=http://offers:8084

Health Checks

curl http://localhost:8080/health   # API gateway
curl http://localhost:8081/health   # Account
curl http://localhost:8083/health   # Verification
curl http://localhost:8085/          # Trades (uses / not /health)

Test Partner Setup

Create a test partner in PostgreSQL if one doesn't exist:

# Generate SHA256 hash of your test API key
echo -n "test-e2e-local-key" | shasum -a 256 | awk '{print $1}'

# Insert partner
PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -c "
INSERT INTO partners (partner_short_name, api_key_hash, webhook_secret, settings)
VALUES ('e2e-test', '<sha256_hash>', 'test-webhook-secret', '{\"platform_fee_pct\": 1.5}')
ON CONFLICT (partner_short_name) DO NOTHING;"

Create route configs for the test partner:

PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -c "
INSERT INTO partner_route_config (partner_code, country_code, payment_network_id, fiat_currency, config, active)
VALUES
  ('e2e-test', 'LT', 3, 'EUR', '{\"payment_method_type_slug\": \"bank-transfer\"}', true),
  ('e2e-test', 'NG', 30, 'NGN', '{\"payment_method_type_slug\": \"bank-transfer\"}', true)
ON CONFLICT DO NOTHING;"

Trades Service: System Settings

The trades service requires NEW_USER_MULTIPLIER_FOR_PERCENTS in system_settings. If the column name is outdated:

PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -c "
UPDATE system_settings SET identifier = 'NEW_USER_MULTIPLIER_FOR_PERCENTS'
WHERE identifier = 'NEW_USER_MULTIPLIER';"

Known Local Environment Issues

MongoDB Database Name Mismatch

Production and staging use database verification (singular). The local verification-service .env uses verifications (plural). This means the account service (which reads from verification) won't find KYC data written by the verification service locally.

Workaround for local testing: Temporarily change the verification-service .env:

# Change from:
MONGODB_URI=mongodb://mongodb:password123@shared-mongodb:27017/verifications?authSource=admin
# To:
MONGODB_URI=mongodb://mongodb:password123@shared-mongodb:27017/verification?authSource=admin

Then restart the verification-service container. Revert after testing.

Verification Service .env Inline Comments

Docker --env-file does NOT strip inline comments. If you recreate the verification-service container, inline comments like:

AIPRISE_API_KEY=abc123 # Sandbox key

become part of the value (abc123 # Sandbox key). Move comments to their own line:

# Sandbox key
AIPRISE_API_KEY=abc123

Node.js dotenv handles inline comments correctly, so this only matters when recreating Docker containers with --env-file.

Verification Service Volume Mount + node_modules

The verification-service image bakes in node_modules for Linux. If you volume-mount the source directory (-v ./verification-service:/usr/src/app), the host's node_modules (built for macOS) overrides the container's.

Fix: Use a separate volume for node_modules:

docker run -d \
  -v /path/to/verification-service:/usr/src/app \
  -v verif_node_modules:/usr/src/app/node_modules \
  verification-service:latest

Then install missing native modules inside the container:

docker exec verification-service sh -c "cd /usr/src/app && npm install sharp"

Go Services: shared-modules Private Dependency

Account and trades services depend on github.com/Unigox/shared-modules. Docker containers may not have git or GitHub credentials. If air fails to rebuild:

# Add local replace directive (DO NOT commit)
echo 'replace github.com/Unigox/shared-modules/go/auth => /shared-modules/go/auth' >> go.mod
docker restart <container>
# Revert after testing
git checkout go.mod

The account container has /shared-modules volume-mounted. For trades, copy it manually:

docker cp /path/to/shared-modules trades-service:/shared-modules

Switch API Not Available Locally

The Switch liquidity provider API (switch-v2.up.railway.app) requires a production API key. Local trades service can't create EUR offramp quotes or initiate trades through Switch. Test Switch-related features on staging instead, or verify via code review.

E2E Test Cases

All tests use:

API=http://localhost:8080
KEY="test-e2e-local-key"

Test 1: User Creation + KYC with Address Fields

Tests: account service user creation, verification service direct_data KYC, auto-verify flow.

# 1. Create user
curl -s -X POST "$API/api/v1/partner/users" \
  -H "Content-Type: application/json" -H "X-API-Key: $KEY" \
  -d '{"user_ref": "e2e-test-1", "email": "[email protected]"}'
# Save user_uuid from response

# 2. Submit KYC with address fields
curl -s -X POST "$API/api/v1/partner/users/$USER_UUID/kyc-submissions" \
  -H "Content-Type: application/json" -H "X-API-Key: $KEY" \
  -d '{
    "method": "direct_data",
    "data": {
      "pii": {
        "first_name": "Alice",
        "last_name": "Tester",
        "country_code": "LT",
        "dob": "1990-05-15",
        "address": "Gedimino pr 1",
        "city": "Vilnius",
        "postal_code": "01103"
      }
    }
  }'

# 3. Verify auto-verified
curl -s "$API/api/v1/partner/users/$USER_UUID/verification-status" \
  -H "X-API-Key: $KEY"
# Expected: status = "VERIFIED"

Expected results:

• User created with user_uuid and kyc_status: NOT_INITIATED

• KYC submission returns success: true

• Verification status becomes VERIFIED (direct_data auto-verify)

• AiPrise async AML screening fires in background (may fail locally with sandbox key, not blocking)

Payload structure note: The KYC endpoint expects { method, data: { pii: { ... } } } — the PII fields are nested under data.pii, not directly under data.

Test 2: PATCH /kyc to Update Optional PII

Tests: updating address/city/postal_code on an existing verified user without re-triggering verification.

# 1. Create user and submit minimal KYC (required fields only)
# ... (same as Test 1, but omit address/city/postal_code)

# 2. PATCH to add address
curl -s -X PATCH "$API/api/v1/partner/users/$USER_UUID/kyc" \
  -H "Content-Type: application/json" -H "X-API-Key: $KEY" \
  -d '{
    "address": "Hauptstrasse 1",
    "city": "Berlin",
    "postal_code": "10115",
    "phone_number": "[phone]"
  }'

# 3. Verify still VERIFIED
curl -s "$API/api/v1/partner/users/$USER_UUID/verification-status" \
  -H "X-API-Key: $KEY"

Expected results:

• PATCH returns success: true with updated_fields: ["address", "city", "postal_code", "phone_number"]

• Verification status stays VERIFIED

• MongoDB KycData has address, city, postalCode, phoneNumber at top level

Verify MongoDB:

docker exec shared-mongodb mongosh "mongodb://mongodb:password123@localhost:27017/verification?authSource=admin" \
  --quiet --eval "d=db.kycdatas.findOne({userId:'<INTERNAL_USER_ID>'}); printjson({city:d.city, address:d.address, postalCode:d.postalCode});"

Note: MongoDB userId is the internal integer ID (as string), not the public UUID. Look up with:

PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -tAc \
  "SELECT user_id FROM user_partner_relation WHERE public_uuid='$USER_UUID'"

Test 3: Payment Details Auto-Populate from KYC

Tests: account service auto-populates holder_city/holder_street/holder_postal_code from KYC data when creating EUR payment details.

Prerequisite: User must have address/city/postal_code in KYC (from Test 2). Also requires the MongoDB database name workaround (see Known Issues above).

curl -s -X POST "$API/api/v1/partner/users/$USER_UUID/payment-details" \
  -H "Content-Type: application/json" -H "X-API-Key: $KEY" \
  -d '{
    "currency": "EUR",
    "rail": "iban-sepa",
    "details": {"iban": "LT123456789012345678", "full_name": "Alice Tester"},
    "country_code": "LT"
  }'

Expected results:

• Payment details created with payment_details_id

• Database details JSONB contains holder_city, holder_street, holder_postal_code auto-populated from KYC

• Response details only shows iban and full_name (auto-populated fields are not in the response, only in DB)

Verify in PostgreSQL:

PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -tAc \
  "SELECT details::text FROM payment_details WHERE id=$PAYMENT_DETAILS_ID"
# Should contain: holder_city, holder_street, holder_postal_code

Common failures:

• "invalid rail" — partner_route_config missing for the test partner (see Setup section)

• "Invalid JSON payload" — missing required field rail in request body

• Auto-populate doesn't fire — MongoDB database name mismatch (see Known Issues)

• Full name validation error — full_name must be 2-50 chars, letters/spaces/hyphens/apostrophes only

Test 4: EUR Offramp Order with action_required

Tests: trades service returns action_required in order response when address is missing for EUR/AUD/GBP offramp.

Note: This test requires Switch API access or pre-created trade data. Locally, Switch returns 401. To test, insert trade data directly:

# Create a trade in trade_created status for the test partner with EUR
# This requires offers, trade_requests, and trades rows — complex setup.
# Recommended: test on staging where Switch API works, or verify via code review.

If a trade exists in trade_created status with partner_details_checked_at IS NULL, trade_type = 'SELL', and fiat_currency_code = 'EUR':

curl -s "$API/api/v1/partner/orders/$ORDER_ID" -H "X-API-Key: $KEY"

Expected response includes:

{
  "next_action": "update_kyc_address",
  "action_required": {
    "type": "update_kyc_address",
    "message": "The payout provider requires the recipient's physical address...",
    "endpoint": "PATCH /api/v1/partner/users/{user_uuid}/kyc",
    "fields": [
      {"field": "address", "label": "Street address of the recipient"},
      {"field": "city", "label": "City of the recipient"},
      {"field": "postal_code", "label": "Postal code of the recipient"}
    ]
  }
}

Test 5: Switch EUR Country Whitelist

Tests: Switch offers are excluded for unsupported EUR countries (e.g. Cyprus).

This is a code-level test — the SwitchSupportsEurCountry function in trades/internal/service/trade_request/providers/provider_switch.go filters offers during matching. No live API needed.

cd /path/to/trades && go test ./internal/service/trade_request/providers/ -run TestSwitchSupportsEurCountry -v

If no unit test exists, verify by reading the code:

• switchEurSupportedCountries list: 35 European countries

• CY (Cyprus) is NOT in the list

• LT (Lithuania) IS in the list

• Only filters EUR + SELL (offramp). BUY (onramp) is not filtered.

• When countryCode is empty, falls back to IBAN prefix (first 2 chars)

Test 6: Regression — Existing Flows

Basic smoke tests to verify existing functionality isn't broken.

# Get user
curl -s "$API/api/v1/partner/users/$USER_UUID" -H "X-API-Key: $KEY"
# Expected: user data with kyc status, payment_profiles

# Verify auth
curl -s "$API/api/v1/partner/verify-auth" -H "X-API-Key: $KEY"
# Expected: partner info

# Get payment details
curl -s "$API/api/v1/partner/users/$USER_UUID/payment-details" -H "X-API-Key: $KEY"
# Expected: list of payment profiles

# Delete payment details
curl -s -X DELETE "$API/api/v1/partner/users/$USER_UUID/payment-details/$PD_ID" -H "X-API-Key: $KEY"
# Expected: success (unless it's the last PD on an active offer)

Debugging Tips

Service Logs

docker logs account --tail 50 2>&1 | grep -i "error\|warn"
docker logs verification-service --tail 50 2>&1 | grep -i "error"
docker logs trades-service --tail 50 2>&1 | grep -i "error\|fatal"

MongoDB Queries

# List recent KYC records
docker exec shared-mongodb mongosh "mongodb://mongodb:password123@localhost:27017/verification?authSource=admin" \
  --quiet --eval "db.kycdatas.find().sort({_id:-1}).limit(5).forEach(d => printjson({userId:d.userId, fn:d.firstName, city:d.city}));"

PostgreSQL Queries

# Check user partner relation
PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -c "
SELECT upr.user_id, upr.public_uuid, upr.partner_id
FROM user_partner_relation upr
WHERE upr.public_uuid = '$USER_UUID';"

# Check payment details contents
PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -c "
SELECT id, details::text FROM payment_details WHERE id = $PD_ID;"

# Check partner route configs
PGPASSWORD=password123 psql -h localhost -U postgres -d unigox_db -c "
SELECT prc.partner_code, pn.slug, prc.fiat_currency
FROM partner_route_config prc
JOIN payment_networks pn ON pn.id = prc.payment_network_id
WHERE prc.partner_code = 'e2e-test' AND prc.active = true;"

API Gateway Path Transformations

The API gateway transforms paths before proxying to backend services:

Gateway Path	Backend Path	Service
/partner/users/{id}/kyc-submissions	/partner/kyc-submissions/{id}	verification
/partner/users/{id}/verification-status	/partner/verification-status/{id}	verification
/partner/users/{id}/kyc/documents	/partner/{id}/kyc/documents	verification
/partner/users/{id}/kyc	/partner/users/{id}/kyc	verification (no transform)
/partner/users/*	/api/v1/partner/users/*	account (prefixed)
/partner/orders/*	/api/v1/partner/orders/*	trades (prefixed)