Update a Payout Profile

Overview

Update a Payout Profile to configure how fees and payouts are handled for a merchant. You can switch between NET settlement (fees netted against payouts) and GROSS settlement (separate payout and fee transactions), or modify the schedules and payment rails.

Resource Access

User Permissions: Admin users only
Endpoint: PUT /payout_profiles/\{payout_profile_id}

Arguments

Parameter	Type	Required	Description
payout_profile_id	string	Yes	The unique ID of the Payout Profile to update
type	string	Yes	Settlement type: "NET" or "GROSS"
net	object	Conditional	Required if type is "NET". Contains NET settlement schedule
net.frequency	string	Yes	Settlement frequency: DAILY, WEEKLY, or MONTHLY
net.rail	string	Yes	Payment rail: NEXT_DAY_ACH, SAME_DAY_ACH, or PUSH_TO_CARD
net.payment_instrument_id	string	Yes	Payment Instrument ID for settlements
net.submission_delay_days	string	No	Number of days to delay submission (as string)
net.day_of_month	integer	Conditional	Required for MONTHLY frequency (1-31)
gross	object	Conditional	Required if type is "GROSS". Contains separate payout and fee schedules
gross.payouts	object	Yes	Payout schedule configuration
gross.fees	object	Yes	Fee collection schedule configuration

Example Request (Update to NET Settlement)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payout_profiles/PPpayoutProfile123' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "NET",
    "net": {
      "frequency": "MONTHLY",
      "day_of_month": 10,
      "submission_delay_days": "1",
      "payment_instrument_id": "PIwHjXGehKvgoCxMrKaFpx22",
      "rail": "SAME_DAY_ACH"
    }
  }'

Example Request (Update to GROSS Settlement)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payout_profiles/PPpayoutProfile456' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "GROSS",
    "gross": {
      "payouts": {
        "frequency": "DAILY",
        "rail": "NEXT_DAY_ACH",
        "payment_instrument_id": "PIpaymentInstrument111",
        "submission_delay_days": 0,
        "start_time": 18,
        "time_zone": "America/New_York",
        "funding_requirement": "DEFAULT"
      },
      "fees": {
        "frequency": "WEEKLY",
        "rail": "NEXT_DAY_ACH",
        "payment_instrument_id": "PIpaymentInstrument222",
        "submission_delay_days": 2,
        "start_time": 10,
        "time_zone": "America/New_York",
        "funding_requirement": "DEFAULT"
      }
    }
  }'

Example Response (NET Settlement)

{
  "id": "PPpayoutProfile123",
  "created_at": "2023-05-15T14:30:00Z",
  "updated_at": "2023-12-10T11:20:00Z",
  "linked_id": "MUmerchantExample456",
  "linked_type": "MERCHANT",
  "type": "NET",
  "tags": {},
  "net": {
    "frequency": "MONTHLY",
    "rail": "SAME_DAY_ACH",
    "payment_instrument_id": "PIwHjXGehKvgoCxMrKaFpx22",
    "submission_delay_days": 1,
    "start_time": null,
    "time_zone": "America/New_York",
    "day_of_month": 10,
    "funding_requirement": "DEFAULT"
  },
  "gross": null,
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payout_profiles/PPpayoutProfile123"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample456"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIwHjXGehKvgoCxMrKaFpx22"
    }
  }
}

Example Response (GROSS Settlement)

{
  "id": "PPpayoutProfile456",
  "created_at": "2023-06-10T09:00:00Z",
  "updated_at": "2023-12-10T11:25:00Z",
  "linked_id": "MUmerchantExample789",
  "linked_type": "MERCHANT",
  "type": "GROSS",
  "tags": {},
  "net": null,
  "gross": {
    "payouts": {
      "frequency": "DAILY",
      "rail": "NEXT_DAY_ACH",
      "payment_instrument_id": "PIpaymentInstrument111",
      "submission_delay_days": 0,
      "start_time": 18,
      "time_zone": "America/New_York",
      "day_of_month": null,
      "funding_requirement": "DEFAULT"
    },
    "fees": {
      "frequency": "WEEKLY",
      "rail": "NEXT_DAY_ACH",
      "payment_instrument_id": "PIpaymentInstrument222",
      "submission_delay_days": 2,
      "start_time": 10,
      "time_zone": "America/New_York",
      "day_of_month": null,
      "funding_requirement": "DEFAULT"
    }
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payout_profiles/PPpayoutProfile456"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample789"
    },
    "payout_payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentInstrument111"
    },
    "fee_payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentInstrument222"
    }
  }
}

Additional Information

Settlement Type Selection:
- NET Settlement (type: "NET"):
  - Best for: Simple merchant setups, smaller merchants, consolidated accounting
  - Fees are automatically deducted from payouts
  - Single transaction per settlement period
  - Merchant receives net amount after fees
  - Example use case: Small business with $10K/month volume, prefers simple accounting
- GROSS Settlement (type: "GROSS"):
  - Best for: Larger merchants, detailed reporting requirements, separate accounting for payouts and fees
  - Payouts and fees are separate transactions
  - More transparency in financial reporting
  - Allows different schedules for payouts vs fees
  - Example use case: Enterprise merchant needs detailed transaction tracking, wants daily payouts but monthly fee billing
Frequency Options:
- DAILY: Settlement processed every business day
  - Best for: High-volume merchants, cash flow needs
  - Most common for GROSS payouts
- WEEKLY: Settlement processed once per week
  - Best for: Mid-volume merchants, balanced cash flow
  - Reduces transaction fees vs daily
- MONTHLY: Settlement processed once per month
  - Best for: Low-volume merchants, specific billing cycles
  - Requires day_of_month parameter (1-31)
  - Lowest transaction costs
Payment Rail Options:
- NEXT_DAY_ACH: Standard ACH transfer, settles next business day
  - Most common and cost-effective
  - Reliable and widely supported
  - Typical cost: $0.25-$1.00 per transaction
- SAME_DAY_ACH: Expedited ACH, settles same business day
  - Higher cost but faster access to funds
  - Must be submitted before cutoff time (typically 2:45 PM ET)
  - Typical cost: $1.00-$5.00 per transaction
- PUSH_TO_CARD: Send to debit card, typically instant
  - Best for: Consumer payouts, gig economy platforms
  - Higher cost but instant availability
  - Only for payouts, not fee collection
  - Typical cost: 1-2% of transfer amount
Schedule Configuration Fields:
- payment_instrument_id:
  - Must be a verified bank account or debit card
  - For NET: One payment instrument handles both payouts and fees
  - For GROSS: Can use same or different instruments for payouts and fees
  - Must belong to the merchant
- submission_delay_days:
  - Delays settlement submission after calculation
  - 0 = immediate submission when scheduled
  - 1-7 = hold for risk review, fraud monitoring, or merchant preference
  - Common settings: 0 for trusted merchants, 1-3 for new merchants
- start_time: Hour of day (0-23) when settlement window opens
  - Example: 18 = 6:00 PM
  - Affects when settlement is processed
- time_zone: IANA time zone (America/New_York, America/Los_Angeles, etc.)
  - Ensures consistent settlement times
  - Important for multi-timezone operations
- day_of_month: Required for MONTHLY frequency
  - Valid range: 1-31
  - If day doesn't exist in month (e.g., 31st in February), uses last day of month
- funding_requirement: Typically "DEFAULT"
Switching Between NET and GROSS:
- Can switch settlement types by updating the profile
- When switching from NET to GROSS, specify both payouts and fees schedules
- When switching from GROSS to NET, only the net schedule is needed
- Changes typically take effect for the next settlement cycle
Payment Instrument Requirements:
- Must be verified before use (see Payment Instruments API)
- For bank accounts: Must complete micro-deposit verification
- For debit cards: Must be a valid debit card (not credit)
- Merchants can update their payment instruments separately
Validation Rules:
- submission_delay_days is a string in the request but stored as integer
- day_of_month is required when frequency is MONTHLY
- For GROSS, both payouts and fees objects are required
- Payment instruments must exist and be verified
- Cannot use PUSH_TO_CARD for fee collection (only NEXT_DAY_ACH or SAME_DAY_ACH)
Use Cases:
- Upgrade merchant from monthly to daily settlements as volume grows
- Switch from NET to GROSS for better financial reporting
- Change payment rail to SAME_DAY_ACH for faster access to funds
- Update bank account if merchant changes banking relationships
- Add submission delay for new merchants during onboarding period
Impact on Settlements:
- Changes typically take effect for settlements calculated after the update
- In-flight settlements may use the old configuration
- Check with settlement queue to see pending settlements
Best Practices:
- Test configuration changes in staging environment first
- Notify merchants before changing settlement schedules
- Use GROSS for merchants requiring detailed accounting
- Use NET for simpler merchant setups
- Consider merchant cash flow needs when selecting frequency
- Balance cost (transaction fees) vs convenience (faster settlements)

Overview​

Resource Access​

Arguments​

Example Request (Update to NET Settlement)​

Example Request (Update to GROSS Settlement)​

Example Response (NET Settlement)​

Example Response (GROSS Settlement)​

Additional Information​