Create a Funding Transfer Attempt for a Settlement

Overview

Create an instant payout (Funding Transfer Attempt) to push settlement funds to a merchant's debit card. This provides real-time access to funds instead of waiting 1-3 days for standard ACH transfer.

Resource Access

User Permissions: Admin users only
Endpoint: POST /settlements/\{settlement_id}/funding_transfer_attempts

Arguments

Parameter	Type	Required	Description
settlement_id	string	Yes (path)	The unique ID of the Settlement to pay out
payment_instrument	string	Yes	ID of the debit card to receive funds
tags	object	No	Key-value pairs for custom metadata

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/funding_transfer_attempts' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_instrument": "PIdebitCardExample123",
    "tags": {
      "instant_payout": "true",
      "merchant_request": "urgent",
      "requested_by": "merchant_portal"
    }
  }'

Example Response

{
  "id": "FTAattemptExample001",
  "created_at": "2023-12-11T10:00:00Z",
  "updated_at": "2023-12-11T10:00:15Z",
  "amount": 935000,
  "currency": "USD",
  "state": "SUCCEEDED",
  "settlement_id": "STsettlementExample123",
  "payment_instrument_id": "PIdebitCardExample123",
  "processor": "VISA_DIRECT",
  "trace_id": "VD987654321",
  "failure_code": null,
  "failure_message": null,
  "tags": {
    "instant_payout": "true",
    "merchant_request": "urgent",
    "requested_by": "merchant_portal"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/funding_transfer_attempts/FTAattemptExample001"
    },
    "settlement": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIdebitCardExample123"
    },
    "merchant_identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/MImerchantIdentity123"
    }
  }
}

Additional Information

Instant Payout: Push funds to merchant's debit card in minutes
- Alternative to standard ACH (1-3 days)
- Uses Visa Direct or Mastercard Send
- Higher fees but immediate availability
Payment Instrument Requirements:
- Must be type PAYMENT_CARD
- Must be subtype DEBIT (credit cards not supported)
- Card must be eligible for instant payouts
- Card must belong to merchant in settlement
Amount: Automatically uses settlement net_amount
- Cannot specify custom amount
- Full settlement paid out to card
- Amount in cents (smallest currency unit)
Processor Selection: Automatically determined by card
- VISA_DIRECT: For Visa debit cards
- MASTERCARD_SEND: For Mastercard debit cards
- No manual selection needed
State Lifecycle:
- PENDING: Attempt submitted to processor
  - Typically transitions within seconds
- SUCCEEDED: Funds pushed to card successfully
  - Merchant can access funds immediately
- FAILED: Attempt rejected by processor
  - See failure_code and failure_message
  - May need to retry with different card or fallback to ACH
Common Failure Codes:
- CARD_NOT_ELIGIBLE: Card doesn't support instant payouts
  - Solution: Use standard ACH transfer instead
- CARD_EXPIRED: Card expiration date passed
  - Solution: Merchant must update card
- CARD_BLOCKED: Card frozen, closed, or blocked
  - Solution: Merchant must use different card
- AMOUNT_EXCEEDS_LIMIT: Payout exceeds card/merchant limits
  - Solution: Split into multiple settlements or use ACH
- INSUFFICIENT_FUNDS: Platform account lacks funds
  - Solution: Add funds to platform account
- PROCESSOR_ERROR: Network/technical error
  - Solution: Retry or use ACH fallback
Fees: Instant payouts cost more than ACH
- Typical flat fee: $0.50 - $2.00 per payout
- Or percentage-based: 1-2% of payout amount
- Deducted from platform account (not merchant)
- Merchant may be charged via separate fee entry
Limits:
- Per-transaction: Often $10,000 - $25,000 maximum
- Daily/monthly: Varies by merchant risk profile
- Limits enforced by Visa/Mastercard networks
- Platform may have additional limits
Use Cases:
- Urgent Merchant Payout:
  - Merchant needs funds immediately
  - Emergency or cash flow issue
  - Willing to pay instant payout fee
  - Create attempt instead of waiting for ACH
- Same-Day Settlement:
  - Platform offers instant payout as premium feature
  - Merchant enrolled in instant payout program
  - Automatically create attempt on settlement approval
  - Merchant receives funds within minutes
- Retry After Failure:
  - First instant payout failed (card expired)
  - Merchant updates to new card
  - Create new attempt with updated card
  - Second attempt succeeds
Best Practices:
- Verify Card Eligibility: Check card details before creating attempt
  - Use GET /payment_instruments/{id} to verify card active and eligible
- Handle Failures Gracefully: Have fallback to ACH
  - If instant payout fails, automatically create standard funding transfer
  - Notify merchant of fallback
- Communicate Fees: Ensure merchant aware of instant payout costs
  - Display fee in merchant portal
  - Get merchant confirmation before creating attempt
- Track Usage: Monitor instant payout adoption
  - Which merchants use instant payouts
  - Success/failure rates by card network
  - Cost vs. merchant satisfaction
- Set Reasonable Limits: Balance risk and merchant needs
  - Higher limits for trusted merchants
  - Lower limits for new/risky merchants

vs. Standard ACH:

Aspect	Instant Payout	Standard ACH
Speed	Minutes	1-3 business days
Cost	$0.50-$2.00 or 1-2%	Free or $0.10-$0.25
Destination	Debit card only	Bank account
Limits	$10K-$25K per transaction	Much higher
Availability	Business hours (mostly)	24/7
Failure Rate	Higher	Lower

Settlement Requirements:
- Settlement must be APPROVED
- Settlement cannot already have funding transfer
- Settlement amount must be positive (net_amount > 0)
Idempotency: Creating multiple attempts not recommended
- Each attempt charges fees
- System doesn't prevent duplicates
- Use GET endpoint to check for existing attempts first
Related Endpoints:
- GET /settlements/{id}/funding_transfer_attempts: List all attempts
- GET /settlements/{id}/funding_transfers: View standard ACH transfers
- GET /payment_instruments/{id}: Check card eligibility
- GET /settlements/{id}: Verify settlement status and amount

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​