Skip to main content

List Split Transfers by Parent Transfer ID

Overview​

Retrieve a list of all Split Transfers associated with a specific parent Transfer. Split Transfers divide a single payment transaction among multiple merchants, enabling marketplace and platform payment distribution.

Resource Access​

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

Arguments​

ParameterTypeRequiredDescription
parent_transfer_idstringYes (query)ID of the original parent Transfer that was split
limitintegerNoMaximum number of records to return (default: 10)
offsetintegerNoNumber of records to skip for pagination

Example Request​

curl -X GET \
  'https://api.ahrvo.network/payments/na/split_transfers?parent_transfer_id=TRparentTransfer123&limit=20' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response​

{
  "_embedded": {
    "split_transfers": [
      {
        "id": "STsplitTransfer001",
        "created_at": "2023-12-10T14:30:00Z",
        "updated_at": "2023-12-10T14:30:00Z",
        "amount": 7500,
        "currency": "USD",
        "fee": 150,
        "fee_profile_id": "FPfeeProfile123",
        "identity_id": "IDidentityMerchant1",
        "merchant_id": "MUmerchant001",
        "parent_transfer_id": "TRparentTransfer123",
        "ready_to_settle_at": "2023-12-10T14:30:00Z",
        "type": "DEBIT",
        "tags": {
          "merchant_name": "Vendor A",
          "product_category": "electronics"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/split_transfers/STsplitTransfer001"
          },
          "parent_transfer": {
            "href": "https://api.ahrvo.network/payments/na/transfers/TRparentTransfer123"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant001"
          },
          "fees": {
            "href": "https://api.ahrvo.network/payments/na/split_transfers/STsplitTransfer001/fees"
          }
        }
      },
      {
        "id": "STsplitTransfer002",
        "created_at": "2023-12-10T14:30:00Z",
        "updated_at": "2023-12-10T14:30:00Z",
        "amount": 2500,
        "currency": "USD",
        "fee": 50,
        "fee_profile_id": "FPfeeProfile456",
        "identity_id": "IDidentityMerchant2",
        "merchant_id": "MUmerchant002",
        "parent_transfer_id": "TRparentTransfer123",
        "ready_to_settle_at": "2023-12-10T14:30:00Z",
        "type": "DEBIT",
        "tags": {
          "merchant_name": "Vendor B",
          "product_category": "shipping"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/split_transfers/STsplitTransfer002"
          },
          "parent_transfer": {
            "href": "https://api.ahrvo.network/payments/na/transfers/TRparentTransfer123"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant002"
          },
          "fees": {
            "href": "https://api.ahrvo.network/payments/na/split_transfers/STsplitTransfer002/fees"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 2
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/split_transfers?parent_transfer_id=TRparentTransfer123&limit=20"
    },
    "parent_transfer": {
      "href": "https://api.ahrvo.network/payments/na/transfers/TRparentTransfer123"
    }
  }
}

Additional Information​

  • Split Transfers: Divides a single payment among multiple merchants
    • One parent Transfer (original customer payment)
    • Multiple child Split Transfers (distributed to merchants)
    • Each split represents a merchant's portion
  • Parent Transfer: The original Transfer that was split
    • Customer makes one payment
    • Platform divides it among vendors/merchants
    • Parent Transfer ID required to find all splits
  • Use Cases:
    • Marketplace Payments:
      • Customer orders from multiple sellers
      • One checkout, payment split among sellers
      • Example: $100 order → $75 to Vendor A, $25 to Vendor B
    • Service Fee Distribution:
      • Payment includes service fees
      • Main amount to merchant
      • Platform fee to platform account
    • Multi-Party Transactions:
      • Ride-sharing: Driver + Platform
      • Food delivery: Restaurant + Delivery + Platform
      • Freelance platform: Worker + Platform
    • Commission-Based Models:
      • Affiliate commissions
      • Referral fees
      • Partner revenue sharing
  • Amount Field: Each split's portion in cents
    • Example: $100 parent transfer
      • Split 1: 7500 cents ($75.00)
      • Split 2: 2500 cents ($25.00)
    • Sum of splits should equal parent transfer amount (minus platform fees)
  • Fee Field: Fee charged on this specific split
    • Charged to the merchant receiving this split
    • Independent of other splits' fees
    • May vary by merchant's fee profile
    • In cents (smallest currency unit)
  • Type: Usually DEBIT
    • DEBIT: Merchant receives funds (typical)
    • CREDIT: Merchant pays funds (rare, for refunds)
  • Ready to Settle At: When split becomes eligible for settlement
    • Typically same time as parent transfer
    • May differ if holds or delays applied
    • Used for settlement batching
  • Merchant ID: The merchant receiving this split portion
    • Different merchant for each split
    • Maps to Identity ID (merchant's identity record)
  • Fee Profile ID: Determines fee calculation for this split
    • Each merchant may have different fee structure
    • Null if default fee profile used
  • Parent Transfer Calculation Example:
    • Customer payment: $100.00 (10,000 cents)
    • Platform fee: $10.00 (1,000 cents)
    • Remaining to split: $90.00 (9,000 cents)
    • Split 1 (Vendor A): $75.00 (7,500 cents) - Fee: $1.50 (150 cents)
    • Split 2 (Vendor B): $15.00 (1,500 cents) - Fee: $0.50 (50 cents)
    • Split totals: 7,500 + 1,500 = 9,000 cents ✓
    • Vendor A nets: $75.00 - $1.50 = $73.50
    • Vendor B nets: $15.00 - $0.50 = $14.50
  • Common Scenarios:

    • E-commerce Marketplace:

      • Customer buys items from 3 sellers
      • $50 + $30 + $20 = $100 total
      • One parent Transfer: $100
      • Three Split Transfers: $50, $30, $20
      • Each seller paid independently

    • Ride-Sharing:

      • Passenger pays $25
      • Platform fee: $5 (kept by platform, not split)
      • Driver portion: $20 (Split Transfer to driver)
      • One parent Transfer, one Split Transfer

    • Subscription Revenue Share:

      • Customer pays $50/month
      • Content creator: $35 (70%)
      • Platform: $15 (30%)
      • Two Split Transfers or one split + platform retention
  • Pagination: Use for merchants with many splits
    • Large marketplaces may have dozens of splits per transaction
    • Use offset and limit parameters
  • Tags: Custom metadata for splits
    • Track merchant names, product categories, business units
    • Useful for reporting and reconciliation
    • Queryable for analytics
  • Settlement: Each split settles independently
    • Different merchants may have different settlement schedules
    • Vendor A: Daily settlements
    • Vendor B: Weekly settlements
    • Each split follows its merchant's settlement config
  • Reconciliation:
    • Verify parent transfer amount = sum of splits + platform fees
    • Check each merchant received correct portion
    • Validate fee calculations
  • Related Endpoints:
    • GET /split_transfers/{id}: Fetch individual split details
    • GET /split_transfers/{id}/fees: View fees for a split
    • GET /transfers/{parent_transfer_id}: View parent transfer details
    • GET /merchants/{merchant_id}: View merchant receiving split