Skip to main content

List Payout Profiles

Overview​

Retrieve a paginated list of all Payout Profiles in your system. Payout Profiles define how merchants' fees and payouts are calculated and processed, including Net and Gross settlement schedules.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: GET /payout_profiles

Arguments​

ParameterTypeRequiredDescription
limitintegerNoMaximum number of records to return (default: 5)
after_cursorstringNoCursor for pagination to fetch the next page of results

Example Request​

curl -X GET \
  'https://api.ahrvo.network/payments/na/payout_profiles?limit=10' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response​

{
  "_embedded": {
    "payout_profiles": [
      {
        "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"
          }
        }
      },
      {
        "id": "PPpayoutProfile456",
        "created_at": "2023-06-10T09:00:00Z",
        "updated_at": "2023-10-05T16:45:00Z",
        "linked_id": "MUmerchantExample789",
        "linked_type": "MERCHANT",
        "type": "GROSS",
        "tags": {
          "merchant_name": "Big Shop LLC"
        },
        "net": null,
        "gross": {
          "payouts": {
            "frequency": "WEEKLY",
            "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/PPpayoutProfile456"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample789"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 10,
    "count": 2
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payout_profiles?limit=10"
    }
  }
}

Additional Information​

  • Payout Profile Types:
    • NET Settlement: Fees are deducted from payouts, resulting in a single net transfer to the merchant
      • Simpler for merchants with one consolidated settlement
      • The net object contains a single schedule for combined payout/fee processing
    • GROSS Settlement: Payouts and fees are handled as separate transactions
      • Provides more transparency and control
      • The gross object contains separate payouts and fees schedules
  • Schedule Configuration: Each schedule (NET or GROSS) includes:
    • frequency: How often settlements occur (DAILY, WEEKLY, MONTHLY)
    • rail: Payment method (NEXT_DAY_ACH, SAME_DAY_ACH, PUSH_TO_CARD)
    • payment_instrument_id: The bank account or card to use for the transfer
    • submission_delay_days: Number of days to delay the settlement after it's calculated
    • start_time: Hour of day (0-23) when the settlement window opens
    • time_zone: Time zone for scheduling (e.g., America/New_York, America/Los_Angeles)
    • day_of_month: For MONTHLY frequency, which day to process (1-31)
    • funding_requirement: Funding mechanism (typically DEFAULT)
  • Linked Resources:
    • linked_id: The Merchant ID this profile is associated with
    • linked_type: Always "MERCHANT" (Payout Profiles are linked to merchants)
  • Pagination: Use the after_cursor parameter with the cursor from page.next to retrieve subsequent pages
  • Use Cases:
    • Review all payout configurations across merchants
    • Audit settlement schedules and payment rails
    • Identify merchants using specific payout frequencies or rails
    • Bulk analysis of fee collection methods
    • Compare NET vs GROSS settlement usage
  • Filtering: While this endpoint doesn't support direct filtering, you can:
    • Filter results client-side after fetching
    • Use tags to categorize and identify profiles
    • Retrieve specific merchant profiles using GET /merchants/{merchant_id}/payout_profile
  • Automatic Creation: Payout Profiles are automatically created when a Merchant is provisioned
  • Related Resources: Use the _links object to navigate to:
    • The Merchant this profile belongs to
    • Payment Instruments referenced in the schedule