Wallet Core Admin

Overview

POS terminal profiles define settlement behavior, fee structures, and transaction limits for groups of terminals. Profiles enable consistent configuration across multiple terminals and support external sweep operations.

What is a Terminal Profile?

A terminal profile is a configuration template that defines how POS terminals process and settle transactions. Instead of configuring each terminal individually, profiles allow you to apply consistent settings across multiple terminals.

Aspect	Description
Settlement Frequency	How often transactions are batched and settled (instant, hourly, 6-hourly, end of day)
Settlement Route	Where settled funds are sent (terminal account or profile wallet)
Fee Defaults	Default fee structure applied to transactions
Transaction Limits	Configurable limits for transaction amounts
Timezone	Settlement window calculations based on timezone

Settlement Routes

Profiles support two settlement routing modes that determine where funds flow after settlement.

Route	Code	Behavior
Terminal Account	terminal_settlement_account	Each terminal settles directly to its configured bank account
Profile Wallet	profile_wallet	All terminals settle to a shared profile wallet, enabling batched external sweeps

Settlement Frequency Options

Control how often transaction batches are processed and settled.

Frequency	Code	Description
Instant	instant	Settle immediately after each transaction completes
Hourly	hourly	Batch and settle every hour
Every 6 Hours	six_hourly	Batch and settle every 6 hours
End of Day	end_of_day	Batch all day's transactions and settle at end of day based on timezone

External Sweeps

When using profile_wallet settlement route, accumulated funds can be swept to an external bank account. Sweeps aggregate multiple settlement jobs into a single payout operation.

Create Profile

Create a new POS terminal profile for a tenant.

Endpoint

POST/api/v1/admin/pos-profiles

Creates a new terminal profile with specified settlement configuration. The profile can then be assigned to terminals.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Response- The created profile object

json

{
  "id": "prof_550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "processor_id": "proc_a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d",
  "name": "Lagos Merchants - Daily Settlement",
  "description": "End-of-day settlement for Lagos-based merchants",
  "settlement_frequency": "end_of_day",
  "settlement_route": "profile_wallet",
  "settlement_timezone": "Africa/Lagos",
  "settlement_account": {
    "bank_code": "058",
    "account_code": "0123456789",
    "account_name": "Lagos Merchants Ltd",
    "bank_name": "GTBank"
  },
  "linked_terminal_count": 0,
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-01-15T09:00:00Z"
}

Request Payload

json

{
  "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "processor_id": "proc_a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d",
  "name": "Lagos Merchants - Daily Settlement",
  "description": "End-of-day settlement for Lagos merchants",
  "settlement_frequency": "end_of_day",
  "settlement_route": "profile_wallet",
  "settlement_timezone": "Africa/Lagos",
  "settlement_account": {
    "bank_code": "058",
    "account_code": "0123456789",
    "account_name": "Lagos Merchants Ltd",
    "bank_name": "GTBank"
  },
  "fee_defaults": {
    "flat_fee": 100,
    "percentage_fee": 0.015,
    "cap_fee": 2000
  },
  "limit_metadata": {
    "min_transaction": 100,
    "max_transaction": 5000000,
    "daily_limit": 50000000
  }
}

Example Request

bash

curl -X POST "https://api.example.com/api/v1/admin/pos-profiles" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d @payload.json

List Profiles

Retrieve all terminal profiles, optionally filtered by tenant.

Endpoint

GET/api/v1/admin/pos-profiles

List all terminal profiles across the platform. Platform admins can view all profiles; filter by tenant_id to scope results.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	No	Filter profiles by tenant UUID. Omit to list all tenants.

Response- Array of profile objects

json

{
  "profiles": [
    {
      "id": "prof_550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "processor_id": "proc_a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d",
      "tenant": {
        "id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Acme Payments"
      },
      "processor": {
        "id": "proc_a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d",
        "name": "PayStack Processor"
      },
      "name": "Lagos Merchants - Daily Settlement",
      "description": "End-of-day settlement for Lagos merchants",
      "settlement_frequency": "end_of_day",
      "settlement_route": "profile_wallet",
      "settlement_timezone": "Africa/Lagos",
      "linked_terminal_count": 45,
      "last_used_at": "2024-01-20T18:30:00Z",
      "created_at": "2024-01-15T09:00:00Z",
      "updated_at": "2024-01-18T14:22:00Z"
    }
  ]
}

Example Request

bash

# List all profiles
curl -X GET "https://api.example.com/api/v1/admin/pos-profiles" \
  -H "Authorization: Bearer {admin_token}"

# Filter by tenant
curl -X GET "https://api.example.com/api/v1/admin/pos-profiles?tenant_id=tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer {admin_token}"

Response Fields

Field	Type	Description
id	string	Unique profile identifier
tenant_id	string	Parent tenant UUID
processor_id	string	Associated processor UUID
tenant	object	Nested tenant info (id, name)
processor	object	Nested processor info (id, name)
name	string	Profile display name
description	string \| null	Optional description
settlement_frequency	string	instant \| hourly \| six_hourly \| end_of_day
settlement_route	string	terminal_settlement_account \| profile_wallet
settlement_timezone	string	IANA timezone string
linked_terminal_count	integer	Number of terminals using this profile
last_used_at	string \| null	ISO timestamp of last terminal activity
created_at	string	ISO timestamp
updated_at	string	ISO timestamp

Get Profile Details

Retrieve detailed information about a specific terminal profile.

Endpoint

GET/api/v1/admin/pos-profiles/{profileID}

Get comprehensive details for a single profile including settlement account, fee defaults, and limit metadata.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Path Parameters

Parameter	Type	Required	Description
`profileID`	string	Yes	UUID of the profile to retrieve

Response- Full profile object with all configuration details

json

{
  "id": "prof_550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "processor_id": "proc_a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d",
  "tenant": {
    "id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Acme Payments"
  },
  "processor": {
    "id": "proc_a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d",
    "name": "PayStack Processor"
  },
  "name": "Lagos Merchants - Daily Settlement",
  "description": "End-of-day settlement for Lagos-based merchants",
  "settlement_frequency": "end_of_day",
  "settlement_route": "profile_wallet",
  "settlement_timezone": "Africa/Lagos",
  "settlement_account": {
    "bank_code": "058",
    "account_code": "0123456789",
    "account_name": "Lagos Merchants Ltd",
    "bank_name": "GTBank",
    "provider": "paystack"
  },
  "profile_settlement_account_id": "acc_123e4567-e89b-12d3-a456-426614174000",
  "fee_defaults": {
    "flat_fee": 100,
    "percentage_fee": 0.015,
    "cap_fee": 2000
  },
  "limit_metadata": {
    "min_transaction": 100,
    "max_transaction": 5000000,
    "daily_limit": 50000000
  },
  "linked_terminal_count": 45,
  "last_used_at": "2024-01-20T18:30:00Z",
  "created_by": "admin_user_123",
  "updated_by": "admin_user_456",
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-01-18T14:22:00Z"
}

Example Request

bash

curl -X GET "https://api.example.com/api/v1/admin/pos-profiles/prof_550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer {admin_token}"

Fee Defaults Schema

The fee_defaults object can contain various fee configuration options.

Field	Type	Description
flat_fee	number	Fixed fee amount in minor units (kobo/cents)
percentage_fee	number	Percentage fee as decimal (0.015 = 1.5%)
cap_fee	number	Maximum fee cap in minor units
min_fee	number	Minimum fee floor in minor units

Limit Metadata Schema

The limit_metadata object defines transaction constraints.

Field	Type	Description
min_transaction	number	Minimum transaction amount allowed
max_transaction	number	Maximum single transaction amount
daily_limit	number	Maximum daily transaction volume
monthly_limit	number	Maximum monthly transaction volume

Error Responses

Status	Code	Description
403	ACCESS_DENIED	Admin does not have permission to view this profile
404	NOT_FOUND	Profile with specified ID does not exist

Update Profile

Update an existing terminal profile's configuration.

Endpoint

PATCH/api/v1/admin/pos-profiles/{profileID}

Partially update a profile's settings. Only provided fields are updated; omitted fields remain unchanged. Changes apply to all terminals using this profile.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`profileID`	string	Yes	UUID of the profile to update

Response- The updated profile object

json

{
  "id": "prof_550e8400-e29b-41d4-a716-446655440000",
  "name": "Lagos Merchants - Hourly Settlement",
  "settlement_frequency": "hourly",
  "updated_at": "2024-01-21T10:15:00Z"
}

Request Payload

json

{
  "name": "Lagos Merchants - Hourly Settlement",
  "settlement_frequency": "hourly",
  "fee_defaults": {
    "flat_fee": 50,
    "percentage_fee": 0.01,
    "cap_fee": 1500
  }
}

Example Request

bash

curl -X PATCH "https://api.example.com/api/v1/admin/pos-profiles/prof_550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d @payload.json

Important Considerations

When updating profiles with linked terminals, consider the following impacts:

Change	Impact
Settlement Frequency	New frequency applies to future settlement windows. In-progress settlements complete under old settings.
Settlement Route	Changing route affects where future settlements are directed. Existing balances remain in place.
Fee Defaults	New fees apply to future transactions only. Historical transactions retain original fees.
Limits	New limits apply immediately to all linked terminals.

Delete Profile

Delete a terminal profile. Profiles with linked terminals cannot be deleted.

Endpoint

DELETE/api/v1/admin/pos-profiles/{profileID}

Permanently delete a terminal profile. This operation fails if any terminals are currently assigned to the profile.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Path Parameters

Parameter	Type	Required	Description
`profileID`	string	Yes	UUID of the profile to delete

Response- Success response with no body (204 No Content)

json

Example Request

bash

curl -X DELETE "https://api.example.com/api/v1/admin/pos-profiles/prof_550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer {admin_token}"

Error Responses

Status	Code	Description
400	PROFILE_HAS_TERMINALS	Cannot delete profile with linked terminals. Reassign or remove terminals first.
400	PROFILE_HAS_PENDING_SETTLEMENTS	Cannot delete profile with pending settlements. Wait for settlements to complete.
403	ACCESS_DENIED	Admin does not have permission to delete this profile
404	NOT_FOUND	Profile with specified ID does not exist

Deletion Prerequisites

Before deleting a profile, ensure:

Requirement	How to Check
No linked terminals	GET /pos-profiles/{id} and verify linked_terminal_count is 0
No pending settlements	GET /pos-profiles/{id}/sweeps?status=pending returns empty
No active sweep jobs	All external sweeps have completed or failed

Trigger External Sweep

Initiate an external sweep to transfer accumulated profile wallet funds to an external bank account.

Endpoint

POST/api/v1/admin/pos-profiles/{profileID}/sweep

Trigger an external sweep for a profile using profile_wallet settlement route. Aggregates all pending settlement jobs into a single payout to the configured external bank account.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`profileID`	string	Yes	UUID of the profile to sweep

Response- The created sweep object

json

{
  "id": "swp_123e4567-e89b-12d3-a456-426614174000",
  "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "profile_id": "prof_550e8400-e29b-41d4-a716-446655440000",
  "amount": "1500000.00",
  "currency": "NGN",
  "status": "pending",
  "job_count": 12,
  "settlement_amount_total": "1500000.00",
  "destination": {
    "bank_code": "058",
    "account_number": "0123456789",
    "account_name": "Lagos Merchants Ltd",
    "bank_name": "GTBank"
  },
  "created_at": "2024-01-21T12:00:00Z",
  "updated_at": "2024-01-21T12:00:00Z"
}

Request Payload

json

{
  "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Example Request

bash

curl -X POST "https://api.example.com/api/v1/admin/pos-profiles/prof_550e8400-e29b-41d4-a716-446655440000/sweep" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'

Sweep Workflow

Understanding how external sweeps are processed.

Step	Status	Description
1. Initiate	pending	Sweep is created, settlement jobs are aggregated
2. Submit	payout_submitted	Payout request sent to provider
3. Complete	settled	Funds successfully transferred to external account
4. Failed	failed	Payout failed - check error details and retry

Prerequisites

Sweep operations require specific conditions to be met.

Requirement	Description
Profile Route	Profile must use settlement_route: 'profile_wallet'
Settlement Account	Profile must have valid settlement_account configured
Pending Settlements	At least one settlement job must be pending sweep
Sufficient Balance	Profile wallet must have sufficient balance

Error Responses

Status	Code	Description
400	INVALID_SETTLEMENT_ROUTE	Profile does not use profile_wallet settlement route
400	NO_SETTLEMENT_ACCOUNT	Profile does not have external settlement account configured
400	NO_PENDING_SETTLEMENTS	No settlement jobs pending sweep
400	INSUFFICIENT_BALANCE	Profile wallet balance insufficient for sweep
409	SWEEP_IN_PROGRESS	Another sweep is already in progress for this profile

List Profile Sweeps

Retrieve external sweep history for a terminal profile.

Endpoint

GET/api/v1/admin/pos-profiles/{profileID}/sweeps

List all external sweeps for a profile, with optional status filtering and pagination.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Path Parameters

Parameter	Type	Required	Description
`profileID`	string	Yes	UUID of the profile

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	Yes	UUID of the tenant
`status`	string	No	Filter by sweep statusValues: pending, payout_submitted, settled, failed
`limit`	integer	No (default: 20)	Page size
`offset`	integer	No (default: 0)	Page offset

Response- Paginated list of sweep objects

json

{
  "data": [
    {
      "id": "swp_123e4567-e89b-12d3-a456-426614174000",
      "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "profile_id": "prof_550e8400-e29b-41d4-a716-446655440000",
      "amount": "1500000.00",
      "currency": "NGN",
      "status": "settled",
      "payout_id": "pay_xyz789",
      "job_count": 12,
      "settlement_amount_total": "1500000.00",
      "destination": {
        "bank_code": "058",
        "account_number": "0123456789",
        "account_name": "Lagos Merchants Ltd",
        "bank_name": "GTBank"
      },
      "metadata": {
        "provider_reference": "REF123456"
      },
      "created_at": "2024-01-21T12:00:00Z",
      "updated_at": "2024-01-21T12:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 45
  }
}

Example Request

bash

# List all sweeps
curl -X GET "https://api.example.com/api/v1/admin/pos-profiles/prof_550e8400-e29b-41d4-a716-446655440000/sweeps?tenant_id=tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer {admin_token}"

# Filter by status
curl -X GET "https://api.example.com/api/v1/admin/pos-profiles/prof_550e8400-e29b-41d4-a716-446655440000/sweeps?tenant_id=tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479&status=pending" \
  -H "Authorization: Bearer {admin_token}"

Sweep Status Reference

Status	Description	Next Steps
pending	Sweep created, awaiting payout submission	System will automatically submit payout
payout_submitted	Payout sent to provider, awaiting confirmation	Monitor for settlement or failure
settled	Funds successfully transferred	No action required - sweep complete
failed	Payout failed	Review error, fix issue, trigger new sweep

Response Fields

Field	Type	Description
id	string	Unique sweep identifier
tenant_id	string	Parent tenant UUID
profile_id	string	Parent profile UUID
amount	string	Total sweep amount (decimal string)
currency	string	Currency code (e.g., NGN)
status	string	Current sweep status
payout_id	string \| null	Provider payout reference (when submitted)
job_count	integer	Number of settlement jobs included
settlement_amount_total	string	Sum of all settlement amounts
destination	object	External bank account details
metadata	object	Additional sweep metadata
created_at	string	ISO timestamp
updated_at	string	ISO timestamp

Get Sweep Details

Retrieve detailed information about a specific external sweep including individual settlement jobs.

Endpoint

GET/api/v1/admin/pos-profiles/{profileID}/sweeps/{sweepID}

Get comprehensive details for a single sweep including the list of settlement jobs that were aggregated into this sweep.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Path Parameters

Parameter	Type	Required	Description
`profileID`	string	Yes	UUID of the parent profile
`sweepID`	string	Yes	UUID of the sweep to retrieve

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	Yes	UUID of the tenant

Response- Full sweep object with jobs array

json

{
  "id": "swp_123e4567-e89b-12d3-a456-426614174000",
  "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "profile_id": "prof_550e8400-e29b-41d4-a716-446655440000",
  "amount": "1500000.00",
  "currency": "NGN",
  "status": "settled",
  "payout_id": "pay_xyz789",
  "job_count": 3,
  "settlement_amount_total": "1500000.00",
  "destination": {
    "bank_code": "058",
    "account_number": "0123456789",
    "account_name": "Lagos Merchants Ltd",
    "bank_name": "GTBank"
  },
  "jobs": [
    {
      "id": "job_aaa111",
      "terminal_id": "2057TID001",
      "terminal_name": "Store Alpha POS",
      "window_start": "2024-01-20T00:00:00Z",
      "window_end": "2024-01-20T23:59:59Z",
      "state": "settled",
      "settlement_amount": "500000.00",
      "transaction_count": 45,
      "sweep_id": "swp_123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2024-01-21T00:00:00Z",
      "updated_at": "2024-01-21T12:05:00Z"
    },
    {
      "id": "job_bbb222",
      "terminal_id": "2057TID002",
      "terminal_name": "Store Beta POS",
      "window_start": "2024-01-20T00:00:00Z",
      "window_end": "2024-01-20T23:59:59Z",
      "state": "settled",
      "settlement_amount": "650000.00",
      "transaction_count": 62,
      "sweep_id": "swp_123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2024-01-21T00:00:00Z",
      "updated_at": "2024-01-21T12:05:00Z"
    },
    {
      "id": "job_ccc333",
      "terminal_id": "2057TID003",
      "terminal_name": "Store Gamma POS",
      "window_start": "2024-01-20T00:00:00Z",
      "window_end": "2024-01-20T23:59:59Z",
      "state": "settled",
      "settlement_amount": "350000.00",
      "transaction_count": 28,
      "sweep_id": "swp_123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2024-01-21T00:00:00Z",
      "updated_at": "2024-01-21T12:05:00Z"
    }
  ],
  "metadata": {
    "provider_reference": "REF123456",
    "provider": "paystack"
  },
  "created_at": "2024-01-21T12:00:00Z",
  "updated_at": "2024-01-21T12:05:00Z"
}

Example Request

bash

curl -X GET "https://api.example.com/api/v1/admin/pos-profiles/prof_550e8400-e29b-41d4-a716-446655440000/sweeps/swp_123e4567-e89b-12d3-a456-426614174000?tenant_id=tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer {admin_token}"

Settlement Job Fields

Each job in the jobs array represents a single terminal's settlement window that was swept.

Field	Type	Description
id	string	Unique settlement job identifier
terminal_id	string	Terminal ID (e.g., '2057TID001')
terminal_name	string \| null	Human-readable terminal name
window_start	string	Settlement window start (ISO timestamp)
window_end	string	Settlement window end (ISO timestamp)
state	string	Job state (pending, collecting, settled, failed)
settlement_amount	string	Amount from this terminal (decimal string)
transaction_count	integer	Number of transactions in this settlement
sweep_id	string	Parent sweep ID
created_at	string	ISO timestamp
updated_at	string	ISO timestamp

Use Cases

Common scenarios for viewing sweep details.

Scenario	What to Check
Reconciliation	Compare jobs array totals with destination bank statement
Dispute Resolution	Identify which terminal/settlement is in question
Audit Trail	Track when settlements were swept and to where
Failed Sweep Debug	Review job states to identify problematic settlements

Architecture & Best Practices

Understanding profile architecture and recommended patterns for managing terminal configurations.

Profile Hierarchy

How profiles fit into the overall terminal management structure.

Level	Entity	Relationship
Platform	Tenant	A tenant can have multiple profiles
Tenant	Profile	A profile belongs to one tenant and one processor
Profile	Terminal	A terminal is assigned to one profile
Profile	Sweep	A profile can have multiple sweeps over time

Settlement Route Comparison

Choosing the right settlement route for your use case.

Aspect	terminal_settlement_account	profile_wallet
Fund Flow	Each terminal settles independently	All terminals pool into profile wallet
External Payout	Direct to terminal's bank account	Batched sweep to profile's bank account
Reconciliation	Per-terminal bank statements	Single profile-level statement
Use Case	Independent merchants	Aggregated merchant operations
Complexity	Simpler - no sweep management	More control - batched payouts

Recommended Patterns

Best practices for profile management.

Pattern	Description
Single Profile per Merchant Type	Group terminals by settlement needs (e.g., 'Retail - Daily', 'Enterprise - Weekly')
Environment Separation	Use different profiles for test vs production terminals
Fee Standardization	Define fee_defaults at profile level, override at terminal only when needed
Timezone Awareness	Set settlement_timezone to merchant's local timezone for predictable EOD settlements
Monitor Linked Count	Track linked_terminal_count to identify unused profiles

Profile Lifecycle

Stage	Actions	Considerations
Create	POST /pos-profiles	Define settlement config before assigning terminals
Assign Terminals	PATCH /terminals/{id}	Update terminal's profile_id to link
Monitor	GET /pos-profiles/{id}	Track linked_terminal_count and last_used_at
Update	PATCH /pos-profiles/{id}	Changes apply to all linked terminals
Sweep (if profile_wallet)	POST /pos-profiles/{id}/sweep	Batch payout accumulated funds
Retire	Reassign terminals, DELETE profile	Cannot delete with linked terminals

POS Terminal Profiles

Overview

What is a Terminal Profile?

Settlement Routes

Settlement Frequency Options

External Sweeps

Create Profile

Endpoint

Request Payload

Example Request

List Profiles

Endpoint

Example Request

Response Fields

Get Profile Details

Endpoint

Example Request

Fee Defaults Schema

Limit Metadata Schema

Error Responses

Update Profile

Endpoint

Request Payload

Example Request

Important Considerations

Delete Profile

Endpoint

Example Request

Error Responses

Deletion Prerequisites

Trigger External Sweep

Endpoint

Request Payload

Example Request

Sweep Workflow

Prerequisites

Error Responses

List Profile Sweeps

Endpoint

Example Request

Sweep Status Reference

Response Fields

Get Sweep Details

Endpoint

Example Request

Settlement Job Fields

Use Cases

Architecture & Best Practices

Profile Hierarchy

Settlement Route Comparison

Recommended Patterns

Profile Lifecycle