Fetch Payout Profile by Merchant

Overview

Fetch the Payout Profile automatically created for a specific Merchant. This is a convenience endpoint that retrieves a merchant's payout configuration without needing to know the Payout Profile ID.

Resource Access

User Permissions: Admin users only
Endpoint: GET /merchants/\{merchant_id}/payout_profile

Arguments

Parameter	Type	Required	Description
merchant_id	string	Yes	The unique ID of the Merchant

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/merchants/MUmerchantExample456/payout_profile' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response (NET Settlement)

{
  "id": "PPpayoutProfile123",
  "created_at": "2023-05-15T14:30:00Z",
  "updated_at": "2023-09-20T10:15:00Z",
  "linked_id": "MUmerchantExample456",
  "linked_type": "MERCHANT",
  "type": "NET",
  "tags": {
    "merchant_name": "Acme Corp"
  },
  "net": {
    "frequency": "DAILY",
    "rail": "NEXT_DAY_ACH",
    "payment_instrument_id": "PIpaymentInstrument789",
    "submission_delay_days": 1,
    "start_time": 18,
    "time_zone": "America/New_York",
    "day_of_month": null,
    "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/PIpaymentInstrument789"
    }
  }
}

Example Response (GROSS Settlement)

{
  "id": "PPpayoutProfile789",
  "created_at": "2023-07-20T11:00:00Z",
  "updated_at": "2023-11-15T14:30:00Z",
  "linked_id": "MUmerchantExample456",
  "linked_type": "MERCHANT",
  "type": "GROSS",
  "tags": {
    "merchant_name": "Acme Corp",
    "settlement_tier": "premium"
  },
  "net": null,
  "gross": {
    "payouts": {
      "frequency": "DAILY",
      "rail": "SAME_DAY_ACH",
      "payment_instrument_id": "PIpaymentInstrument111",
      "submission_delay_days": 0,
      "start_time": 10,
      "time_zone": "America/Los_Angeles",
      "day_of_month": null,
      "funding_requirement": "DEFAULT"
    },
    "fees": {
      "frequency": "MONTHLY",
      "rail": "NEXT_DAY_ACH",
      "payment_instrument_id": "PIpaymentInstrument222",
      "submission_delay_days": 2,
      "start_time": 14,
      "time_zone": "America/Los_Angeles",
      "day_of_month": 1,
      "funding_requirement": "DEFAULT"
    }
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payout_profiles/PPpayoutProfile789"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample456"
    },
    "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

Automatic Creation: When a Merchant is successfully provisioned, a Payout Profile is automatically created with default settings
One-to-One Relationship: Each Merchant has exactly one Payout Profile
- The linked_id field in the profile matches the merchant's ID
- The linked_type is always "MERCHANT"
Alternative Access: This endpoint provides the same data as:
- GET /payout_profiles/{payout_profile_id}
- But you can use the Merchant ID instead of looking up the Payout Profile ID first
Settlement Configuration: The response shows the complete settlement configuration:
- NET Settlement: Single schedule for combined payout/fee processing
  - Fees are deducted from payouts automatically
  - Merchant receives net amount in one transfer
  - Simpler for merchants with straightforward needs
- GROSS Settlement: Separate schedules for payouts and fees
  - Payouts and fees are independent transactions
  - More flexibility and transparency
  - Better for detailed financial reporting
Schedule Details:
- frequency: How often settlements occur (DAILY, WEEKLY, MONTHLY)
- rail: Payment method (NEXT_DAY_ACH, SAME_DAY_ACH, PUSH_TO_CARD)
- payment_instrument_id: Bank account or card for the transfer
- submission_delay_days: Days to delay after calculation (risk management)
- start_time: Hour of day when settlement window opens (0-23)
- time_zone: IANA time zone for scheduling
- day_of_month: For MONTHLY, which day to process (1-31)
- funding_requirement: Funding mechanism (typically DEFAULT)
Use Cases:
- Retrieve settlement schedule when onboarding a merchant
- Display payout settings in merchant dashboard
- Verify payment instrument configuration before processing
- Check when next settlement will occur
- Troubleshoot payout timing or delivery issues
- Provide merchant support with settlement details
Common Workflows:
1. Merchant Onboarding:
  - Create Merchant → Payout Profile auto-created
  - Fetch profile to verify default settings
  - Update if custom settlement schedule is needed
2. Merchant Support:
  - Merchant calls asking "When will I get paid?"
  - Use this endpoint to retrieve their schedule
  - Explain frequency, rail, and timing
3. Configuration Review:
  - Audit merchant settlement settings
  - Ensure payment instruments are verified
  - Check for optimal frequency/rail combination
Updating Configuration:
- Use PUT /payout_profiles/{payout_profile_id} to modify settings
- Can get the profile ID from the response to this endpoint
- Or use the ID from the merchant's _links if available
Payment Instrument Validation:
- The payment_instrument_id must be verified before settlements can process
- For bank accounts: Micro-deposit verification required
- For debit cards: Card validation required
- Check Payment Instrument status if settlements are failing
Default Configuration:
- New merchants typically start with:
  - Type: NET (simpler for most merchants)
  - Frequency: DAILY (better cash flow)
  - Rail: NEXT_DAY_ACH (cost-effective)
  - Submission delay: 1-3 days (risk management for new merchants)
- Can be customized during or after onboarding
Merchant Experience:
- NET settlement: Merchant sees one deposit with fees already deducted
  - Example: $1,000 in sales, $50 in fees → $950 deposited
- GROSS settlement: Merchant sees separate payout and fee transactions
  - Example: $1,000 payout deposited, $50 fee deducted separately
Related Endpoints:
- POST /merchants: Creates merchant and auto-creates payout profile
- GET /merchants/{merchant_id}: Returns merchant details with link to payout profile
- PUT /payout_profiles/{payout_profile_id}: Updates payout configuration
- GET /payment_instruments/{payment_instrument_id}: Verify payment instrument status
Error Scenarios:
- If merchant doesn't exist: 404 Not Found
- If merchant exists but profile isn't created yet: Should not occur (auto-created)
- If payment instrument is unverified: Profile exists but settlements won't process

Overview​

Resource Access​

Arguments​

Example Request​

Example Response (NET Settlement)​

Example Response (GROSS Settlement)​

Additional Information​

Overview

Resource Access

Arguments

Example Request

Example Response (NET Settlement)

Example Response (GROSS Settlement)

Additional Information