Skip to main content

Fetch a Split Transfer

Overview​

Fetch the details of a single Split Transfer by its unique ID. Use this endpoint to retrieve detailed information about a specific portion of a split payment.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: GET /split_transfers/\{split_transfer_id}

Arguments​

ParameterTypeRequiredDescription
split_transfer_idstringYes (path)The unique ID of the Split Transfer

Example Request​

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

Example Response​

{
  "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": "Premium Electronics Store",
    "product_category": "electronics",
    "order_id": "ORD-2023-12345",
    "marketplace_order_item_id": "ITEM-789"
  },
  "_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"
    },
    "identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDidentityMerchant1"
    },
    "fees": {
      "href": "https://api.ahrvo.network/payments/na/split_transfers/STsplitTransfer001/fees"
    },
    "settlement": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlement456"
    }
  }
}

Additional Information​

  • Split Transfer Details: Complete information about one merchant's portion
    • Amount they receive from the split payment
    • Fees deducted from their portion
    • Settlement timing and status
    • Links to related resources
  • Amount: This merchant's share in cents
    • Example: 7500 = $75.00
    • Part of larger parent transfer
    • May represent percentage or fixed amount
  • Fee: Fee charged to this specific merchant
    • Example: 150 cents = $1.50
    • Deducted from merchant's settlement
    • Based on merchant's fee profile
    • Net payout = amount - fee ($75.00 - $1.50 = $73.50)
  • Type:
    • DEBIT: Merchant receives funds (standard for sales)
    • CREDIT: Merchant pays funds (for refunds/reversals)
  • Fee Profile ID: Determines how fees calculated
    • Each merchant can have custom fee structure
    • Examples:
      • Flat fee: $0.30 per transaction
      • Percentage: 2.9% of amount
      • Tiered: Different rates by volume
    • Null if using default platform fee profile
  • Identity ID: The merchant's identity record
    • Links to merchant account details
    • Bank account information
    • Business information
  • Merchant ID: The merchant receiving this split
    • Unique identifier for the vendor/seller
    • May have multiple splits in same parent transfer (if selling multiple items)
  • Parent Transfer ID: Original customer payment
    • Links back to full transaction
    • Use to see complete payment context
    • All splits share same parent
  • Ready to Settle At: Settlement eligibility timestamp
    • When split becomes available for payout
    • May differ from parent transfer if holds applied
    • Used by settlement engine to batch payouts
  • Tags: Custom metadata for tracking
    • merchant_name: Human-readable merchant identifier
    • product_category: What was purchased
    • order_id: Link to order management system
    • marketplace_order_item_id: Specific item in multi-item order
    • Custom fields for business needs
  • Use Cases:

    • Merchant Support:

      • Merchant calls asking about specific payment
      • Look up split transfer by ID
      • Explain amount, fees, settlement timing

    • Reconciliation:

      • Merchant's records don't match platform
      • Fetch split transfer details
      • Verify amount and fee calculations
      • Check settlement status

    • Dispute Resolution:

      • Customer disputes charge
      • Need to identify which merchant to contact
      • Fetch split to see merchant details
      • Follow merchant link to contact info

    • Financial Reporting:

      • Generate merchant payout report
      • Fetch each split transfer for details
      • Aggregate amounts and fees
      • Export for accounting

    • Audit Trail:

      • Compliance review of transactions
      • Fetch split transfer details
      • Verify proper fee application
      • Check settlement timing
  • Related Links (in _links):
    • self: This split transfer
    • parent_transfer: Original customer payment
    • merchant: Merchant receiving this split
    • identity: Merchant's identity/account details
    • fees: Detailed fee breakdown (use dedicated endpoint)
    • settlement: The settlement batch containing this split
  • Settlement Integration:
    • Split transfers settle independently
    • Each merchant has own settlement schedule
    • Multiple splits from same parent may settle at different times
    • Check settlement link to see payout status
  • Fee Calculation Examples:

    • Flat Fee:

      • Amount: $75.00 (7,500 cents)
      • Fee: $0.30 (30 cents)
      • Net: $74.70

    • Percentage Fee:

      • Amount: $75.00 (7,500 cents)
      • Fee: 2% = $1.50 (150 cents)
      • Net: $73.50

    • Tiered Fee:

      • First $50: 2.9% = $1.45
      • Next $25: 2.5% = $0.625
      • Total fee: $2.08 (208 cents)
      • Net: $72.92
  • Common Workflows:

    • Track Payment Status:

      1. Customer makes payment (parent transfer created)
      2. Platform creates split transfers
      3. Fetch split transfer to check status
      4. Monitor settlement link until paid

    • Resolve Missing Payment:

      1. Merchant claims they didn't receive payment
      2. Fetch split transfer by ID
      3. Check settlement link - is it settled?
      4. If settled, show settlement details
      5. If pending, explain settlement schedule

    • Update Merchant:

      1. Need to change merchant for a split
      2. Cannot modify existing split transfer
      3. Must void/refund and create new transaction
      4. Split transfers are immutable once created
  • Best Practices:
    • Store split_transfer_id in your order management system
    • Use tags to link splits to your business objects
    • Regularly reconcile splits against your records
    • Monitor settlement status via settlement link
    • Keep parent_transfer_id for full transaction context
  • Immutability: Split transfers cannot be modified
    • Amount, merchant, fees are fixed at creation
    • To change, must create refund/reversal
    • New transaction required for corrections
  • Related Endpoints:
    • GET /split_transfers: List all splits for parent transfer
    • GET /split_transfers/{id}/fees: Detailed fee breakdown
    • GET /transfers/{parent_transfer_id}: View parent transfer
    • GET /merchants/{merchant_id}: Merchant details
    • GET /settlements/{settlement_id}: Settlement containing this split