Skip to main content
Connected accounts are sub-organizations that sit under your parent organization. They allow you to build multi-merchant platforms — such as marketplaces or SaaS products — where each merchant has their own isolated account for payments, balances, and reporting, while you manage them centrally through your platform API key. Common use cases:
  • A marketplace that processes payments on behalf of independent sellers
  • A SaaS platform that provisions payment-enabled accounts for each of its business customers
  • A platform that needs to separate funds across multiple merchants or brands
Connected accounts are only available via API key authentication. You must use your platform’s API key (not a user session) for all connected account operations.

​
List connected accounts

Retrieve all sub-organizations under your platform. 
GET /api/v1/organizations/connected-accounts

curl https://api.syncgrampay.com/api/v1/organizations/connected-accounts \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY"
Response 
[
  {
    "id": "org_seller_01",
    "name": "Seller A",
    "parent_organization_id": "org_platform_01",
    "onboarding_status": "completed",
    "payments_status": "active",
    "country": "NG",
    "current_env": "live",
    "fee_handling": "org_pays_fee",
    "enabled_capabilities": ["payments"],
    "is_active": true,
    "created_at": "2024-03-10T12:00:00Z",
    "updated_at": "2024-06-01T09:00:00Z"
  }
]

​
Create a connected account

Provision a new sub-organization under your platform. 
POST /api/v1/organizations/connected-accounts

​
Request fields

​
name
string
required
Display name for the connected account.
​
contact_email
string
required
Contact email address for the connected account. Must be unique across all organizations.
​
country
string
Two-letter ISO country code. Defaults to your platform organization’s country if omitted.
curl -X POST https://api.syncgrampay.com/api/v1/organizations/connected-accounts \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Seller B",
    "contact_email": "seller-b@example.com",
    "country": "GH"
  }'
Response 
{
  "id": "org_seller_02",
  "name": "Seller B",
  "parent_organization_id": "org_platform_01",
  "onboarding_status": "pending",
  "payments_status": "inactive",
  "country": "GH",
  "current_env": "test",
  "fee_handling": "org_pays_fee",
  "enabled_capabilities": [],
  "is_active": true,
  "created_at": "2024-06-15T14:22:00Z",
  "updated_at": "2024-06-15T14:22:00Z"
}

​
Get a connected account

Retrieve the details of a specific connected account. 
GET /api/v1/organizations/{organization_id}

curl https://api.syncgrampay.com/api/v1/organizations/org_seller_02 \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
  -H "X-Connected-Account-ID: org_seller_02"

​
Act on behalf of a connected account

To make API calls in the context of a connected account — such as creating checkouts, initiating payouts, or listing transactions — pass the X-Connected-Account-ID header with any request. 
X-Connected-Account-ID: org_seller_02
Syncgram Pay will scope the operation to the connected account instead of your platform organization. Example: create a checkout on behalf of a connected account 
curl -X POST https://api.syncgrampay.com/api/v1/payments/checkouts \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
  -H "X-Connected-Account-ID: org_seller_02" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing": {
      "base_currency": "NGN",
      "amount": "5000.00"
    },
    "customer_email": "buyer@example.com",
    "customer_first_name": "Ada",
    "customer_last_name": "Okafor",
    "metadata": {
      "order_id": "1042"
    }
  }'
Your platform API key authorizes the request. The X-Connected-Account-ID header determines which organization’s context the operation runs in.

​
Response fields

​
id
string
Unique identifier for the connected account.
​
name
string
Display name of the connected account.
​
parent_organization_id
string
The ID of your platform organization that owns this connected account.
​
onboarding_status
string
Onboarding state of the connected account. One of pending, in_progress, or completed.
​
payments_status
string
Whether the connected account can process payments. One of inactive, pending, or active.
​
country
string
Two-letter ISO country code for the connected account.
​
current_env
string
Active environment. Either test or live.
​
fee_handling
string
Fee handling mode. Either org_pays_fee or customer_pays_fee.
​
enabled_capabilities
array
Capabilities active on this connected account, such as payments or payouts.
​
is_active
boolean
Whether this connected account is currently active.

​
Limitations

Connected accounts operate with the following restrictions:
  • Connected accounts cannot create API keys. API keys are managed at the platform level only.
  • Connected accounts cannot configure webhooks. Webhooks are registered on your platform organization and receive events for all connected accounts.
  • A connected account cannot create its own connected accounts — nesting is not supported.