Connected accounts are child organizations created under your platform organization. Use them to manage multiple merchants or sub-accounts from a single API key. Only top-level organizations can create connected accounts — connected accounts cannot create their own children.
To operate on behalf of a connected account, include the X-Connected-Account-ID header with any API request. Syncgram Pay will scope that request to the connected account instead of your platform organization.
X-Connected-Account-ID: org_01j8connected123
List connected accounts
GET /api/v1/organizations/connected-accounts
Response
An array of organization objects. Each object has the same fields as the Get Organization response.
[
{
"id": "org_01j8connected123",
"name": "Merchant A",
"owner_user_id": "usr_01j8xyz789",
"parent_organization_id": "org_01j8abc123def456",
"onboarding_status": "COMPLETED",
"payments_status": "ENABLED",
"country": "NG",
"current_env": "live",
"fee_handling": "customer_pays",
"enabled_capabilities": ["payouts"],
"is_active": true,
"created_at": "2024-01-10T08:00:00Z",
"updated_at": "2024-01-10T08:00:00Z"
}
]
Example
curl https://api.syncgrampay.com/api/v1/organizations/connected-accounts \
-H "Authorization: Bearer sk_live_01j..."
Create a connected account
POST /api/v1/organizations/connected-accounts
contact_email must be unique across all organizations — if you do not provide one, it defaults to your platform organization’s contact email. Each connected account starts with its own independent onboarding and payments status.
Request
Display name for the connected account.
Contact email for the connected account. Must be unique. Defaults to the platform organization’s email if omitted.
ISO 3166-1 alpha-2 country code. Defaults to the platform organization’s country if omitted.
Response
Returns the newly created organization object. See the Get Organization response fields for a full description.
{
"id": "org_01j9newconnected456",
"name": "Merchant B",
"owner_user_id": "usr_01j8xyz789",
"parent_organization_id": "org_01j8abc123def456",
"onboarding_status": "PENDING",
"payments_status": "DISABLED",
"country": "NG",
"current_env": "test",
"fee_handling": "customer_pays",
"enabled_capabilities": [],
"is_active": true,
"created_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z"
}
Error codes
| Status | Description |
|---|
400 Bad Request | contact_email is required and could not be resolved |
403 Forbidden | Connected accounts cannot create child organizations |
409 Conflict | An organization with this contact_email already exists |
Example
curl -X POST https://api.syncgrampay.com/api/v1/organizations/connected-accounts \
-H "Authorization: Bearer sk_live_01j..." \
-H "Content-Type: application/json" \
-d '{
"name": "Merchant B",
"contact_email": "merchantb@example.com",
"country": "NG"
}'
Acting on behalf of a connected account
Once you have a connected account’s id, pass it in the X-Connected-Account-ID header to make API calls scoped to that account. This works for payouts, conversions, and any other endpoint that accepts API key authentication.
curl -X POST https://api.syncgrampay.com/api/v1/payouts/withdrawals \
-H "Authorization: Bearer sk_live_01j..." \
-H "X-Connected-Account-ID: org_01j9newconnected456" \
-H "Content-Type: application/json" \
-d '{
"from_currency": "USD",
"to_currency": "NGN",
"amount": 200,
"payment_method": "BANK_TRANSFER",
"reference": "merchant-b-payout-001",
"email": "recipient@example.com",
"account_number": "0987654321",
"bank_code": "058"
}'
Funds and balances are isolated per organization. A withdrawal made on behalf of a connected account debits that account’s balance, not your platform organization’s balance.