Individual Activation API

Activate individual customer accounts after verification and consent acceptance.

Base URL: https://sandbox.finhub.cloud/api/v2.1/customer/individual

Available Operations

Activate Customer

POST /{customerId}/activation

Check Activation

GET /{customerId}/owner/{ownerId}/activation/check

Upload for Activation

POST /{customerId}/owner/{ownerId}/activation/upload

Approve Activation

POST /{customerId}/owner/{ownerId}/activation/approve

Activate Customer

Activates an individual customer account after verification and consent acceptance.

Prerequisites

All prerequisites must be met before activation can succeed. Use the Check Activation endpoint first to verify readiness.

Pre-Activation Validation Checklist

Customer Registration Complete

Customer must be registered with status CS_REGISTRATION_COMPLETED

Verification Approved

Identity verification must be in status APPROVED

For standard customers: TENANT_VERIFIED level required
For high-risk customers: POWER_TENANT_VERIFIED level required

All Required Consents Accepted

Three mandatory consents must be accepted:

✅ Terms and Conditions (TERMS_AND_CONDITIONS)
✅ Privacy Policy (PRIVACY_POLICY)
✅ Data Processing (DATA_PROCESSING)

Activation Code Received

Customer must have received the activation code via email

Valid Session

Customer must be authenticated with a valid JWT token

For complete details on authentication, compliance headers, and SDK implementation examples, refer to the Standard HTTP Headers reference documentation.

Check Activation Readiness

Before attempting activation, always check if the customer is ready: Endpoint: GET /{customerId}/owner/{ownerId}/activation/check Response:

{
  "code": 200,
  "message": "Activation readiness check",
  "data": {
    "canActivate": true,
    "verificationOk": true,
    "consentOk": true,
    "missingConsents": [],
    "verificationStatus": "APPROVED",
    "verificationLevel": "TENANT_VERIFIED"
  }
}

If canActivate: false, the response will indicate what’s missing.

Request

customerId

string

required

Customer identifier

Authorization

string

required

Bearer token for authentication

X-Tenant-ID

string

required

Tenant identifierExample: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd

Content-Type

string

required

Must be application/json

string

Response format (optional — defaults to application/json)Example: application/json, text/plain, */*

X-Forwarded-From

string

required

Source identifier for request origin trackingExample: e2e-test

User-Agent

string

required

Client application identifier for security analysisExample: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platformExample: web

deviceId

string

required

Unique device identifier for session tracking. Also accepted as X-Device-Id or device-idExample: 356938035643809

sec-ch-ua-platform

string

Browser client hint for OS platform (accepted alias for platform)Example: "Windows"

code

string

required

Activation code sent to customer emailExample: ACTIVATION_CODE_1768298633438

userId

string

required

Customer user ID or emailExample: marcus.jensen@example.com

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/ff72a196-426a-4ab3-a2d3-e4c583a9bc88/activation" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "code": "ACTIVATION_CODE_1768298633438",
    "userId": "marcus.jensen@example.com"
  }'

{
  "code": 200,
  "message": "Success",
  "data": {
    "wallet": {
      "walletId": "26e4eacc-4d4b-47b1-836d-6819bdca1636",
      "iban": "LT613500048962615846",
      "currency": "EUR",
      "balance": "0",
      "reservedBalance": "0",
      "asset": {
        "assetType": "CURRENCY",
        "currency": "EUR",
        "current": "0.00 EUR",
        "available": "0.00 EUR",
        "blocked": "0.00 EUR"
      }
    },
    "iban": "LT613500048962615846",
    "activationStatus": "ACTIVATED"
  }
}

What Happens During Activation

When you call the activation endpoint, the system performs these actions automatically:

Validate Activation Code

Verifies the activation code is valid and not expired

Check All Prerequisites

Validates:

✅ Verification status is APPROVED
✅ All required consents are accepted
✅ Customer status allows activation

Create Active Wallet

Creates a fully functional wallet with:

Unique IBAN assigned
BIC/SWIFT code assigned
Balance initialized to 0.00 EUR
Status set to ACTIVE

Update Customer Status

Changes customer status from PENDING_ACTIVATION to ACTIVE

Apply Category Features

Activates all features from the customer’s categorization:

Transaction limits
Allowed operations
Payment networks (SEPA, SWIFT)

Record Activation Metadata

Logs activation event with:

Activation timestamp
Request source (from X-Forwarded-From header)
User agent (from User-Agent header)
Activated by user ID

Common Activation Errors

Error: Invalid or Expired Activation Code

Problem:

{
  "code": 400,
  "message": "Invalid or expired activation code",
  "data": {
    "error": "INVALID_ACTIVATION_CODE"
  }
}

Causes:

Activation code already used
Code expired (typically 24-48 hours validity)
Code doesn’t match the customer
Typo in the activation code

Solution:

Request a new activation code
Check for typos in the code
Ensure code hasn’t been used before

Error: Missing Required Consents

Problem:

{
  "code": 422,
  "message": "Customer cannot be activated - missing prerequisites",
  "data": {
    "error": "ACTIVATION_PREREQUISITES_NOT_MET",
    "details": {
      "consentOk": false,
      "verificationOk": true,
      "missingConsents": ["TERMS_AND_CONDITIONS", "PRIVACY_POLICY"]
    }
  }
}

Causes:

Not all three mandatory consents have been accepted
Consent acceptance failed or was revoked

Solution:

Check activation readiness using GET /activation/check
Accept missing consents:
- POST /consents/terms - Terms and Conditions
- POST /consents/privacy - Privacy Policy
- POST /consents/data-processing - Data Processing
Retry activation

Prevention: Always check activation readiness before attempting activation.

Error: Verification Not Approved

Problem:

{
  "code": 422,
  "message": "Customer verification not approved",
  "data": {
    "error": "VERIFICATION_NOT_APPROVED",
    "verificationStatus": "PENDING_REVIEW",
    "details": "Customer must complete KYC verification before activation"
  }
}

Causes:

Verification documents not submitted
Verification still under review
Verification rejected

Solution:

Check verification status: GET /customer/individual/{customerId}/verification
If PENDING_DOCUMENTS: Submit required documents
If PENDING_REVIEW: Wait for review completion (1-3 business days)
If REJECTED: Review rejection reason and resubmit

Error: Customer Already Activated

Problem:

{
  "code": 409,
  "message": "Customer is already activated",
  "data": {
    "error": "CUSTOMER_ALREADY_ACTIVE",
    "activationStatus": "ACTIVATED",
    "activatedAt": "2026-01-12T10:30:00Z"
  }
}

Solution:

Customer is already active, no action needed
Proceed to wallet operations

What Happens After Activation

Once activation is successful:

1. Customer Can Access Financial Operations

View Wallet Balance

GET /fintrans/{accountId}/balance

Check Allowed Operations

GET /fintrans/{accountId}/allowed-operations

Add Beneficiaries

POST /fintrans/{accountId}/beneficiaries

Create Payment Consents

POST /fintrans/{walletId}/payment-consents

2. Next Steps

Fund the Wallet

Top-up the wallet to start making transactionsSee Wallet Operations for funding methods

Add beneficiary accounts for transfersSee Beneficiary Management

Set Up Payment Consents

Define transaction limits and approval workflowsSee Payment Consents

Execute First Transaction

Prepare and execute a transferSee Transfers

3. Wallet Information

After activation, you receive:

Field	Description	Example
`walletId`	Unique wallet identifier	`26e4eacc-4d4b-47b1-836d-6819bdca1636`
`iban`	International Bank Account Number	`LT613500048962615846`
`bic`	Bank Identifier Code	`REVOLT21`
`currency`	Wallet currency	`EUR`
`balance`	Current balance (in cents)	`0`
`status`	Wallet status	`ACTIVE`

API Schema Reference

For the complete OpenAPI schema specification of this endpoint, including all request and response structures, see the API Schema Mapping document.

Check Activation Status

Checks the activation status and readiness for a customer under a specific owner tenant.

Request

customerId

string

required

Customer identifier

ownerTenantId

string

required

Owner tenant identifier

Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/owner/tenant_67890/activation/check" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

{
  "code": 200,
  "message": "Activation check completed",
  "data": {
    "activationAllowed": false,
    "consentOk": false,
    "verificationOk": true,
    "powerTenantApprovalOk": true,
    "powerTenantApprovalRequired": false,
    "riskLevel": "LOW",
    "isHighRisk": false,
    "customerId": "ff72a196-426a-4ab3-a2d3-e4c583a9bc88",
    "powerTenant": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "ownerTenant": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f"
  }
}

Status Flags

Flag	Description	Required
`activationAllowed`	Overall activation status	Must be `true`
`consentOk`	All required consents accepted	Must be `true`
`verificationOk`	KYC verification approved	Must be `true`
`powerTenantApprovalOk`	Tenant approval granted	If required

If activationAllowed is false, check individual flags to determine what’s missing.Common issues:

consentOk: false → Accept required consents (terms, privacy, data-processing)
verificationOk: false → Complete and approve verification workflows

Upload Activation Documents

Uploads additional documents required for activation under a specific owner tenant.

Request

customerId

string

required

Customer identifier

ownerTenantId

string

required

Owner tenant identifier

documentType

string

required

Document type being uploaded

file

required

Document file (multipart/form-data)

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/owner/tenant_67890/activation/upload" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -F "documentType=PROOF_OF_ADDRESS" \
  -F "file=@/path/to/document.pdf"

{
  "success": true,
  "data": {
    "documentId": "doc_12345",
    "customerId": "cust_12345",
    "documentType": "PROOF_OF_ADDRESS",
    "status": "UPLOADED",
    "uploadedAt": "2024-01-15T10:30:00Z"
  }
}

Approve Activation

Approves customer activation under a specific owner tenant (requires admin privileges).

Request

customerId

string

required

Customer identifier

ownerTenantId

string

required

Owner tenant identifier

approvalNotes

string

Notes for the approval

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/cust_12345/owner/tenant_67890/activation/approve" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "approvalNotes": "All documents verified, customer approved"
  }'

{
  "success": true,
  "data": {
    "customerId": "cust_12345",
    "ownerTenantId": "tenant_67890",
    "status": "ACTIVE",
    "activatedAt": "2024-01-15T14:00:00Z",
    "accountId": "acc_67890",
    "walletId": "wal_11111",
    "approvedBy": "admin_user"
  }
}

Activation Flow

Check Readiness

Call /activation/check to verify all requirements are met

Upload Missing Documents

Use /activation/upload to submit any missing documents

Approve Activation

Admin calls /activation/approve to activate the customer

Account Created

Customer receives account and wallet IDs

Activation Types

Type	Description
`STANDARD`	Normal activation process
`EXPEDITED`	Fast-track activation (if eligible)

Response Codes

Code	Description
`200`	Operation successful
`201`	Document uploaded successfully
`400`	Prerequisites not met
`401`	Not Authorized
`403`	Insufficient permissions
`404`	Customer not found
`422`	Customer not verified
`500`	Internal server error

Standard Headers

Complete HTTP headers reference for compliance

Individual Registration

Individual Verification

Complete KYC verification process

Consent Management

Manage customer consents (required before activation)

Wallet Operations

Manage wallet balance and operations

Beneficiary Management

Add and manage beneficiaries for transfers

Changelog

Version	Date	Changes
v2.1	2026-01-13	Added compliance headers, comprehensive error scenarios, business logic documentation
v2.0	2025-12-01	Initial activation API release

Headers

User-Agent

string

required

Browser user agent

Example:

"Mozilla/5.0"

X-Forwarded-For

string

required

Client/application Ip address

Example:

"192.168.0.1"

X-Forwarded-From

string

required

Client/application identifier for request source tracking

Example:

"playground"

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platform

Example:

"web"

deviceId

string

required

Device identifier

Example:

"e2e-test-device"

Authorization

string

required

Bearer token from admin or customer session creation

Example:

"Bearer <token>"

Path Parameters

customerId

string

required

Individual customer identifier (UUID)

Example:

"ff72a196-426a-4ab3-a2d3-e4c583a9bc88"

Body

application/json

code

string

required

Activation code sent to the customer

Example:

"ACTIVATION_CODE_1773494532320"

userId

string

required

User identifier or email of the customer to activate

Example:

"marcus.jensen.1773494532320.cmcdd1@mediumrisk-example.com"

Response

200 - application/json

Customer activated successfully

Standard API response wrapper used by all endpoints

code

integer

HTTP status code

Example:

200

data

object

Response from individual customer activation

Show child attributes

message

string

Human-readable status message

Example:

"Success"

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Individual Activation API

​Available Operations

Activate Customer

Check Activation

Upload for Activation

Approve Activation

​Activate Customer

​Prerequisites

​Pre-Activation Validation Checklist

​Check Activation Readiness

​Request

​Code Examples

​What Happens During Activation

​Common Activation Errors

​Error: Invalid or Expired Activation Code

​Error: Missing Required Consents

​Error: Verification Not Approved

​Error: Customer Already Activated

​What Happens After Activation

​1. Customer Can Access Financial Operations

View Wallet Balance

Check Allowed Operations

Add Beneficiaries

Create Payment Consents

​2. Next Steps

​3. Wallet Information

​API Schema Reference

​Check Activation Status

​Request

​Code Examples

​Status Flags

​Upload Activation Documents

​Request

​Code Examples

​Approve Activation

​Request

​Code Examples

​Activation Flow

​Activation Types

​Response Codes

​Related Endpoints

Standard Headers

Individual Registration

Individual Verification

Consent Management

Wallet Operations

Beneficiary Management

​Changelog

Headers

Path Parameters

Body

Response

Individual Activation API

Available Operations

Activate Customer

Prerequisites

Pre-Activation Validation Checklist

Check Activation Readiness

Request

Code Examples

What Happens During Activation

Common Activation Errors

Error: Invalid or Expired Activation Code

Error: Missing Required Consents

Error: Verification Not Approved

Error: Customer Already Activated

What Happens After Activation

1. Customer Can Access Financial Operations

2. Next Steps

3. Wallet Information

API Schema Reference

Check Activation Status

Request

Code Examples

Status Flags

Upload Activation Documents

Request

Code Examples

Approve Activation

Request

Code Examples

Activation Flow

Activation Types

Response Codes

Related Endpoints

Changelog