Understand payout settings

The /payouts/settings endpoint returns your complete payout configuration—the schedule controlling when automatic payouts run, the destinations mapping currencies to financial accounts, and the aging rules determining transaction eligibility. Understanding this response helps you verify configuration changes, troubleshoot payout timing issues, and ensure funds flow to the correct accounts.

Fetching your settings

Call /payouts/settings to retrieve your current payout configuration. No request body needed—Commerce uses your authentication context to identify your account and return the appropriate settings.

Get payout settings

POST

/payouts/settings

curl https://api.zebo.dev/payouts/settings \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The response contains a settings object with three main sections: schedule configuration, destination mappings, and a unique identifier.

Response structure overview

Complete response example

{
  "settings": {
    "fx_enabled": false,
    "schedule": {
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "spec": {
        "t_plus": "168h",
        "label": "168_hours",
        "abide": "strictly"
      },
      "description": "Automatic weekly payout. Default."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
      "usd": "fa_A1bCdEf2G3HiJk4LmN5oPqRs6tUv7WxY8z9"
    }
  }
}

The top-level settings object groups all payout configuration into a single response. Let's examine each section in detail.

Settings root fields

The settings object contains three root-level fields that define your payout configuration and capabilities.

`fx_enabled`

Type: Boolean
Possible values: true, false

Indicates whether foreign exchange (FX) conversion is enabled for your payouts. When true, Commerce can automatically convert payout funds from one currency to another when routing to destination accounts. When false (default), payouts only transfer funds to accounts matching the transaction currency.

How FX works:

With fx_enabled: false (default behavior), if you have GHS balance transactions, they can only be paid out to a GHS financial account. If you've configured a USD account as the destination for GHS, the payout will fail due to currency mismatch.

With fx_enabled: true, Commerce can convert GHS balance to USD and send the converted amount to your USD account. This is useful for businesses that want to consolidate multiple currencies into a single operating account, or for merchants who prefer to hold funds in a stable foreign currency.

Important considerations:

FX conversion incurs additional fees beyond standard payout fees
Exchange rates are determined at the time of payout execution
FX-enabled payouts may take longer to process due to conversion steps
Not all currency pairs are supported—contact support for available conversions

Controlling FX: Use the /payouts/enable_fx and /payouts/disable_fx endpoints to toggle this setting. Changes take effect immediately for future payouts. See the Payouts FX conversion guide for a complete explanation of how FX works, or jump directly to the enable FX guide and disable FX guide for implementation instructions.

`schedule`

Type: Object

The schedule object defines when automatic payouts run, what mode you're operating in (automatic vs. manual), and the aging rules governing transaction eligibility. This is the core of your payout configuration—it determines cashflow timing and risk management posture.

When you first create a Commerce account, the schedule defaults to weekly automatic payouts. Calling /payouts/disable switches to manual mode; calling /payouts/enable switches back to automatic weekly mode. See the schedule section below for complete field breakdown.

`destinations`

Type: Object (map of currency codes to financial account IDs)
Example: { "ghs": "fa_...", "usd": "fa_..." }

The destinations map specifies which financial account receives payouts for each currency. Keys are lowercase ISO 4217 currency codes (ghs, usd, eur, etc.); values are financial account IDs from your Commerce account.

When an automatic payout runs, Commerce checks this map to determine where to send funds for each currency. If a currency has eligible balance transactions but no configured destination, no payout is created for that currency—the funds remain in your balance until you configure a destination.

Destinations are independent of schedule mode. Whether you're in automatic or manual mode, ghs payouts always route to the financial account mapped to ghs. You configure destinations with /payouts/set_destinations.

Empty destinations: If you've never configured destinations, this field will be an empty object ({}). Automatic payouts won't run until you map at least one currency to a financial account. Manual payouts require either a configured destination or an explicitly specified destination_id in the /payouts/schedule request.

See the destinations section below for detailed explanation of currency routing.

Schedule object fields

The schedule object is the heart of your payout configuration. It defines timing, mode, and eligibility rules.

`schedule.name`

Type: String
Possible values: "weekly", "manual"

Human-readable schedule name. Maps directly to the schedule ID but removes prefixes for brevity:

weekly: Automatic weekly payouts (default)
manual: Manual payout mode

Use this field when displaying schedule information to users—it's more readable than the ID. "You're currently on the weekly payout schedule" is clearer than "You're on payout_sched_weekly."

`schedule.type`

Type: String
Possible values: "automatic", "manual"

The payout control mode. This determines who creates payouts:

automatic: Commerce creates payouts on schedule (every Sunday for weekly). No API calls needed—payouts happen automatically when the schedule runs and eligible transactions exist.
manual: You create payouts by calling /payouts/schedule. Commerce never creates payouts automatically—funds accumulate until you explicitly trigger a payout.

This field is the primary indicator of your mode. Check schedule.type to determine if automatic payouts are enabled (automatic) or disabled (manual). The enable/disable guide terminology ("enabling automatic payouts" vs. "disabling automatic payouts") maps directly to this field's value.

`schedule.interval`

Type: String
Possible values: "weekly", "manual"

The cadence at which automatic payouts run. For weekly schedules, this is "weekly" indicating payouts happen once per week. For manual schedules, this is "manual" indicating no automatic cadence—payouts only happen when you trigger them.

This field reinforces the information in schedule.name and is primarily used internally by Commerce's payout scheduling system. For application logic, schedule.type (automatic vs. manual) is the more useful field.

`schedule.schedule_on`

Type: String
Possible values: "sunday", "manual"

When the schedule runs, if it's automatic. For weekly automatic payouts, this is "sunday" indicating payouts are created every Sunday at midnight UTC. For manual mode, this is "manual" indicating no fixed day—you control the timing.

This field tells you exactly when to expect payouts:

sunday: Automatic payouts create Sunday 00:00 UTC. Funds typically arrive Monday morning (mobile money) or Tuesday-Wednesday (bank transfers).
manual: No scheduled run day. Payouts happen when you call /payouts/schedule, executing immediately or at the execute_after time you specify.

Use this field to explain payout timing to your finance team. "Payouts run every Sunday at midnight UTC" gives them a concrete schedule to plan around.

`schedule.description`

Type: String
Example: "Automatic weekly payout. Default."

Human-readable description of the schedule. Provides context about what this schedule does and whether it's the default configuration. Useful for displaying in dashboards, settings screens, or user interfaces where you want to explain the current payout behavior in plain language.

The description varies based on the schedule:

Weekly automatic: "Automatic weekly payout. Default."
Manual: "Manual payout" or similar brief explanation

`schedule.spec`

Type: Object

The spec object defines the aging rules and eligibility requirements for balance transactions. This is where risk management happens—the spec determines how long funds must remain in your balance before they can be disbursed.

See the spec section below for complete field breakdown.

Schedule spec object fields

The spec (specification) object defines the aging window and enforcement rules for payout eligibility. These fields control how long balance transactions must "age" before they can be included in a payout.

`schedule.spec.t_plus`

Type: String (duration format)
Possible values: "168h" (currently)

The aging requirement as a duration, expressed in hours using Go's duration format. A value of "168h" (168 hours = 7 days) means balance transactions must be at least 7 days old before they're eligible for payout.

How aging works:

Customer pays on Monday, January 1st
Payment settles into your balance within hours (still January 1st)
That balance transaction ages for 7 days
On Tuesday, January 8th (7 days later), the transaction becomes eligible
The next payout that runs (Sunday, January 14th for weekly automatic) includes this transaction

The 7-day aging protects you from late-arriving disputes, refunds, and chargebacks. Most fraudulent transactions surface within a few days. The 7-day window catches these before funds leave your balance, keeping your business solvent even when problems occur.

Why it's a string: Using Go's duration format provides flexibility for various time periods (24h, 48h, 168h) and maintains compatibility with Go's time parsing libraries.

`schedule.spec.label`

Type: String
Example: "168_hours"

Machine-readable label for the aging specification. The format uses underscores and typically matches the duration (e.g., "168_hours" for 168h, "24_hours" for 24h).

Use this field as a stable identifier for the aging spec when logging or tracking configuration changes.

`schedule.spec.abide`

Type: String
Possible values: "strictly" (currently)

The enforcement mode for aging rules. Determines whether the aging requirement is rigid or flexible:

strictly: Aging requirement is rigidly enforced. A transaction that's 6 days and 23 hours old is ineligible—it must be fully 7 days old. No exceptions, no early releases.

Currently, all Commerce schedules use strict enforcement. This protects platform stability and ensures consistent risk management across all merchants. Future specs might introduce flexible modes (e.g., "leniently" for approved high-trust merchants) but this is not available today.

Why strict matters: With strict enforcement, you can confidently predict which transactions will be in the next payout. If today is Wednesday and a transaction settled last Wednesday, it's eligible for the next payout. If it settled last Thursday, it's not eligible until the following payout. No ambiguity.

Understanding destinations

The destinations object maps currencies to financial accounts, defining where payout funds land for each currency you accept.

Structure

{
  "destinations": {
    "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "usd": "fa_A1bCdEf2G3HiJk4LmN5oPqRs6tUv7WxY8z9"
  }
}

Keys: Lowercase ISO 4217 currency codes
Values: Financial account IDs from your Commerce account

Each key-value pair creates a routing rule: "When creating a payout for GHS, send funds to the financial account with ID fa_Q90w...."

How destinations work

Automatic mode: Every Sunday at midnight UTC, Commerce checks your available balance for each currency. For each currency with eligible balance transactions (aged 7+ days), Commerce looks up the destination in this map. If a destination exists, Commerce creates a payout. If no destination exists, no payout is created—funds remain in your balance.

Manual mode: When you call /payouts/schedule, you can either:

Use the configured destination: Omit destination_id from the request. Commerce looks up the currency's destination from this map.
Override the destination: Include destination_id in the request. Commerce sends funds to that specific financial account, ignoring the configured destination.

Currency matching enforcement

When fx_enabled is false (default), Commerce enforces strict currency matching: you cannot route a GHS payout to a USD financial account. When you configure destinations via /payouts/set_destinations, Commerce verifies that each financial account's currency matches the currency key you're mapping it to. Mismatches are rejected with an error.

When fx_enabled is true, Commerce allows currency mismatches and automatically converts funds. For example, you can route GHS payouts to a USD account—Commerce converts the GHS balance to USD at the prevailing exchange rate and sends the converted amount. See the Payouts FX conversion guide for complete details on how rates are determined and what fees apply.

Missing destinations

If destinations is empty ({}), you've never configured payout destinations. Automatic payouts won't run—there's nowhere to send the funds. Manual payouts will fail unless you explicitly specify a destination_id in each /payouts/schedule request.

To configure destinations: Call /payouts/set_destinations with currency-to-financial-account mappings. See the Manage payout destinations guide for complete instructions.

Updating destinations

Destinations can be updated anytime by calling /payouts/set_destinations. Changes take effect immediately:

Automatic mode: The next automatic payout uses the new destination
Manual mode: The next manual payout you trigger uses the new destination (unless you override with destination_id)

Existing scheduled or executing payouts are not affected—they continue using the destination that was configured when they were created. Only future payouts use the updated destination.

Common scenarios

Verifying automatic payouts are enabled

After calling /payouts/enable, verify the change succeeded:

{
  "settings": {
    "schedule": {
      "name": "weekly",
      "type": "automatic",        // ✓ Automatic mode enabled
      "schedule_on": "sunday"     // ✓ Runs every Sunday
    }
  }
}

If schedule.type is "automatic" and schedule.schedule_on is "sunday", automatic payouts are enabled and will run every Sunday at midnight UTC.

Verifying manual mode is active

After calling /payouts/disable, verify the change succeeded:

{
  "settings": {
    "schedule": {
      "name": "manual",
      "type": "manual",           // ✓ Manual mode active
      "schedule_on": "manual"     // ✓ No automatic schedule
    }
  }
}

If schedule.type is "manual", automatic payouts are disabled. You must trigger payouts via /payouts/schedule.

Checking configured currencies

See which currencies have destinations configured:

{
  "settings": {
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}

This account has configured a destination for GHS but not for other currencies. If you accept USD or EUR, those payouts won't run until you configure destinations for them.

Understanding aging eligibility

Check when balance transactions become eligible for payout:

{
  "settings": {
    "schedule": {
      "spec": {
        "t_plus": "7",            // Must age 7 days
        "label": "7 days",
        "abide": "strict"         // Strictly enforced
      }
    }
  }
}

A transaction that settled on Monday won't be eligible until the following Monday (7 full days later). With weekly automatic payouts running Sundays, it will be included in the payout that runs the Sunday after it becomes eligible.

Predicting next payout

If today is Thursday, April 10th, and you're on automatic weekly:

{
  "settings": {
    "schedule": {
      "type": "automatic",
      "schedule_on": "sunday"
    }
  }
}

Your next automatic payout runs Sunday, April 14th at midnight UTC. Balance transactions that settled on or before Thursday, April 3rd (7+ days ago) will be included. Transactions that settled Friday, April 4th or later won't be eligible yet.

Checking FX status

Verify whether foreign exchange conversion is enabled:

{
  "settings": {
    "fx_enabled": false          // ✓ FX disabled (default)
  }
}

If fx_enabled is false, payouts only go to currency-matched accounts. If true, Commerce can convert funds between currencies during payout. Use /payouts/enable_fx or /payouts/disable_fx to toggle this setting.